@beyondwork/docx-react-component 1.0.52 → 1.0.54

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

@@ -0,0 +1,274 @@
+/**
+ * TwPageChromeEntry — memo-wrapped per-page chrome subtree.
+ *
+ * Extracted from `TwPageStackChromeLayer`'s per-page `.map()` so that
+ * `React.memo` can skip re-renders for pages whose `page` reference is
+ * stable (guaranteed post-D1+B2 for pages past the splice-convergence
+ * point).  Rect values are compared structurally (topPx / bottomPx /
+ * pageId) because `resolvePageOverlayRects` allocates new objects each
+ * measurement pass even when positions haven't changed.
+ *
+ * Block arrays and click-handler callbacks are memoized on
+ * `(page, renderFrameRevision)` so they don't create new references
+ * when the page is unchanged.
+ */
+
+import React from "react";
+import type {
+  EditorStoryTarget,
+  PublicPageNode,
+  SurfaceTableRowSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types.ts";
+import type { PageOverlayRect } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
+import { TwTableContinuationHeader } from "../chrome-overlay/tw-table-continuation-header.tsx";
+import { FRAME_PX_PER_TWIP_AT_96DPI } from "../tw-review-workspace.tsx";
+import { TwPageHeaderBand } from "./tw-page-header-band.tsx";
+import { TwPageFooterBand } from "./tw-page-footer-band.tsx";
+import { TwFootnoteArea } from "./tw-footnote-area.tsx";
+
+export interface TwPageChromeEntryProps {
+  rect: PageOverlayRect;
+  pageIndex: number;
+  page: PublicPageNode;
+  facet: WordReviewEditorLayoutFacet;
+  activeStory: EditorStoryTarget;
+  onOpenStory?: (target: EditorStoryTarget) => void;
+  visiblePageIndexRange?: { start: number; end: number } | null;
+  renderFrameRevision: number;
+}
+
+function TwPageChromeEntryInner({
+  rect,
+  pageIndex,
+  page,
+  facet,
+  activeStory,
+  onOpenStory,
+  visiblePageIndexRange,
+  renderFrameRevision,
+}: TwPageChromeEntryProps): React.ReactElement {
+  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];
+
+  // All hooks must be called unconditionally before any early return.
+  const headerBlocks = React.useMemo(
+    () =>
+      headerStory
+        ? facet.getStoryBlocksForRegion(pageIndex, "header").map((b) => b.blockSnapshot)
+        : [],
+    // `page` as dependency captures per-page reference stability (D1+B2):
+    // when page ref is stable, the memo doesn't re-run even if revision ticks.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  const footerBlocks = React.useMemo(
+    () =>
+      footerStory
+        ? facet.getStoryBlocksForRegion(pageIndex, "footer").map((b) => b.blockSnapshot)
+        : [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  const footnoteBlocks = React.useMemo(
+    () =>
+      footnoteRegion
+        ? facet
+            .getStoryBlocksForRegion(pageIndex, "footnote-area")
+            .map((b) => b.blockSnapshot)
+        : [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  // Continuation table header entries: only non-empty for continuation pages
+  // of multi-page tables (isContinuationPage && repeatedHeaderRows.length > 0).
+  const continuationTableEntries = React.useMemo((): Array<{
+    blockId: string;
+    headerRows: readonly SurfaceTableRowSnapshot[];
+  }> => {
+    const bodyBlocks = facet.getStoryBlocksForRegion(pageIndex, "body");
+    const entries: Array<{
+      blockId: string;
+      headerRows: readonly SurfaceTableRowSnapshot[];
+    }> = [];
+    for (const { blockSnapshot } of bodyBlocks) {
+      if (blockSnapshot.kind !== "table") continue;
+      const plan = facet.getTableRenderPlan(blockSnapshot.blockId, pageIndex);
+      if (!plan || plan.repeatedHeaderRows.length === 0) continue;
+      const headerRows = plan.repeatedHeaderRows
+        .map((ref) => blockSnapshot.rows[ref.sourceRowIndex])
+        .filter((r): r is SurfaceTableRowSnapshot => r !== undefined);
+      if (headerRows.length > 0) {
+        entries.push({ blockId: blockSnapshot.blockId, headerRows });
+      }
+    }
+    return entries;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [facet, pageIndex, page, renderFrameRevision]);
+
+  const handleHeaderClick = React.useCallback(
+    () => headerStory && onOpenStory?.(headerStory),
+    [onOpenStory, headerStory],
+  );
+
+  const handleFooterClick = React.useCallback(
+    () => footerStory && onOpenStory?.(footerStory),
+    [onOpenStory, footerStory],
+  );
+
+  const frameHeightPx = rect.bottomPx - rect.topPx;
+
+  // Viewport cull — lightweight placeholder outside the visible range.
+  const isCulled =
+    visiblePageIndexRange !== null &&
+    visiblePageIndexRange !== undefined &&
+    (pageIndex < visiblePageIndexRange.start || pageIndex >= visiblePageIndexRange.end);
+
+  if (isCulled) {
+    return (
+      <div
+        data-page-chrome-frame=""
+        data-page-index={pageIndex}
+        data-page-chrome-culled=""
+        style={{
+          position: "absolute",
+          top: `${rect.topPx}px`,
+          left: 0,
+          width: "100%",
+          height: `${frameHeightPx}px`,
+          pointerEvents: "none",
+        }}
+      />
+    );
+  }
+
+  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);
+
+  // L6d.U1 — 1-based section label for the active-band ribbon.  The
+  // `sectionIndex` on the page is 0-based; reviewers expect "Section 1"
+  // not "Section 0", matching Word's section-break dialog numbering.
+  const sectionNumber = (page.sectionIndex ?? 0) + 1;
+  const headerSectionLabel = `Header — Section ${sectionNumber}`;
+  const footerSectionLabel = `Footer — Section ${sectionNumber}`;
+  const headerActive = headerStory && isActiveStoryMatch(activeStory, headerStory);
+  const footerActive = footerStory && isActiveStoryMatch(activeStory, footerStory);
+
+  return (
+    <div
+      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={Boolean(headerActive)}
+          sectionLabel={headerActive ? headerSectionLabel : undefined}
+          onClick={handleHeaderClick}
+        />
+      ) : null}
+      {footerRegion && footerStory ? (
+        <TwPageFooterBand
+          pageIndex={pageIndex}
+          blocks={footerBlocks}
+          bottomPx={px(layout.footerMargin ?? 720)}
+          leftPx={bandLeftPx}
+          widthPx={bandWidthPx}
+          bandHeightPx={px(footerRegion.heightTwips)}
+          isActiveSlot={Boolean(footerActive)}
+          sectionLabel={footerActive ? footerSectionLabel : undefined}
+          onClick={handleFooterClick}
+        />
+      ) : null}
+      {footnoteRegion ? (
+        <TwFootnoteArea
+          pageIndex={pageIndex}
+          blocks={footnoteBlocks}
+          topPx={px(footnoteRegion.originTwips - layout.marginTop)}
+          leftPx={bandLeftPx}
+          widthPx={px(footnoteRegion.widthTwips)}
+          heightPx={px(footnoteRegion.heightTwips)}
+        />
+      ) : null}
+      {continuationTableEntries.map(({ blockId, headerRows }) => (
+        <TwTableContinuationHeader
+          key={`table-cont-${blockId}`}
+          blockId={blockId}
+          pageIndex={pageIndex}
+          facet={facet}
+          headerRows={headerRows}
+          pxPerTwip={FRAME_PX_PER_TWIP_AT_96DPI}
+          bodyOriginTopPx={px(layout.marginTop)}
+        />
+      ))}
+    </div>
+  );
+}
+
+function propsAreEqual(
+  prev: TwPageChromeEntryProps,
+  next: TwPageChromeEntryProps,
+): boolean {
+  return (
+    prev.pageIndex === next.pageIndex &&
+    prev.page === next.page &&
+    prev.facet === next.facet &&
+    prev.activeStory === next.activeStory &&
+    prev.onOpenStory === next.onOpenStory &&
+    prev.visiblePageIndexRange === next.visiblePageIndexRange &&
+    prev.renderFrameRevision === next.renderFrameRevision &&
+    prev.rect.topPx === next.rect.topPx &&
+    prev.rect.bottomPx === next.rect.bottomPx &&
+    prev.rect.pageId === next.rect.pageId
+  );
+}
+
+export const TwPageChromeEntry = React.memo(TwPageChromeEntryInner, propsAreEqual);
+
+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;
+  }
+  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;
+}

