@actuate-media/cms-admin 0.41.0 → 0.42.0

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, 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/PostSectionEditor.tsx

@@ -34,7 +34,11 @@ import {
   resolveSiteUrl,
 } from '../../lib/preview-link.js'
 import type { SectionSettings, SectionTypeId } from '../page-editor/section-types.js'
-import { hasCanvasRenderer, 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'
@@ -112,6 +116,7 @@ export function PostSectionEditor({
   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]
@@ -419,12 +424,15 @@ export function PostSectionEditor({
 
   const selected = post.sections.find((s) => s.id === selectedId) ?? null
 
-  // Section types the canvas renders as placeholders (custom + unmanaged).
-  // When present the editor surfaces "structure view" messaging and promotes
-  // "View on site" as the primary design preview.
+  // 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)).map((s) => s.sectionType),
+      post.sections
+        .filter((s) => !hasCanvasRenderer(s.sectionType) && !customRenderers[s.sectionType])
+        .map((s) => s.sectionType),
     ),
   )