@actuate-media/cms-admin 0.40.1 → 0.42.0

package/src/views/page-editor/PageSectionEditor.tsx

@@ -5,6 +5,7 @@ import { AlertTriangle, Blocks, Loader2, Lock } from 'lucide-react'
 import { toast } from 'sonner'
 import { ConfirmDialog } from '../../components/ui/ConfirmDialog.js'
 import { ErrorBoundary } from '../../components/ErrorBoundary.js'
+import { VersionHistory } from '../../components/VersionHistory.js'
 import {
   addSection,
   createSection,
@@ -32,6 +33,7 @@ import {
 } from '../../lib/preview-link.js'
 import type { SectionSettings, SectionTypeId } from './section-types.js'
 import { DEFAULT_VIEWPORT, type ViewportId } from './viewports.js'
+import { hasCanvasRenderer, useAdminSectionRenderers } from './sections/index.js'
 import { EditorTopBar, type SaveState } from './EditorTopBar.js'
 import { SectionsPanel } from './SectionsPanel.js'
 import { EditorCanvas } from './EditorCanvas.js'
@@ -82,12 +84,14 @@ export function PageSectionEditor({
 
   const [addOpen, setAddOpen] = useState(false)
   const [settingsOpen, setSettingsOpen] = useState(false)
+  const [historyOpen, setHistoryOpen] = useState(false)
   const [deleteTargetId, setDeleteTargetId] = useState<string | null>(null)
   const [confirmPublish, setConfirmPublish] = useState(false)
   const [leaveTarget, setLeaveTarget] = useState<string | null>(null)
   const [validation, setValidation] = useState<ValidationResult | null>(null)
 
   const { canEdit, canPublish } = useMemo(() => deriveCan(session), [session])
+  const customRenderers = useAdminSectionRenderers()
 
   // A misconfigured `pages` collection (missing the fields the editor
   // writes) would silently drop content on save — detect it up front.
@@ -285,6 +289,23 @@ export function PageSectionEditor({
     }
   }, [page, documentId, onNavigate])
 
+  // After a version restore the server has already written the restored
+  // data — refetch so the editor reflects it instead of the stale state.
+  const handleRestored = useCallback(() => {
+    if (!page?.id) return
+    fetchPageForEditor(page.id)
+      .then((p) => {
+        setPage(p)
+        setSelectedId(null)
+        setDirty(false)
+        setSaveState('idle')
+        setValidation(null)
+      })
+      .catch(() => {
+        toast.error('Version restored — refresh the page to see it.')
+      })
+  }, [page?.id])
+
   // ─── Navigation with unsaved guard ───────────────────────────────────
   const guardedNavigate = useCallback(
     (path: string) => {
@@ -398,6 +419,18 @@ export function PageSectionEditor({
     new Set(page.sections.filter((s) => s.unmanaged).map((s) => s.sectionType)),
   )
 
+  // Section types the canvas renders as placeholders — no built-in body
+  // component and no consumer-registered admin renderer. When present the
+  // editor surfaces "structure view" messaging and promotes "View on site"
+  // as the primary design preview.
+  const structuralTypes = Array.from(
+    new Set(
+      page.sections
+        .filter((s) => !hasCanvasRenderer(s.sectionType) && !customRenderers[s.sectionType])
+        .map((s) => s.sectionType),
+    ),
+  )
+
   return (
     <ErrorBoundary>
       <div className="bg-background flex h-full flex-col overflow-hidden">
@@ -414,9 +447,11 @@ export function PageSectionEditor({
           onBack={() => guardedNavigate('/pages')}
           onPreview={handlePreview}
           onViewOnSite={page.id ? handleViewOnSite : undefined}
+          onHistory={page.id ? () => setHistoryOpen(true) : undefined}
           onOpenSettings={() => setSettingsOpen(true)}
           onSaveDraft={handleSaveDraft}
           onPublish={requestPublish}
+          structuralTypes={structuralTypes}
         />
 
         {readOnly && (
@@ -487,6 +522,7 @@ export function PageSectionEditor({
               viewport={viewport}
               onSelect={setSelectedId}
               onAddSection={() => setAddOpen(true)}
+              structuralTypes={structuralTypes}
             />
           </div>
 
@@ -506,6 +542,16 @@ export function PageSectionEditor({
 
       <AddSectionModal open={addOpen} onClose={() => setAddOpen(false)} onAdd={handleAdd} />
 
+      {page.id && (
+        <VersionHistory
+          collectionSlug="pages"
+          documentId={page.id}
+          open={historyOpen}
+          onClose={() => setHistoryOpen(false)}
+          onRestore={handleRestored}
+        />
+      )}
+
       <PageSettingsModal
         open={settingsOpen}
         page={page}

package/src/views/page-editor/StructureNotice.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+import { Puzzle } from 'lucide-react'
+
+/**
+ * Banner shown above the canvas surface when the document contains section
+ * types the canvas can only render as placeholders (custom / unmanaged
+ * types). Tells authors the canvas is a structural view — the real design
+ * lives on the public site behind "View on site".
+ */
+export function StructureNotice({ structuralTypes }: { structuralTypes: string[] }) {
+  if (structuralTypes.length === 0) return null
+  const count = structuralTypes.length
+  return (
+    <div
+      role="note"
+      className="border-border bg-card text-muted-foreground mx-auto mb-4 flex w-fit max-w-full items-center gap-2 rounded-lg border px-3 py-1.5 text-xs"
+    >
+      <Puzzle className="h-3.5 w-3.5 shrink-0" aria-hidden />
+      <span>
+        <span className="text-foreground font-medium">Structure view</span> — {count} custom section{' '}
+        type{count > 1 ? 's' : ''} shown as placeholders. Use{' '}
+        <span className="text-foreground font-medium">View on site</span> for the real design.
+      </span>
+    </div>
+  )
+}

package/src/views/page-editor/sections/SectionRenderer.tsx

@@ -2,7 +2,9 @@
 
 import { Puzzle } from 'lucide-react'
 import type { PageSection } from '../../../lib/page-editor-service.js'
+import { ErrorBoundary } from '../../../components/ErrorBoundary.js'
 import { getSectionType } from '../section-types.js'
+import { ADMIN_RENDER_OPTIONS, useAdminSectionRenderers } from './admin-renderers.js'
 import { backgroundClass, paddingClass, type PostRenderContext } from './parts.js'
 import { HeroBannerSection } from './HeroBannerSection.js'
 import { MissionSection } from './MissionSection.js'
@@ -15,8 +17,34 @@ import { AuthorBioSection } from './AuthorBioSection.js'
 import { RelatedPostsSection } from './RelatedPostsSection.js'
 import { GallerySection } from './GallerySection.js'
 
+/**
+ * Section types with a real canvas body component below. Anything else —
+ * config-declared custom types (`opal-*`), unmanaged sections, and the
+ * `form` embed — renders as a structural placeholder, so the editors use
+ * this set to tell authors the canvas shows structure, not design.
+ */
+const CANVAS_RENDERED_TYPES: ReadonlySet<string> = new Set([
+  'hero',
+  'text',
+  'feature',
+  'stats',
+  'cta',
+  'article-body',
+  'quote',
+  'author-bio',
+  'related-posts',
+  'gallery',
+])
+
+/** True when the canvas renders this type for real (not as a placeholder). */
+export function hasCanvasRenderer(sectionType: string): boolean {
+  return CANVAS_RENDERED_TYPES.has(sectionType)
+}
+
 /** Dispatch a section's body component by type. Shared by editor + preview. */
 function SectionBody({ section, context }: { section: PageSection; context?: PostRenderContext }) {
+  const customRenderers = useAdminSectionRenderers()
+
   switch (section.sectionType) {
     case 'hero':
       return <HeroBannerSection section={section} />
@@ -38,11 +66,33 @@ function SectionBody({ section, context }: { section: PageSection; context?: Pos
       return <RelatedPostsSection section={section} context={context} />
     case 'gallery':
       return <GallerySection section={section} />
-    default:
-      // Custom (config-declared) types and unmanaged (externally-managed)
-      // sections have no built-in body component. Render a neutral placeholder
-      // so the canvas reflects their presence + order instead of a blank gap.
+    default: {
+      // Custom (config-declared) and unmanaged types: use a consumer-supplied
+      // canvas renderer when one is registered (see admin-renderers.tsx).
+      // Consumer code can throw, so a per-section error boundary falls back
+      // to the structural placeholder instead of taking down the editor.
+      const Custom = customRenderers[section.sectionType]
+      if (Custom) {
+        // The renderer contract types `settings` as an open record (matching
+        // the sections-react wire shape); the admin's concrete
+        // `SectionSettings` interface is the same object at runtime but has
+        // no index signature, so bridge the nominal gap here.
+        const wireSection = {
+          ...section,
+          settings: { ...section.settings } as Record<string, unknown>,
+        }
+        // Rendered as a component (not invoked inline) so a throw happens
+        // inside the boundary's subtree and is actually caught.
+        return (
+          <ErrorBoundary key={section.id} fallback={<PlaceholderSection section={section} />}>
+            <Custom section={wireSection} ctx={context} options={ADMIN_RENDER_OPTIONS} />
+          </ErrorBoundary>
+        )
+      }
+      // No renderer registered: a neutral placeholder keeps the canvas
+      // reflecting the section's presence + order instead of a blank gap.
       return <PlaceholderSection section={section} />
+    }
   }
 }
 

package/src/views/page-editor/sections/admin-renderers.tsx

@@ -0,0 +1,105 @@
+'use client'
+
+/**
+ * Pluggable canvas renderers for custom section types.
+ *
+ * By default the editor canvas renders custom (config-declared) and unmanaged
+ * section types as structural placeholders. Projects that want a real design
+ * preview inside the admin can pass renderers to `<AdminRoot
+ * sectionRenderers={...}>`; the canvas and the eye preview then use them in
+ * place of the placeholder.
+ *
+ * The renderer signature is a structural mirror of `SectionRenderer` from
+ * `@actuate-media/sections-react` (cms-admin depends on cms-core only, so the
+ * type is duplicated rather than imported). Because the shapes match, a
+ * consumer can hand `AdminRoot` the exact same components it registers for
+ * the public site:
+ *
+ * ```tsx
+ * import { OPAL_RENDERERS } from './sections' // SectionRendererMap
+ * <AdminRoot sectionRenderers={OPAL_RENDERERS} ... />
+ * ```
+ *
+ * Renderers run inside the admin bundle, so they must be client-safe (no
+ * server-only imports). Each one is wrapped in an error boundary — a throwing
+ * renderer falls back to the structural placeholder instead of taking down
+ * the editor.
+ */
+import { createContext, useContext, type ReactNode } from 'react'
+
+/** Structural mirror of `RenderImageProps` from `@actuate-media/sections-react`. */
+export interface AdminRenderImageProps {
+  src: string
+  alt: string
+  width?: number | null
+  height?: number | null
+  className?: string
+  priority?: boolean
+  sizes?: string
+}
+
+/** Structural mirror of `PostContext` from `@actuate-media/sections-react`. */
+export interface AdminSectionPostContext {
+  title?: string
+  excerpt?: string
+  body?: string
+  featuredImageUrl?: string
+  publishDate?: string | null
+  category?: string
+  author?: { name?: string; bio?: string; avatarUrl?: string }
+  relatedPosts?: Array<{ title: string; url?: string; excerpt?: string }>
+}
+
+/** Props passed to an admin section renderer (mirrors `SectionRendererProps`). */
+export interface AdminSectionRendererProps {
+  section: {
+    id: string
+    sectionType: string
+    name?: string
+    visible?: boolean
+    content?: Record<string, unknown>
+    settings?: Record<string, unknown>
+  }
+  ctx?: AdminSectionPostContext
+  options: {
+    sanitizeHtml: (html: string) => string
+    baseUrl: string
+    renderImage: (props: AdminRenderImageProps) => ReactNode
+  }
+}
+
+/** A canvas renderer for one custom section type. */
+export type AdminSectionRenderer = (props: AdminSectionRendererProps) => ReactNode
+
+/** Section-type id → canvas renderer. */
+export type AdminSectionRendererMap = Record<string, AdminSectionRenderer>
+
+/**
+ * Render options passed to every admin renderer. Rich text is sanitized on
+ * write by cms-core, so the canvas (same trust domain as the public default)
+ * uses the identity sanitizer; images render as plain lazy `<img>` since the
+ * editor canvas has no next/image pipeline.
+ */
+export const ADMIN_RENDER_OPTIONS: AdminSectionRendererProps['options'] = {
+  sanitizeHtml: (html) => html,
+  baseUrl: '',
+  renderImage: ({ src, alt, className, priority, width, height }) => (
+    <img
+      src={src}
+      alt={alt}
+      className={className}
+      width={width ?? undefined}
+      height={height ?? undefined}
+      loading={priority ? undefined : 'lazy'}
+    />
+  ),
+}
+
+const AdminSectionRenderersContext = createContext<AdminSectionRendererMap>({})
+
+export const AdminSectionRenderersProvider = AdminSectionRenderersContext.Provider
+
+/** The renderer map passed to `<AdminRoot sectionRenderers>` (empty by default). */
+export function useAdminSectionRenderers(): AdminSectionRendererMap {
+  return useContext(AdminSectionRenderersContext)
+}

package/src/views/page-editor/sections/index.ts

@@ -1,5 +1,17 @@
-export { SectionRenderer } from './SectionRenderer.js'
+export { SectionRenderer, hasCanvasRenderer } from './SectionRenderer.js'
 export type { SectionRendererProps } from './SectionRenderer.js'
+export {
+  AdminSectionRenderersProvider,
+  useAdminSectionRenderers,
+  ADMIN_RENDER_OPTIONS,
+} from './admin-renderers.js'
+export type {
+  AdminSectionRenderer,
+  AdminSectionRendererMap,
+  AdminSectionRendererProps,
+  AdminSectionPostContext,
+  AdminRenderImageProps,
+} from './admin-renderers.js'
 export type { PostRenderContext } from './parts.js'
 export { HeroBannerSection } from './HeroBannerSection.js'
 export { MissionSection } from './MissionSection.js'

package/src/views/post-editor/PostEditorCanvas.tsx

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react
 import { FileText, Plus } from 'lucide-react'
 import type { PageSection, PostHeaderConfig } from '../../lib/post-editor-service.js'
 import { SectionRenderer, type PostRenderContext } from '../page-editor/sections/index.js'
+import { StructureNotice } from '../page-editor/StructureNotice.js'
 import { getViewport, type ViewportId } from '../page-editor/viewports.js'
 import { PostHeader } from './PostHeader.js'
 
@@ -15,6 +16,8 @@ interface PostEditorCanvasProps {
   viewport: ViewportId
   onSelect: (id: string) => void
   onAddSection: () => void
+  /** Section types rendered as placeholders — shows the "Structure view" notice. */
+  structuralTypes?: string[]
 }
 
 /**
@@ -31,6 +34,7 @@ export function PostEditorCanvas({
   viewport,
   onSelect,
   onAddSection,
+  structuralTypes = [],
 }: PostEditorCanvasProps) {
   const vp = getViewport(viewport)
   const containerRef = useRef<HTMLDivElement>(null)
@@ -70,6 +74,7 @@ export function PostEditorCanvas({
 
   return (
     <div ref={containerRef} className="bg-muted h-full overflow-auto p-6">
+      <StructureNotice structuralTypes={structuralTypes} />
       <div
         className="mx-auto"
         style={{ width: vp.width * scale, height: surfaceHeight ?? undefined }}

package/src/views/post-editor/PostSectionEditor.tsx

@@ -5,6 +5,7 @@ import { AlertTriangle, Loader2 } from 'lucide-react'
 import { toast } from 'sonner'
 import { ConfirmDialog } from '../../components/ui/ConfirmDialog.js'
 import { ErrorBoundary } from '../../components/ErrorBoundary.js'
+import { VersionHistory } from '../../components/VersionHistory.js'
 import {
   addSection,
   createSection,
@@ -33,7 +34,11 @@ import {
   resolveSiteUrl,
 } from '../../lib/preview-link.js'
 import type { SectionSettings, SectionTypeId } from '../page-editor/section-types.js'
-import type { PostRenderContext } from '../page-editor/sections/index.js'
+import {
+  hasCanvasRenderer,
+  useAdminSectionRenderers,
+  type PostRenderContext,
+} from '../page-editor/sections/index.js'
 import { DEFAULT_VIEWPORT, type ViewportId } from '../page-editor/viewports.js'
 import { EditorTopBar, type SaveState } from '../page-editor/EditorTopBar.js'
 import { SectionsPanel } from '../page-editor/SectionsPanel.js'
@@ -104,12 +109,14 @@ export function PostSectionEditor({
 
   const [addOpen, setAddOpen] = useState(false)
   const [fieldsOpen, setFieldsOpen] = useState(false)
+  const [historyOpen, setHistoryOpen] = useState(false)
   const [deleteTargetId, setDeleteTargetId] = useState<string | null>(null)
   const [confirmPublish, setConfirmPublish] = useState(false)
   const [leaveTarget, setLeaveTarget] = useState<string | null>(null)
   const [validation, setValidation] = useState<ValidationResult | null>(null)
 
   const { canEdit, canPublish } = useMemo(() => deriveCan(session), [session])
+  const customRenderers = useAdminSectionRenderers()
 
   const typeLabel = useMemo(() => {
     const col = config?.collections?.[postType]
@@ -302,6 +309,23 @@ export function PostSectionEditor({
     }
   }, [post, documentId, postType, onNavigate])
 
+  // After a version restore the server has already written the restored
+  // data — refetch so the editor reflects it instead of the stale state.
+  const handleRestored = useCallback(() => {
+    if (!post?.id) return
+    fetchPostForEditor(postType, post.id)
+      .then((p) => {
+        setPost(p)
+        setSelectedId(null)
+        setDirty(false)
+        setSaveState('idle')
+        setValidation(null)
+      })
+      .catch(() => {
+        toast.error('Version restored — refresh the page to see it.')
+      })
+  }, [postType, post?.id])
+
   const guardedNavigate = useCallback(
     (path: string) => {
       if (dirty) setLeaveTarget(path)
@@ -400,6 +424,18 @@ export function PostSectionEditor({
 
   const selected = post.sections.find((s) => s.id === selectedId) ?? null
 
+  // Section types the canvas renders as placeholders — no built-in body
+  // component and no consumer-registered admin renderer. When present the
+  // editor surfaces "structure view" messaging and promotes "View on site"
+  // as the primary design preview.
+  const structuralTypes = Array.from(
+    new Set(
+      post.sections
+        .filter((s) => !hasCanvasRenderer(s.sectionType) && !customRenderers[s.sectionType])
+        .map((s) => s.sectionType),
+    ),
+  )
+
   return (
     <ErrorBoundary>
       <div className="bg-background flex h-full flex-col overflow-hidden">
@@ -417,9 +453,11 @@ export function PostSectionEditor({
           onBack={() => guardedNavigate('/posts')}
           onPreview={handlePreview}
           onViewOnSite={post.id ? handleViewOnSite : undefined}
+          onHistory={post.id ? () => setHistoryOpen(true) : undefined}
           onOpenSettings={() => setFieldsOpen(true)}
           onSaveDraft={handleSaveDraft}
           onPublish={requestPublish}
+          structuralTypes={structuralTypes}
         />
 
         {validation && (
@@ -452,6 +490,7 @@ export function PostSectionEditor({
               viewport={viewport}
               onSelect={setSelectedId}
               onAddSection={() => setAddOpen(true)}
+              structuralTypes={structuralTypes}
             />
           </div>
 
@@ -476,6 +515,16 @@ export function PostSectionEditor({
         onAdd={handleAdd}
       />
 
+      {post.id && (
+        <VersionHistory
+          collectionSlug={postType}
+          documentId={post.id}
+          open={historyOpen}
+          onClose={() => setHistoryOpen(false)}
+          onRestore={handleRestored}
+        />
+      )}
+
       <PostFieldsModal
         open={fieldsOpen}
         post={post}