@actuate-media/cms-admin 0.11.0 → 0.12.1

package/src/components/LivePreview.tsx

@@ -1,7 +1,16 @@
 'use client'
 
 import { useState, useRef, useEffect, useCallback } from 'react'
-import { Monitor, Tablet, Smartphone, RefreshCw, ExternalLink, X } from 'lucide-react'
+import {
+  Monitor,
+  Tablet,
+  Smartphone,
+  RefreshCw,
+  ExternalLink,
+  X,
+  Wifi,
+  WifiOff,
+} from 'lucide-react'
 import { cmsApi } from '../lib/api.js'
 
 interface LivePreviewProps {
@@ -13,6 +22,7 @@ interface LivePreviewProps {
 }
 
 type Viewport = 'desktop' | 'tablet' | 'mobile'
+type StreamStatus = 'idle' | 'connecting' | 'connected' | 'offline'
 
 const VIEWPORT_WIDTHS: Record<Viewport, string> = {
   desktop: '100%',
@@ -20,6 +30,23 @@ const VIEWPORT_WIDTHS: Record<Viewport, string> = {
   mobile: '375px',
 }
 
+const PREVIEW_STREAM_PATH = '/api/cms/preview/stream'
+
+function postToIframe(
+  iframe: HTMLIFrameElement | null,
+  src: string | null,
+  data: Record<string, unknown>,
+): void {
+  if (!iframe?.contentWindow || !src) return
+  let targetOrigin: string
+  try {
+    targetOrigin = new URL(src).origin
+  } catch {
+    targetOrigin = window.location.origin
+  }
+  iframe.contentWindow.postMessage({ type: 'actuate-preview-update', data }, targetOrigin)
+}
+
 export function LivePreview({
   collection,
   documentId,
@@ -31,40 +58,89 @@ export function LivePreview({
   const [viewport, setViewport] = useState<Viewport>('desktop')
   const [loading, setLoading] = useState(true)
   const [previewSrc, setPreviewSrc] = useState<string | null>(null)
+  const [previewToken, setPreviewToken] = useState<string | null>(null)
+  const [streamStatus, setStreamStatus] = useState<StreamStatus>('idle')
 
   useEffect(() => {
     if (!documentId || !previewUrl) {
       setPreviewSrc(null)
+      setPreviewToken(null)
       return
     }
 
+    let cancelled = false
+
     async function fetchToken() {
       const res = await cmsApi<{ token: string }>('/preview/token', {
         method: 'POST',
         body: JSON.stringify({ collection, documentId }),
       })
+      if (cancelled) return
       if (res.data?.token) {
         const sep = previewUrl!.includes('?') ? '&' : '?'
+        setPreviewToken(res.data.token)
         setPreviewSrc(`${previewUrl}${sep}preview=true#token=${res.data.token}`)
       }
     }
 
     fetchToken()
+    return () => {
+      cancelled = true
+    }
   }, [collection, documentId, previewUrl])
 
   useEffect(() => {
-    if (!iframeRef.current?.contentWindow || !previewSrc) return
-    let targetOrigin: string
-    try {
-      targetOrigin = new URL(previewSrc).origin
-    } catch {
-      targetOrigin = window.location.origin
+    postToIframe(iframeRef.current, previewSrc, values)
+  }, [values, previewSrc])
+
+  /**
+   * SSE pipe — when the server pushes a draft update for the same
+   * `{collection, documentId}`, forward the new `values` straight to the
+   * iframe via `postMessage`. The bus key matches the token's payload, so
+   * a second admin session updating the same draft (e.g. an AI agent)
+   * appears live in this preview without polling.
+   */
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof EventSource === 'undefined') return
+    if (!documentId || !previewToken) {
+      setStreamStatus('idle')
+      return
     }
-    iframeRef.current.contentWindow.postMessage(
-      { type: 'actuate-preview-update', data: values },
-      targetOrigin,
+    setStreamStatus('connecting')
+    const source = new EventSource(
+      `${PREVIEW_STREAM_PATH}?token=${encodeURIComponent(previewToken)}`,
+      { withCredentials: true },
     )
-  }, [values, previewSrc])
+
+    const onReady = () => setStreamStatus('connected')
+    const onUpdate = (event: MessageEvent<string>) => {
+      try {
+        const payload = JSON.parse(event.data) as { values?: Record<string, unknown> }
+        if (payload.values && typeof payload.values === 'object') {
+          postToIframe(iframeRef.current, previewSrc, payload.values)
+        }
+      } catch {
+        // Ignore malformed events — the SSE wire format guarantees JSON,
+        // but a future schema bump shouldn't break this consumer.
+      }
+    }
+    const onError = () => setStreamStatus('offline')
+    const onOpen = () => setStreamStatus((s) => (s === 'offline' ? 'connecting' : s))
+
+    source.addEventListener('ready', onReady)
+    source.addEventListener('update', onUpdate)
+    source.addEventListener('error', onError)
+    source.addEventListener('open', onOpen)
+
+    return () => {
+      source.removeEventListener('ready', onReady)
+      source.removeEventListener('update', onUpdate)
+      source.removeEventListener('error', onError)
+      source.removeEventListener('open', onOpen)
+      source.close()
+      setStreamStatus('idle')
+    }
+  }, [documentId, previewToken, previewSrc])
 
   const handleRefresh = useCallback(() => {
     if (iframeRef.current) {
@@ -112,6 +188,36 @@ export function LivePreview({
               <Icon className="h-4 w-4" />
             </button>
           ))}
+          <span
+            className="ml-2 inline-flex items-center gap-1 rounded-full bg-white px-2 py-0.5 text-[10px] font-medium text-gray-600"
+            title={
+              streamStatus === 'connected'
+                ? 'Live preview is streaming updates from the server.'
+                : streamStatus === 'connecting'
+                  ? 'Connecting to the live preview stream…'
+                  : streamStatus === 'offline'
+                    ? 'Live stream disconnected. Updates from this admin still work; cross-session updates will reconnect automatically.'
+                    : 'Live preview stream idle.'
+            }
+          >
+            {streamStatus === 'connected' ? (
+              <>
+                <Wifi className="h-3 w-3 text-green-600" aria-hidden /> Live
+              </>
+            ) : streamStatus === 'connecting' ? (
+              <>
+                <Wifi className="h-3 w-3 animate-pulse text-blue-500" aria-hidden /> Connecting
+              </>
+            ) : streamStatus === 'offline' ? (
+              <>
+                <WifiOff className="h-3 w-3 text-amber-500" aria-hidden /> Reconnecting
+              </>
+            ) : (
+              <>
+                <WifiOff className="h-3 w-3 text-gray-400" aria-hidden /> Idle
+              </>
+            )}
+          </span>
         </div>
         <div className="flex items-center gap-1">
           <button

package/src/components/NotificationBell.tsx

@@ -0,0 +1,242 @@
+'use client'
+
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+
+import {
+  type Notification,
+  type NotificationOutcome,
+  listNotifications as defaultListNotifications,
+  markAllNotificationsRead as defaultMarkAllRead,
+  markNotificationRead as defaultMarkRead,
+  notificationSummary,
+  unreadCount as defaultUnreadCount,
+} from '../lib/notifications-client.js'
+
+/**
+ * Top-bar notification bell + dropdown panel. Slice 6 of Phase 3
+ * surfaces every collaboration event that affects the current user —
+ * comment replies, resolves, and mentions — without forcing the
+ * editor to round-trip through the comments side panel.
+ *
+ * Design choices:
+ *
+ * - **Polling, not SSE.** Phase 3 already ships an SSE stream for live
+ *   previews (Phase 2 / `/preview/stream`), but extending it to
+ *   per-user notifications adds a non-trivial fan-out path and a fresh
+ *   security surface (privacy-leak risk on misconfigured streams). The
+ *   bell polls every `pollIntervalMs` (default 30s) and on dropdown
+ *   open. A push-based extension is queued as a Phase 4 follow-up.
+ * - **Optimistic read state.** When the user clicks a notification we
+ *   mark it read locally before the server confirms — so the bell
+ *   counter feels instant. Server failures roll the state back via
+ *   the `onError` toast.
+ * - **API injection.** The dependency-injection seam matches the rest
+ *   of the admin (`CommentSidePanel.api`) so unit tests can substitute
+ *   in-memory fakes.
+ */
+export interface NotificationsApi {
+  list: (opts: { includeRead?: boolean }) => Promise<NotificationOutcome<Notification[]>>
+  unread: () => Promise<NotificationOutcome<number>>
+  markRead: (id: string) => Promise<NotificationOutcome<Notification>>
+  markAllRead: () => Promise<NotificationOutcome<number>>
+}
+
+const defaultApi: NotificationsApi = {
+  list: (opts) => defaultListNotifications(opts),
+  unread: () => defaultUnreadCount(),
+  markRead: (id) => defaultMarkRead(id),
+  markAllRead: () => defaultMarkAllRead(),
+}
+
+export interface NotificationBellProps {
+  /** Polling cadence in milliseconds. Default 30,000. Pass 0 to disable. */
+  pollIntervalMs?: number
+  /** Optional click hook — called with the notification when a row is clicked. */
+  onSelect?: (notification: Notification) => void
+  /** Error sink — bubble server failures to a toast / banner. */
+  onError?: (message: string) => void
+  /** Override the API client (tests). */
+  api?: NotificationsApi
+  className?: string
+}
+
+export function NotificationBell({
+  pollIntervalMs = 30_000,
+  onSelect,
+  onError,
+  api = defaultApi,
+  className,
+}: NotificationBellProps): React.JSX.Element {
+  const [open, setOpen] = useState(false)
+  const [unread, setUnread] = useState(0)
+  const [items, setItems] = useState<Notification[]>([])
+  const [loading, setLoading] = useState(false)
+  const mountedRef = useRef(true)
+  useEffect(() => {
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  const refreshUnread = useCallback(async () => {
+    const out = await api.unread()
+    if (!mountedRef.current) return
+    if (!out.ok) {
+      onError?.(out.error)
+      return
+    }
+    setUnread(out.result)
+  }, [api, onError])
+
+  const refreshList = useCallback(
+    async (includeRead = false) => {
+      setLoading(true)
+      const out = await api.list({ includeRead })
+      if (!mountedRef.current) return
+      if (!out.ok) {
+        onError?.(out.error)
+        setItems([])
+      } else {
+        setItems(out.result)
+      }
+      setLoading(false)
+    },
+    [api, onError],
+  )
+
+  useEffect(() => {
+    void refreshUnread()
+    if (!pollIntervalMs) return
+    const id = setInterval(() => void refreshUnread(), pollIntervalMs)
+    return () => clearInterval(id)
+  }, [refreshUnread, pollIntervalMs])
+
+  useEffect(() => {
+    if (!open) return
+    void refreshList(false)
+  }, [open, refreshList])
+
+  const handleClickRow = useCallback(
+    async (n: Notification) => {
+      // Optimistic update: drop the unread count + tag the row read.
+      if (!n.readAt) {
+        setUnread((v) => Math.max(0, v - 1))
+        setItems((arr) =>
+          arr.map((row) => (row.id === n.id ? { ...row, readAt: new Date().toISOString() } : row)),
+        )
+        const out = await api.markRead(n.id)
+        if (!out.ok) {
+          onError?.(out.error)
+          // Roll back on failure.
+          setUnread((v) => v + 1)
+          setItems((arr) => arr.map((row) => (row.id === n.id ? { ...row, readAt: null } : row)))
+        }
+      }
+      onSelect?.(n)
+    },
+    [api, onError, onSelect],
+  )
+
+  const handleMarkAll = useCallback(async () => {
+    const previous = items.slice()
+    const now = new Date().toISOString()
+    setItems(items.map((n) => ({ ...n, readAt: n.readAt ?? now })))
+    setUnread(0)
+    const out = await api.markAllRead()
+    if (!out.ok) {
+      onError?.(out.error)
+      setItems(previous)
+      await refreshUnread()
+    }
+  }, [api, items, onError, refreshUnread])
+
+  return (
+    <div className={`relative ${className ?? ''}`} data-testid="notification-bell">
+      <button
+        type="button"
+        className="relative rounded p-1.5 text-gray-600 hover:bg-gray-100 hover:text-gray-900"
+        aria-label="Notifications"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+        data-testid="bell-button"
+      >
+        <BellIcon />
+        {unread > 0 && (
+          <span
+            className="absolute -top-0.5 -right-0.5 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-red-600 px-1 text-[10px] font-semibold text-white"
+            data-testid="bell-badge"
+          >
+            {unread > 99 ? '99+' : unread}
+          </span>
+        )}
+      </button>
+      {open && (
+        <div
+          role="menu"
+          className="absolute right-0 z-50 mt-1 w-80 rounded border border-gray-200 bg-white shadow-lg"
+          data-testid="bell-dropdown"
+        >
+          <header className="flex items-center justify-between border-b border-gray-100 px-3 py-2">
+            <span className="text-sm font-semibold text-gray-900">Notifications</span>
+            <button
+              type="button"
+              className="text-xs text-gray-600 hover:text-gray-900 disabled:opacity-50"
+              onClick={handleMarkAll}
+              disabled={unread === 0}
+              data-testid="bell-mark-all"
+            >
+              Mark all read
+            </button>
+          </header>
+          <div className="max-h-80 overflow-y-auto" aria-busy={loading} data-testid="bell-list">
+            {loading ? (
+              <p className="px-3 py-2 text-xs text-gray-500">Loading…</p>
+            ) : items.length === 0 ? (
+              <p className="px-3 py-2 text-xs text-gray-500">All caught up.</p>
+            ) : (
+              <ul>
+                {items.map((n) => (
+                  <li key={n.id}>
+                    <button
+                      type="button"
+                      role="menuitem"
+                      className={`block w-full px-3 py-2 text-left text-xs hover:bg-gray-50 ${
+                        n.readAt ? 'text-gray-500' : 'font-medium text-gray-900'
+                      }`}
+                      onClick={() => handleClickRow(n)}
+                      data-testid={`bell-row-${n.id}`}
+                      data-read={n.readAt ? 'true' : 'false'}
+                    >
+                      <div>{notificationSummary(n)}</div>
+                      <div className="mt-0.5 text-[10px] text-gray-400">{n.createdAt}</div>
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function BellIcon(): React.JSX.Element {
+  return (
+    <svg
+      aria-hidden="true"
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9" />
+      <path d="M10.3 21a1.94 1.94 0 0 0 3.4 0" />
+    </svg>
+  )
+}

package/src/components/OfflineStatus.tsx

@@ -0,0 +1,90 @@
+'use client'
+
+import React from 'react'
+
+import type {
+  CollaborationStatus,
+  OfflinePersistenceStatus,
+} from '../lib/collaboration-provider.js'
+
+/**
+ * Compact connection + offline-draft indicator. Rendered alongside the
+ * presence chips above the editor toolbar so editors get a single,
+ * always-visible signal:
+ *
+ * - **Saved & synced** — IndexedDB store is ready and the gateway
+ *   socket is connected.
+ * - **Saved locally** — IndexedDB ready but the socket is disconnected
+ *   (offline drafts in flight; will sync on reconnect).
+ * - **Syncing local copy…** — IndexedDB is replaying the last snapshot
+ *   into the doc. The editor is still usable but undo / cursor sync
+ *   may flicker briefly.
+ * - **Local drafts unsupported** — `indexedDB` is unavailable; the
+ *   editor will rely on the gateway only. Refresh loses uncommitted
+ *   edits.
+ * - **Local drafts failed** — IndexedDB threw on init (quota, private
+ *   browsing). Same risk as "unsupported", but with a different cause.
+ *
+ * Keeping the component dumb and prop-driven keeps the unit tests
+ * trivial — the parent owns the status transitions.
+ */
+export interface OfflineStatusProps {
+  connection: CollaborationStatus
+  offline: OfflinePersistenceStatus
+}
+
+export function OfflineStatus({ connection, offline }: OfflineStatusProps): React.JSX.Element {
+  const { label, tone } = describeOfflineStatus(connection, offline)
+  const baseClass = 'inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[11px] font-medium'
+  const toneClass = TONE_CLASSES[tone]
+  return (
+    <span className={`${baseClass} ${toneClass}`} data-testid="offline-status" data-tone={tone}>
+      <span
+        aria-hidden="true"
+        className={`inline-block h-1.5 w-1.5 rounded-full ${DOT_CLASSES[tone]}`}
+      />
+      {label}
+    </span>
+  )
+}
+
+export type OfflineTone = 'good' | 'warn' | 'info' | 'bad'
+
+const TONE_CLASSES: Record<OfflineTone, string> = {
+  good: 'bg-emerald-50 text-emerald-700',
+  warn: 'bg-amber-50 text-amber-800',
+  info: 'bg-blue-50 text-blue-700',
+  bad: 'bg-red-50 text-red-700',
+}
+
+const DOT_CLASSES: Record<OfflineTone, string> = {
+  good: 'bg-emerald-500',
+  warn: 'bg-amber-500',
+  info: 'bg-blue-500',
+  bad: 'bg-red-500',
+}
+
+/**
+ * Pure helper that maps the (connection, offline) status pair to a
+ * single user-facing label + colour tone. Exported so the unit tests
+ * can exercise every combination without rendering React.
+ */
+export function describeOfflineStatus(
+  connection: CollaborationStatus,
+  offline: OfflinePersistenceStatus,
+): { label: string; tone: OfflineTone } {
+  if (offline === 'error') return { label: 'Local drafts failed', tone: 'bad' }
+  if (offline === 'unsupported') {
+    // No local persistence; the WebSocket is the only safety net.
+    if (connection === 'connected') return { label: 'Synced', tone: 'good' }
+    if (connection === 'connecting') return { label: 'Connecting…', tone: 'info' }
+    return { label: 'Offline — drafts not persisted', tone: 'warn' }
+  }
+  if (offline === 'loading' || offline === 'pending') {
+    return { label: 'Restoring local copy…', tone: 'info' }
+  }
+  // offline === 'ready' from here on.
+  if (connection === 'connected') return { label: 'Saved & synced', tone: 'good' }
+  if (connection === 'connecting') return { label: 'Saved locally — reconnecting…', tone: 'warn' }
+  return { label: 'Saved locally — offline', tone: 'warn' }
+}

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('') || '?'
+  )
+}