SDK-wired comment components

What each export of @sanity/collaboration/sdk replaces, and when to use it or drop down to the SDK hooks.

@sanity/collaboration/sdk joins the components to the App SDK. It has four exports, and each one replaces a piece of wiring you would otherwise write against the SDK hooks (Comments in the App SDK). This page says which piece each one replaces, so you can tell when to reach for it and when to drop below it.

It assumes an app with the SDK set up (Setup) and @sanity/collaboration installed (Get started). The setup is in those pages, and this one links to them rather than repeating them.

The components need to know who is viewing and how to turn a user ID into a name and an avatar. CommentsProvider takes both as props; SDKCommentsProvider fills them in from the SDK's auth and user stores.

import {SDKCommentsProvider} from '@sanity/collaboration/sdk'

<Suspense fallback={<p>Resolving your identity…</p>}>
  <SDKCommentsProvider>{/* the comment surface */}</SDKCommentsProvider>
</Suspense>

It suspends until the current user is known. A logged-out viewer throws to the nearest error boundary, since the components have no anonymous mode.

Its own props say which resource users are resolved against: projectId, organizationId, and resourceType. projectId falls back to the surrounding SanityApp, and resourceType defaults to 'organization' when you pass an organizationId and to 'project' otherwise. Everything else passes through to CommentsProvider: mentionOptions, reactionOptions, capabilities, formatTime, labels, and the selection and linking props activeComment, defaultActiveComment, onActiveCommentChange, and onActiveCommentNotFound. See Users and identity for what it fills in, and Enable mentions and Link to a comment for the props it passes on.

CommentsPanel takes threads and callbacks. SDKCommentsPanel takes a document handle instead, reads the threads with useCommentThreads, wires every card's writes with useSDKThreadCallbacks, and starts new threads with createComment.

<SDKCommentsProvider>
  <ArticleEditor {...handle} />
  <Suspense fallback={<p>Loading comments…</p>}>
    <SDKCommentsPanel {...handle} compose={{fieldPath: 'title'}} />
  </Suspense>
</SDKCommentsProvider>

It renders no provider of its own, so it needs an SDKCommentsProvider above it. That is what lets it share identity and selection with an editor beside it: one setActiveComment drives both. It suspends until the threads have loaded, so the Suspense boundary above it is yours.

Get started renders one, step by step. Drop to CommentsPanel or CommentList when a write has to go through something of your own, or the data is not the SDK's.

Every write a CommentThread offers maps onto one useCommentActions call. useSDKThreadCallbacks writes that mapping for you and returns a function from a thread to its card's callbacks:

const threadCallbacks = useSDKThreadCallbacks(handle)

<CommentThread thread={thread} {...threadCallbacks(thread)} />

Which callback calls which action is in One callback, one action. onCopyLink is not in it: only your app knows what its URLs look like.

Spread it before your own props, and anything you pass after wins. Failed writes go to onError, which defaults to console.error. See Comment data flow and Show a failed write.

onRetry cannot re-send a thread parent anchored to a run of text, since creating it needs the anchor and a comment carries only the resolved selection. It reports that to onError instead; see The adapter that writes the mapping for you.

PortableTextComments draws highlights and reports new comments and moved anchors through callbacks. SDKPortableTextComments sends those to createComment and updateCommentAnchor, and passes the editor's blocks as the anchor's fieldValue so a comment on unsaved text lands on the right words.

<SDKPortableTextComments {...handle} path="body" threads={threads} />

It also needs an SDKCommentsProvider above it, since the composer it opens reads the current user and the mention options from there. The threads are still yours to read. Comment on Portable Text wires it step by step, and Anchor inline comments covers what it writes.

• The props, with the plain counterparts, in Storybook: Providers, CommentsPanel, Hooks, and Portable Text.
• Levels of abstraction in the comment stack, for every rung between these and your own UI.