@beyondwork/docx-react-component 1.0.42 → 1.0.43

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -17,6 +17,7 @@ import type {
   ActiveListContext,
   CommentSidebarThreadSnapshot,
   DocumentNavigationSnapshot,
+  EditorStoryTarget,
   EditorViewStateSnapshot,
   FormattingStateSnapshot,
   FormattingAlignment,
@@ -157,6 +158,16 @@ export interface TwReviewWorkspaceProps {
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  /** P9g — live collab session for the `"collab"` chrome preset's top nav. */
+  collabSession?: import("../runtime/collab-session.ts").CollabSession;
+  collabTransportStatus?: import("../api/awareness-identity-types.ts").TransportStatus;
+  collabActorId?: string;
+  collabSendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
   reviewQueue?: ReviewQueueSnapshot;
   documentContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
   selectionContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
@@ -278,7 +289,18 @@ export interface TwReviewWorkspaceProps {
   onAcceptAllChanges?: () => void;
   onRejectAllChanges?: () => void;
   onCloseStory?: () => void;
+  /**
+   * @deprecated P8.11 — the workspace no longer renders a workspace-level
+   * header band with an "Edit header" button; per-page header bands route
+   * clicks via `onOpenStory` / `runtime.openStory` directly.  The prop
+   * remains optional for one release so existing hosts continue to
+   * compile; supplying it emits a `console.warn` on mount.
+   */
   onOpenHeaderStory?: () => void;
+  /**
+   * @deprecated P8.11 — see `onOpenHeaderStory`.  Footer variant of the
+   * same deprecation.
+   */
   onOpenFooterStory?: () => void;
   /**
    * Open a header/footer story for a specific page.  Called when the user
@@ -288,6 +310,13 @@ export interface TwReviewWorkspaceProps {
    */
   onOpenHeaderStoryForPage?: (pageIndex: number) => void;
   onOpenFooterStoryForPage?: (pageIndex: number) => void;
+  /**
+   * P8.11 — fired when a per-page chrome band (header / footer) is
+   * clicked to promote it into the active editing surface.  Wire to
+   * `runtime.openStory(target)`; the chrome layer's portal mechanism
+   * then reparents the PM surface into the matching band's active slot.
+   */
+  onOpenStory?: (target: EditorStoryTarget) => void;
   onSetParagraphIndentation?: (indentation: {
     left?: number;
     right?: number;
@@ -384,6 +413,17 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   } as TwReviewWorkspaceProps & EditorCommandBag;
   const { snapshot, viewState } = props;
   const selectionToolbarRootRef = useRef<HTMLDivElement>(null);
+  // P8.11 — body slot wrapping `{props.document}` (the PM surface) + scroll
+  // root ref.  The chrome layer's `TwPageStackChromeLayer` needs both to
+  // measure per-page rects and to reparent PM's DOM node across band
+  // portals when `activeStory` changes.  See comment near the body slot
+  // in the render tree below.
+  const bodySlotRef = useRef<HTMLDivElement | null>(null);
+  const scrollRootRef = useRef<HTMLDivElement | null>(null);
+  const [pmSurfaceElement, setPmSurfaceElement] =
+    useState<HTMLElement | null>(null);
+  const [pageStackScrollRoot, setPageStackScrollRoot] =
+    useState<HTMLElement | null>(null);
   const caps = props.capabilities;
   const isPageWorkspace = props.workspaceMode === "page";
   const markupDisplay = props.markupDisplay;
@@ -640,8 +680,10 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [props.layoutFacet, selectionPosition, snapshot.activeStory, renderFrameRevision]);
-  const headerBandLabel = resolvePageBandLabel("header", snapshot.activeStory);
-  const footerBandLabel = resolvePageBandLabel("footer", snapshot.activeStory);
+  // P8.11 — `headerBandLabel` / `footerBandLabel` retired along with the
+  // workspace-level bands.  Per-page bands in `TwPageStackChromeLayer`
+  // render the actual header / footer story blocks via
+  // `TwRegionBlockRenderer`, so a label row is no longer meaningful here.
   const hidePageBorderForActiveEditing =
     isPageWorkspace &&
     snapshot.activeStory.kind === "main" &&
@@ -708,6 +750,88 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     }
   }, [isPageWorkspace, snapshot.activeStory.kind]);
 
