@prenta/admin 0.92.0

package/src/lib/collaboration-provider.ts

@@ -0,0 +1,306 @@
+/**
+ * Browser-side Yjs collaboration provider for the TipTap editor.
+ *
+ * Wraps `y-websocket`'s `WebsocketProvider` with sensible defaults and a
+ * narrow public API. The wire protocol is byte-compatible with the
+ * cms-core realtime gateway shipped in PR #106, so the standard
+ * `WebsocketProvider` connects without any custom client code.
+ *
+ * Auth flows through the browser's cookie jar — `cms-admin` already uses
+ * cookie-based sessions, and the WebSocket upgrade request carries those
+ * cookies automatically against same-origin gateways. For cross-origin
+ * deployments, attach a query-string token via the `params` option.
+ */
+import { Awareness } from 'y-protocols/awareness'
+import { WebsocketProvider } from 'y-websocket'
+import { IndexeddbPersistence } from 'y-indexeddb'
+import * as Y from 'yjs'
+
+/** Connection status reported via `onStatus` and surfaced in the editor UI. */
+export type CollaborationStatus = 'connecting' | 'connected' | 'disconnected'
+
+/**
+ * Offline-draft persistence status. Slice 6 layers a local IndexedDB
+ * mirror on top of the y-websocket transport so edits made while
+ * disconnected aren't lost. The lifecycle is:
+ *
+ * - `unsupported` — `indexedDB` is unavailable (Safari private mode,
+ *   SSR, jsdom-without-fake-indexeddb).
+ * - `pending` — provider is being constructed; no local state yet.
+ * - `loading` — IndexedDB is replaying the last saved snapshot into
+ *   the Y.Doc.
+ * - `ready` — the local store is initialised and every change is
+ *   persisted locally before the WebSocket pushes it upstream.
+ * - `error` — IndexedDB threw; the editor still works in-memory but
+ *   refresh will lose pending edits.
+ */
+export type OfflinePersistenceStatus = 'unsupported' | 'pending' | 'loading' | 'ready' | 'error'
+
+/** Per-user presence info that becomes the local awareness state. */
+export interface CollaborationUser {
+  /** Display name (used for cursor labels and the presence chip strip). */
+  name: string
+  /** CSS color value for the user's cursor / chip background. */
+  color: string
+  /** Optional avatar URL (32-square recommended). Rendered if present. */
+  avatarUrl?: string
+  /** Stable user id from the cms-core session (used as a dedup key). */
+  userId?: string
+}
+
+export interface CollaborationOptions {
+  /** Logical document id (becomes the y-websocket "room name"). */
+  documentId: string
+  /**
+   * Base URL of the realtime gateway, e.g. `wss://your.app/api/cms/realtime/sync`.
+   * The provider appends `/${documentId}` automatically (y-websocket convention).
+   * Use `ws://` for local dev.
+   */
+  url: string
+  /** Presence info for the local user. */
+  user: CollaborationUser
+  /**
+   * Extra query-string parameters (e.g. an auth token for cross-origin
+   * deployments). Forwarded to `WebsocketProvider`'s `params` option.
+   */
+  params?: Record<string, string>
+  /** Called on every connection-state transition. */
+  onStatus?: (status: CollaborationStatus) => void
+  /** Called on connection-level errors (e.g. 4401 auth rejection). */
+  onError?: (err: Error) => void
+  /**
+   * If `false`, the helper does not connect on construction. Useful for
+   * tests and for editors that want a `Y.Doc` without network traffic.
+   * Defaults to `true`.
+   */
+  connect?: boolean
+  /**
+   * Offline-draft persistence. When `true` (default), the provider
+   * mounts a `y-indexeddb` mirror so edits made while the WebSocket is
+   * disconnected survive a refresh. Pass `false` to skip the mirror
+   * (e.g. on shared kiosk machines where you don't want drafts in
+   * IndexedDB).
+   */
+  offline?: boolean
+  /** Called on every offline-persistence status transition. */
+  onOfflineStatus?: (status: OfflinePersistenceStatus) => void
+}
+
+export interface CollaborationContext {
+  /** Shared Y.Doc — bind this to the TipTap `Collaboration` extension. */
+  ydoc: Y.Doc
+  /** The underlying y-websocket provider. */
+  provider: WebsocketProvider
+  /** Awareness instance — bind to `CollaborationCursor` and the presence strip. */
+  awareness: Awareness
+  /**
+   * Local IndexedDB mirror, when `offline` is enabled and the runtime
+   * supports it. `null` when persistence is disabled or unsupported
+   * (e.g. SSR / Safari private browsing).
+   */
+  offlinePersistence: IndexeddbPersistence | null
+  /** Latest offline-persistence status. Mirrors `onOfflineStatus`. */
+  offlineStatus: OfflinePersistenceStatus
+  /** Stop the provider, evict awareness, and destroy the Y.Doc. */
+  destroy: () => void
+}
+
+/** Optional dependency-injection seam used by tests to avoid real WebSockets. */
+export interface CollaborationDeps {
+  WebsocketProviderCtor?: typeof WebsocketProvider
+  /**
+   * Override the IndexedDB persistence constructor (test seam). The
+   * default uses `y-indexeddb` which requires a browser-like
+   * `indexedDB` global; tests inject a no-op stub.
+   */
+  IndexeddbPersistenceCtor?: typeof IndexeddbPersistence
+  /**
+   * Override the IndexedDB feature check. Defaults to inspecting
+   * `globalThis.indexedDB`. Tests inject `() => true` to exercise the
+   * persistence path under happy-dom.
+   */
+  isIndexedDbSupported?: () => boolean
+}
+
+/**
+ * Open a collaboration session for `documentId`. Must be called in a browser
+ * context (jsdom is fine for tests when a fake provider is injected).
+ *
+ * The returned `ydoc` is the document the editor binds to via TipTap's
+ * `Collaboration` extension; `awareness` carries cursor + presence state.
+ * Always call `destroy()` on unmount to evict the local awareness state and
+ * close the socket.
+ */
+export function createCollaborationProvider(
+  opts: CollaborationOptions,
+  deps: CollaborationDeps = {},
+): CollaborationContext {
+  if (
+    typeof globalThis === 'undefined' ||
+    typeof (globalThis as { window?: unknown }).window === 'undefined'
+  ) {
+    // Note: jsdom defines `window`, so this only trips on bare-Node SSR.
+    throw new Error(
+      'createCollaborationProvider can only be called in a browser context (window is undefined)',
+    )
+  }
+  if (!opts.documentId || !opts.url) {
+    throw new Error('createCollaborationProvider requires both documentId and url')
+  }
+
+  const Ctor = deps.WebsocketProviderCtor ?? WebsocketProvider
+  const ydoc = new Y.Doc()
+  const provider = new Ctor(opts.url, opts.documentId, ydoc, {
+    connect: opts.connect ?? true,
+    params: opts.params,
+  })
+
+  // Layer y-indexeddb on top of the y-websocket transport for offline
+  // drafts. Both providers share the same Y.Doc, so they automatically
+  // converge: IndexedDB hydrates the doc on load, the websocket pushes
+  // pending updates to the gateway on reconnect.
+  const offlineEnabled = opts.offline !== false
+  const offlineCheck = deps.isIndexedDbSupported ?? defaultIndexedDbSupportCheck
+  let offlineStatus: OfflinePersistenceStatus = 'pending'
+  const setOfflineStatus = (next: OfflinePersistenceStatus) => {
+    offlineStatus = next
+    opts.onOfflineStatus?.(next)
+  }
+  let offlinePersistence: IndexeddbPersistence | null = null
+  if (!offlineEnabled) {
+    setOfflineStatus('unsupported')
+  } else if (!offlineCheck()) {
+    setOfflineStatus('unsupported')
+  } else {
+    setOfflineStatus('loading')
+    const PersistenceCtor = deps.IndexeddbPersistenceCtor ?? IndexeddbPersistence
+    try {
+      offlinePersistence = new PersistenceCtor(
+        // Namespace the IndexedDB key by documentId so multiple docs in
+        // the same admin session don't collide.
+        `prenta-cms:${opts.documentId}`,
+        ydoc,
+      )
+      // `whenSynced` is the canonical "snapshot replay finished" hook
+      // from y-indexeddb (https://github.com/yjs/y-indexeddb).
+      offlinePersistence.whenSynced
+        .then(() => setOfflineStatus('ready'))
+        .catch((err: unknown) => {
+          opts.onError?.(err instanceof Error ? err : new Error('Offline persistence failed'))
+          setOfflineStatus('error')
+        })
+    } catch (err) {
+      opts.onError?.(err instanceof Error ? err : new Error('Offline persistence failed'))
+      setOfflineStatus('error')
+      offlinePersistence = null
+    }
+  }
+
+  // Seed local awareness with the user's presence info. The
+  // `CollaborationCursor` TipTap extension reads `user.name` + `user.color`
+  // out of awareness state and renders cursors accordingly.
+  provider.awareness.setLocalState({
+    user: {
+      name: opts.user.name,
+      color: opts.user.color,
+      avatarUrl: opts.user.avatarUrl,
+      userId: opts.user.userId,
+    },
+  })
+
+  if (opts.onStatus) {
+    const handler = (event: { status: string }) => {
+      const status = normaliseStatus(event.status)
+      if (status) opts.onStatus!(status)
+    }
+    provider.on('status', handler)
+  }
+  if (opts.onError) {
+    const handler = () => {
+      // y-websocket emits this on socket close + on protocol errors. We
+      // surface a generic Error so callers can render a toast without
+      // sniffing y-websocket internals.
+      opts.onError!(new Error('Realtime connection error'))
+    }
+    provider.on('connection-error', handler)
+  }
+
+  const destroy = () => {
+    try {
+      provider.awareness.setLocalState(null)
+    } catch {
+      /* awareness may already be torn down */
+    }
+    try {
+      provider.destroy()
+    } catch {
+      /* idempotent */
+    }
+    if (offlinePersistence) {
+      try {
+        // y-indexeddb keeps the IDB connection open until `destroy()`;
+        // we don't drop the stored data (that's the point of offline
+        // drafts), but we close the handle so the runtime can GC.
+        offlinePersistence.destroy()
+      } catch {
+        /* idempotent */
+      }
+    }
+    try {
+      ydoc.destroy()
+    } catch {
+      /* idempotent */
+    }
+  }
+
+  return {
+    ydoc,
+    provider,
+    awareness: provider.awareness,
+    offlinePersistence,
+    get offlineStatus() {
+      return offlineStatus
+    },
+    destroy,
+  }
+}
+
+function defaultIndexedDbSupportCheck(): boolean {
+  return (
+    typeof globalThis !== 'undefined' &&
+    typeof (globalThis as { indexedDB?: unknown }).indexedDB !== 'undefined'
+  )
+}
+
+function normaliseStatus(value: string): CollaborationStatus | null {
+  if (value === 'connected') return 'connected'
+  if (value === 'connecting') return 'connecting'
+  if (value === 'disconnected') return 'disconnected'
+  return null
+}
+
+/**
+ * Reduce an Awareness map into a deduplicated array of `CollaborationUser`s.
+ * Used by `PresenceChips` and any other UI that visualises co-editors.
+ */
+export interface PresenceSnapshot {
+  /** Local user's client id (so UIs can omit themselves from the strip). */
+  selfClientId: number
+  /** Connected users, deduplicated by `userId` when present, otherwise by clientId. */
+  users: Array<{ clientId: number; user: CollaborationUser }>
+}
+
+export function summarisePresence(awareness: Awareness): PresenceSnapshot {
+  const seenUserIds = new Set<string>()
+  const users: PresenceSnapshot['users'] = []
+  for (const [clientId, state] of awareness.getStates()) {
+    const user = (state as { user?: CollaborationUser })?.user
+    if (!user || typeof user.name !== 'string') continue
+    if (user.userId) {
+      if (seenUserIds.has(user.userId)) continue
+      seenUserIds.add(user.userId)
+    }
+    users.push({ clientId, user })
+  }
+  return { selfClientId: awareness.clientID, users }
+}

