@actuate-media/cms-admin 0.11.0 → 0.12.1

package/src/fields/component-block-helpers.ts

@@ -0,0 +1,341 @@
+/**
+ * Pure helpers behind `<ComponentBlockField>`. Extracted so vitest can
+ * exercise them in node without spinning up jsdom — the React component
+ * just composes these into UI.
+ *
+ * Kept structurally typed (no peer-dep import of types here would be
+ * cleaner, but the `PropType` discriminated union is the contract we
+ * promise consumers, so we lean on the package's types).
+ */
+
+import {
+  detectDiscriminator,
+  findVariant,
+} from '@actuate-media/component-blocks/discriminated-union'
+import type {
+  DiscriminatedUnion,
+  DiscriminatedVariant,
+} from '@actuate-media/component-blocks/discriminated-union'
+import type { ComponentSpec, Manifest, PropSpec, PropType } from '@actuate-media/component-blocks'
+
+import type { ComponentBlockValue } from './ComponentBlockField.js'
+
+/**
+ * Compute the list of components an editor can pick from given the
+ * manifest + the optional allow-list. Returns the full list when no
+ * filter is provided; returns `[]` when every entry is filtered out
+ * (the caller renders an error in that case).
+ */
+export function getAllowedComponents(
+  manifest: Manifest,
+  allow: string[] | undefined,
+): ComponentSpec[] {
+  if (!allow || allow.length === 0) return manifest.components
+  return manifest.components.filter((c) => allow.includes(c.name))
+}
+
+/**
+ * JSON-encode any value so it round-trips cleanly through the
+ * JsonFallback textarea. Previously the helper short-circuited for
+ * strings (returning the raw string), which made the textarea
+ * stateful: typing `"hello"` parsed to the JS string `hello`,
+ * re-rendered as bare `hello`, then `JSON.parse('hello')` threw on
+ * the next edit and the field "locked" as a raw string. Always
+ * stringifying keeps the textarea visually consistent with the
+ * underlying JSON value.
+ *
+ * Falls back to `String(v)` for values that can't be JSON-encoded
+ * (e.g. circular refs) so the field remains editable.
+ */
+export function safeJsonStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v, null, 2)
+  } catch {
+    return String(v)
+  }
+}
+
+/**
+ * Map an `<select>` change-event value to an enum-prop value.
+ *
+ * The placeholder `<option value="">Select…</option>` clears the field
+ * to `undefined`; any other value is the stringified array index into
+ * `options`. Extracted so we can test the clear semantics without
+ * spinning up jsdom: previously the inline handler used `Number("")`,
+ * which evaluates to `0` and silently picked the first option instead
+ * of clearing.
+ */
+export function parseEnumSelection<T>(raw: string, options: readonly T[]): T | undefined {
+  if (raw === '') return undefined
+  const idx = Number(raw)
+  if (!Number.isInteger(idx) || idx < 0 || idx >= options.length) return undefined
+  return options[idx]
+}
+
+/**
+ * Produce a sensible empty value for a freshly-created array item or
+ * required prop. The admin form generator never wants `undefined` in
+ * an array; that breaks downstream PropInput defaults and confuses
+ * validators.
+ */
+export function defaultForType(type: PropType): unknown {
+  switch (type.kind) {
+    case 'string':
+      return ''
+    case 'number':
+      return 0
+    case 'boolean':
+      return false
+    case 'enum':
+      return type.values[0] ?? ''
+    case 'literal':
+      return type.value
+    case 'array':
+      return []
+    case 'object':
+      return Object.fromEntries(
+        type.fields.filter((f) => f.required).map((f) => [f.name, defaultForType(f.type)]),
+      )
+    case 'union': {
+      // Discriminated unions DO have a sensible structural default:
+      // pick the first variant and seed its required fields (plus the
+      // discriminator). This makes a Hero with a `cta: Link | Modal`
+      // prop render an editable form on first paint instead of forcing
+      // the editor through the JSON textarea fallback.
+      const detected = detectDiscriminator(type)
+      if (detected) {
+        const variant = detected.variants[0]!
+        const out: Record<string, unknown> = { [detected.field]: variant.value }
+        for (const field of variant.remainingFields) {
+          if (field.required) out[field.name] = defaultForType(field.type)
+        }
+        return out
+      }
+      return null
+    }
+    default:
+      // `reference`, `unknown`: there's no single sensible structural
+      // default. We return `null` instead of `undefined` so the value
+      // survives a JSON round-trip — `JSON.stringify` turns
+      // `undefined` array items into `null` anyway, which would
+      // contradict the documented "never undefined in an array"
+      // invariant and surface as the literal string `null` in the
+      // JsonFallback textarea.
+      return null
+  }
+}
+
+/**
+ * Seed an empty props object for a freshly-picked component using each
+ * prop's explicit `defaultValue` when set, else the structural default
+ * from {@link defaultForType} (only for required props — optional
+ * unset props stay absent so they render as empty inputs).
+ */
+export function seedPropsForComponent(spec: ComponentSpec): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const prop of spec.props) {
+    if (prop.defaultValue !== undefined && prop.defaultValue !== null) {
+      out[prop.name] = prop.defaultValue
+      continue
+    }
+    if (prop.required) {
+      const seed = defaultForType(prop.type)
+      // For non-discriminated `union` / `reference` / `unknown` kinds
+      // defaultForType returns `null` (so arrays survive a JSON
+      // round-trip), but seeding a top-level required prop with
+      // `null` would immediately trip the validator's "Missing
+      // required prop" branch on first render — the user would see
+      // a red error before they touched anything. Leave those
+      // required props absent so the absence and the validation
+      // message describe the same state honestly; the user provides
+      // a value via the JsonFallback. Discriminated unions return
+      // a structural default and seed cleanly.
+      if (seed !== null) {
+        out[prop.name] = seed
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Compute the next value for a discriminated-union field when the
+ * editor switches variants. Pure helper so the React component stays
+ * thin and the seeding rules can be unit-tested without rendering.
+ *
+ * Seeding rules:
+ *   1. The discriminator field is always written to the variant's
+ *      tag value.
+ *   2. Optional fields shared by both variants survive the switch
+ *      (preserves "edited the same label" intent across, e.g.,
+ *      Link → Modal where both carry `label`).
+ *   3. Required fields exclusive to the new variant are seeded by
+ *      priority: explicit `field.defaultValue` first (matches
+ *      `seedPropsForComponent`), else the structural default from
+ *      `defaultForType` — but only when that default is non-null.
+ *      A `null` from `defaultForType` (reference / unknown / non-
+ *      discriminated union types) is treated as "no sensible default"
+ *      and the field is left absent so the validator's
+ *      "missing required prop" message and the data agree.
+ *   4. Fields exclusive to the previous variant are dropped so the
+ *      value stays structurally valid against the chosen variant.
+ */
+export function switchUnionVariant(
+  current: unknown,
+  union: DiscriminatedUnion,
+  variant: DiscriminatedVariant,
+): Record<string, unknown> {
+  const obj = isPlainObject(current) ? current : {}
+  const next: Record<string, unknown> = { [union.field]: variant.value }
+  const carryable = new Set(variant.remainingFields.map((f) => f.name))
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === union.field) continue
+    if (carryable.has(k)) next[k] = v
+  }
+  for (const field of variant.remainingFields) {
+    if (!field.required || next[field.name] !== undefined) continue
+    if (field.defaultValue !== undefined && field.defaultValue !== null) {
+      next[field.name] = field.defaultValue
+      continue
+    }
+    const seed = defaultForType(field.type)
+    if (seed !== null) {
+      next[field.name] = seed
+    }
+  }
+  return next
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Build a minimal structural validator that mirrors the rules the
+ * cms-core `validateComponentBlockValue` runs server-side, so the form
+ * can show feedback without a round-trip. Kept in sync with cms-core
+ * by inspection; the canonical implementation lives there.
+ */
+export function buildClientValidator(
+  manifest: Manifest,
+  allow: string[] | undefined,
+): (value: ComponentBlockValue) => string | true {
+  // An empty `allow` array is treated the same way `getAllowedComponents`
+  // treats it: as "no filter". Without this, the picker shows every
+  // component while the validator rejects every selection, leading to
+  // a UI/validator deadlock.
+  const allowed = allow && allow.length > 0 ? new Set(allow) : null
+  return (value) => {
+    const spec = manifest.components.find((c) => c.name === value.component)
+    if (!spec) {
+      const known = manifest.components.map((c) => c.name).join(', ') || '<none>'
+      return `Unknown component '${value.component}'. Manifest knows: ${known}.`
+    }
+    if (allowed && !allowed.has(value.component)) {
+      return `Component '${value.component}' is not in the allow-list for this field.`
+    }
+    for (const propSpec of spec.props) {
+      const v = value.props[propSpec.name]
+      if (v === undefined || v === null) {
+        if (propSpec.required) {
+          return `Missing required prop '${propSpec.name}' for component '${value.component}'.`
+        }
+        continue
+      }
+      const err = clientShapeError(v, propSpec)
+      if (err) return err
+    }
+    return true
+  }
+}
+
+function clientShapeError(value: unknown, prop: PropSpec): string | null {
+  const t = prop.type
+  switch (t.kind) {
+    case 'string':
+      return typeof value === 'string' ? null : `Prop '${prop.name}' must be a string.`
+    case 'number':
+      return typeof value === 'number' && !Number.isNaN(value)
+        ? null
+        : `Prop '${prop.name}' must be a number.`
+    case 'boolean':
+      return typeof value === 'boolean' ? null : `Prop '${prop.name}' must be a boolean.`
+    case 'enum':
+      return t.values.includes(value as never)
+        ? null
+        : `Prop '${prop.name}' must be one of: ${t.values.join(', ')}.`
+    case 'array':
+      return Array.isArray(value) ? null : `Prop '${prop.name}' must be an array.`
+    case 'object': {
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return `Prop '${prop.name}' must be an object.`
+      }
+      // Recurse: check that each required nested field is present and
+      // structurally compatible. Without this, passing `{}` for an
+      // object prop with required `label` and `href` children sailed
+      // through the client validator while the server-side
+      // validateComponentBlockValue would reject it on save — a
+      // silent gap in the "live structural validation" promise.
+      const obj = value as Record<string, unknown>
+      for (const field of t.fields) {
+        const child = obj[field.name]
+        if (child === undefined || child === null) {
+          if (field.required) {
+            return `Prop '${prop.name}.${field.name}' is required but missing.`
+          }
+          continue
+        }
+        const childError = clientShapeError(child, {
+          ...field,
+          // Build a dotted path so parsePerPropErrors can attribute
+          // the error to the nested input, not just the outer prop.
+          name: `${prop.name}.${field.name}`,
+        })
+        if (childError) return childError
+      }
+      return null
+    }
+    case 'union': {
+      // Discriminated unions get the same recursive treatment as plain
+      // objects: route the value into the matching variant's schema
+      // and validate against that. Non-discriminated unions remain
+      // unvalidated on the client (server still catches them) — the
+      // shape is too open to assert structurally.
+      const detected = detectDiscriminator(t)
+      if (!detected) return null
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return `Prop '${prop.name}' must be an object with a '${detected.field}' discriminator.`
+      }
+      const variant = findVariant(value, detected)
+      if (!variant) {
+        const allowed = detected.variants.map((v) => JSON.stringify(v.value)).join(', ')
+        return `Prop '${prop.name}.${detected.field}' must be one of: ${allowed}.`
+      }
+      // Recurse into the variant's fields, scoped to the prop path.
+      // We treat the variant as an inline object so the existing
+      // object-branch logic applies verbatim.
+      return clientShapeError(value, {
+        name: prop.name,
+        required: prop.required,
+        type: variant.type,
+      })
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * The validator returns a single error string. The form wants to show
+ * the message under the specific input that triggered it — so we parse
+ * the message back into a sparse `{ propPath → message }` map. Pure
+ * function so it's trivial to unit-test.
+ */
+export function parsePerPropErrors(message: string | null): Record<string, string> {
+  if (!message) return {}
+  const propMatch = /Prop '([^']+)'/.exec(message)
+  if (propMatch) return { [propMatch[1]!]: message }
+  const missing = /Missing required prop '([^']+)'/.exec(message)
+  if (missing) return { [missing[1]!]: message }
+  return {}
+}

