@portabletext/plugin-sdk-value 8.0.5 → 8.1.0

package/README.md

@@ -3,8 +3,9 @@
 > Connect a Portable Text Editor with a Sanity document using the SDK
 
 Two-way synchronization between a Portable Text Editor and a field in a Sanity
-document, plus presence: other people's carets show up in the field, and the
-local user's caret shows up for them, including in the Studio.
+document, plus presence and inline comments: other people's carets show up in
+the field and the local user's caret shows up for them, and comment threads
+anchored to text draw as highlights, all interoperating with the Studio.
 
 ## Installation
 
@@ -18,6 +19,7 @@ npm install @portabletext/plugin-sdk-value
 - **Real-time updates**: Automatically handles patches from external sources (other users, mutations, etc.)
 - **Optimistic updates**: Provides smooth user experience with immediate local updates
 - **Presence**: Reports where the local user is editing, and draws other people's carets
+- **Inline comments**: Draws highlights for comment threads anchored to text, and starts new threads on the selection
 
 ## Usage
 
@@ -72,6 +74,55 @@ Pass `renderCursor={null}` to draw no carets at all while still reporting the
 local user's presence, which is what you want if you only care about keeping the
 document in sync.
 
+### Inline comments
+
+Comment threads anchored to text in the field draw as highlights, and new
+threads can be started on the current selection. The composer UI stays with the
+app, the same split presence uses for carets. Comments are written in the shape
+Sanity Studio stores, so threads round-trip between an SDK app and the Studio.
+
+`useSDKCommentDecorations` returns `RangeDecoration[]` for the open threads on
+the field. Pass it through `rangeDecorations`, which `SDKPortableTextEditable`
+merges with the presence carets:
+
+```tsx
+const decorations = useSDKCommentDecorations({
+  ...documentHandle,
+  path: 'content',
+  renderDecoration: (comment) => (props) => (
+    <span data-comment-id={comment.id} style={{background: '#fef3c7'}}>
+      {props.children}
+    </span>
+  ),
+})
+
+return (
+  <SDKPortableTextEditable
+    {...documentHandle}
+    path="content"
+    rangeDecorations={decorations}
+  />
+)
+```
+
+`useSDKCommentAuthoring` is the write side: `commentableSelection` is set when
+the current selection can take a comment, and `createInlineComment` starts a
+thread anchored to it:
+
+```tsx
+const {commentableSelection, createInlineComment} = useSDKCommentAuthoring({
+  ...documentHandle,
+  path: 'content',
+})
+
+// Show the composer while `commentableSelection` is set, then:
+await createInlineComment({message})
+```
+
+Highlights follow the text while the user types, and a highlight whose text is
+deleted or rewritten beyond recognition is dropped rather than drawn on the
+wrong words. Resolved threads draw nothing, matching the Studio.
+
 ### Rendering the editable yourself
 
 `SDKValuePlugin` still works as a sibling component if you would rather keep
@@ -138,5 +189,5 @@ the Studio, whose field indicators compare the exact document id its form is on.
 
 This plugin requires:
 
-- `@sanity/sdk-react` 2.19 or newer, where the presence hooks were added
+- `@sanity/sdk-react` 2.20.1 or newer, where the comment hooks were added
 - The document must exist in the Sanity dataset

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DocumentHandle, usePresenceForDocument } from "@sanity/sdk-react";
+import { Comment, CommentMessage, DocumentHandle, DocumentResource, usePresenceForDocument } from "@sanity/sdk-react";
 import { EditorSelection, Patch, PortableTextBlock, PortableTextEditableProps, RangeDecoration } from "@portabletext/editor";
 import { PropsWithChildren, ReactElement } from "react";
 import "@portabletext/patches";