package/src/lib/collection-routes.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical admin routes for opening / creating documents.
+ *
+ * Post-type and Pages collections have dedicated section-based editors that the
+ * generic `/:collection/:id` route does NOT reach — routing a post through the
+ * generic editor silently strips its `sections` data, and a post collection
+ * whose slug is `posts` 404s under `/:collection/:id` entirely. Centralizing the
+ * mapping here keeps `Dashboard`, `CollectionList`, and any future caller in
+ * agreement instead of each re-deriving (and getting it wrong).
+ */
+
+export interface CollectionRouteMeta {
+  type?: string
+}
+
+/** The route that opens an existing document in its correct editor. */
+export function editPathForDoc(
+  col: CollectionRouteMeta | undefined,
+  collection: string,
+  id: string,
+): string {
+  if (col?.type === 'post') return `/posts/${collection}/${id}/edit`
+  if (collection === 'pages') return `/pages/${id}/edit`
+  return `/${collection}/${id}`
+}
+
+/** The route that starts a new document in the correct editor. */
+export function newPathForCollection(
+  col: CollectionRouteMeta | undefined,
+  collection: string,
+): string {
+  if (col?.type === 'post') return `/posts/${collection}/new`
+  if (collection === 'pages') return `/pages/new`
+  return `/${collection}/new`
+}