+  // P8.11 — capture the scroll-root DOM element on mount so the chrome
+  // overlay's `TwPageStackChromeLayer` can measure per-page rects and
+  // observe DOM mutations.  `scrollRootRef` is attached to the existing
+  // `[data-wre-scroll-root]` container; rely on a mount effect rather
+  // than a ref callback so render-time state stays cheap.
+  useEffect(() => {
+    if (scrollRootRef.current !== pageStackScrollRoot) {
+      setPageStackScrollRoot(scrollRootRef.current);
+    }
+    // A `useEffect` re-runs after every render; the comparison guard
+    // keeps `setPageStackScrollRoot` from firing every commit.  The
+    // scroll-root identity only changes when the component re-mounts.
+  });
+
+  // P8.11 — capture the PM surface DOM element.  The ProseMirror surface
+  // mounts inside `bodySlotRef` on its own schedule (the PM constructor
+  // runs inside the `TwProseMirrorSurface` child component).  A
+  // `MutationObserver` scoped to the body slot's `childList` picks up
+  // the PM root on first commit; once captured, the chrome layer owns
+  // reparent state (including portal-slot promotion), so we skip
+  // further updates unless PM is actually disconnected from the
+  // document (e.g. session/document swap tearing PM down).
+  useEffect(() => {
+    const slot = bodySlotRef.current;
+    if (!slot) return undefined;
+
+    // If we already hold a live reference, the chrome layer may have
+    // portaled PM into a per-page band — PM has left `bodySlotRef` but
+    // is still connected to the document.  We keep the reference until
+    // the node is fully disconnected.
+    if (pmSurfaceElement && pmSurfaceElement.isConnected) {
+      return undefined;
+    }
+
+    const readPm = (): HTMLElement | null =>
+      slot.querySelector<HTMLElement>(".ProseMirror");
+
+    const current = readPm();
+    if (current !== pmSurfaceElement) {
+      setPmSurfaceElement(current);
+    }
+    const runtime = slot.ownerDocument?.defaultView as
+      | (Window & { MutationObserver?: typeof MutationObserver })
+      | null;
+    if (!runtime?.MutationObserver) return undefined;
+    const observer = new runtime.MutationObserver(() => {
+      const next = readPm();
+      if (next !== null && next !== pmSurfaceElement) {
+        setPmSurfaceElement(next);
+      }
+    });
+    // `childList: true, subtree: false` — we only care when children of
+    // the body slot change (e.g. PM is added for the first time).
+    // Subtree mutations (PM's own edits) are not our concern and would
+    // fire on every keystroke.
+    observer.observe(slot, { childList: true, subtree: false });
+    return () => observer.disconnect();
+  }, [pmSurfaceElement]);
+
+  // P8.11 — deprecation shim for the legacy `onOpenHeaderStory` /
+  // `onOpenFooterStory` props.  Per-page chrome bands route clicks via
+  // `onOpenStory` + `runtime.openStory` directly; the workspace-level
+  // bands that consumed these callbacks are gone.  Kept optional for one
+  // release so existing hosts compile; a mount-time `console.warn` nudges
+  // them toward `onOpenStory`.
+  useEffect(() => {
+    if (props.onOpenHeaderStory) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[docx-react-component] `onOpenHeaderStory` is deprecated. Per-page header bands route clicks via runtime.openStory directly. (P8)",
+      );
+    }
+    if (props.onOpenFooterStory) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[docx-react-component] `onOpenFooterStory` is deprecated. Per-page footer bands route clicks via runtime.openStory directly. (P8)",
+      );
+    }
+    // Mount-once: we only want to nudge hosts at startup, not per render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   useEffect(() => {
     if (typeof window === "undefined") {
       return;
@@ -818,6 +942,20 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           <div className="px-3 pt-3">
             <ChromePresetToolbar
               chromePreset={chromePreset}
+              {...(props.collabSession ? { collabSession: props.collabSession } : {})}
+              {...(props.collabTransportStatus
+                ? { collabTransportStatus: props.collabTransportStatus }
+                : {})}
+              {...(props.activeCommentId !== undefined
+                ? { activeCommentId: props.activeCommentId }
+                : {})}
+              {...(props.collabActorId !== undefined
+                ? { collabActorId: props.collabActorId }
+                : {})}
+              {...(props.collabSendBaseline
+                ? { collabSendBaseline: props.collabSendBaseline }
+                : {})}
+              chromeOptionsResolved={chromeOptions}
               capabilities={caps}
               compatibility={snapshot.compatibility}
               warnings={snapshot.warnings}
@@ -1076,6 +1214,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           {/* Document column */}
           <div className="flex flex-1 flex-col min-w-0">
             <div
+              ref={scrollRootRef}
               className="flex-1 overflow-y-auto bg-surface"
               data-wre-scroll-root="true"
             >
@@ -1345,25 +1484,6 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                           }
                         : pageChromeModel.documentGridStyle}
                     >
