@prenta/admin 0.95.1 → 0.96.0

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

@@ -0,0 +1,171 @@
+'use client'
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { CanvasMetaLine } from './CanvasMetaLine.js'
+import { fitScale, getBreakpoint, type BreakpointId, type Zoom } from '../../lib/breakpoints.js'
+
+export interface CanvasSurfaceProps {
+  breakpoint: BreakpointId
+  zoom?: Zoom
+  /**
+   * Reports the measured scale so the header's zoom chip can show a real
+   * percentage. Only the canvas knows the available width, so the number has
+   * to travel up rather than being recomputed by the header.
+   */
+  onScaleChange?: (scale: number) => void
+  /**
+   * Reports the canvas surface element, so the reflow guard can clone it. The
+   * guard needs the real element rather than a `document.querySelector`, which
+   * would also match the site-preview frame's canvas when that is mounted.
+   */
+  onCanvasElement?: (el: HTMLElement | null) => void
+  /** Tips, notices, or the review bar — rendered above the meta line. */
+  chrome?: React.ReactNode
+  /** The page itself. Rendered inside the scaled, container-queried surface. */
+  children: React.ReactNode
+}
+
+/**
+ * The scaled preview surface, shared by the page and post editors.
+ *
+ * The canvas renders at the breakpoint's **real CSS width** and is scaled down
+ * with a transform. Combined with `container-type: inline-size`, that makes the
+ * page reflow against its own width — the same container queries that style the
+ * live page decide the layout. A max-width clamp cannot do this: it yields a
+ * narrow desktop layout rather than the mobile one.
+ *
+ * Extracted because the arithmetic was being maintained in two places and got
+ * it wrong in one of them (see the `clientWidth - 48` entry in
+ * docs/page-builder-handoff-followups.md). The editors differ only in what
+ * they put INSIDE the surface — the post editor renders a header above its
+ * sections — and not at all in how it is measured, sized or scaled.
+ *
+ * Two measurement rules, both learned the hard way:
+ *
+ *   1. Available width comes from a **zero-height sentinel** rendered as the
+ *      panel's first child, not from `panel.clientWidth - padding`. The two
+ *      disagree once a scrollbar appears or the host scales the preview, and
+ *      the padding arithmetic silently rots whenever the gutter changes.
+ *   2. Both measurements are re-taken on **every render**, not only from the
+ *      ResizeObserver. Page height changes with every text edit, image swap and
+ *      show/hide — none of which resize the observed elements. The observer
+ *      exists for later window resizes; its first callback is not a substitute.
+ */
+export function CanvasSurface({
+  breakpoint,
+  zoom = 'fit',
+  onScaleChange,
+  onCanvasElement,
+  chrome,
+  children,
+}: CanvasSurfaceProps) {
+  const bp = getBreakpoint(breakpoint)
+  const sentinelRef = useRef<HTMLDivElement>(null)
+  const surfaceRef = useRef<HTMLDivElement>(null)
+
+  const [available, setAvailable] = useState(0)
+  const [pageHeight, setPageHeight] = useState(0)
+
+  // No dependency array: page height changes on edits that resize nothing the
+  // observer watches. Both setters bail when the value is unchanged, so this
+  // settles after one extra pass instead of looping.
+  useLayoutEffect(() => {
+    const measure = () => {
+      const sentinelWidth = sentinelRef.current?.offsetWidth ?? 0
+      if (sentinelWidth > 0) setAvailable((prev) => (prev === sentinelWidth ? prev : sentinelWidth))
+
+      const height = surfaceRef.current?.offsetHeight ?? 0
+      if (height > 0) setPageHeight((prev) => (prev === height ? prev : height))
+    }
+
+    measure()
+
+    const ro = new ResizeObserver(measure)
+    if (sentinelRef.current) ro.observe(sentinelRef.current)
+    if (surfaceRef.current) ro.observe(surfaceRef.current)
+    return () => ro.disconnect()
+  })
+
+  const scale = fitScale(available, bp.width, zoom)
+
+  useEffect(() => {
+    onScaleChange?.(scale)
+  }, [scale, onScaleChange])
+
+  return (
+    <>
+      {/*
+       * Zero-height sentinel. Its offsetWidth IS the usable width — it is
+       * subject to exactly the same padding, scrollbar and host scaling as the
+       * canvas, so there is no arithmetic to get wrong. Must stay the first
+       * child and must stay zero-height.
+       */}
+      <div ref={sentinelRef} aria-hidden className="h-0" />
+
+      {chrome}
+      <CanvasMetaLine breakpoint={bp} pageHeight={pageHeight} scale={scale} />
+
+      {/*
+       * Fit box: reserves the scaled footprint so the surrounding scroll area
+       * sizes correctly against a transformed child. Deliberately has NO
+       * width/height transition — a transition frozen mid-flight (a preview
+       * that is not visible never finishes one) reports a bogus height and
+       * corrupts the next measurement.
+       */}
+      <div
+        className="prenta-canvas-fit mx-auto block"
+        style={{
+          width: Math.round(bp.width * scale),
+          height: pageHeight ? Math.round(pageHeight * scale) : undefined,
+        }}
+      >
+        {/* `prenta-canvas` is the public hook for consumer brand CSS: site
+            styles that should render in this preview scope to
+            `.prenta-admin .prenta-canvas` instead of the admin root. It also
+            carries `container-type: inline-size` (theme.css) — that is what
+            makes the `@pv-*` steps in the section renderers resolve against
+            the simulated width instead of the viewport. */}
+        <div
+          ref={(el) => {
+            surfaceRef.current = el
+            onCanvasElement?.(el)
+          }}
+          className="prenta-canvas border-border bg-card origin-top-left overflow-hidden rounded-lg text-left shadow-[0_2px_20px_rgba(0,0,0,0.12)] motion-safe:transition-[width,transform] motion-safe:duration-(--mo-slow) motion-safe:ease-(--ease)"
+          style={{
+            width: bp.width,
+            transform: `scale(${scale})`,
+            transformOrigin: 'top left',
+          }}
+        >
+          {children}
+        </div>
+      </div>
+    </>
+  )
+}
+
+/** The scroll container both editors wrap their surface in. */
+export function CanvasScroll({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="prenta-canvas-scroll bg-muted h-full overflow-auto px-6 pt-4.5 pb-10 text-center">
+      {children}
+    </div>
+  )
+}
+
+/** Registers section DOM nodes so the canvas can scroll one into view. */
+export function useSectionRefs(selectedId: string | null) {
+  const sectionRefs = useRef<Map<string, HTMLElement>>(new Map())
+
+  const registerRef = useCallback((id: string, el: HTMLElement | null) => {
+    if (el) sectionRefs.current.set(id, el)
+    else sectionRefs.current.delete(id)
+  }, [])
+
+  useEffect(() => {
+    if (!selectedId) return
+    sectionRefs.current.get(selectedId)?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+  }, [selectedId])
+
+  return registerRef
+}

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

