@actuate-media/cms-admin 0.12.0 → 0.13.0

package/src/components/PresenceChips.tsx

@@ -0,0 +1,150 @@
+'use client'
+
+import React, { useEffect, useState } from 'react'
+import { Awareness } from 'y-protocols/awareness'
+
+import {
+  summarisePresence,
+  type CollaborationStatus,
+  type PresenceSnapshot,
+} from '../lib/collaboration-provider.js'
+
+export interface PresenceChipsProps {
+  /** Awareness instance returned from `createCollaborationProvider`. */
+  awareness: Awareness
+  /**
+   * Optional connection status. When provided the strip renders a small
+   * status pill (Connected / Connecting / Disconnected) on the left side.
+   */
+  status?: CollaborationStatus
+  /**
+   * Hide the local user from the strip. Defaults to `true` — the local user
+   * already knows they're editing.
+   */
+  hideSelf?: boolean
+  /** Max chips to show before collapsing to "+N". Defaults to 5. */
+  maxVisible?: number
+  className?: string
+}
+
+/**
+ * Small avatar / initials strip showing who else is currently editing the
+ * document. Subscribes to the supplied `Awareness` instance for live
+ * updates.
+ *
+ * The component is intentionally stateless about transport — it only reads
+ * from Awareness and `status`. Wiring is the caller's job.
+ */
+export function PresenceChips({
+  awareness,
+  status,
+  hideSelf = true,
+  maxVisible = 5,
+  className,
+}: PresenceChipsProps) {
+  const [snapshot, setSnapshot] = useState<PresenceSnapshot>(() => summarisePresence(awareness))
+
+  useEffect(() => {
+    const update = () => {
+      setSnapshot(summarisePresence(awareness))
+    }
+    update()
+    awareness.on('update', update)
+    awareness.on('change', update)
+    return () => {
+      awareness.off('update', update)
+      awareness.off('change', update)
+    }
+  }, [awareness])
+
+  const visible = hideSelf
+    ? snapshot.users.filter((u) => u.clientId !== snapshot.selfClientId)
+    : snapshot.users
+  const overflow = Math.max(0, visible.length - maxVisible)
+  const shown = visible.slice(0, maxVisible)
+
+  return (
+    <div
+      className={`inline-flex items-center gap-1.5 text-xs ${className ?? ''}`}
+      data-testid="presence-chips"
+    >
+      {status && <StatusPill status={status} />}
+      {shown.length === 0 && status !== 'connecting' && (
+        <span className="text-gray-500" data-testid="presence-empty">
+          You're the only one here
+        </span>
+      )}
+      {shown.map(({ clientId, user }) => (
+        <Chip key={clientId} name={user.name} color={user.color} avatarUrl={user.avatarUrl} />
+      ))}
+      {overflow > 0 && (
+        <span
+          className="rounded-full bg-gray-100 px-2 py-0.5 text-gray-700"
+          data-testid="presence-overflow"
+        >
+          +{overflow}
+        </span>
+      )}
+    </div>
+  )
+}
+
+function StatusPill({ status }: { status: CollaborationStatus }) {
+  const palette: Record<CollaborationStatus, { dot: string; label: string; text: string }> = {
+    connected: { dot: 'bg-emerald-500', label: 'Live', text: 'text-emerald-700' },
+    connecting: { dot: 'bg-amber-400 animate-pulse', label: 'Connecting', text: 'text-amber-700' },
+    disconnected: { dot: 'bg-gray-300', label: 'Offline', text: 'text-gray-500' },
+  }
+  const cfg = palette[status]
+  return (
+    <span
+      className={`inline-flex items-center gap-1 rounded-full bg-gray-50 px-2 py-0.5 ${cfg.text}`}
+      data-testid={`presence-status-${status}`}
+    >
+      <span className={`h-1.5 w-1.5 rounded-full ${cfg.dot}`} />
+      {cfg.label}
+    </span>
+  )
+}
+
+function Chip({ name, color, avatarUrl }: { name: string; color: string; avatarUrl?: string }) {
+  const initials = nameToInitials(name)
+  return (
+    <span
+      className="inline-flex items-center gap-1 rounded-full bg-white px-1.5 py-0.5 ring-1 ring-gray-200"
+      title={name}
+      data-testid="presence-chip"
+    >
+      {avatarUrl ? (
+        <img
+          src={avatarUrl}
+          alt=""
+          className="h-4 w-4 rounded-full object-cover"
+          style={{ boxShadow: `0 0 0 1.5px ${color}` }}
+        />
+      ) : (
+        <span
+          aria-hidden="true"
+          className="flex h-4 w-4 items-center justify-center rounded-full text-[8px] font-semibold text-white"
+          style={{ backgroundColor: color }}
+        >
+          {initials}
+        </span>
+      )}
+      <span className="max-w-[80px] truncate text-gray-700">{name}</span>
+    </span>
+  )
+}
+
+/** Convert "Alice Cooper" → "AC", single names → "A", empty → "?". */
+export function nameToInitials(name: string): string {
+  const cleaned = name.trim()
+  if (!cleaned) return '?'
+  const parts = cleaned.split(/\s+/).slice(0, 2)
+  return (
+    parts
+      .map((p) => (p[0] ?? '').toUpperCase())
+      .filter(Boolean)
+      .join('') || '?'
+  )
+}