-                      {isPageWorkspace && chromeVisibility.pageChrome ? (
-                        <div
-                          data-testid="page-header-band"
-                          className="relative z-10 flex items-center justify-between border-b border-border/50 bg-surface/45 px-4 text-[11px] text-secondary backdrop-blur-[1px]"
-                          style={pageShellMetrics.headerBandStyle}
-                        >
-                          <span className="uppercase tracking-[0.12em] text-tertiary">{headerBandLabel}</span>
-                          {snapshot.pageLayout?.headerVariants[0] ? (
-                            <button
-                              type="button"
-                              aria-label="Open header story"
-                              onClick={props.onOpenHeaderStory}
-                              className="rounded-md px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                            >
-                              Edit header
-                            </button>
-                          ) : null}
-                        </div>
-                      ) : null}
                       {isPageWorkspace && chromeVisibility.pageChrome && pageChromeModel.showPageBorder && !hidePageBorderForActiveEditing ? (
                         <div
                           aria-hidden="true"
@@ -1373,15 +1493,23 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                         />
                       ) : null}
                       <div className={isPageWorkspace ? "relative z-10" : "relative"}>
-                        {/* Page chrome (frame borders, header/footer bands,
-                            page-number labels, inter-page separators) is
-                            rendered as in-flow widget decorations inside
-                            the PM surface itself — see
-                            `pm-page-break-decorations.ts`.  That keeps the
-                            chrome perfectly aligned with PM content without
-                            any absolute-positioned overlay that would drift
-                            relative to the browser's line layout. */}
-                        {props.document}
+                        {/* P8.11 — workspace-level header / footer bands
+                            retired.  The PM surface now mounts inside
+                            `data-pm-body-slot`; per-page header, footer,
+                            footnote, and endnote chrome is owned by
+                            `TwPageStackChromeLayer` inside `TwChromeOverlay`
+                            (see below).  When the user clicks a per-page
+                            band, the chrome layer reparents PM's DOM node
+                            into the active band's `data-pm-portal-slot`;
+                            when the user returns to the body, PM slides
+                            back into this wrapper. */}
+                        <div
+                          data-pm-body-slot=""
+                          ref={bodySlotRef}
+                          style={{ width: "100%" }}
+                        >
+                          {props.document}
+                        </div>
                         {props.layoutFacet ? (
                           <TwChromeOverlay
                             facet={props.layoutFacet}
@@ -1410,28 +1538,18 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                                 ? handleScopeCardAskAgent
                                 : undefined
                             }
+                            pageStackScrollRoot={
+                              isPageWorkspace && chromeVisibility.pageChrome
+                                ? pageStackScrollRoot
+                                : undefined
+                            }
+                            renderFrameRevision={renderFrameRevision}
+                            activeStory={snapshot.activeStory}
+                            onOpenStory={props.onOpenStory}
+                            pmSurfaceElement={pmSurfaceElement}
                           />
                         ) : null}
                       </div>
