@actuate-media/cms-admin 0.12.0 → 0.13.0

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,314 @@
+'use client'
+
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+
+import {
+  type Notification,
+  type NotificationOutcome,
+  type NotificationStreamHandle,
+  type NotificationStreamOptions,
+  listNotifications as defaultListNotifications,
+  markAllNotificationsRead as defaultMarkAllRead,
+  markNotificationRead as defaultMarkRead,
+  notificationSummary,
+  subscribeNotificationStream as defaultSubscribeStream,
+  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:
+ *
+ * - **SSE push, with poll fallback (Phase 7).** A persistent
+ *   `EventSource` subscribes to `/api/cms/notifications/stream` for
+ *   instant delivery; new notifications bump the badge immediately
+ *   instead of after the next 30 s poll tick. The poll loop is kept
+ *   alive at a back-pressure-friendly cadence (default 60 s — twice
+ *   the legacy 30 s value because SSE handles the common case) and
+ *   acts as a backstop for:
+ *     1. multi-node deployments where the in-process bus only
+ *        publishes to subscribers on the same node, and
+ *     2. proxies / browsers that silently drop the EventSource
+ *        without firing `onerror`.
+ * - **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 — including the EventSource subscriber, which
+ *   isn't available in JSDOM by default.
+ */
+export interface NotificationsApi {
+  list: (opts: { includeRead?: boolean }) => Promise<NotificationOutcome<Notification[]>>
+  unread: () => Promise<NotificationOutcome<number>>
+  markRead: (id: string) => Promise<NotificationOutcome<Notification>>
+  markAllRead: () => Promise<NotificationOutcome<number>>
+  /**
+   * Open a per-user SSE subscription. Implementations MUST always
+   * return a handle — even in environments without `EventSource`
+   * (SSR, JSDOM without a polyfill), where a no-op `{ close() {} }`
+   * is the right answer. The bell's effect calls `handle.close()`
+   * unconditionally on unmount; a `null` return would crash.
+   * Omitting the member entirely is the supported way to opt out of
+   * SSE (the bell then runs poll-only).
+   */
+  subscribe?: (opts: NotificationStreamOptions) => NotificationStreamHandle
+}
+
+const defaultApi: NotificationsApi = {
+  list: (opts) => defaultListNotifications(opts),
+  unread: () => defaultUnreadCount(),
+  markRead: (id) => defaultMarkRead(id),
+  markAllRead: () => defaultMarkAllRead(),
+  subscribe: (opts) => defaultSubscribeStream(opts),
+}
+
+export interface NotificationBellProps {
+  /**
+   * Polling cadence in milliseconds for the fallback loop. Default
+   * 60,000 (twice the pre-SSE value — push handles the common case).
+   * Pass 0 to disable polling entirely (relies on SSE only — only
+   * safe on single-node deployments).
+   */
+  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 = 60_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)
+  // Set of notification IDs we've already rendered. The SSE handler
+  // consults this synchronously so duplicate deliveries (REST refresh
+  // + SSE push, or two SSE retries) don't double-bump the badge.
+  // Kept in sync with `items` via an effect — the items state is the
+  // source of truth; this ref is a derived O(1) lookup index.
+  const seenIdsRef = useRef<Set<string>>(new Set())
+  useEffect(() => {
+    seenIdsRef.current = new Set(items.map((n) => n.id))
+  }, [items])
+  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])
+
+  // SSE push subscription. Bumps the badge + prepends the new row to
+  // the open dropdown the instant the server publishes. Falls back
+  // silently when the api/runtime doesn't support EventSource — the
+  // poll loop above keeps the bell correct in that case.
+  useEffect(() => {
+    if (!api.subscribe) return
+    const handle = api.subscribe({
+      onNotification: (n) => {
+        if (!mountedRef.current) return
+        // Defensive: SSE events can race with REST refreshes (or with
+        // their own retries). The seen-id ref is updated
+        // synchronously so a second delivery of the same row is a
+        // no-op for BOTH `items` and the unread badge — guarding only
+        // setItems would still let the counter drift.
+        if (seenIdsRef.current.has(n.id)) return
+        seenIdsRef.current.add(n.id)
+        setItems((arr) => [n, ...arr])
+        if (!n.readAt) setUnread((v) => v + 1)
+      },
+      onError: () => {
+        // Don't surface every transient SSE disconnect as a UI error —
+        // the browser auto-reconnects, and the poll loop keeps state
+        // converging. We deliberately stay quiet here.
+      },
+    })
+    return () => handle.close()
+  }, [api])
+
+  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 () => {
+    // Snapshot ONLY the previously-unread IDs (and their original
+    // readAt values, which are null by definition). On rollback we
+    // restore those specific rows and leave anything that arrived
+    // via SSE while the request was in flight alone — otherwise a
+    // failed mark-all-read would drop fresh notifications.
+    const previouslyUnreadIds = items.filter((n) => n.readAt === null).map((n) => n.id)
+    if (previouslyUnreadIds.length === 0) return
+    const ids = new Set(previouslyUnreadIds)
+    const now = new Date().toISOString()
+    setItems((arr) => arr.map((n) => (ids.has(n.id) ? { ...n, readAt: n.readAt ?? now } : n)))
+    setUnread(0)
+    const out = await api.markAllRead()
+    if (!out.ok) {
+      onError?.(out.error)
+      // Functional rollback: only revert the rows we optimistically
+      // marked. Anything mid-flight (SSE arrivals, locally-added) is
+      // untouched.
+      setItems((arr) => arr.map((n) => (ids.has(n.id) ? { ...n, readAt: null } : n)))
+      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' }
+}