package/src/fields/index.ts

@@ -15,3 +15,7 @@ export type { BlockTypeDefinition } from './block-types.js'
 export { GroupField } from './GroupField.js'
 export { NavBuilderField } from './NavBuilderField.js'
 export { NumberField } from './NumberField.js'
+export { ComponentBlockField } from './ComponentBlockField.js'
+export type { ComponentBlockFieldProps, ComponentBlockValue } from './ComponentBlockField.js'
+export { PropInput, defaultForType } from './PropInput.js'
+export type { PropInputProps } from './PropInput.js'

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'
@@ -105,3 +125,10 @@ export { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts.js'
 export { cmsApi, setApiBase, ensureCsrfToken } from './lib/api.js'
 export { useApiData } from './lib/useApiData.js'
 export type { UseApiDataResult } from './lib/useApiData.js'
+
+export { ComponentBlockField, PropInput, defaultForType } from './fields/index.js'
+export type {
+  ComponentBlockFieldProps,
+  ComponentBlockValue,
+  PropInputProps,
+} from './fields/index.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/coauthor-client.ts

@@ -0,0 +1,160 @@
+import { cmsApi } from './api.js'
+
+/**
+ * Inline AI co-author client — thin, typed wrapper around the
+ * `POST /ai/coauthor` endpoint exposed by `cms-core`.
+ *
+ * The endpoint implements four text-transformation micro-actions backed by
+ * the configured AI provider. This client lives in `cms-admin` so the
+ * editor (bubble menu) and the command palette (slash commands) can share
+ * exactly one request path, error model, and option shape.
+ *
+ * Mirrors the request body documented in `packages/cms-core/src/api/handlers.ts`:
+ *
+ *   POST /ai/coauthor
+ *   { action, text, style?, tone?, instructions?, targetLength? }
+ */
+
+export type CoauthorAction = 'rewrite' | 'expand' | 'compress' | 'proofread'
+
+/**
+ * Frozen tuple of every action the server accepts. Used both as a type-safe
+ * iteration source (bubble menu pills, slash-command registration) and by
+ * the runtime `isCoauthorAction` guard so callers don't drift from the
+ * server's allowlist.
+ */
+export const COAUTHOR_ACTIONS = ['rewrite', 'expand', 'compress', 'proofread'] as const
+
+const ACTION_LABELS: Record<CoauthorAction, string> = {
+  rewrite: 'Rewrite',
+  expand: 'Expand',
+  compress: 'Compress',
+  proofread: 'Proofread',
+}
+
+const ACTION_DESCRIPTIONS: Record<CoauthorAction, string> = {
+  rewrite: 'Rewrite the selection in a new tone or style',
+  expand: 'Expand the selection with more detail',
+  compress: 'Shorten the selection while preserving meaning',
+  proofread: 'Correct grammar, spelling, and punctuation',
+}
+
+/**
+ * Hard client-side ceiling that matches `AI_CONTEXT_MAX_CHARS` in cms-core.
+ * Catching this here avoids a round-trip just to get a 400 back when a user
+ * pastes a giant block into the bubble menu.
+ */
+export const COAUTHOR_TEXT_MAX_CHARS = 50_000
+
+export type ProofreadChange = {
+  original: string
+  corrected: string
+  reason?: string
+}
+
+export interface CoauthorOptions {
+  /** Free-form style cue, e.g. "more concise", "academic". Used by rewrite. */
+  style?: string
+  /** Tone cue, e.g. "friendly", "professional". Used by rewrite. */
+  tone?: string
+  /** Free-form instructions. Used by expand. */
+  instructions?: string
+  /** Target length in words. Used by compress. */
+  targetLength?: number
+}
+
+export interface CoauthorResult {
+  action: CoauthorAction
+  text: string
+  /** Populated only when `action === 'proofread'`. */
+  changes?: ProofreadChange[]
+}
+
+export type CoauthorOutcome =
+  | { ok: true; result: CoauthorResult }
+  | { ok: false; error: string; status: number }
+
+export function coauthorActionLabel(action: CoauthorAction): string {
+  return ACTION_LABELS[action]
+}
+
+export function coauthorActionDescription(action: CoauthorAction): string {
+  return ACTION_DESCRIPTIONS[action]
+}
+
+export function isCoauthorAction(value: unknown): value is CoauthorAction {
+  return typeof value === 'string' && (COAUTHOR_ACTIONS as readonly string[]).includes(value)
+}
+
+/**
+ * Run a text-transformation micro-action against `/ai/coauthor`.
+ *
+ * Returns a discriminated outcome so callers can switch on `outcome.ok`
+ * without a try/catch — the underlying `cmsApi` already turns every
+ * non-2xx and every network failure into a structured error envelope.
+ *
+ * Pre-flight validation is intentionally cheap (whitespace + length) so the
+ * server stays the single source of truth for richer auth/rate-limit logic.
+ */
+export async function coauthorText(
+  action: CoauthorAction,
+  text: string,
+  opts: CoauthorOptions = {},
+): Promise<CoauthorOutcome> {
+  if (!isCoauthorAction(action)) {
+    return { ok: false, error: `Unknown action "${String(action)}"`, status: 0 }
+  }
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return { ok: false, error: 'No text provided', status: 0 }
+  }
+  if (text.length > COAUTHOR_TEXT_MAX_CHARS) {
+    return {
+      ok: false,
+      error: `Text exceeds ${COAUTHOR_TEXT_MAX_CHARS.toLocaleString()} character limit`,
+      status: 0,
+    }
+  }
+
+  const body: Record<string, unknown> = { action, text }
+  if (opts.style !== undefined) body.style = opts.style
+  if (opts.tone !== undefined) body.tone = opts.tone
+  if (opts.instructions !== undefined) body.instructions = opts.instructions
+  if (opts.targetLength !== undefined) body.targetLength = opts.targetLength
+
+  const res = await cmsApi<{
+    action?: CoauthorAction
+    text?: unknown
+    changes?: unknown
+  }>('/ai/coauthor', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+
+  if (res.error || !res.data) {
+    return {
+      ok: false,
+      error: res.error ?? `Request failed (${res.status})`,
+      status: res.status,
+    }
+  }
+
+  if (typeof res.data.text !== 'string') {
+    return {
+      ok: false,
+      error: 'Malformed response from /ai/coauthor (missing text)',
+      status: res.status,
+    }
+  }
+
+  return {
+    ok: true,
+    result: {
+      action: res.data.action ?? action,
+      text: res.data.text,
+      changes:
+        action === 'proofread' && Array.isArray(res.data.changes)
+          ? (res.data.changes as ProofreadChange[])
+          : undefined,
+    },
+  }
+}