package/src/lib/collection-schema.ts

@@ -0,0 +1,62 @@
+/**
+ * Collection schema guard shared by the Page and Post editors.
+ *
+ * Both editors persist content as top-level keys on a collection document
+ * (`sections`, `metaTitle`, …). The server's field-access layer only writes
+ * keys that are *declared as fields* on the collection — any undeclared key is
+ * silently dropped on save. A collection missing e.g. the `sections` field
+ * would therefore discard all section content with no error, so the editors
+ * use this check to refuse to operate (and explain why) instead.
+ *
+ * When `config` (or its collections) is not provided — some embedding/test
+ * contexts don't pass it — we can't check, so we report nothing missing and
+ * trust the consumer.
+ */
+
+interface CollectionLike {
+  slug?: string
+  fields?: unknown
+}
+
+/** Look up a collection by slug; `collections` may be a record or an array. */
+export function findCollection(config: unknown, slug: string): CollectionLike | null {
+  const collections = (config as { collections?: unknown } | null | undefined)?.collections
+  if (!collections) return null
+  if (Array.isArray(collections)) {
+    return (collections as CollectionLike[]).find((c) => c?.slug === slug) ?? null
+  }
+  if (typeof collections === 'object') {
+    return (collections as Record<string, CollectionLike>)[slug] ?? null
+  }
+  return null
+}
+
+/** Field definitions may be a record (keyed by name) or an array of `{ name }`. */
+export function declaredFieldNames(fields: unknown): Set<string> | null {
+  if (!fields) return null
+  if (Array.isArray(fields)) {
+    return new Set(
+      (fields as Array<{ name?: string }>)
+        .map((f) => f?.name)
+        .filter((n): n is string => typeof n === 'string'),
+    )
+  }
+  if (typeof fields === 'object') return new Set(Object.keys(fields as Record<string, unknown>))
+  return null
+}
+
+/**
+ * Returns the `required` field keys absent from the collection's declared
+ * fields, or `[]` when the collection / its fields can't be inspected.
+ */
+export function missingCollectionFields(
+  config: unknown,
+  slug: string,
+  required: readonly string[],
+): string[] {
+  const collection = findCollection(config, slug)
+  if (!collection) return []
+  const declared = declaredFieldNames(collection.fields)
+  if (declared === null) return []
+  return required.filter((k) => !declared.has(k))
+}