package/src/ui-tailwind/page-stack/tw-page-footer-band.tsx

@@ -27,11 +27,16 @@ export interface TwPageFooterBandProps {
   widthPx: number;
   /** True when this band is the active-story slot. Renders portal target instead of read-only DOM. */
   isActiveSlot: boolean;
+  /**
+   * Lane 6d.U1 — section label for the active-band ribbon (e.g. "Footer — Section 1").
+   * Only rendered when `isActiveSlot` is true.
+   */
+  sectionLabel?: string;
   onClick: () => void;
   "data-testid"?: string;
 }
 
-export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
+export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
   pageIndex,
   blocks,
   bandHeightPx,
@@ -39,13 +44,16 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
   leftPx,
   widthPx,
   isActiveSlot,
+  sectionLabel,
   onClick,
   "data-testid": testId,
 }) => {
   return (
     <div
+      className="wre-page-band"
       data-page-band="footer"
       data-page-index={pageIndex}
+      data-active={isActiveSlot ? "true" : undefined}
       data-testid={testId}
       onClick={onClick}
       style={{
@@ -57,6 +65,11 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
         cursor: "pointer",
       }}
     >
+      {isActiveSlot && sectionLabel ? (
+        <span className="wre-page-band__label" data-kind="page-band-label">
+          {sectionLabel}
+        </span>
+      ) : null}
       {isActiveSlot ? (
         <div
           data-pm-portal-slot
@@ -68,6 +81,6 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
       )}
     </div>
   );
-};
+});
 
 export default TwPageFooterBand;

