@sanity/sdk 2.18.0 → 2.20.0

package/src/presence/paths.test.ts

@@ -0,0 +1,70 @@
+import {type Path} from '@sanity/types'
+import {describe, expect, it} from 'vitest'
+
+import {startsWithPath} from './paths'
+
+describe('startsWithPath', () => {
+  it('treats the empty path as a prefix of everything, which is the document root', () => {
+    expect(startsWithPath([], ['title'])).toBe(true)
+    expect(startsWithPath([], [])).toBe(true)
+  })
+
+  it('matches a path against itself', () => {
+    expect(startsWithPath(['title'], ['title'])).toBe(true)
+  })
+
+  it('matches a descendant', () => {
+    expect(startsWithPath(['body'], ['body', 'children'])).toBe(true)
+  })
+
+  it('does not match an ancestor, since a longer prefix cannot fit', () => {
+    expect(startsWithPath(['body', 'children'], ['body'])).toBe(false)
+  })
+
+  it('does not match a sibling', () => {
+    expect(startsWithPath(['title'], ['subtitle'])).toBe(false)
+  })
+
+  it('does not match a partial segment name', () => {
+    // `title` must not be treated as a prefix of `titleImage`.
+    expect(startsWithPath(['title'], ['titleImage'])).toBe(false)
+  })
+
+  it('compares keyed segments by key rather than by identity', () => {
+    // Distinct objects with the same key, which is what arrives over the wire.
+    expect(startsWithPath(['cast', {_key: 'a'}], ['cast', {_key: 'a'}, 'name'])).toBe(true)
+    expect(startsWithPath(['cast', {_key: 'a'}], ['cast', {_key: 'b'}, 'name'])).toBe(false)
+  })
+
+  it('does not confuse a keyed segment with a string or a number', () => {
+    expect(startsWithPath([{_key: 'a'}], ['a'])).toBe(false)
+    expect(startsWithPath(['a'], [{_key: 'a'}])).toBe(false)
+    expect(startsWithPath([{_key: '0'}], [0])).toBe(false)
+  })
+
+  it('compares numeric indexes', () => {
+    expect(startsWithPath(['awards', 0], ['awards', 0])).toBe(true)
+    expect(startsWithPath(['awards', 0], ['awards', 1])).toBe(false)
+  })
+
+  it('compares index tuples structurally', () => {
+    const prefix: Path = ['body', [0, 2]]
+    expect(startsWithPath(prefix, ['body', [0, 2], 'children'])).toBe(true)
+    expect(startsWithPath(prefix, ['body', [0, 3]])).toBe(false)
+    expect(startsWithPath(prefix, ['body', [0, '']])).toBe(false)
+  })
+
+  it('does not confuse a tuple with a keyed segment', () => {
+    expect(startsWithPath([[0, 2]], [{_key: 'a'}])).toBe(false)
+    expect(startsWithPath([{_key: 'a'}], [[0, 2]])).toBe(false)
+  })
+
+  it('handles a realistic Portable Text span path', () => {
+    const field: Path = ['body']
+    const span: Path = ['body', {_key: 'block-1'}, 'children', {_key: 'span-1'}, 'text']
+
+    expect(startsWithPath(field, span)).toBe(true)
+    expect(startsWithPath(['title'], span)).toBe(false)
+    expect(startsWithPath(['body', {_key: 'block-2'}], span)).toBe(false)
+  })
+})

package/src/presence/paths.ts

@@ -0,0 +1,41 @@
+import {type IndexTuple, type KeyedSegment, type Path, type PathSegment} from '@sanity/types'
+
+/**
+ * Segments are not always strings, despite what `PresenceLocation.path` declares.
+ * Array items arrive as `{_key}` and Portable Text spans as a mix of keys and
+ * property names, because that is what the Studio sends.
+ */
+function isKeyedSegment(segment: PathSegment): segment is KeyedSegment {
+  return (
+    typeof segment === 'object' && segment !== null && !Array.isArray(segment) && '_key' in segment
+  )
+}
+
+/**
+ * Index tuples (`[from, to]`) only occur in slice selections, which presence never
+ * reports. Compared structurally rather than assumed absent.
+ */
+function isEqualTuple(a: IndexTuple, b: IndexTuple): boolean {
+  return a.length === b.length && a.every((value, index) => value === b[index])
+}
+
+/** Compares two path segments, whatever shape they arrive in. */
+function isEqualSegment(a: PathSegment, b: PathSegment): boolean {
+  if (a === b) return true
+  if (isKeyedSegment(a) && isKeyedSegment(b)) return a._key === b._key
+  if (Array.isArray(a) && Array.isArray(b)) return isEqualTuple(a, b)
+  return false
+}
+
+/**
+ * True when `candidate` is at or below `prefix` in the document tree.
+ *
+ * Equivalent to `startsWith` from the Studio's `@sanity/util/paths`, which is not
+ * an SDK dependency.
+ *
+ * @internal
+ */
+export function startsWithPath(prefix: Path, candidate: Path): boolean {
+  if (prefix.length > candidate.length) return false
+  return prefix.every((segment, index) => isEqualSegment(segment, candidate[index]))
+}