@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/ui-tailwind/page-stack/tw-page-stack-chrome-layer.tsx

@@ -0,0 +1,477 @@
+/**
+ * TwPageStackChromeLayer — per-page chrome overlay sibling of
+ * `TwPageStackOverlayLayer` (P3.b).
+ *
+ * Where the P3.b layer paints the decorative paper-frame rounded-rect
+ * treatment for each page, this layer composes the *content* chrome for
+ * those same pages: header / footer bands, footnote areas, and a
+ * document-end endnote area.  It reuses P3.b's measurement helpers
+ * (`measureWidgetsViaBoundingRect`, `resolvePageOverlayRects`) so the
+ * per-page pixel rectangles stay identical between the two layers.
+ *
+ * Band placement
+ * --------------
+ * For each measured page rect the layer emits one
+ * `<div data-page-chrome-frame data-page-index={i}>` positioned at the
+ * rect's top/height.  Inside the frame, four children conditionally
+ * mount:
+ *
+ *   1. `<TwPageHeaderBand>` — when the page's `regions.header` + the
+ *      resolved `stories.header` both exist.
+ *   2. `<TwPageFooterBand>` — symmetric; uses the page's
+ *      `regions.footer` + `stories.footer`.
+ *   3. `<TwFootnoteArea>` — when `regions.footnotes?.[0]` is non-empty
+ *      (at least one footnote was allocated on this page).  The P8.6
+ *      polish reserves only a single footnote region per page today;
+ *      multi-region split lands later.
+ *   4. Endnotes live OUTSIDE the per-page loop — one
+ *      `<TwEndnoteArea>` sibling renders after every page frame with
+ *      the document-end endnote bodies (per OOXML
+ *      `w:endnotePr/w:pos="docEnd"`).
+ *
+ * Twip → px conversion uses the same `FRAME_PX_PER_TWIP_AT_96DPI`
+ * constant the outer workspace uses, so band geometry matches the page
+ * frame's physical size exactly.
+ *
+ * Active slot
+ * -----------
+ * When `activeStory` matches a band's resolved story target, the band
+ * renders in "active slot" mode — it emits a
+ * `data-pm-portal-slot` target instead of a read-only
+ * `TwRegionBlockRenderer`.
+ *
+ * PM portal reparent (P8.10)
+ * --------------------------
+ * When `pmSurfaceElement` is supplied, the layer runs a
+ * `useLayoutEffect` that keeps the PM DOM node parented to whichever
+ * band currently owns the active slot.  The effect:
+ *
+ *   1. Resolves the active target via
+ *      `overlayRoot.querySelector("[data-pm-portal-slot]")` — if the
+ *      current `activeStory` matches one or more visible bands, every
+ *      matching band emits a slot; we pick the first in document
+ *      order and park PM there.
+ *   2. Otherwise falls back to the body slot
+ *      (`[data-pm-body-slot]`) by walking up from the scroll root /
+ *      owner document.
+ *   3. If `pmSurfaceElement.parentElement !== target`, captures the
+ *      PM selection state, calls `target.appendChild(pmSurfaceElement)`,
+ *      then restores selection + focus when the PM view is supplied.
+ *
+ * `useLayoutEffect` is deliberate — running after commit but before
+ * paint avoids a visible flash where PM briefly appears in the wrong
+ * slot (or in neither slot, since React wipes the old portal-slot
+ * container).  Selection capture/restore is best-effort: when the PM
+ * view handle isn't supplied (e.g. early P8.10 before P8.11 threads it
+ * through the workspace), the DOM reparent still happens — the caller
+ * simply accepts that selection may land at offset 0 after a swap.
+ */
+
+import React from "react";
+import type {
+  EditorStoryTarget,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types.ts";
+import {
+  measureWidgetsViaBoundingRect,
+  resolvePageOverlayRects,
+  type PageOverlayRect,
+} from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
+import { TwPageHeaderBand } from "./tw-page-header-band.tsx";
+import { TwPageFooterBand } from "./tw-page-footer-band.tsx";
+import { TwFootnoteArea } from "./tw-footnote-area.tsx";
+import { TwEndnoteArea } from "./tw-endnote-area.tsx";
+import { FRAME_PX_PER_TWIP_AT_96DPI } from "../tw-review-workspace.tsx";
+
+/**
+ * Minimal structural type for the PM `EditorView` handle consumed by
+ * the portal-swap effect.  We only read `.hasFocus()` and optionally
+ * `.focus()` so we avoid a static dependency on `prosemirror-view` in
+ * this chrome file — the production call site threads the real
+ * `EditorView` via the same interface.
+ */
+export interface PmPortalView {
+  hasFocus: () => boolean;
+  focus: () => void;
+}
+
+export interface TwPageStackChromeLayerProps {
+  /** Layout facet — source of per-page regions, stories, and blocks. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Scroll root whose `[data-page-frame-*]` markers drive per-page rects. */
+  scrollRoot: HTMLElement | null;
+  /**
+   * Render-frame revision tick incremented on `layout_recomputed`,
+   * `incremental_relayout`, `render_frame_ready`, or `zoom_changed`.
+   * Bumping re-measures per-page rects.
+   */
+  renderFrameRevision: number;
+  /** Current active story target — used to promote the matching band to slot mode. */
+  activeStory: EditorStoryTarget;
+  /** Fires when a band is clicked.  Task 10 routes PM into the matching band. */
+  onOpenStory?: (target: EditorStoryTarget) => void;
+  /**
+   * PM surface DOM element (typically `view.dom`, i.e. the outer
+   * `.ProseMirror` div).  When supplied, the layer reparents this
+   * element across band slots via imperative `appendChild` in a
+   * `useLayoutEffect`: it becomes a child of the active band's
+   * `[data-pm-portal-slot]` when `activeStory` matches a visible band,
+   * or returns to `[data-pm-body-slot]` when `activeStory.kind` is
+   * `"main"`.  When omitted, the layer skips the reparent step — useful
+   * for the pre-P8.10 callers that only consume the read-only chrome.
+   */
+  pmSurfaceElement?: HTMLElement | null;
+  /**
+   * Optional PM view handle — lets the layer check `hasFocus()` before
+   * the reparent and re-focus PM afterwards so mid-edit clicks don't
+   * silently drop focus.  When omitted the layer still reparents the
+   * DOM element; only the refocus step is skipped.
+   */
+  pmView?: PmPortalView | null;
+  /** Optional test id applied to the layer root. */
+  "data-testid"?: string;
+}
+
+export const TwPageStackChromeLayer: React.FC<TwPageStackChromeLayerProps> = ({
+  facet,
+  scrollRoot,
+  renderFrameRevision,
+  activeStory,
+  onOpenStory,
+  pmSurfaceElement,
+  pmView,
+  "data-testid": testId,
+}) => {
+  const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
+  const overlayRootRef = React.useRef<HTMLDivElement | null>(null);
+  const rafHandleRef = React.useRef<number | null>(null);
+
+  // --------------------------------------------------------------------
+  // rAF-debounced refresh.  Mirrors the pattern in
+  // `TwPageStackOverlayLayer` (see that file's P14 hardening note) —
+  // multiple triggers within the same animation frame coalesce to one
+  // measurement pass.
+  // --------------------------------------------------------------------
+
+  const refreshRectsNow = React.useCallback(() => {
+    if (!scrollRoot) {
+      setRects([]);
+      return;
+    }
+    const origin = overlayRootRef.current;
+    const pageCount = facet.getPageCount();
+    if (origin) {
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin);
+      const originRect = origin.getBoundingClientRect();
+      // jsdom + SSR never populate `origin.clientHeight` (no layout
+      // pass).  Fall back to `originRect.height`, and if that's also
+      // zero, to `scrollRoot.clientHeight` so the last page rect still
+      // resolves (otherwise pages whose bottom edge depends on the
+      // scroll-height fallback would be silently dropped).
+      const scrollHeight =
+        origin.clientHeight > 0
+          ? origin.clientHeight
+          : originRect.height > 0
+            ? originRect.height
+            : scrollRoot.clientHeight;
+      setRects(
+        resolvePageOverlayRects({
+          widgets,
+          pageCount,
+          scrollHeight,
+        }),
+      );
+    } else {
+      setRects(resolvePageOverlayRects([scrollRoot, pageCount]));
+    }
+  }, [facet, scrollRoot]);
+
+  const refreshRects = React.useCallback(() => {
+    if (!scrollRoot) {
+      setRects([]);
+      return;
+    }
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & {
+          requestAnimationFrame?: (cb: () => void) => number;
+          cancelAnimationFrame?: (handle: number) => void;
+        })
+      | null;
+    const raf = runtime?.requestAnimationFrame;
+    if (!raf) {
+      refreshRectsNow();
+      return;
+    }
+    if (rafHandleRef.current !== null) return;
+    rafHandleRef.current = raf(() => {
+      rafHandleRef.current = null;
+      refreshRectsNow();
+    });
+  }, [scrollRoot, refreshRectsNow]);
+
+  React.useEffect(() => {
+    refreshRects();
+    return () => {
+      const runtime = scrollRoot?.ownerDocument?.defaultView as
+        | (Window & { cancelAnimationFrame?: (h: number) => void })
+        | null;
+      if (rafHandleRef.current !== null && runtime?.cancelAnimationFrame) {
+        runtime.cancelAnimationFrame(rafHandleRef.current);
+        rafHandleRef.current = null;
+      }
+    };
+  }, [refreshRects, renderFrameRevision, scrollRoot]);
+
+  // Observe scroll-root size changes.
+  React.useEffect(() => {
+    if (!scrollRoot) return;
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & { ResizeObserver?: typeof ResizeObserver })
+      | null;
+    if (!runtime?.ResizeObserver) return;
+    const observer = new runtime.ResizeObserver(() => refreshRects());
+    observer.observe(scrollRoot);
+    return () => observer.disconnect();
+  }, [scrollRoot, refreshRects]);
+
+  // Observe DOM mutations on the scroll root so PM re-renders
+  // (page-break widgets added / removed) re-trigger measurement.
+  //
+  // Matches `TwPageStackOverlayLayer`:
+  //   - `subtree: false` (P14.e) avoids per-keystroke character-data
+  //     churn — page boundaries only shift on childList changes.
+  //   - Self-mutation filter (P14.a) ignores mutations whose targets
+  //     live inside the overlay root itself, which prevents the
+  //     `setRects` → reconciliation → mutation callback loop.
+  React.useEffect(() => {
+    if (!scrollRoot) return;
+    const runtime = scrollRoot.ownerDocument?.defaultView as
+      | (Window & { MutationObserver?: typeof MutationObserver })
+      | null;
+    if (!runtime?.MutationObserver) return;
+    const observer = new runtime.MutationObserver((records) => {
+      const overlay = overlayRootRef.current;
+      if (overlay) {
+        const allSelf = records.every(
+          (r) => r.target instanceof Node && overlay.contains(r.target),
+        );
+        if (allSelf) return;
+      }
+      refreshRects();
+    });
+    observer.observe(scrollRoot, { childList: true, subtree: false });
+    return () => observer.disconnect();
+  }, [scrollRoot, refreshRects]);
+
+  // --------------------------------------------------------------------
+  // P8.10 — PM portal reparent.
+  //
+  // When `pmSurfaceElement` is supplied, keep the PM DOM node parented
+  // to the band whose story matches `activeStory`; otherwise return
+  // it to the body slot.  `useLayoutEffect` runs after React commits
+  // the band re-render (so the portal-slot div exists) but before the
+  // browser paints (so the swap is invisible to the user).
+  //
+  // Effect dependencies:
+  //   - `pmSurfaceElement` — identity change means a different PM DOM
+  //     node needs to be parented; we re-run so the fresh node lands
+  //     in the right slot.
+  //   - `activeStory` — the identity of the active band changes.
+  //   - `rects` — per-page rects refreshing may cause the active band
+  //     to mount for the first time (e.g. page 2's band wasn't
+  //     measured on the previous pass), so we re-check the portal slot.
+  // --------------------------------------------------------------------
+  React.useLayoutEffect(() => {
+    if (!pmSurfaceElement) return;
+    const overlay = overlayRootRef.current;
+    // Find a portal slot the ChromeLayer currently exposes.  Every
+    // visible band whose story equals `activeStory` renders a slot —
+    // so if a header variant repeats across pages, every one of those
+    // pages emits a `[data-pm-portal-slot]` div.  PM is a single DOM
+    // element, so we pick the first slot in document order via
+    // `querySelector` (singular) and park the element there.  The
+    // remaining slot divs stay empty until the next reparent.
+    const activeSlot =
+      overlay?.querySelector<HTMLElement>("[data-pm-portal-slot]") ?? null;
+    // Body slot lives outside the chrome overlay root.  Walk up from
+    // the PM element's owner document so jsdom tests and the real
+    // production host both resolve the same target.
+    const ownerDoc =
+      pmSurfaceElement.ownerDocument ??
+      scrollRoot?.ownerDocument ??
+      overlay?.ownerDocument ??
+      null;
+    const bodySlot =
+      ownerDoc?.querySelector<HTMLElement>("[data-pm-body-slot]") ?? null;
+    const target = activeSlot ?? bodySlot;
+    if (!target) return;
+    if (pmSurfaceElement.parentElement === target) return;
+
+    // Capture selection + focus so the reparent is transparent to the
+    // user.  Moving a contenteditable element via `appendChild` drops
+    // the DOM selection range on some browsers; we re-run focus after
+    // the DOM mutation so the runtime-driven selection sync can
+    // restore PM's caret.
+    const hadFocus = pmView?.hasFocus() ?? false;
+    target.appendChild(pmSurfaceElement);
+    if (hadFocus && pmView) {
+      try {
+        pmView.focus();
+      } catch {
+        // Swallow — re-focus is best-effort.  Production PM will
+        // recompute selection from the snapshot on the next
+        // updateState pass.
+      }
+    }
+  }, [pmSurfaceElement, pmView, activeStory, rects, scrollRoot]);
+
+  // --------------------------------------------------------------------
+  // Render
+  // --------------------------------------------------------------------
+
+  const endnoteBlocks = React.useMemo(
+    () =>
+      facet
+        .getDocumentEndnoteBlocks()
+        .map((block) => block.blockSnapshot),
+    // Endnote bodies are cached per-revision at the facet boundary — we
+    // can piggy-back on `renderFrameRevision` to invalidate the local
+    // memo when the facet's revision ticks.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, renderFrameRevision],
+  );
+
+  return (
+    <div
+      ref={overlayRootRef}
+      data-page-stack-chrome-layer=""
+      data-testid={testId ?? "page-stack-chrome-layer"}
+      style={{ position: "absolute", inset: 0, pointerEvents: "none" }}
+    >
+      {rects.map((rect, pageIndex) => {
+        const page = facet.getPage(pageIndex);
+        if (!page) return null;
+
+        const layout = page.layout;
+        const headerStory = page.stories.header;
+        const footerStory = page.stories.footer;
+        const headerRegion = page.regions.header;
+        const footerRegion = page.regions.footer;
+        const footnoteRegion = page.regions.footnotes?.[0];
+
+        const headerBlocks = headerStory
+          ? facet
+              .getStoryBlocksForRegion(pageIndex, "header")
+              .map((b) => b.blockSnapshot)
+          : [];
+        const footerBlocks = footerStory
+          ? facet
+              .getStoryBlocksForRegion(pageIndex, "footer")
+              .map((b) => b.blockSnapshot)
+          : [];
+        const footnoteBlocks = footnoteRegion
+          ? facet
+              .getStoryBlocksForRegion(pageIndex, "footnote-area")
+              .map((b) => b.blockSnapshot)
+          : [];
+
+        const px = (twips: number): number => twips * FRAME_PX_PER_TWIP_AT_96DPI;
+        const bandWidthPx = px(
+          layout.pageWidth - layout.marginLeft - layout.marginRight,
+        );
+        const bandLeftPx = px(layout.marginLeft);
+        const frameHeightPx = rect.bottomPx - rect.topPx;
+
+        return (
+          <div
+            key={`page-chrome-${rect.pageId}`}
+            data-page-chrome-frame=""
+            data-page-index={pageIndex}
+            style={{
+              position: "absolute",
+              top: `${rect.topPx}px`,
+              left: 0,
+              width: "100%",
+              height: `${frameHeightPx}px`,
+              pointerEvents: "none",
+            }}
+          >
+            {headerRegion && headerStory ? (
+              <TwPageHeaderBand
+                pageIndex={pageIndex}
+                blocks={headerBlocks}
+                topPx={px(layout.headerMargin ?? 720)}
+                leftPx={bandLeftPx}
+                widthPx={bandWidthPx}
+                bandHeightPx={px(headerRegion.heightTwips)}
+                isActiveSlot={isActiveStoryMatch(activeStory, headerStory)}
+                onClick={() => onOpenStory?.(headerStory)}
+              />
+            ) : null}
+            {footerRegion && footerStory ? (
+              <TwPageFooterBand
+                pageIndex={pageIndex}
+                blocks={footerBlocks}
+                bottomPx={px(layout.footerMargin ?? 720)}
+                leftPx={bandLeftPx}
+                widthPx={bandWidthPx}
+                bandHeightPx={px(footerRegion.heightTwips)}
+                isActiveSlot={isActiveStoryMatch(activeStory, footerStory)}
+                onClick={() => onOpenStory?.(footerStory)}
+              />
+            ) : null}
+            {footnoteRegion ? (
+              <TwFootnoteArea
+                pageIndex={pageIndex}
+                blocks={footnoteBlocks}
+                topPx={px(footnoteRegion.originTwips - layout.marginTop)}
+                leftPx={bandLeftPx}
+                widthPx={px(footnoteRegion.widthTwips)}
+                heightPx={px(footnoteRegion.heightTwips)}
+              />
+            ) : null}
+          </div>
+        );
+      })}
+      <TwEndnoteArea blocks={endnoteBlocks} />
+    </div>
+  );
+};
+
+/**
+ * Strict equality for two `EditorStoryTarget` values — used to decide
+ * whether a given band should render in active-slot mode.
+ *
+ * For `"main"` the kinds must match; for header/footer the triple
+ * `(relationshipId, variant, sectionIndex)` must match; for footnote /
+ * endnote the `noteId` must match.  Any mismatch returns false.
+ */
+function isActiveStoryMatch(
+  active: EditorStoryTarget,
+  candidate: EditorStoryTarget,
+): boolean {
+  if (active.kind !== candidate.kind) return false;
+  if (active.kind === "main" || candidate.kind === "main") {
+    return active.kind === candidate.kind;
+  }
+  if (active.kind === "footnote" && candidate.kind === "footnote") {
+    return active.noteId === candidate.noteId;
+  }
+  if (active.kind === "endnote" && candidate.kind === "endnote") {
+    return active.noteId === candidate.noteId;
+  }
+  // header / footer — triple match.
+  if (
+    (active.kind === "header" && candidate.kind === "header") ||
+    (active.kind === "footer" && candidate.kind === "footer")
+  ) {
+    return (
+      active.relationshipId === candidate.relationshipId &&
+      active.variant === candidate.variant &&
+      active.sectionIndex === candidate.sectionIndex
+    );
+  }
+  return false;
+}
+
+export default TwPageStackChromeLayer;