-                      {isPageWorkspace && chromeVisibility.pageChrome ? (
-                        <div
-                          data-testid="page-footer-band"
-                          className="relative z-10 flex items-center justify-between border-t border-border/50 bg-surface/45 px-4 text-[11px] text-secondary backdrop-blur-[1px]"
-                          style={pageShellMetrics.footerBandStyle}
-                        >
-                          <span className="uppercase tracking-[0.12em] text-tertiary">{footerBandLabel}</span>
-                          {snapshot.pageLayout?.footerVariants[0] ? (
-                            <button
-                              type="button"
-                              aria-label="Open footer story"
-                              onClick={props.onOpenFooterStory}
-                              className="rounded-md px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                            >
-                              Edit footer
-                            </button>
-                          ) : null}
-                        </div>
-                      ) : null}
                     </div>
                   </div>
                 </div>
@@ -1717,8 +1835,6 @@ export interface PageShellMetrics {
   frameHeightPx?: number;
   contentInsetStyle: CSSProperties;
   pageFrameStyle: CSSProperties;
-  headerBandStyle: CSSProperties;
-  footerBandStyle: CSSProperties;
 }
 
 function buildPageChromeModel(
@@ -1764,8 +1880,6 @@ export function buildPageShellMetrics(
     return {
       contentInsetStyle: {},
       pageFrameStyle: {},
-      headerBandStyle: {},
-      footerBandStyle: {},
       frameWidthPx: 0,
       frameHeightPx: 0,
     };
@@ -1779,17 +1893,11 @@ export function buildPageShellMetrics(
   const frameHeightPx = Math.round(pageLayout.pageHeight * pxPerTwip);
   const horizontalInsetPx = Math.round(pageLayout.marginLeft * pxPerTwip);
   const horizontalInsetRightPx = Math.round(pageLayout.marginRight * pxPerTwip);
-  // Header BAND height = margin space NOT consumed by header content.
-  // When marginTop == headerMargin, the band has no headroom — floor to
-  // MIN_BAND_HEIGHT_PX so empty bands stay clickable.
-  const headerBandHeightPx = Math.max(
-    MIN_BAND_HEIGHT_PX,
-    Math.round(Math.max(0, pageLayout.marginTop - pageLayout.headerMargin) * pxPerTwip),
-  );
-  const footerBandHeightPx = Math.max(
-    MIN_BAND_HEIGHT_PX,
-    Math.round(Math.max(0, pageLayout.marginBottom - pageLayout.footerMargin) * pxPerTwip),
-  );
+
+  // P8.11 — `headerBandStyle` / `footerBandStyle` removed.  The
+  // workspace-level band divs that consumed them are gone; per-page
+  // bands (rendered by `TwPageStackChromeLayer`) compute their own
+  // heights from the runtime's `PageRegionsSnapshot`.
 
   return {
     contentInsetStyle: {
@@ -1802,12 +1910,6 @@ export function buildPageShellMetrics(
       boxShadow: "0 24px 48px -32px rgba(15, 23, 42, 0.38), 0 8px 20px -18px rgba(15, 23, 42, 0.22)",
       border: "1px solid rgba(148, 163, 184, 0.2)",
     },
-    headerBandStyle: {
-      minHeight: `${headerBandHeightPx}px`,
-    },
-    footerBandStyle: {
-      minHeight: `${footerBandHeightPx}px`,
-    },
     frameWidthPx,
     frameHeightPx,
   };
@@ -1849,30 +1951,6 @@ export function resolveZoomMultiplier(
   );
 }
 
-function resolvePageBandLabel(
-  region: "header" | "footer",
-  activeStory: RuntimeRenderSnapshot["activeStory"],
-): string {
-  const regionLabel = region === "header" ? "header" : "footer";
-  let label: string;
-  if (activeStory.kind !== region) {
-    label = region === "header" ? "Header" : "Footer";
-  } else {
-    switch (activeStory.variant) {
-      case "first":
-        label = `First page ${regionLabel}`;
-        break;
-      case "even":
-        label = `Even page ${regionLabel}`;
-        break;
-      default:
-        label = `Default ${regionLabel}`;
-        break;
-    }
-  }
-  return label;
-}
-
 function buildLineNumberMarkers(
   blocks: readonly SurfaceBlockSnapshot[],
   pages: ReadonlyArray<DocumentNavigationSnapshot["pages"][number]>,