Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Two-way synchronization between a Portable Text Editor and a field in a Sanity
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.
anchored to text draw as highlights, all interoperating with Sanity Studio.

## Installation

Expand Down Expand Up @@ -79,7 +79,8 @@ document in sync.
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.
Sanity Studio stores, so threads round-trip between an SDK app and Sanity
Studio.

`useSDKCommentDecorations` returns `RangeDecoration[]` for the open threads on
the field. Pass it through `rangeDecorations`, which `SDKPortableTextEditable`
Expand Down Expand Up @@ -123,7 +124,7 @@ 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.
wrong words. Resolved threads draw nothing, matching Sanity Studio.

### Rendering the editable yourself

Expand Down Expand Up @@ -185,7 +186,7 @@ function MyEditor(props: DocumentHandle) {
Carets are drawn with the built-in component unless you pass `renderCursor`, and
are collapsed to a single point at the participant's focus. Presence
answers where someone is, so decorating their whole selection would highlight
text the local user never selected. The Studio does the same.
text the local user never selected. Sanity Studio does the same.

Participants are counted by session, not by person. The same user in two tabs
draws two carets, in the same colour. Group by `user.sanityUserId` in your own
Expand All @@ -196,7 +197,8 @@ The local user is never included, so an app does not draw its own caret.
Which document is reported follows the handle's `perspective`, or the ambient one
from `ResourceProvider`. Pass the plain document id and let the perspective
select the draft, the published document, or a release version. This matters for
the Studio, whose field indicators compare the exact document id its form is on.
the Sanity Studio form, whose field indicators compare the exact document id
it is on.

## Requirements

Expand Down
8 changes: 4 additions & 4 deletions src/comments-anchoring.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ import {
} from './comments-anchoring'

/**
* The scenarios are ported from the Studio's
* The scenarios are ported from Sanity's
* `buildRangeDecorationSelectionsFromComments` suite, fixtures included, so the
* two implementations can be diffed against the same cases. One known gap the
* Studio's suite also carries is pinned with `test.fails` below.
* two implementations can be diffed against the same cases. One known gap that
* Sanity's suite also carries is pinned with `test.fails` below.
*/

function span(_key: string, text: string) {
Expand Down Expand Up @@ -166,7 +166,7 @@ describe(resolveCommentSelections.name, () => {
expect(resolve(value, stored(MARKED))).toEqual([])
})

// A known gap, carried by the Studio's own suite too: text typed
// A known gap, carried by Sanity's own suite too: text typed
// immediately after the range is absorbed into it. Pinned with `fails` so
// this flips loudly if the algorithm ever gains the behaviour.
test.fails('an edit immediately after the range does not expand it', () => {
Expand Down
14 changes: 7 additions & 7 deletions src/comments-anchoring.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import {
import {arrayifyPath} from './plugin.sdk-value'

/**
* How the Studio stores an inline comment's anchor: per Portable Text block the
* How Sanity stores an inline comment's anchor: per Portable Text block the
* selection touches, the block's entire plain text with these two private-use
* characters inserted where the selection starts and ends. Text rather than
* offsets, so the anchor can be re-found after the text around it changes.
Expand All @@ -34,7 +34,7 @@ const COMMENT_INDICATORS_REGEX = new RegExp(
const CHILD_SYMBOL = '\uF0D0'

/**
* Kept from the Studio implementation: high enough to avoid re-anchoring onto
* Kept from the Sanity implementation: high enough to avoid re-anchoring onto
* the wrong occurrence of a repeated word, low enough not to hurt.
*/
const DMP_MARGIN = 15
Expand Down Expand Up @@ -151,10 +151,10 @@ function diffApply(current: string, patches: Patch[]): string {
/**
* Finds each stored anchor in the current editor value.
*
* A direct port of the Studio's `buildRangeDecorationSelectionsFromComments`,
* minus its Studio-only inputs. The stored text is diffed against the block's
* current text, so an anchor survives edits around it and inside it up to a
* similarity threshold. An anchor whose text is gone, or changed beyond
* A direct port of Sanity's `buildRangeDecorationSelectionsFromComments`, minus
* the inputs only Sanity Studio has. The stored text is diffed against the
* block's current text, so an anchor survives edits around it and inside it up
* to a similarity threshold. An anchor whose text is gone, or changed beyond
* recognition, is dropped rather than drawn somewhere wrong.
*
* Live tracking while the user types is not this function's job: the editor's
Expand Down Expand Up @@ -210,7 +210,7 @@ export function resolveCommentSelections(
endIndex,
)
const {levenshtein} = diffText(newCommentedText, oldCommentedText)
// Kept from the Studio, oddity included: only the *old* length is halved.
// Kept from Sanity, oddity included: only the *old* length is halved.
const threshold = Math.round(
newCommentedText.length + oldCommentedText.length / 2,
)
Expand Down
4 changes: 2 additions & 2 deletions src/comments-selection.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -144,8 +144,8 @@ describe(buildStoredSelection.name, () => {
})

test('what it writes, the reader finds again', () => {
// The round trip is the point of matching the Studio's format: written
// here, resolved by the same code path that resolves Studio comments.
// The round trip is the point of matching Sanity's format: written
// here, resolved by the same code path that resolves Sanity comments.
const foo = block('b1', [span('s1', 'foo bar baz')])
const built = buildStoredSelection({
selection: {anchor: point('b1', 's1', 4), focus: point('b1', 's1', 7)},
Expand Down
6 changes: 3 additions & 3 deletions src/comments-selection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ export interface BuiltSelection {
/**
* The path of the array holding the selected blocks, relative to the editor.
* Empty for blocks at the top level. Comments anchor on the containing array,
* matching what the Studio stores.
* matching what Sanity stores.
*/
containerPath: Path
/** The anchor in the Studio's stored shape, ready to pass to `createComment`. */
/** The anchor in Sanity's stored shape, ready to pass to `createComment`. */
selection: StoredTextSelection
}

Expand All @@ -38,7 +38,7 @@ export interface BuiltSelection {
*
* Per selected block, the block's entire plain text with the selection
* boundaries marked by the two indicator characters. The write-time mirror of
* `resolveCommentSelections`, and deliberately built the way the Studio builds
* `resolveCommentSelections`, and deliberately built the way Sanity builds
* it so a comment written here re-anchors there and back.
*
* Returns `null` when there is nothing commentable: a collapsed selection,
Expand Down
4 changes: 2 additions & 2 deletions src/plugin.collision-matrix.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -733,8 +733,8 @@ async function collideAndSettle(options: {
* (formatting) commits before another client's text append into the same
* span, the append's diff-match-patch hunk no longer matches either half
* at the server and is dropped. Recovering the text would need operational
* rebase of the in-flight patch (what `@sanity/mutate` does in the
* Studio). The combo must still converge to valid Portable Text; only the
* rebase of the in-flight patch (what `@sanity/mutate` does in Sanity
* Studio). The combo must still converge to valid Portable Text. Only the
* marker-survival assertion is relaxed.
*/
const KNOWN_MARKER_LOSS: Array<{
Expand Down
6 changes: 3 additions & 3 deletions src/plugin.sdk-comments.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ export interface UseSDKCommentDecorationsOptions extends DocumentHandle {
*
* Suspends while the document's comments load, like every SDK read hook.
*
* Resolved threads draw nothing: this mirrors the Studio, where resolving a
* Resolved threads draw nothing: this mirrors Sanity Studio, where resolving a
* thread removes its highlight from the text.
*
* @public
Expand Down Expand Up @@ -248,8 +248,8 @@ function getCommentableSelection(
* 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.
* the app's, the same split Sanity Studio and Canvas use. Comments are written
* in the shape Sanity Studio stores, so a thread started here shows up there.
*
* @public
*/
Expand Down
2 changes: 1 addition & 1 deletion src/presence-caret.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ const DOT_SIZE = 6
* Picks a stable colour for a participant.
*
* Keyed on the user rather than the session, so one person in two tabs draws two
* carets in the same colour. The Studio colours by user for the same reason.
* carets in the same colour. Sanity Studio colours by user for the same reason.
*
* @public
*/
Expand Down
4 changes: 2 additions & 2 deletions src/presence-cursors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ export interface RangeDecorationOptions<TCursor extends RemoteCursor> {
* Reduces a selection to a caret at its focus point.
*
* Presence answers where someone is, so decorating their whole selection would
* highlight text the local user never selected. The Studio collapses the same
* way, which keeps the two consistent when both are open on a document.
* highlight text the local user never selected. Sanity Studio collapses the
* same way, which keeps the two consistent when both are open on a document.
*
* @public
*/
Expand Down
4 changes: 2 additions & 2 deletions src/sdk-editable.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,8 @@ export function resolveCursorRenderer(

/**
* Appends the presence carets to whatever decorations the caller passed, so
* theirs survive. The Studio merges the same way. When carets are switched off
* the caller's own decorations pass straight through.
* theirs survive. Sanity Studio merges the same way. When carets are switched
* off the caller's own decorations pass straight through.
*
* @internal
*/
Expand Down
Loading