package/src/lib/comment-anchor.ts

@@ -0,0 +1,179 @@
+/**
+ * Comment anchor helpers — convert between Yjs **relative positions** and
+ * the Base64 wire format the comments REST API speaks.
+ *
+ * Why relative positions: storing absolute offsets (e.g. char 42–58) is
+ * fatal under concurrent editing because someone inserting text before
+ * char 42 silently shifts the meaning of every saved anchor. Yjs ships
+ * `createRelativePositionFromTypeIndex` /
+ * `createAbsolutePositionFromRelativePosition` for exactly this case —
+ * they identify a slot in the CRDT graph that survives concurrent edits.
+ *
+ * The wire shape is `{ from: string; to: string }` where each end is the
+ * Base64 of `Y.encodeRelativePosition(rel)`. The slice 4 server treats
+ * the field as opaque; this module is the only place in the workspace
+ * that interprets it.
+ *
+ * ## Choosing the right Yjs type to anchor against
+ *
+ * `createRelativePositionFromTypeIndex(type, index)` interprets `index`
+ * differently depending on the type:
+ *
+ * - `Y.XmlText` / `Y.Text` — index is the character offset within the
+ *   text. **This is what comment anchors use** because character offsets
+ *   are the natural unit for a text selection.
+ * - `Y.XmlFragment` / `Y.XmlElement` — index counts *children*. Useful
+ *   for "before/after this child" anchors but not what we want here.
+ *
+ * Slice 5's TipTap binding maps a PM selection to the underlying
+ * `Y.XmlText` instance + character offset before calling `encodeAnchor`,
+ * and inverts that mapping after `decodeAnchor` returns. The y-prosemirror
+ * plugin keeps a `mapping` for this conversion; consumers that aren't
+ * using y-prosemirror can talk to the Y types directly.
+ */
+
+import * as Y from 'yjs'
+
+import type { CommentAnchor } from './comments-client.js'
+
+export interface CreateAnchorInput {
+  /** Live Yjs document the editor is bound to. */
+  doc: Y.Doc
+  /**
+   * Yjs text type the selection lives in. Almost always a `Y.XmlText`
+   * for TipTap; we keep the bound a little loose so plain `Y.Text` works
+   * for non-rich-text editors.
+   */
+  yType: Y.XmlText | Y.Text
+  /** Character offset (inclusive) of the selection start within `yType`. */
+  from: number
+  /** Character offset (exclusive) of the selection end within `yType`. */
+  to: number
+}
+
+/**
+ * Build a comment anchor from an editor selection. Returns `null` when
+ * the range is empty or inverted — the caller should not save anchors
+ * that would resolve to nothing.
+ */
+export function encodeAnchor(input: CreateAnchorInput): CommentAnchor | null {
+  if (input.from >= input.to) return null
+  if (input.from < 0) return null
+  // `createRelativePositionFromTypeIndex` clamps `index` to `[0, type.length]`
+  // internally, but we surface an explicit failure when the *intent* is
+  // out of bounds so the caller can flag a stale selection.
+  if (input.to > input.yType.length) return null
+
+  const relFrom = Y.createRelativePositionFromTypeIndex(input.yType, input.from)
+  const relTo = Y.createRelativePositionFromTypeIndex(input.yType, input.to)
+
+  return {
+    from: encodeBase64(Y.encodeRelativePosition(relFrom)),
+    to: encodeBase64(Y.encodeRelativePosition(relTo)),
+  }
+}
+
+export interface ResolveAnchorInput {
+  doc: Y.Doc
+  anchor: CommentAnchor
+}
+
+export interface ResolvedAnchor {
+  /**
+   * The text type the relative position landed on. Comparing identity
+   * (`resolved.yType === editorBoundText`) lets the caller decide
+   * whether a comment is still attached to the expected text node.
+   */
+  yType: Y.AbstractType<unknown>
+  /** Character offset of the saved selection start, after concurrent edits. */
+  from: number
+  /** Character offset of the saved selection end. */
+  to: number
+}
+
+/**
+ * Resolve a stored anchor back to live editor positions. Returns `null`
+ * when:
+ *
+ * - the anchor bytes are not valid base64 / not a Yjs relative position,
+ * - the relative position cannot be mapped (the anchored content was
+ *   deleted entirely), or
+ * - the two ends collapse to the same offset (text between them was
+ *   deleted, effectively detaching the comment).
+ *
+ * Slice 5 surfaces detached comments in the side panel with a small
+ * "anchor lost" badge so editors can still resolve / discuss them.
+ */
+export function decodeAnchor(input: ResolveAnchorInput): ResolvedAnchor | null {
+  let relFromBytes: Uint8Array
+  let relToBytes: Uint8Array
+  try {
+    relFromBytes = decodeBase64(input.anchor.from)
+    relToBytes = decodeBase64(input.anchor.to)
+  } catch {
+    return null
+  }
+
+  let relFrom: Y.RelativePosition
+  let relTo: Y.RelativePosition
+  try {
+    relFrom = Y.decodeRelativePosition(relFromBytes)
+    relTo = Y.decodeRelativePosition(relToBytes)
+  } catch {
+    return null
+  }
+
+  const absFrom = Y.createAbsolutePositionFromRelativePosition(relFrom, input.doc)
+  const absTo = Y.createAbsolutePositionFromRelativePosition(relTo, input.doc)
+  if (absFrom === null || absTo === null) return null
+
+  // Both ends must land on the same text node — otherwise the user's
+  // original selection has been split across nodes and we cannot paint
+  // a clean highlight without further work in slice 5.
+  if (absFrom.type !== absTo.type) return null
+
+  if (absFrom.index >= absTo.index) return null
+
+  return {
+    yType: absFrom.type,
+    from: absFrom.index,
+    to: absTo.index,
+  }
+}
+
+/**
+ * Base64 encode without depending on Node's `Buffer` (the admin bundle
+ * is browser-first). We hand-roll the encode because both `btoa` and
+ * `Buffer` have ergonomic mis-fits for `Uint8Array` payloads.
+ */
+function encodeBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = ''
+    for (let i = 0; i < bytes.byteLength; i++) {
+      binary += String.fromCharCode(bytes[i]!)
+    }
+    return btoa(binary)
+  }
+  const BufferCtor = (
+    globalThis as {
+      Buffer?: { from(arr: Uint8Array): { toString(enc: string): string } }
+    }
+  ).Buffer
+  if (BufferCtor) return BufferCtor.from(bytes).toString('base64')
+  throw new Error('No base64 encoder available')
+}
+
+function decodeBase64(s: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(s)
+    const out = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i++) {
+      out[i] = binary.charCodeAt(i)
+    }
+    return out
+  }
+  const BufferCtor = (globalThis as { Buffer?: { from(s: string, enc: string): Uint8Array } })
+    .Buffer
+  if (BufferCtor) return new Uint8Array(BufferCtor.from(s, 'base64'))
+  throw new Error('No base64 decoder available')
+}