@actuate-media/cms-admin 0.12.0 → 0.12.1

package/src/__tests__/lib/collaboration-provider.test.ts

@@ -0,0 +1,425 @@
+import { Awareness } from 'y-protocols/awareness'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+
+import {
+  createCollaborationProvider,
+  summarisePresence,
+  type CollaborationOptions,
+} from '../../lib/collaboration-provider.js'
+
+// The provider helper requires a browser-like context (checks for `window`).
+// The cms-admin vitest config runs under `node`, so we stub a minimal window
+// for the whole file.
+const originalWindow = (globalThis as { window?: unknown }).window
+beforeAll(() => {
+  ;(globalThis as { window?: unknown }).window = globalThis
+})
+afterAll(() => {
+  ;(globalThis as { window?: unknown }).window = originalWindow
+})
+
+/**
+ * Fake WebsocketProvider that records constructor args + exposes manual
+ * emit hooks so tests can simulate connection-state transitions without
+ * opening real sockets.
+ */
+class FakeWsProvider {
+  static instances: FakeWsProvider[] = []
+  readonly url: string
+  readonly room: string
+  readonly ydoc: Y.Doc
+  readonly opts: { connect?: boolean; params?: Record<string, string> }
+  readonly awareness: Awareness
+  private listeners = new Map<string, Set<(payload: unknown) => void>>()
+  destroyed = false
+
+  constructor(
+    url: string,
+    room: string,
+    ydoc: Y.Doc,
+    opts: { connect?: boolean; params?: Record<string, string> },
+  ) {
+    this.url = url
+    this.room = room
+    this.ydoc = ydoc
+    this.opts = opts
+    this.awareness = new Awareness(ydoc)
+    FakeWsProvider.instances.push(this)
+  }
+
+  on(event: string, handler: (payload: unknown) => void): void {
+    let bucket = this.listeners.get(event)
+    if (!bucket) {
+      bucket = new Set()
+      this.listeners.set(event, bucket)
+    }
+    bucket.add(handler)
+  }
+
+  emit(event: string, payload: unknown): void {
+    const bucket = this.listeners.get(event)
+    if (!bucket) return
+    for (const handler of bucket) handler(payload)
+  }
+
+  destroy(): void {
+    this.destroyed = true
+  }
+}
+
+const Ctor = FakeWsProvider as unknown as ConstructorParameters<
+  typeof import('y-websocket').WebsocketProvider
+> extends unknown[]
+  ? typeof import('y-websocket').WebsocketProvider
+  : never
+
+const baseOptions: CollaborationOptions = {
+  documentId: 'doc-1',
+  url: 'ws://localhost:1234/realtime',
+  user: { name: 'Alice', color: '#ff00aa', userId: 'user_1' },
+}
+
+describe('createCollaborationProvider — construction', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+  afterEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('throws if the global window is undefined (true SSR)', () => {
+    const origWindow = (globalThis as { window?: unknown }).window
+    delete (globalThis as { window?: unknown }).window
+    try {
+      expect(() =>
+        createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor }),
+      ).toThrow(/browser context/)
+    } finally {
+      ;(globalThis as { window?: unknown }).window = origWindow
+    }
+  })
+
+  it('throws when documentId is missing', () => {
+    expect(() =>
+      createCollaborationProvider(
+        { ...baseOptions, documentId: '' },
+        { WebsocketProviderCtor: Ctor },
+      ),
+    ).toThrow(/documentId/)
+  })
+
+  it('throws when url is missing', () => {
+    expect(() =>
+      createCollaborationProvider({ ...baseOptions, url: '' }, { WebsocketProviderCtor: Ctor }),
+    ).toThrow(/url/)
+  })
+
+  it('instantiates the provider with the supplied url + documentId', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances.length).toBe(1)
+    const instance = FakeWsProvider.instances[0]!
+    expect(instance.url).toBe(baseOptions.url)
+    expect(instance.room).toBe(baseOptions.documentId)
+    expect(instance.ydoc).toBe(ctx.ydoc)
+    ctx.destroy()
+  })
+
+  it('forwards params (e.g. auth token) to the provider', () => {
+    createCollaborationProvider(
+      { ...baseOptions, params: { token: 'abc' } },
+      { WebsocketProviderCtor: Ctor },
+    )
+    expect(FakeWsProvider.instances[0]!.opts.params).toEqual({ token: 'abc' })
+  })
+
+  it('defaults connect to true', () => {
+    createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances[0]!.opts.connect).toBe(true)
+  })
+
+  it('respects connect: false for offline / test usage', () => {
+    createCollaborationProvider({ ...baseOptions, connect: false }, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances[0]!.opts.connect).toBe(false)
+  })
+})
+
+describe('createCollaborationProvider — awareness seeding', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('writes the user info into local awareness state', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    const localState = ctx.awareness.getLocalState() as { user?: typeof baseOptions.user }
+    expect(localState.user).toEqual(baseOptions.user)
+    ctx.destroy()
+  })
+
+  it('includes avatarUrl in awareness when supplied', () => {
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, user: { ...baseOptions.user, avatarUrl: 'https://example.test/a.png' } },
+      { WebsocketProviderCtor: Ctor },
+    )
+    const localState = ctx.awareness.getLocalState() as { user?: { avatarUrl?: string } }
+    expect(localState.user?.avatarUrl).toBe('https://example.test/a.png')
+    ctx.destroy()
+  })
+})
+
+describe('createCollaborationProvider — onStatus / onError', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('forwards normalised status transitions to onStatus', () => {
+    const onStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onStatus },
+      { WebsocketProviderCtor: Ctor },
+    )
+    const provider = FakeWsProvider.instances[0]!
+    provider.emit('status', { status: 'connecting' })
+    provider.emit('status', { status: 'connected' })
+    provider.emit('status', { status: 'disconnected' })
+    expect(onStatus.mock.calls.map((c) => c[0])).toEqual([
+      'connecting',
+      'connected',
+      'disconnected',
+    ])
+    ctx.destroy()
+  })
+
+  it('ignores unknown status values', () => {
+    const onStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onStatus },
+      { WebsocketProviderCtor: Ctor },
+    )
+    FakeWsProvider.instances[0]!.emit('status', { status: 'gibberish' })
+    expect(onStatus).not.toHaveBeenCalled()
+    ctx.destroy()
+  })
+
+  it('calls onError when the provider fires a connection-error event', () => {
+    const onError = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onError },
+      { WebsocketProviderCtor: Ctor },
+    )
+    FakeWsProvider.instances[0]!.emit('connection-error', { code: 4401 })
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toMatch(/connection error/i)
+    ctx.destroy()
+  })
+})
+
+describe('createCollaborationProvider — destroy', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('clears local awareness, destroys the provider, and destroys the doc', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    const provider = FakeWsProvider.instances[0]!
+    const docDestroySpy = vi.spyOn(ctx.ydoc, 'destroy')
+    ctx.destroy()
+    expect(ctx.awareness.getLocalState()).toBeNull()
+    expect(provider.destroyed).toBe(true)
+    expect(docDestroySpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('is idempotent — second destroy does not throw', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    ctx.destroy()
+    expect(() => ctx.destroy()).not.toThrow()
+  })
+})
+
+describe('createCollaborationProvider — offline persistence', () => {
+  /** Stub IndexeddbPersistence that lets tests drive `whenSynced`. */
+  class FakeIdb {
+    static instances: FakeIdb[] = []
+    readonly name: string
+    readonly ydoc: Y.Doc
+    private resolve!: () => void
+    private reject!: (err: Error) => void
+    whenSynced: Promise<void>
+    destroyed = false
+    constructor(name: string, ydoc: Y.Doc) {
+      this.name = name
+      this.ydoc = ydoc
+      this.whenSynced = new Promise<void>((res, rej) => {
+        this.resolve = res
+        this.reject = rej
+      })
+      FakeIdb.instances.push(this)
+    }
+    fulfill() {
+      this.resolve()
+    }
+    fail(err: Error) {
+      this.reject(err)
+    }
+    destroy() {
+      this.destroyed = true
+    }
+  }
+  const IdbCtor = FakeIdb as unknown as ConstructorParameters<
+    typeof import('y-indexeddb').IndexeddbPersistence
+  > extends unknown[]
+    ? typeof import('y-indexeddb').IndexeddbPersistence
+    : never
+
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+    FakeIdb.instances.length = 0
+  })
+
+  it('marks offlineStatus as unsupported when indexedDB is unavailable', () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => false,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('unsupported')
+    expect(ctx.offlinePersistence).toBeNull()
+    expect(ctx.offlineStatus).toBe('unsupported')
+    expect(FakeIdb.instances.length).toBe(0)
+    ctx.destroy()
+  })
+
+  it('opts out entirely when offline: false is passed', () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, offline: false, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('unsupported')
+    expect(ctx.offlinePersistence).toBeNull()
+    expect(FakeIdb.instances.length).toBe(0)
+    ctx.destroy()
+  })
+
+  it('emits loading → ready when IndexedDB whenSynced resolves', async () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('loading')
+    expect(FakeIdb.instances.length).toBe(1)
+    expect(FakeIdb.instances[0]!.name).toBe(`actuate-cms:${baseOptions.documentId}`)
+    expect(ctx.offlinePersistence).toBe(FakeIdb.instances[0]!)
+    FakeIdb.instances[0]!.fulfill()
+    await new Promise((r) => setTimeout(r, 0))
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('ready')
+    expect(ctx.offlineStatus).toBe('ready')
+    ctx.destroy()
+    expect(FakeIdb.instances[0]!.destroyed).toBe(true)
+  })
+
+  it('emits error when whenSynced rejects', async () => {
+    const onOfflineStatus = vi.fn()
+    const onError = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus, onError },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    FakeIdb.instances[0]!.fail(new Error('quota exceeded'))
+    await new Promise((r) => setTimeout(r, 0))
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('error')
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toBe('quota exceeded')
+    ctx.destroy()
+  })
+
+  it('emits error when IndexeddbPersistence constructor throws', () => {
+    const onOfflineStatus = vi.fn()
+    const onError = vi.fn()
+    class ThrowingIdb {
+      constructor() {
+        throw new Error('IDB blocked')
+      }
+    }
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus, onError },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor:
+          ThrowingIdb as unknown as typeof FakeIdb as unknown as typeof IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('error')
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toBe('IDB blocked')
+    expect(ctx.offlinePersistence).toBeNull()
+    ctx.destroy()
+  })
+})
+
+describe('summarisePresence', () => {
+  function makeAwareness(): Awareness {
+    return new Awareness(new Y.Doc())
+  }
+
+  it('returns the local awareness clientId', () => {
+    const aw = makeAwareness()
+    const snap = summarisePresence(aw)
+    expect(snap.selfClientId).toBe(aw.clientID)
+  })
+
+  it('includes peers that have a user object with a name', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff', userId: 'u1' } })
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(1)
+    expect(snap.users[0]!.user.name).toBe('Alice')
+  })
+
+  it('skips entries with no user info', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({})
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(0)
+  })
+
+  it('deduplicates by userId when peers share the same logical user', () => {
+    const aw = makeAwareness()
+    const otherDoc = new Y.Doc()
+    const otherAw = new Awareness(otherDoc)
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff', userId: 'u1' } })
+    otherAw.setLocalState({ user: { name: 'Alice (tab 2)', color: '#000', userId: 'u1' } })
+    // Manually pipe otherAw's state into aw to simulate the awareness fan-out.
+    aw.getStates().set(otherAw.clientID, otherAw.getLocalState()!)
+    const snap = summarisePresence(aw)
+    // Both states share userId 'u1' → only one entry.
+    expect(snap.users).toHaveLength(1)
+  })
+
+  it('keeps multiple peers without userId as distinct entries', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff' } })
+    aw.getStates().set(9999, { user: { name: 'Bob', color: '#000' } })
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(2)
+    expect(snap.users.map((u) => u.user.name).sort()).toEqual(['Alice', 'Bob'])
+  })
+})

