@actuate-media/cms-admin 0.11.0 → 0.12.1

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/fields/ComponentBlockField.tsx

@@ -0,0 +1,179 @@
+'use client'
+
+/**
+ * Top-level admin field for component-aware blocks. Consumes a
+ * {@link Manifest} produced by `@actuate-media/component-blocks`,
+ * renders a component picker (when more than one component is allowed)
+ * and a recursive props form via {@link PropInput}.
+ *
+ * Storage shape:
+ *   { component: 'Hero', props: { title: 'Welcome', alignment: 'center' } }
+ *
+ * Live validation runs through `validateComponentBlockValue` from
+ * `@actuate-media/cms-core`. The whole-value error is shown at the top
+ * of the form, and the per-prop error map (parsed out of the message
+ * string) is forwarded into `PropInput` so each input can render its
+ * own inline error.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import type { Manifest } from '@actuate-media/component-blocks'
+
+import {
+  buildClientValidator,
+  getAllowedComponents,
+  parsePerPropErrors,
+  seedPropsForComponent,
+} from './component-block-helpers.js'
+import { PropInput } from './PropInput.js'
+
+export interface ComponentBlockValue {
+  component: string
+  props: Record<string, unknown>
+}
+
+export interface ComponentBlockFieldProps {
+  label?: string
+  manifest: Manifest
+  /** Optional whitelist of component names. */
+  allow?: string[]
+  /** Default component picked when the field is first used. */
+  defaultComponent?: string
+  value?: ComponentBlockValue
+  onChange: (value: ComponentBlockValue) => void
+  /**
+   * Optional async validator hook. Receives the proposed value and the
+   * field config; should return `true` for ok or a string error.
+   * Falls back to a built-in structural validator when not provided —
+   * which is what cms-core would do server-side at save time anyway.
+   */
+  validate?: (value: ComponentBlockValue) => string | true
+  helpText?: string
+}
+
+export function ComponentBlockField({
+  label,
+  manifest,
+  allow,
+  defaultComponent,
+  value,
+  onChange,
+  validate,
+  helpText,
+}: ComponentBlockFieldProps) {
+  const allowedComponents = useMemo(() => getAllowedComponents(manifest, allow), [manifest, allow])
+  // Track the initial seed application so we don't repeatedly stomp
+  // the editor's prop values on every render. The defaultComponent
+  // seed only fires once, when value is undefined on mount.
+  const seededRef = useRef(false)
+
+  useEffect(() => {
+    if (seededRef.current) return
+    if (value) {
+      seededRef.current = true
+      return
+    }
+    const picked =
+      allowedComponents.find((c) => c.name === defaultComponent) ?? allowedComponents[0]
+    if (!picked) return
+    seededRef.current = true
+    onChange({ component: picked.name, props: seedPropsForComponent(picked) })
+  }, [allowedComponents, defaultComponent, value, onChange])
+
+  const currentSpec =
+    (value && manifest.components.find((c) => c.name === value.component)) ?? allowedComponents[0]
+
+  // Pure structural validation when caller didn't provide their own.
+  // Keeps the form usable even without a live validator wired in.
+  const builtinValidate = useMemo(() => buildClientValidator(manifest, allow), [manifest, allow])
+  const validator = validate ?? builtinValidate
+
+  const [errorMessage, setErrorMessage] = useState<string | null>(null)
+  const perPropErrors = useMemo(() => parsePerPropErrors(errorMessage), [errorMessage])
+
+  useEffect(() => {
+    if (!value) {
+      setErrorMessage(null)
+      return
+    }
+    const result = validator(value)
+    setErrorMessage(result === true ? null : result)
+  }, [value, validator])
+
+  function handleComponentChange(componentName: string) {
+    const spec = manifest.components.find((c) => c.name === componentName)
+    if (!spec) return
+    onChange({ component: spec.name, props: seedPropsForComponent(spec) })
+  }
+
+  function handlePropChange(propName: string, next: unknown) {
+    if (!value) return
+    onChange({
+      ...value,
+      props: { ...value.props, [propName]: next },
+    })
+  }
+
+  if (!currentSpec) {
+    return (
+      <div className="rounded-md border border-[var(--destructive)] bg-red-50 p-3 text-sm text-[var(--destructive)]">
+        Component block has no components to choose from.
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-3">
+      {label ? <label className="block text-sm font-medium">{label}</label> : null}
+
+      {allowedComponents.length > 1 ? (
+        <label className="block text-sm">
+          <div className="mb-1 text-xs tracking-wide text-[var(--muted-foreground)] uppercase">
+            Component
+          </div>
+          <select
+            value={currentSpec.name}
+            onChange={(e) => handleComponentChange(e.target.value)}
+            className="w-full rounded-md border border-[var(--border)] bg-[var(--input-background)] px-3 py-2 text-sm outline-none focus:ring-2 focus:ring-[var(--ring)]"
+          >
+            {allowedComponents.map((spec) => (
+              <option key={spec.name} value={spec.name}>
+                {spec.displayName}
+              </option>
+            ))}
+          </select>
+        </label>
+      ) : null}
+
+      {errorMessage ? (
+        <div className="rounded-md border border-[var(--destructive)] bg-red-50 px-3 py-2 text-xs text-[var(--destructive)]">
+          {errorMessage}
+        </div>
+      ) : null}
+
+      <fieldset className="rounded-md border border-[var(--border)] bg-[var(--card)] p-4">
+        <legend className="px-1 text-xs tracking-wide text-[var(--muted-foreground)] uppercase">
+          {currentSpec.displayName}
+        </legend>
+        {currentSpec.description ? (
+          <p className="mb-3 text-xs text-[var(--muted-foreground)]">{currentSpec.description}</p>
+        ) : null}
+        <div className="space-y-4">
+          {currentSpec.props.map((prop) => (
+            <PropInput
+              key={prop.name}
+              prop={prop}
+              value={value?.props?.[prop.name]}
+              onChange={(next) => handlePropChange(prop.name, next)}
+              errors={perPropErrors}
+              path={prop.name}
+            />
+          ))}
+        </div>
+      </fieldset>
+
+      {helpText ? <p className="text-xs text-[var(--muted-foreground)]">{helpText}</p> : null}
+    </div>
+  )
+}

package/src/fields/FieldRenderer.tsx

@@ -13,6 +13,7 @@ import { BlockBuilderField } from './BlockBuilderField.js'
 import { GroupField } from './GroupField.js'
 import { NavBuilderField } from './NavBuilderField.js'
 import { NumberField } from './NumberField.js'
+import { ComponentBlockField } from './ComponentBlockField.js'
 
 export interface FieldDefinition {
   name: string
@@ -28,6 +29,9 @@ export interface FieldDefinition {
   multi?: boolean
   fields?: FieldDefinition[]
   blocks?: any[]
+  manifest?: unknown
+  allow?: string[]
+  defaultComponent?: string
 }
 
 export interface FieldRendererProps {
@@ -50,6 +54,7 @@ const FIELD_MAP: Record<string, React.ComponentType<any>> = {
   group: GroupField,
   nav: NavBuilderField,
   number: NumberField,
+  componentBlock: ComponentBlockField,
 }
 
 export function FieldRenderer({ field, value, onChange }: FieldRendererProps) {
@@ -79,6 +84,9 @@ export function FieldRenderer({ field, value, onChange }: FieldRendererProps) {
       fields={field.fields}
       blocks={field.blocks}
       name={field.name}
+      manifest={field.manifest}
+      allow={field.allow}
+      defaultComponent={field.defaultComponent}
     />
   )
 }