@@ -41,6 +41,10 @@ interface SDKRemoteCursor {
  * @public
  */
 interface SDKPresencePluginProps extends DocumentHandle {
+  /**
+   * @deprecated Use `resource` instead.
+   */
+  source?: DocumentResource;
   /**
    * The document path of the Portable Text field, for example `content`. The
    * same form `SDKValuePlugin` takes.
@@ -53,6 +57,10 @@ interface SDKPresencePluginProps extends DocumentHandle {
  * @public
  */
 interface UseSDKPresenceCursorsOptions extends DocumentHandle {
+  /**
+   * @deprecated Use `resource` instead.
+   */
+  source?: DocumentResource;
   path: string;
   renderCursor: RenderCursorFunction;
 }
@@ -86,7 +94,93 @@ declare function SDKPresencePlugin(props: SDKPresencePluginProps): null;
  * @public
  */
 declare function useSDKPresenceCursors(options: UseSDKPresenceCursorsOptions): RangeDecoration[];
+/**
+ * Draws one comment's highlight. The plugin has no opinion about how a
+ * highlight looks, so it is the caller's to provide, the same way presence
+ * takes `renderCursor`.
+ *
+ * @public
+ */
+type RenderCommentDecorationFunction = (comment: Comment) => (props: PropsWithChildren) => ReactElement;
+/**
+ * Options for {@link useSDKCommentDecorations}.
+ *
+ * @public
+ */
+interface UseSDKCommentDecorationsOptions extends DocumentHandle {
+  /**
+   * The document path of the Portable Text field, for example `content`. The
+   * same form `SDKValuePlugin` takes.
+   */
+  path: string;
+  renderDecoration: RenderCommentDecorationFunction;
+}
+/**
+ * Inline comment highlights for a Portable Text field, as range decorations.
+ *
+ * Pass the result to `<PortableTextEditable rangeDecorations={...} />`. Each
+ * thread's first comment that carries a text anchor on this field gets one
+ * decoration. Highlights stay put while the local user types, and a highlight
+ * whose text has been deleted or rewritten beyond recognition is dropped
+ * rather than drawn on the wrong words.
+ *
+ * Suspends while the document's comments load, like every SDK read hook.
+ *
+ * Resolved threads draw nothing: this mirrors the Studio, where resolving a
+ * thread removes its highlight from the text.
+ *
+ * @public
+ */
+declare function useSDKCommentDecorations(options: UseSDKCommentDecorationsOptions): RangeDecoration[];
+/**
+ * Options for {@link useSDKCommentAuthoring}.
+ *
+ * @public
+ */
+interface UseSDKCommentAuthoringOptions extends DocumentHandle {
+  /**
+   * The document path of the Portable Text field, for example `content`.
+   */
+  path: string;
+}
+/**
+ * What {@link useSDKCommentAuthoring} returns.
+ *
+ * @public
+ */
+interface SDKCommentAuthoring {
+  /**
+   * The current selection when it can take a comment, `null` otherwise. Show
+   * the comment affordance when this is set, and position it off the
+   * selection. A selection can take a comment when it is expanded, contains
+   * text, and stays within one array of blocks.
+   */
+  commentableSelection: EditorSelection;
+  /**
+   * Starts a comment thread anchored to the text selected right now.
+   *
+   * The anchor is captured from the live selection at call time, so call this
+   * from the affordance while the selection still stands. Rejects when nothing
+   * commentable is selected.
+   */
+  createInlineComment: (options: {
+    message: CommentMessage;
+    /** Reuse the id of a failed comment to retry it. */
+    commentId?: string;
+  }) => Promise<Comment>;
+}
+/**
+ * Lets the app author inline comments on a Portable Text field.
+ *
+ * The plugin captures the selection and writes the comment; the composer UI is
+ * the app's, the same split the Studio and Canvas use. Comments are written in
+ * the shape the Studio stores, so a thread started here shows up there.
+ *
+ * @public
+ */
+declare function useSDKCommentAuthoring(options: UseSDKCommentAuthoringOptions): SDKCommentAuthoring;
 interface SDKValuePluginProps extends DocumentHandle {
+  source?: DocumentResource;
   path: string;
 }
 /**
@@ -132,6 +226,10 @@ declare function ValueSyncPlugin(props: ValueSyncConfig): null;
  * @public
  */
 interface SDKPortableTextEditableProps extends DocumentHandle, Omit<PortableTextEditableProps, keyof DocumentHandle> {
+  /**
+   * @deprecated Use `resource` instead.
+   */
+  source?: DocumentResource;
   /**
    * The document path of the Portable Text field, for example `content`.
    */
@@ -170,5 +268,5 @@ interface SDKPortableTextEditableProps extends DocumentHandle, Omit<PortableText
  * @public
  */
 declare function SDKPortableTextEditable(props: SDKPortableTextEditableProps): import("react").JSX.Element;
-export { type RenderCursorFunction, SDKPortableTextEditable, type SDKPortableTextEditableProps, SDKPresencePlugin, type SDKPresencePluginProps, type SDKRemoteCursor, SDKValuePlugin, type UseSDKPresenceCursorsOptions, ValueSyncPlugin, useSDKPresenceCursors };
+export { type RenderCommentDecorationFunction, type RenderCursorFunction, type SDKCommentAuthoring, SDKPortableTextEditable, type SDKPortableTextEditableProps, SDKPresencePlugin, type SDKPresencePluginProps, type SDKRemoteCursor, SDKValuePlugin, type UseSDKCommentAuthoringOptions, type UseSDKCommentDecorationsOptions, type UseSDKPresenceCursorsOptions, ValueSyncPlugin, useSDKCommentAuthoring, useSDKCommentDecorations, useSDKPresenceCursors };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.sdk-presence.tsx","../src/plugin.sdk-value.tsx","../src/sdk-editable.tsx"],"mappings":";;;;;;;;;KAeK,mBAAmB,kBACf;;;;;;;KASG,wBACV,QAAQ,qBACJ,OAAO,sBAAsB;;;;;;;;;UAUlB;;;;;EAKf;;;;EAIA,WAAW;EACX,MAAM;;;;;;;UAQS,+BAA+B;;;;;EAK9C;;;;;;;UAQe,qCAAqC;EACpD;EACA,cAAc;;;;;;;;;;;;;;;;iBAiBA,kBAAkB,OAAO;;;;;;;;;;;;;;;iBAwBzB,sBACd,SAAS,+BACR;UC48BO,4BAA4B;EACpC;;;;;iBAqCc,eAAe,OAAO,sCAAmB,IAAA;;;;KAiFpD;EACH,sBAAsB;EACtB,YAAY,OAAO;EACnB,sBAAsB;;;;;;;;EAQtB,mBACE,WAAW,SAAS;;;;;;EAOtB,eAAe,SAAS;;;;;;;;;;;;iBAaV,gBAAgB,OAAO;;;;;;UChsCtB,qCAEb,gBAGA,KAAK,iCAAiC;;;;EAIxC;;;;;;EAMA,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6CD,wBAAwB,OAAO,+CAA4B,IAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.sdk-presence.tsx","../src/plugin.sdk-comments.tsx","../src/plugin.sdk-value.tsx","../src/sdk-editable.tsx"],"mappings":";;;;;;;;;KAiBK,mBAAmB,kBACf;;;;;;;KASG,wBACV,QAAQ,qBACJ,OAAO,sBAAsB;;;;;;;;;UAUlB;;;;;EAKf;;;;EAIA,WAAW;EACX,MAAM;;;;;;;UAQS,+BAA+B;;;;EAI9C,SAAS;;;;;EAKT;;;;;;;UAQe,qCAAqC;;;;EAIpD,SAAS;EACT;EACA,cAAc;;;;;;;;;;;;;;;;iBAiBA,kBAAkB,OAAO;;;;;;;;;;;;;;;iBAwBzB,sBACd,SAAS,+BACR;;;;;;;;KCnCS,mCACV,SAAS,aACL,OAAO,sBAAsB;;;;;;UAOlB,wCAAwC;;;;;EAKvD;EACA,kBAAkB;;;;;;;;;;;;;;;;;;iBAmBJ,yBACd,SAAS,kCACR;;;;;;UAgGc,sCAAsC;;;;EAIrD;;;;;;;UAQe;;;;;;;EAOf,sBAAsB;;;;;;;;EAQtB,sBAAsB;IACpB,SAAS;;IAET;QACI,QAAQ;;;;;;;;;;;iBAwBA,uBACd,SAAS,gCACR;UC0yBO,4BAA4B;EACpC,SAAS;EACT;;;;;iBAqCc,eAAe,OAAO,sCAAmB,IAAA;;;;KAkFpD;EACH,sBAAsB;EACtB,YAAY,OAAO;EACnB,sBAAsB;;;;;;;;EAQtB,mBACE,WAAW,SAAS;;;;;;EAOtB,eAAe,SAAS;;;;;;;;;;;;iBAaV,gBAAgB,OAAO;;;;;;UCnsCtB,qCAEb,gBAGA,KAAK,iCAAiC;;;;EAIxC,SAAS;;;;EAIT;;;;;;EAMA,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6CD,wBAAwB,OAAO,+CAA4B,IAAA"}