package/src/components/TipTapEditor.tsx

@@ -1,8 +1,24 @@
 'use client'
 
-import React, { useState } from 'react'
+import React, { useEffect, useMemo, useRef, useState } from 'react'
 import { useEditor, EditorContent, type Editor } from '@tiptap/react'
 import { MediaPickerModal } from './MediaPickerModal.js'
+import { AICoauthorBubbleMenu } from './AICoauthorBubbleMenu.js'
+import { PresenceChips } from './PresenceChips.js'
+import { OfflineStatus } from './OfflineStatus.js'
+import { CommentMark, COMMENT_MARK_STYLES } from './CommentMark.js'
+import { CommentSidePanel } from './CommentSidePanel.js'
+import { clearActiveEditorIf, setActiveEditor } from '../lib/active-editor.js'
+import {
+  createCollaborationProvider,
+  type CollaborationContext,
+  type CollaborationStatus,
+  type CollaborationUser,
+  type OfflinePersistenceStatus,
+} from '../lib/collaboration-provider.js'
+import { encodeAnchor } from '../lib/comment-anchor.js'
+import type { CommentAnchor } from '../lib/comments-client.js'
+import * as Y from 'yjs'
 import StarterKit from '@tiptap/starter-kit'
 import UnderlineExt from '@tiptap/extension-underline'
 import Link from '@tiptap/extension-link'
@@ -15,6 +31,8 @@ import TextAlign from '@tiptap/extension-text-align'
 import Placeholder from '@tiptap/extension-placeholder'
 import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight'
 import HorizontalRule from '@tiptap/extension-horizontal-rule'