package/src/__tests__/lib/comment-anchor.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest'
+import * as Y from 'yjs'
+
+import { decodeAnchor, encodeAnchor } from '../../lib/comment-anchor.js'
+
+/**
+ * Build a Yjs doc with a TipTap-style XmlFragment containing one
+ * paragraph element whose text is the supplied string. Returns both the
+ * doc and the `Y.XmlText` leaf so tests can anchor against the right
+ * type (`createRelativePositionFromTypeIndex` indexes characters when
+ * called against an `XmlText`/`Text`, and child slots when called
+ * against the `XmlFragment` / element).
+ */
+function makeDoc(text: string): { doc: Y.Doc; yText: Y.XmlText } {
+  const doc = new Y.Doc()
+  const fragment = doc.getXmlFragment('default')
+  const paragraph = new Y.XmlElement('paragraph')
+  const yText = new Y.XmlText(text)
+  paragraph.insert(0, [yText])
+  fragment.insert(0, [paragraph])
+  return { doc, yText }
+}
+
+describe('encodeAnchor', () => {
+  it('produces non-empty base64 strings for a valid selection', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc, yType: yText, from: 0, to: 5 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+    expect(anchor.from.length).toBeGreaterThan(0)
+    expect(anchor.to.length).toBeGreaterThan(0)
+    expect(anchor.from).not.toBe(anchor.to)
+  })
+
+  it('returns null for an empty range', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    expect(encodeAnchor({ doc, yType: yText, from: 3, to: 3 })).toBeNull()
+  })
+
+  it('returns null for an inverted range', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    expect(encodeAnchor({ doc, yType: yText, from: 5, to: 1 })).toBeNull()
+  })
+
+  it('returns null when from < 0', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    expect(encodeAnchor({ doc, yType: yText, from: -1, to: 5 })).toBeNull()
+  })
+
+  it('returns null when to > yType.length', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    expect(encodeAnchor({ doc, yType: yText, from: 0, to: 999 })).toBeNull()
+  })
+
+  it('produces stable output for the same range called twice', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    const a1 = encodeAnchor({ doc, yType: yText, from: 0, to: 5 })
+    const a2 = encodeAnchor({ doc, yType: yText, from: 0, to: 5 })
+    expect(a1).toEqual(a2)
+  })
+})
+
+describe('decodeAnchor — round trip', () => {
+  it('round-trips the original positions on an unchanged doc', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc, yType: yText, from: 6, to: 11 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+    const resolved = decodeAnchor({ doc, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(resolved.from).toBe(6)
+    expect(resolved.to).toBe(11)
+    expect(resolved.yType).toBe(yText)
+  })
+
+  it('returns null when the anchor blobs are not valid base64', () => {
+    const { doc } = makeDoc('Hello world')
+    expect(
+      decodeAnchor({
+        doc,
+        anchor: { from: 'not valid !@#$', to: 'also not !@#$' },
+      }),
+    ).toBeNull()
+  })
+})
+
+describe('decodeAnchor — survives concurrent edits', () => {
+  it('shifts the anchor right when text is inserted before it', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    // Anchor "world" (chars 6..11).
+    const anchor = encodeAnchor({ doc, yType: yText, from: 6, to: 11 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    // Prepend "Hey, " — five characters — to the text.
+    yText.insert(0, 'Hey, ')
+
+    const resolved = decodeAnchor({ doc, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(yText.toString().slice(resolved.from, resolved.to)).toBe('world')
+  })
+
+  it('still resolves when text is appended after the anchor', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc, yType: yText, from: 0, to: 5 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    yText.insert(yText.length, '!')
+
+    const resolved = decodeAnchor({ doc, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(yText.toString().slice(resolved.from, resolved.to)).toBe('Hello')
+  })
+
+  it('detaches (returns null) when the anchored text is deleted', () => {
+    const { doc, yText } = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc, yType: yText, from: 6, to: 11 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    // Delete "world" — five chars starting at index 6.
+    yText.delete(6, 5)
+
+    const resolved = decodeAnchor({ doc, anchor })
+    // After deletion both ends collapse; we treat `from >= to` as detached
+    // so the panel can flag the comment as "anchor lost".
+    expect(resolved).toBeNull()
+  })
+
+  it('survives a sequence of inserts on both sides', () => {
+    const { doc, yText } = makeDoc('alpha beta gamma')
+    const anchor = encodeAnchor({ doc, yType: yText, from: 6, to: 10 }) // "beta"
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    yText.insert(0, '>> ')
+    yText.insert(yText.length, ' <<')
+    yText.insert(0, '!')
+
+    const resolved = decodeAnchor({ doc, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(yText.toString().slice(resolved.from, resolved.to)).toBe('beta')
+  })
+})
+
+describe('decodeAnchor — independent docs', () => {
+  it('survives transport between two clones (the multi-user scenario)', () => {
+    const a = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc: a.doc, yType: a.yText, from: 6, to: 11 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    // Sync a fresh clone (the other client's doc) from author A's state.
+    const docB = new Y.Doc()
+    Y.applyUpdate(docB, Y.encodeStateAsUpdate(a.doc))
+
+    const resolved = decodeAnchor({ doc: docB, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(resolved.from).toBe(6)
+    expect(resolved.to).toBe(11)
+  })
+
+  it('still resolves after the clone makes its own edit', () => {
+    const a = makeDoc('Hello world')
+    const anchor = encodeAnchor({ doc: a.doc, yType: a.yText, from: 6, to: 11 })
+    expect(anchor).not.toBeNull()
+    if (!anchor) return
+
+    const docB = new Y.Doc()
+    Y.applyUpdate(docB, Y.encodeStateAsUpdate(a.doc))
+    // Look up B's mirror of the same text node and edit it.
+    const fragmentB = docB.getXmlFragment('default')
+    const paragraphB = fragmentB.firstChild as Y.XmlElement
+    const yTextB = paragraphB.firstChild as Y.XmlText
+    yTextB.insert(0, 'Hey, ')
+
+    const resolved = decodeAnchor({ doc: docB, anchor })
+    expect(resolved).not.toBeNull()
+    if (!resolved) return
+    expect(yTextB.toString().slice(resolved.from, resolved.to)).toBe('world')
+  })
+})