feat(plugin-sdk-value): add inline comment decorations and authoring - #3159
feat(plugin-sdk-value): add inline comment decorations and authoring#3159ryanbonial wants to merge 2 commits into
Conversation
🦋 Changeset detectedLatest commit: cdb6acb The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Bundle Stats✅ No significant changes. All scenario measurements (7)🗺️
Significant means at least 1.0 KB and 1% gzip, or at least 5 ms and 10% import time. |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
f2721f6 to
5b75a10
Compare
5b75a10 to
09fb1ac
Compare
09fb1ac to
fc5c204
Compare
1 participant
Why
Sanity SDK 2.20.1 shipped comment hooks (
useComments,useCommentActions), including inline text anchors on Portable Text fields. SDK apps that author content in the editor need both halves of that in the editor itself: highlights for existing comment threads, and a way to start a thread on the current selection. Today only Sanity Studio and Canvas can do this, and each hand-built the machinery privately.This adds the machinery once, here, as two hooks. The composer UI stays with the app, the same split this package already uses for presence (
renderCursor), and the same one Studio and Canvas chose.What
useSDKCommentDecorations({...handle, path, renderDecoration})returnsRangeDecoration[]for open comment threads anchored to text in this field. Anchors re-resolve when comments change; between resolutions the editor's ownonMovedtracks edits, so there is no per-keystroke diffing. An anchor whose text is gone or rewritten beyond recognition is dropped rather than drawn on the wrong words.useSDKCommentAuthoring({...handle, path})exposescommentableSelection(set when the live selection can take a comment) andcreateInlineComment({message}), which captures the selection at call time and writes through@sanity/sdk-react.Comments are written in the exact shape Sanity Studio stores (per selected block, the block's plain text with the selection boundaries marked by two private-use characters), so threads round-trip between an SDK app and the Studio. That format is deliberately internal to this package: the platform's comments storage is migrating, and keeping the anchor format out of the public API is what lets it change without a breaking release. The public surface is two hooks and the four types their signatures reference, mirroring the presence exports one for one.
What to review
src/comments-anchoring.tsis a direct port of Studio'sbuildRangeDecorationSelectionsFromComments, oddities preserved and annotated (the asymmetric similarity threshold, the child-separator offset walk). Its fixture suite is Studio's own, ported values and expectations.src/comments-selection.tsis the write side, new code: the editor'sgetSelectedTextBlocksalready walks the selection, so this is a fraction of Studio's equivalent. Cross-container selections refuse to build rather than guessing an anchor.src/plugin.sdk-comments.tsxholds the hooks. The moved-highlight state is remembered against the comment list it was reported for, so a re-resolution wins over stale positions without an effect (the earlier draft used one; lint rightly objected).Testing
115 unit tests and 61 browser tests pass. The test that matters most is the round trip: what
buildStoredSelectionwrites,resolveCommentSelectionsfinds again at the same offsets, which is the interop contract with Studio expressed as a test. Not covered here: an end-to-end against a live dataset; the SDK side of that lives in sanity-io/sdk (see sanity-io/sdk#1085 and sanity-io/sdk#1087).