+import Collaboration from '@tiptap/extension-collaboration'
+import CollaborationCursor from '@tiptap/extension-collaboration-cursor'
 import { common, createLowlight } from 'lowlight'
 import {
   Bold,
@@ -45,12 +63,73 @@ import {
 
 const lowlight = createLowlight(common)
 
+/**
+ * Configuration for real-time collaboration on this editor.
+ *
+ * When supplied the editor switches into CRDT mode: history is delegated to
+ * Yjs, edits sync through the cms-core realtime gateway, and a presence
+ * strip with live cursors appears beside the toolbar. The `content` prop is
+ * ignored in collaboration mode (the gateway is the source of truth);
+ * `onChange` still fires on every local update so existing autosave wiring
+ * keeps working.
+ */
+export interface TipTapCollaborationConfig {
+  documentId: string
+  /**
+   * Base URL of the realtime gateway. `wss://your.app/api/cms/realtime/sync`
+   * in production, `ws://localhost:3000/api/cms/realtime/sync` for dev.
+   */
+  url: string
+  user: CollaborationUser
+  /** Extra query params (e.g. auth token for cross-origin deployments). */
+  params?: Record<string, string>
+}
+
 export interface TipTapEditorProps {
   content: string
   onChange: (html: string) => void
   placeholder?: string
   editable?: boolean
   className?: string
+  /**
+   * Toggle the AI co-author bubble menu on text selection.
+   * Defaults to `true` when the editor is editable. Set to `false` to opt
+   * out (e.g. for preview-only renders, or environments where the
+   * `/ai/coauthor` endpoint is intentionally disabled).
+   */
+  enableAI?: boolean
+  /**
+   * Enable real-time collaboration via the cms-core realtime gateway. When
+   * set, the editor swaps in Yjs-backed history + the collaboration cursor
+   * extension and renders a presence strip above the toolbar.
+   */
+  collaboration?: TipTapCollaborationConfig
+  /**
+   * Enable inline comments. When set, the `CommentMark` extension is
+   * loaded and a `CommentSidePanel` renders next to the editor. Anchors
+   * are encoded against the active Yjs text node when collaboration is
+   * also on, so highlights survive concurrent edits.
+   *
+   * Comments are independent of the collaboration prop — you can attach
+   * comments to a static document, but cross-user "live" highlighting
+   * only kicks in when collaboration is also enabled.
+   */
+  comments?: TipTapCommentsConfig
+}
+
+/**
+ * Configuration for the comments side panel. The panel issues REST calls
+ * against the slice-4 endpoints; this prop is just the small set of
+ * presentation + identity bits the panel can't infer from the editor.
+ */
+export interface TipTapCommentsConfig {
+  documentId: string
+  /** Logged-in user id — gates edit + delete affordances. */
+  currentUserId: string
+  /** Set to true to expose moderation actions on every comment. */
+  isAdmin?: boolean
+  /** Error sink so the host shell can show a toast. */
+  onError?: (message: string) => void
 }
 
 const editorStyles = `
@@ -401,14 +480,66 @@ export function TipTapEditor({
   placeholder,
   editable = true,
   className,
+  enableAI = true,
+  collaboration,
+  comments,
 }: TipTapEditorProps) {
   const [mediaPickerOpen, setMediaPickerOpen] = useState(false)
+  // The collaboration context is created once per (documentId, url) tuple
+  // and torn down on prop changes / unmount. We deliberately key on a
+  // stringified tuple so swapping users keeps the same Y.Doc (their seat at
+  // the document doesn't drop) while swapping documents creates a new one.
+  const collabKey = collaboration ? `${collaboration.documentId}::${collaboration.url}` : null
+  const collabRef = useRef<CollaborationContext | null>(null)
+  const [collabStatus, setCollabStatus] = useState<CollaborationStatus>('connecting')
+  const [offlineStatus, setOfflineStatus] = useState<OfflinePersistenceStatus>('pending')
+  useEffect(() => {
+    if (!collaboration) {
+      collabRef.current = null
+      return
+    }
+    const ctx = createCollaborationProvider({
+      documentId: collaboration.documentId,
+      url: collaboration.url,
+      user: collaboration.user,
+      params: collaboration.params,
+      onStatus: setCollabStatus,
+      onOfflineStatus: setOfflineStatus,
+    })
+    collabRef.current = ctx
+    return () => {
+      ctx.destroy()
+      if (collabRef.current === ctx) collabRef.current = null
+    }
+    // We rely on collabKey to scope effect identity. user / params are
+    // tolerated to mutate freely; the Yjs awareness state is updated
+    // separately in the awareness-seeding effect below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collabKey])
+
+  // Keep the local awareness state in sync with user info changes without
+  // tearing down the collaboration session.
+  useEffect(() => {
+    if (!collaboration || !collabRef.current) return
+    collabRef.current.awareness.setLocalState({ user: collaboration.user })
+  }, [
+    collaboration?.user.name,
+    collaboration?.user.color,
+    collaboration?.user.avatarUrl,
+    collaboration?.user.userId,
+    collaboration,
+  ])
 
-  const editor = useEditor({
-    extensions: [
+  const extensions = useMemo(() => {
+    // The TipTap extension union is hostile to mutation (the inferred
+    // element type is too narrow). We collect into `unknown[]` and let
+    // `useEditor`'s prop typing carry the contract from the call site.
+    const base: unknown[] = [
       StarterKit.configure({
         codeBlock: false,
         horizontalRule: false,
+        // History is owned by Yjs when collaboration is enabled.
+        history: collaboration ? false : undefined,
       }),
       UnderlineExt,
       Link.configure({
@@ -429,13 +560,54 @@ export function TipTapEditor({
       }),
       CodeBlockLowlight.configure({ lowlight }),
       HorizontalRule,
-    ],
-    content,
-    editable: editable !== false,
-    onUpdate: ({ editor: ed }) => {
-      onChange(ed.getHTML())
+    ]
+    if (collaboration && collabRef.current) {
+      base.push(
+        Collaboration.configure({ document: collabRef.current.ydoc }),
+        CollaborationCursor.configure({
+          provider: collabRef.current.provider,
+          user: collaboration.user,
+        }),
+      )
+    }
+    if (comments) {
+      base.push(CommentMark)
+    }
+    return base
+    // Re-derive extensions when the collaboration session or comments
+    // toggle changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collabKey, placeholder, comments != null])
+
+  const editor = useEditor(
+    {
+      // TipTap's `Extensions` type is the union of every loaded extension's
+      // typed shape, which we can't satisfy when we conditionally append
+      // collaboration extensions. The runtime contract is correct — TipTap
+      // duck-types — so we cast through the narrow `any` slot.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      extensions: extensions as any[],
+      // When collaboration is enabled the Y.Doc is the source of truth; we
+      // pass `content: ''` to avoid double-applying the initial HTML.
+      content: collaboration ? '' : content,
+      editable: editable !== false,
+      onUpdate: ({ editor: ed }) => {
+        onChange(ed.getHTML())
+      },
+      onFocus: ({ editor: ed }) => {
+        setActiveEditor(ed)
+      },
     },
-  })
+    // Force re-init when collaboration extensions change.
+    [collabKey],
+  )
+
+  useEffect(() => {
+    if (!editor) return
+    return () => {
+      clearActiveEditorIf(editor)
+    }
+  }, [editor])
 
   if (!editor) return null
 
@@ -447,13 +619,55 @@ export function TipTapEditor({
       .run()
   }
 
-  return (
+  const awareness = collabRef.current?.awareness ?? null
+
+  /**
+   * Encode an anchor for the current selection. Returns `null` when the
+   * selection is empty (the panel falls back to a doc-level comment),
+   * or when collaboration isn't enabled (we have no Yjs text node to
+   * anchor against — slice 5's anchors are CRDT-relative by design).
+   */
+  const composeAnchor = (): CommentAnchor | null => {
+    if (!collabRef.current) return null
+    const sel = editor.state.selection
+    if (sel.empty) return null
+    // The Y.Doc shape that TipTap collaboration uses is
+    //   doc.getXmlFragment('default') → [paragraph, …] → [text, …]
+    // We anchor against the first XmlText child of the paragraph that
+    // contains the selection start. This is the simple-but-correct
+    // single-node case; multi-paragraph selections fall back to a
+    // doc-level comment (anchor: null) and the user can re-anchor
+    // later.
+    const fragment = collabRef.current.ydoc.getXmlFragment('default')
+    const yType = findTextNodeForPosition(fragment, sel.from)
+    if (!yType) return null
+    // The relative offset within the text node mirrors the PM offset
+    // minus the paragraph's opening token. For the canonical single-
+    // text-child case this is `sel.from - paragraphStart - 1`.
+    const offset = computeTextOffset(fragment, sel.from)
+    if (offset === null) return null
+    return encodeAnchor({
+      doc: collabRef.current.ydoc,
+      yType,
+      from: offset,
+      to: offset + (sel.to - sel.from),
+    })
+  }
+
+  const editorPane = (
     <div
-      className={`overflow-hidden rounded-lg border border-gray-200 bg-white ${className ?? ''}`}
+      className={`flex-1 overflow-hidden rounded-lg border border-gray-200 bg-white ${className ?? ''}`}
     >
+      {collaboration && awareness && (
+        <div className="flex items-center justify-between gap-2 border-b border-gray-100 bg-white px-2 py-1.5">
+          <PresenceChips awareness={awareness} status={collabStatus} />
+          <OfflineStatus connection={collabStatus} offline={offlineStatus} />
+        </div>
+      )}
       {editable && <Toolbar editor={editor} onOpenMediaPicker={() => setMediaPickerOpen(true)} />}
+      {editable && enableAI && <AICoauthorBubbleMenu editor={editor} />}
       <EditorContent editor={editor} />
-      <style dangerouslySetInnerHTML={{ __html: editorStyles }} />
+      <style dangerouslySetInnerHTML={{ __html: editorStyles + COMMENT_MARK_STYLES }} />
       <MediaPickerModal
         open={mediaPickerOpen}
         onClose={() => setMediaPickerOpen(false)}
@@ -462,4 +676,88 @@ export function TipTapEditor({
       />
     </div>
   )
+
+  if (!comments) return editorPane
+
+  return (
+    <div className="flex h-full gap-3">
+      {editorPane}
+      <div className="w-80 shrink-0">
+        <CommentSidePanel
+          documentId={comments.documentId}
+          currentUserId={comments.currentUserId}
+          isAdmin={comments.isAdmin}
+          onComposeAnchor={composeAnchor}
+          onError={comments.onError}
+          onActiveCommentChange={(id) => {
+            // When a thread is opened in the panel, paint the matching
+            // CommentMark with the active modifier so it stands out in
+            // the doc. We do this by toggling a class on the rendered
+            // span — purely visual; no doc mutation.
+            if (typeof document === 'undefined') return
+            document
+              .querySelectorAll('span.actuate-comment--active')
+              .forEach((el) => el.classList.remove('actuate-comment--active'))
+            if (id) {
+              document
+                .querySelectorAll(`span[data-comment-id="${cssEscape(id)}"]`)
+                .forEach((el) => el.classList.add('actuate-comment--active'))
+            }
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Walk the XmlFragment's children until we reach the paragraph
+ * containing the given ProseMirror position. Return its first XmlText
+ * child, or null when the structure is anything other than the canonical
+ * `paragraph → [text]` shape we anchor against.
+ *
+ * This is the *simple-case* mapping — slice 5 anchors to a single text
+ * node per comment. Selections that span multiple paragraphs fall back
+ * to a document-level comment (anchor: null) and the user can re-anchor
+ * later from the side panel. y-prosemirror has a richer mapping we may
+ * pull in once slice 5 ships.
+ */
+function findTextNodeForPosition(fragment: Y.XmlFragment, pmPos: number): Y.XmlText | null {
+  let walked = 0
+  for (const child of fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement)) continue
+    const textChild = child.firstChild
+    const textLen = textChild instanceof Y.XmlText ? textChild.length : 0
+    // Each paragraph contributes `1 + textLen + 1` PM positions
+    // (open token, contents, close token).
+    const blockSpan = 2 + textLen
+    if (pmPos <= walked + blockSpan) {
+      return textChild instanceof Y.XmlText ? textChild : null
+    }
+    walked += blockSpan
+  }
+  return null
+}
+
+function computeTextOffset(fragment: Y.XmlFragment, pmPos: number): number | null {
+  let walked = 0
+  for (const child of fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement)) continue
+    const textChild = child.firstChild
+    const textLen = textChild instanceof Y.XmlText ? textChild.length : 0
+    const blockSpan = 2 + textLen
+    if (pmPos <= walked + blockSpan) {
+      // PM positions skip the paragraph's open token (1 char).
+      const inside = pmPos - walked - 1
+      if (inside < 0 || inside > textLen) return null
+      return inside
+    }
+    walked += blockSpan
+  }
+  return null
+}
+
+/** Cheap CSS attr-value escaper for `data-comment-id` lookups. */
+function cssEscape(value: string): string {
+  return value.replace(/(["\\])/g, '\\$1')
 }

package/src/index.ts

@@ -97,6 +97,26 @@ export type { MediaPickerModalProps } from './components/MediaPickerModal.js'
 export { ThemeProvider, useTheme } from './components/ThemeProvider.js'
 export { FocalPointPicker } from './components/FocalPointPicker.js'
 export { PresenceIndicator } from './components/PresenceIndicator.js'
+export { NotificationBell } from './components/NotificationBell.js'
+export type { NotificationBellProps, NotificationsApi } from './components/NotificationBell.js'
+export {
+  listNotifications,
+  unreadCount as listNotificationsUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  notificationSummary,
+} from './lib/notifications-client.js'
+export type {
+  Notification,
+  NotificationKind,
+  NotificationPayload,
+  NotificationOutcome,
+  ListNotificationsOptions,
+} from './lib/notifications-client.js'
+export { OfflineStatus, describeOfflineStatus } from './components/OfflineStatus.js'
+export type { OfflineStatusProps } from './components/OfflineStatus.js'
+export { CommentSidePanel } from './components/CommentSidePanel.js'
+export type { CommentSidePanelProps } from './components/CommentSidePanel.js'
 export { LocaleProvider, useLocale } from './components/LocaleProvider.js'
 export type { LocaleProviderProps } from './components/LocaleProvider.js'
 export { LocaleSwitcher } from './components/LocaleSwitcher.js'

package/src/lib/active-editor.ts

@@ -0,0 +1,39 @@
+import type { Editor } from '@tiptap/react'
+
+/**
+ * Singleton registry for the most-recently focused TipTap editor in the
+ * admin shell. Lets out-of-tree surfaces (Cmd+K palette, slash commands,
+ * future global shortcuts) target the editor a user was last working in
+ * without prop-drilling refs through the layout.
+ *
+ * The `TipTapEditor` component calls `setActiveEditor(editor)` from its
+ * `onFocus` callback and clears it on unmount. Subscribers receive a no-op
+ * payload — they should re-read via `getActiveEditor()` after the
+ * notification.
+ */
+
+let activeEditor: Editor | null = null
+const listeners = new Set<() => void>()
+
+export function setActiveEditor(editor: Editor | null): void {
+  if (activeEditor === editor) return
+  activeEditor = editor
+  for (const listener of listeners) listener()
+}
+
+export function getActiveEditor(): Editor | null {
+  return activeEditor
+}
+
+export function clearActiveEditorIf(editor: Editor): void {
+  if (activeEditor === editor) {
+    setActiveEditor(null)
+  }
+}
+
+export function subscribeActiveEditor(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}

package/src/lib/api.ts

@@ -6,6 +6,17 @@ export function setApiBase(path: string) {
   basePath = path
 }
 
+/**
+ * Current API base path. Exposed so non-`fetch` consumers (in
+ * particular `EventSource` for SSE channels) can resolve URLs against
+ * the same prefix configured via `setApiBase()`. Keep this read-only
+ * — mutation must always flow through `setApiBase()` so we never have
+ * two callers with diverging views of the base.
+ */
+export function getApiBase(): string {
+  return basePath
+}
+
 function getCsrfToken(): string {
   if (typeof document === 'undefined') return ''
   const match = document.cookie.match(/(?:^|;\s*)actuate_csrf=([^;]*)/)