package/src/ui-tailwind/page-stack/tw-page-header-band.tsx

@@ -28,11 +28,16 @@ export interface TwPageHeaderBandProps {
   widthPx: number;
   /** True when this band is the active-story slot. Renders portal target instead of read-only DOM. */
   isActiveSlot: boolean;
+  /**
+   * Lane 6d.U1 — section label for the active-band ribbon (e.g. "Header — Section 1").
+   * Only rendered when `isActiveSlot` is true.
+   */
+  sectionLabel?: string;
   onClick: () => void;
   "data-testid"?: string;
 }
 
-export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
+export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
   pageIndex,
   blocks,
   bandHeightPx,
@@ -40,13 +45,16 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
   leftPx,
   widthPx,
   isActiveSlot,
+  sectionLabel,
   onClick,
   "data-testid": testId,
 }) => {
   return (
     <div
+      className="wre-page-band"
       data-page-band="header"
       data-page-index={pageIndex}
+      data-active={isActiveSlot ? "true" : undefined}
       data-testid={testId}
       onClick={onClick}
       style={{
@@ -58,6 +66,11 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
         cursor: "pointer",
       }}
     >
+      {isActiveSlot && sectionLabel ? (
+        <span className="wre-page-band__label" data-kind="page-band-label">
+          {sectionLabel}
+        </span>
+      ) : null}
       {isActiveSlot ? (
         <div
           data-pm-portal-slot
@@ -69,6 +82,6 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
       )}
     </div>
   );
-};
+});
 
 export default TwPageHeaderBand;

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

@@ -77,11 +77,8 @@ import {
   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";
+import { TwPageChromeEntry } from "./tw-page-chrome-entry.tsx";
 
 /**
  * Minimal structural type for the PM `EditorView` handle consumed by
@@ -364,120 +361,31 @@ export const TwPageStackChromeLayer: React.FC<TwPageStackChromeLayerProps> = ({
       ref={overlayRootRef}
       data-page-stack-chrome-layer=""
       data-testid={testId ?? "page-stack-chrome-layer"}
+      // L6d.U1 — expose the active-story kind so the CSS can dim the
+      // body when an H/F story is being edited and un-dim again when
+      // the active story is the main body.
+      data-story-active={
+        activeStory.kind === "header" || activeStory.kind === "footer"
+          ? activeStory.kind
+          : undefined
+      }
       style={{ position: "absolute", inset: 0, pointerEvents: "none" }}
     >
       {rects.map((rect, pageIndex) => {
         const page = facet.getPage(pageIndex);
         if (!page) return null;
-
-        // L7 Phase 2.8 — viewport cull. Pages outside the visible range
-        // (plus overscan) render an empty frame wrapper: the
-        // `data-page-chrome-frame` + `data-page-index` attributes stay
-        // put so downstream DOM queries (portal-slot, test hooks) keep
-        // working, but the four heavy React subtrees below do not mount.
-        const frameHeightPxForCull = rect.bottomPx - rect.topPx;
-        if (
-          visiblePageIndexRange &&
-          (pageIndex < visiblePageIndexRange.start ||
-            pageIndex >= visiblePageIndexRange.end)
-        ) {
-          return (
-            <div
-              key={`page-chrome-${rect.pageId}`}
-              data-page-chrome-frame=""
-              data-page-index={pageIndex}
-              data-page-chrome-culled=""
-              style={{
-                position: "absolute",
-                top: `${rect.topPx}px`,
-                left: 0,
-                width: "100%",
-                height: `${frameHeightPxForCull}px`,
-                pointerEvents: "none",
-              }}
-            />
-          );
-        }
-
-        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
+          <TwPageChromeEntry
             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>
+            rect={rect}
+            pageIndex={pageIndex}
+            page={page}
+            facet={facet}
+            activeStory={activeStory}
+            onOpenStory={onOpenStory}
+            visiblePageIndexRange={visiblePageIndexRange}
+            renderFrameRevision={renderFrameRevision}
+          />
         );
       })}
       <TwEndnoteArea blocks={endnoteBlocks} />
@@ -485,40 +393,4 @@ export const TwPageStackChromeLayer: React.FC<TwPageStackChromeLayerProps> = ({
   );
 };
 
-/**
- * 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;