@@ -1,10 +1,9 @@
 'use client'
 
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { LayoutTemplate } from 'lucide-react'
 import { CanvasEditTip } from '../../components/CanvasEditTip.js'
-import { CanvasMetaLine } from './CanvasMetaLine.js'
-import { fitScale, getBreakpoint, type BreakpointId, type Zoom } from '../../lib/breakpoints.js'
+import { CanvasScroll, CanvasSurface, useSectionRefs } from './CanvasSurface.js'
+import type { BreakpointId, Zoom } from '../../lib/breakpoints.js'
 import type { PageSection } from '../../lib/page-editor-service.js'
 import { SectionRenderer } from './sections/index.js'
 import { StructureNotice } from './StructureNotice.js'
@@ -15,17 +14,7 @@ interface EditorCanvasProps {
   breakpoint: BreakpointId
   zoom?: Zoom
   onSelect: (id: string) => void
-  /**
-   * Reports the measured scale so the header's zoom chip can show a real
-   * percentage. Only the canvas knows the available width, so the number has
-   * to travel up rather than being recomputed by the header.
-   */
   onScaleChange?: (scale: number) => void
-  /**
-   * Reports the canvas surface element, so the reflow guard can clone it. The
-   * guard needs the real element rather than a `document.querySelector`, which
-   * would also match the site-preview frame's canvas when that is mounted.
-   */
   onCanvasElement?: (el: HTMLElement | null) => void
   /** Section types rendered as placeholders — shows the "Structure view" notice. */
   structuralTypes?: string[]
@@ -46,24 +35,11 @@ interface EditorCanvasProps {
 }
 
 /**
- * The preview canvas.
- *
- * The canvas renders at the breakpoint's **real CSS width** and is scaled down
- * with a transform. Combined with `container-type: inline-size`, that makes the
- * page reflow against its own width — the same container queries that style the
- * live page decide the layout. A max-width clamp cannot do this: it yields a
- * narrow desktop layout rather than the mobile one.
+ * The page editor's preview canvas.
  *
- * Two measurement rules, both learned the hard way:
- *
- *   1. Available width comes from a **zero-height sentinel** rendered as the
- *      panel's first child, not from `panel.clientWidth - padding`. The two
- *      disagree once a scrollbar appears or the host scales the preview, and
- *      the padding arithmetic silently rots whenever the gutter changes.
- *   2. Both measurements are re-taken on **every render**, not only from the
- *      ResizeObserver. Page height changes with every text edit, image swap and
- *      show/hide — none of which resize the observed elements. The observer
- *      exists for later window resizes; its first callback is not a substitute.
+ * Measurement, scaling and the fit box live in {@link CanvasSurface}, shared
+ * with the post editor. What is left here is what is genuinely page-specific:
+ * which chrome sits above the canvas, and what goes inside it.
  */
 export function EditorCanvas({
   sections,
@@ -79,70 +55,31 @@ export function EditorCanvas({
   changedSectionIds,
   reviewBar,
 }: EditorCanvasProps) {
-  const bp = getBreakpoint(breakpoint)
-  const sentinelRef = useRef<HTMLDivElement>(null)
-  const surfaceRef = useRef<HTMLDivElement>(null)
-  const sectionRefs = useRef<Map<string, HTMLElement>>(new Map())
-
-  const [available, setAvailable] = useState(0)
-  const [pageHeight, setPageHeight] = useState(0)
-
-  const registerRef = useCallback((id: string, el: HTMLElement | null) => {
-    if (el) sectionRefs.current.set(id, el)
-    else sectionRefs.current.delete(id)
-  }, [])
-
-  // No dependency array: page height changes on edits that resize nothing the
-  // observer watches. Both setters bail when the value is unchanged, so this
-  // settles after one extra pass instead of looping.
-  useLayoutEffect(() => {
-    const measure = () => {
-      const sentinelWidth = sentinelRef.current?.offsetWidth ?? 0
-      if (sentinelWidth > 0) setAvailable((prev) => (prev === sentinelWidth ? prev : sentinelWidth))
-
-      const height = surfaceRef.current?.offsetHeight ?? 0
-      if (height > 0) setPageHeight((prev) => (prev === height ? prev : height))
-    }
-
-    measure()
-
-    const ro = new ResizeObserver(measure)
-    if (sentinelRef.current) ro.observe(sentinelRef.current)
-    if (surfaceRef.current) ro.observe(surfaceRef.current)
-    return () => ro.disconnect()
-  })
-
-  // Scroll the selected section into view within the canvas.
-  useEffect(() => {
-    if (!selectedId) return
-    const el = sectionRefs.current.get(selectedId)
-    if (el) el.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
-  }, [selectedId])
-
-  const scale = fitScale(available, bp.width, zoom)
-
-  useEffect(() => {
-    onScaleChange?.(scale)
-  }, [scale, onScaleChange])
+  const registerRef = useSectionRefs(selectedId)
+
+  // A design-owned page always ships the template's sections, so an empty
+  // canvas means the template resolved to nothing — a configuration problem,
+  // not a page to scale and measure.
+  if (sections.length === 0) {
+    return (
+      <CanvasScroll>
+        <EmptyCanvas />
+      </CanvasScroll>
+    )
+  }
 
   return (
-    <div className="prenta-canvas-scroll bg-muted h-full overflow-auto px-6 pt-4.5 pb-10 text-center">
-      {/*
-       * Zero-height sentinel. Its offsetWidth IS the usable width — it is
-       * subject to exactly the same padding, scrollbar and host scaling as the
-       * canvas, so there is no arithmetic to get wrong. Must stay the first
-       * child and must stay zero-height.
-       */}
-      <div ref={sentinelRef} aria-hidden className="h-0" />
-
-      {sections.length === 0 ? (
-        <EmptyCanvas />
-      ) : (
-        <>
-          {/* The review bar REPLACES the editing chrome rather than joining it:
-              a tip about clicking sections to edit them is actively wrong while
-              the canvas is showing a version you cannot edit. */}
-          {reviewing ? (
+    <CanvasScroll>
+      <CanvasSurface
+        breakpoint={breakpoint}
+        zoom={zoom}
+        onScaleChange={onScaleChange}
+        onCanvasElement={onCanvasElement}
+        chrome={
+          // The review bar REPLACES the editing chrome rather than joining it:
+          // a tip about clicking sections to edit them is actively wrong while
+          // the canvas is showing a version you cannot edit.
+          reviewing ? (
             reviewBar
           ) : (
             <>
@@ -152,58 +89,23 @@ export function EditorCanvas({
                 sitePreviewAvailable={sitePreviewAvailable}
               />
             </>
-          )}
-          <CanvasMetaLine breakpoint={bp} pageHeight={pageHeight} scale={scale} />
-
-          {/*
-           * Fit box: reserves the scaled footprint so the surrounding scroll
-           * area sizes correctly against a transformed child. Deliberately has
-           * NO width/height transition — a transition frozen mid-flight (a
-           * preview that is not visible never finishes one) reports a bogus
-           * height and corrupts the next measurement.
-           */}
-          <div
-            className="prenta-canvas-fit mx-auto block"
-            style={{
-              width: Math.round(bp.width * scale),
-              height: pageHeight ? Math.round(pageHeight * scale) : undefined,
-            }}
-          >
-            {/* `prenta-canvas` is the public hook for consumer brand CSS:
-                site styles that should render in this preview scope to
-                `.prenta-admin .prenta-canvas` instead of the admin root. */}
-            <div
-              ref={(el) => {
-                surfaceRef.current = el
-                onCanvasElement?.(el)
-              }}
-              // `prenta-canvas` carries `container-type: inline-size` (theme.css)
-              // — that is what makes the `@pv-*` steps in the section renderers
-              // resolve against the simulated width instead of the viewport.
-              className="prenta-canvas border-border bg-card origin-top-left overflow-hidden rounded-lg text-left shadow-[0_2px_20px_rgba(0,0,0,0.12)] motion-safe:transition-[width,transform] motion-safe:duration-(--mo-slow) motion-safe:ease-(--ease)"
-              style={{
-                width: bp.width,
-                transform: `scale(${scale})`,
-                transformOrigin: 'top left',
-              }}
-            >
-              {sections.map((section) => (
-                <SectionRenderer
-                  key={section.id}
-                  section={section}
-                  editable
-                  reviewing={reviewing}
-                  changed={changedSectionIds?.has(section.id) ?? false}
-                  selected={section.id === selectedId}
-                  onSelect={onSelect}
-                  registerRef={registerRef}
-                />
-              ))}
-            </div>
-          </div>
-        </>
-      )}
-    </div>
+          )
+        }
+      >
+        {sections.map((section) => (
+          <SectionRenderer
+            key={section.id}
+            section={section}
+            editable
+            reviewing={reviewing}
+            changed={changedSectionIds?.has(section.id) ?? false}
+            selected={section.id === selectedId}
+            onSelect={onSelect}
+            registerRef={registerRef}
+          />
+        ))}
+      </CanvasSurface>
+    </CanvasScroll>
   )
 }
 

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

@@ -1,12 +1,13 @@
 'use client'
 
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { FileText, Plus } from 'lucide-react'
 import { CanvasEditTip } from '../../components/CanvasEditTip.js'
+import type { Zoom } from '../../lib/breakpoints.js'
 import type { PageSection, PostHeaderConfig } from '../../lib/post-editor-service.js'
+import { CanvasScroll, CanvasSurface, useSectionRefs } from '../page-editor/CanvasSurface.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 { type ViewportId } from '../page-editor/viewports.js'
 import { PostHeader } from './PostHeader.js'
 
 interface PostEditorCanvasProps {
@@ -15,7 +16,10 @@ interface PostEditorCanvasProps {
   context: PostRenderContext
   selectedId: string | null
   viewport: ViewportId
+  zoom?: Zoom
   onSelect: (id: string) => void
+  onScaleChange?: (scale: number) => void
+  onCanvasElement?: (el: HTMLElement | null) => void
   /** Add-section CTA on the empty canvas. Omitted by design-owned editors. */
   onAddSection?: () => void
   /** Section types rendered as placeholders — shows the "Structure view" notice. */
@@ -25,10 +29,17 @@ interface PostEditorCanvasProps {
 }
 
 /**
- * Post preview canvas. Mirrors the Page editor canvas (scaled surface that
- * fits the selected viewport) but renders the post header above the section
- * list so the editor shows the full post layout — header regions plus body
- * sections — exactly as it will ship.
+ * Post preview canvas.
+ *
+ * Shares {@link CanvasSurface} with the page editor, so measurement, scaling,
+ * the fit box and the meta line are one implementation rather than two. What is
+ * post-specific is what goes inside: the post header renders above the body
+ * sections, so the editor shows the full layout — header regions plus sections
+ * — exactly as it will ship.
+ *
+ * Before this shared surface the post canvas derived its width from
+ * `container.clientWidth - 48`, which disagrees with the canvas's own metrics
+ * once a scrollbar appears, and it had no breakpoint/scale readout at all.
  */
 export function PostEditorCanvas({
   sections,
@@ -36,82 +47,51 @@ export function PostEditorCanvas({
   context,
   selectedId,
   viewport,
+  zoom = 'fit',
   onSelect,
+  onScaleChange,
+  onCanvasElement,
   onAddSection,
   structuralTypes = [],
   sitePreviewAvailable = false,
 }: PostEditorCanvasProps) {
-  const vp = getViewport(viewport)
-  const containerRef = useRef<HTMLDivElement>(null)
-  const surfaceRef = useRef<HTMLDivElement>(null)
-  const sectionRefs = useRef<Map<string, HTMLElement>>(new Map())
-  const [scale, setScale] = useState(1)
-  const [surfaceHeight, setSurfaceHeight] = useState<number | null>(null)
-
-  const registerRef = useCallback((id: string, el: HTMLElement | null) => {
-    if (el) sectionRefs.current.set(id, el)
-    else sectionRefs.current.delete(id)
-  }, [])
-
-  useLayoutEffect(() => {
-    const container = containerRef.current
-    if (!container) return
-    const recompute = () => {
-      const available = container.clientWidth - 48
-      const next = Math.min(1, available / vp.width)
-      setScale(next > 0 ? next : 1)
-      if (surfaceRef.current) {
-        setSurfaceHeight(surfaceRef.current.offsetHeight * (next > 0 ? next : 1))
-      }
-    }
-    recompute()
-    const ro = new ResizeObserver(recompute)
-    ro.observe(container)
-    if (surfaceRef.current) ro.observe(surfaceRef.current)
-    return () => ro.disconnect()
-  }, [vp.width, sections, header, context])
-
-  useEffect(() => {
-    if (!selectedId) return
-    const el = sectionRefs.current.get(selectedId)
-    if (el) el.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
-  }, [selectedId])
+  const registerRef = useSectionRefs(selectedId)
 
   return (
-    <div ref={containerRef} className="bg-muted h-full overflow-auto p-6">
-      {sections.length > 0 && <CanvasEditTip />}
-      <StructureNotice
-        structuralTypes={structuralTypes}
-        sitePreviewAvailable={sitePreviewAvailable}
-      />
-      <div
-        className="mx-auto"
-        style={{ width: vp.width * scale, height: surfaceHeight ?? undefined }}
+    <CanvasScroll>
+      <CanvasSurface
+        breakpoint={viewport}
+        zoom={zoom}
+        onScaleChange={onScaleChange}
+        onCanvasElement={onCanvasElement}
+        chrome={
+          <>
+            {sections.length > 0 && <CanvasEditTip />}
+            <StructureNotice
+              structuralTypes={structuralTypes}
+              sitePreviewAvailable={sitePreviewAvailable}
+            />
+          </>
+        }
       >
-        <div
-          ref={surfaceRef}
-          className="prenta-canvas border-border bg-card origin-top overflow-hidden rounded-xl border shadow-sm"
-          style={{ width: vp.width, transform: `scale(${scale})`, transformOrigin: 'top left' }}
-        >
-          <PostHeader config={header} context={context} />
-          {sections.length === 0 ? (
-            <EmptyBody onAddSection={onAddSection} />
-          ) : (
-            sections.map((section) => (
-              <SectionRenderer
-                key={section.id}
-                section={section}
-                context={context}
-                editable
-                selected={section.id === selectedId}
-                onSelect={onSelect}
-                registerRef={registerRef}
-              />
-            ))
-          )}
-        </div>
-      </div>
-    </div>
+        <PostHeader config={header} context={context} />
+        {sections.length === 0 ? (
+          <EmptyBody onAddSection={onAddSection} />
+        ) : (
+          sections.map((section) => (
+            <SectionRenderer
+              key={section.id}
+              section={section}
+              context={context}
+              editable
+              selected={section.id === selectedId}
+              onSelect={onSelect}
+              registerRef={registerRef}
+            />
+          ))
+        )}
+      </CanvasSurface>
+    </CanvasScroll>
   )
 }