@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/ui-tailwind/review-workspace/use-derived-view-state.ts

@@ -0,0 +1,151 @@
+import { useMemo } from "react";
+
+import type {
+  DocumentNavigationSnapshot,
+  RuntimeRenderSnapshot,
+  WordReviewEditorChromeVisibility,
+  ZoomLevel,
+} from "../../api/public-types.ts";
+import type { ActiveSelectionToolModel } from "../../ui/headless/selection-tool-types";
+
+import {
+  buildPageChromeModel,
+  type PageChromeModel,
+} from "./page-chrome.ts";
+import {
+  buildPageShellMetrics,
+  resolveZoomMultiplier,
+  type PageShellMetrics,
+} from "./page-shell-metrics.ts";
+import {
+  resolveActiveParagraphLayout,
+  type ActiveParagraphLayout,
+} from "./paragraph-layout.ts";
+
+export interface UseDerivedViewStateOptions {
+  snapshot: RuntimeRenderSnapshot;
+  documentNavigation: DocumentNavigationSnapshot | undefined;
+  activeSelectionTool: ActiveSelectionToolModel | null | undefined;
+  chromeVisibility: Pick<WordReviewEditorChromeVisibility, "contextToolbars" | "pageChrome">;
+  selectionPosition: number;
+  shouldResolveActiveParagraphLayout: boolean;
+  zoomLevel: ZoomLevel;
+  numericZoomScale: number;
+  viewportWidth: number | undefined;
+  viewportHeight: number | undefined;
+  isPageWorkspace: boolean;
+}
+
+export interface DerivedViewState {
+  activeParagraphLayout: ActiveParagraphLayout | null;
+  pageChromeModel: PageChromeModel;
+  gatedSelectionTool: ActiveSelectionToolModel | null;
+  pageShellMetrics: PageShellMetrics;
+  zoomScale: number;
+  pageZoomBucket: "low" | "base" | "high" | undefined;
+}
+
+/**
+ * Bundle of memoized derived view-state that TwReviewWorkspace feeds
+ * into its chrome + overlay layers:
+ *
+ *   - `activeParagraphLayout` — page-chrome ruler input; resolved only
+ *     when the ruler is visible (layout tools open + page chrome
+ *     present + page workspace mode).
+ *   - `pageChromeModel` — line numbering / page border / grid style.
+ *   - `gatedSelectionTool` — chromeVisibility-scoped view of the host's
+ *     selection tool model.
+ *   - `pageShellMetrics` — real-twip frame + content-inset styles.
+ *   - `zoomScale` — numeric → passthrough; symbolic ("pageWidth" /
+ *     "onePage") → resolved against the active section's real paper
+ *     dimensions via `resolveZoomMultiplier` (P2.c).
+ *   - `pageZoomBucket` — chromeless classification used by
+ *     `TwPageRuler` + zoom controls.
+ */
+export function useDerivedViewState(
+  options: UseDerivedViewStateOptions,
+): DerivedViewState {
+  const {
+    snapshot,
+    documentNavigation,
+    activeSelectionTool,
+    chromeVisibility,
+    selectionPosition,
+    shouldResolveActiveParagraphLayout,
+    zoomLevel,
+    numericZoomScale,
+    viewportWidth,
+    viewportHeight,
+    isPageWorkspace,
+  } = options;
+
+  const activeParagraphLayout = useMemo(
+    () =>
+      shouldResolveActiveParagraphLayout
+        ? resolveActiveParagraphLayout(snapshot.surface, selectionPosition)
+        : null,
+    [selectionPosition, shouldResolveActiveParagraphLayout, snapshot.surface],
+  );
+
+  const pageChromeModel = useMemo(
+    () =>
+      buildPageChromeModel(
+        snapshot.surface,
+        snapshot.pageLayout,
+        documentNavigation,
+        snapshot.activeStory,
+      ),
+    [documentNavigation, snapshot.activeStory, snapshot.pageLayout, snapshot.surface],
+  );
+
+  const gatedSelectionTool = useMemo(() => {
+    if (!activeSelectionTool) return null;
+    if (
+      activeSelectionTool.kind === "structure-context" &&
+      !chromeVisibility.contextToolbars
+    ) {
+      return null;
+    }
+    return activeSelectionTool;
+  }, [activeSelectionTool, chromeVisibility.contextToolbars]);
+
+  const pageShellMetrics = useMemo(
+    () => buildPageShellMetrics(snapshot.pageLayout),
+    [snapshot.pageLayout],
+  );
+
+  const zoomScale = useMemo(() => {
+    if (typeof zoomLevel === "number") return numericZoomScale;
+    return resolveZoomMultiplier(
+      zoomLevel,
+      pageShellMetrics.frameWidthPx ?? 0,
+      pageShellMetrics.frameHeightPx ?? 0,
+      viewportWidth,
+      viewportHeight,
+    );
+  }, [
+    zoomLevel,
+    numericZoomScale,
+    pageShellMetrics.frameWidthPx,
+    pageShellMetrics.frameHeightPx,
+    viewportWidth,
+    viewportHeight,
+  ]);
+
+  const pageZoomBucket: "low" | "base" | "high" | undefined = !isPageWorkspace
+    ? undefined
+    : zoomScale < 1
+      ? "low"
+      : zoomScale > 1
+        ? "high"
+        : "base";
+
+  return {
+    activeParagraphLayout,
+    pageChromeModel,
+    gatedSelectionTool,
+    pageShellMetrics,
+    zoomScale,
+    pageZoomBucket,
+  };
+}

package/src/ui-tailwind/review-workspace/use-diagnostics-signal.ts

@@ -0,0 +1,70 @@
+import { useMemo } from "react";
+
+import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
+import type { SessionCapabilities } from "../../api/public-types";
+
+export interface DiagnosticsSignal {
+  severity: "none" | "info" | "warning" | "blocked";
+  count: number;
+}
+
+export interface UseDiagnosticsSignalOptions {
+  snapshot: RuntimeRenderSnapshot;
+  caps: SessionCapabilities | undefined;
+  preserveOnlyCount: number;
+  blockedReasonsCount: number;
+}
+
+/**
+ * Phase E.1 — diagnostics signal feeds `resolveChromeComposition` so the
+ * `health` rail tab can enter `visibleTabs`. Severity ladder mirrors
+ * `TwAlertBanner`'s precedence (§6.17): blocked export → workflow blocked
+ * → preserve-only / warnings → info.
+ *
+ * Perf — I1 fix: the workspace re-renders on every PM transaction
+ * (inverted-truth architecture — `view.updateState()` replaces PM state
+ * wholesale per commit, per `CLAUDE.md §Performance Invariants #4`).
+ * The derivations below run `Array.prototype.filter` over
+ * `snapshot.compatibility.featureEntries` and `snapshot.warnings`, so
+ * they MUST memoize on structural inputs. One memo for everything the
+ * signal needs keeps the hot path tight.
+ */
+export function useDiagnosticsSignal(
+  options: UseDiagnosticsSignalOptions,
+): DiagnosticsSignal {
+  const { snapshot, caps, preserveOnlyCount, blockedReasonsCount } = options;
+
+  return useMemo(() => {
+    const featureEntries = snapshot.compatibility.featureEntries;
+    const unsupportedFatalCount =
+      caps?.unsupportedFatalCount ??
+      featureEntries.filter((e) => e.featureClass === "unsupported-fatal").length;
+    let infoWarningCount = 0;
+    for (const w of snapshot.warnings) {
+      if (w.severity === "info") infoWarningCount += 1;
+    }
+    const blockingWarningCount = snapshot.warnings.length - infoWarningCount;
+    const count =
+      caps?.healthIssueCount ??
+      preserveOnlyCount + unsupportedFatalCount + snapshot.warnings.length;
+    const severity: "none" | "info" | "warning" | "blocked" =
+      snapshot.compatibility.blockExport || unsupportedFatalCount > 0
+        ? "blocked"
+        : preserveOnlyCount > 0 ||
+            blockingWarningCount > 0 ||
+            blockedReasonsCount > 0
+          ? "warning"
+          : infoWarningCount > 0
+            ? "info"
+            : "none";
+    return { severity, count };
+  }, [
+    snapshot.compatibility.featureEntries,
+    snapshot.compatibility.blockExport,
+    snapshot.warnings,
+    caps?.unsupportedFatalCount,
+    caps?.healthIssueCount,
+    preserveOnlyCount,
+    blockedReasonsCount,
+  ]);
+}

package/src/ui-tailwind/review-workspace/use-grabbed-segment-offsets.ts

@@ -0,0 +1,40 @@
+import { useMemo } from "react";
+
+import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
+
+export interface GrabbedSegmentOffsets {
+  from: number;
+  to: number;
+}
+
+/**
+ * N6 — resolve grabbed-object segment offsets from the surface so the
+ * selection overlay can query the anchor index without a full surface walk.
+ */
+export function useGrabbedSegmentOffsets(
+  snapshot: RuntimeRenderSnapshot,
+): GrabbedSegmentOffsets | null {
+  return useMemo(() => {
+    const objectId = snapshot.grabbedObjectId ?? null;
+    if (!objectId || !snapshot.surface) return null;
+    for (const block of snapshot.surface.blocks) {
+      if (!("segments" in block)) continue;
+      for (const seg of (block as { segments?: unknown[] }).segments ?? []) {
+        const s = seg as {
+          kind?: string;
+          mediaId?: string;
+          from?: number;
+          to?: number;
+        };
+        if (
+          (s.kind === "image" || s.kind === "shape") &&
+          s.mediaId === objectId &&
+          s.from != null
+        ) {
+          return { from: s.from, to: s.to ?? s.from + 1 };
+        }
+      }
+    }
+    return null;
+  }, [snapshot.grabbedObjectId, snapshot.surface]);
+}

package/src/ui-tailwind/review-workspace/use-layout-facet-render-signal.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from "react";
+
+/**
+ * P3.b + P5b + P14.b — subscribe to layout facet events that should
+ * trigger a chrome re-projection (zoom, render frame ready, layout
+ * recomputed / committed, page count changes, measurement backend
+ * ready, etc.) and expose a monotonic revision counter. Consumers
+ * include the counter in dependency arrays of useMemo-backed placement
+ * calculations so they re-run when the layout engine emits new rects.
+ *
+ * Bumps are coalesced through `queueMicrotask` so multiple events in
+ * the same synchronous tick fold into one re-render.
+ */
+export function useLayoutFacetRenderSignal(
+  layoutFacet: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet | undefined,
+): number {
+  const [renderFrameRevision, setRenderFrameRevision] = useState(0);
+
+  useEffect(() => {
+    if (!layoutFacet) return;
+    let pendingBump = false;
+    let cancelled = false;
+    const scheduleBump = () => {
+      if (pendingBump || cancelled) return;
+      pendingBump = true;
+      queueMicrotask(() => {
+        pendingBump = false;
+        if (cancelled) return;
+        setRenderFrameRevision((n) => n + 1);
+      });
+    };
+    const unsub = layoutFacet.subscribe((event) => {
+      switch (event.kind) {
+        case "zoom_changed":
+        case "render_frame_ready":
+        case "layout_recomputed":
+        case "incremental_relayout":
+        case "page_count_changed":
+        case "page_field_dirtied":
+        case "measurement_backend_ready":
+        case "layout_committed":
+          scheduleBump();
+          break;
+        default:
+          break;
+      }
+    });
+    return () => {
+      cancelled = true;
+      unsub();
+    };
+  }, [layoutFacet]);
+
+  return renderFrameRevision;
+}

package/src/ui-tailwind/review-workspace/use-page-markers.ts

@@ -0,0 +1,130 @@
+import { useEffect, useMemo, useState } from "react";
+
+import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
+import {
+  useVisibleBlockRange,
+  useVisiblePageIndexRange,
+} from "../page-stack/use-visible-block-range.ts";
+
+export interface UsePageMarkersOptions {
+  pageStackScrollRoot: HTMLElement | null;
+  snapshot: RuntimeRenderSnapshot;
+  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+}
+
+export interface PageMarkersResult {
+  pageMarkers: readonly HTMLElement[];
+  visibleBlockRange: ReturnType<typeof useVisibleBlockRange>;
+  visiblePageIndexRange: ReturnType<typeof useVisiblePageIndexRange>;
+}
+
+/**
+ * L7 Phase 2 Task 2.2.4a — viewport-scroll wiring.
+ *
+ * Collects DOM elements with `[data-page-frame]` from the PM surface so
+ * the IntersectionObserver inside `useVisibleBlockRange` /
+ * `useVisiblePageIndexRange` can determine which pages are currently
+ * visible. A MutationObserver refreshes the set when the PM surface
+ * re-renders (new document load, page count change, etc.).
+ *
+ * The hook also derives `selectionBlockIndex` internally so the visible
+ * range always includes the selection, and pushes the resolved visible
+ * block range into the layout facet (layout's viewport-culling
+ * machinery).
+ *
+ * Returns the synthetic page-0 marker prepended when the real DOM lacks
+ * one — the boundary widgets between page N and N+1 carry
+ * `data-page-frame="N+1"`, so page 0 has no widget before it.
+ */
+export function usePageMarkers(options: UsePageMarkersOptions): PageMarkersResult {
+  const { pageStackScrollRoot, snapshot, layoutFacet } = options;
+
+  const [pageMarkers, setPageMarkers] = useState<readonly HTMLElement[]>([]);
+
+  useEffect(() => {
+    const root = pageStackScrollRoot;
+    if (!root) {
+      setPageMarkers([]);
+      return undefined;
+    }
+    const refresh = () => {
+      const found = Array.from(root.querySelectorAll<HTMLElement>("[data-page-frame]"));
+      const hasPage0 = found.some(
+        (el) => el.getAttribute("data-page-frame") === "0",
+      );
+      if (!hasPage0 && found.length > 0) {
+        const page1Marker = found.find(
+          (el) => el.getAttribute("data-page-frame") === "1",
+        );
+        const page1First = page1Marker
+          ? Number(page1Marker.getAttribute("data-page-first-block-index") ?? "")
+          : NaN;
+        const page0Last = Number.isFinite(page1First) && page1First > 0
+          ? page1First - 1
+          : -1;
+        const ownerDoc = found[0]!.ownerDocument;
+        const synth = ownerDoc.createElement("span");
+        synth.setAttribute("data-page-frame", "0");
+        synth.setAttribute("data-page-first-block-index", "0");
+        synth.setAttribute("data-page-last-block-index", String(Math.max(0, page0Last)));
+        setPageMarkers([synth, ...found]);
+      } else {
+        setPageMarkers(found);
+      }
+    };
+    refresh();
+    const view = root.ownerDocument?.defaultView;
+    if (!view?.MutationObserver) return undefined;
+    const mo = new view.MutationObserver(refresh);
+    mo.observe(root, { childList: true, subtree: true });
+    return () => mo.disconnect();
+    // Re-run when the scroll root changes OR when a new snapshot lands
+    // (which may have a different page count and new widgets in the PM DOM).
+    // NOTE: snapshot.surface is intentionally excluded — its reference changes on
+    // every requestViewportRefresh(), which would add two extra render passes per
+    // scroll event.  The page-0 fallback uses -1 when page1First is unknown,
+    // which is correct (no page-0 blocks → synthetic marker contributes nothing).
+  }, [pageStackScrollRoot, snapshot.revisionToken]);
+
+  const selectionBlockIndex = useMemo(() => {
+    const sel = snapshot.selection;
+    const blocks = snapshot.surface?.blocks;
+    if (!sel || !blocks) return null;
+    for (let i = 0; i < blocks.length; i++) {
+      const block = blocks[i]!;
+      const blockFrom = block.from;
+      const blockTo = block.to;
+      if (sel.head >= blockFrom && sel.head <= blockTo) return i;
+    }
+    return null;
+  }, [snapshot.selection, snapshot.surface]);
+
+  const visibleBlockRange = useVisibleBlockRange({
+    pageMarkers,
+    overscanPages: 2,
+    selectionBlockIndex,
+    totalBlockCount: snapshot.surface?.blocks.length ?? 0,
+  });
+
+  // L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Returns
+  // `null` while the IntersectionObserver hasn't reported yet; the chrome
+  // layer treats null as "render every page" so first paint is
+  // unaffected. Once the observer fires, the chrome layer only mounts
+  // bands for pages inside `[start, end)` plus overscan, eliminating the
+  // measured 412 ms Layout + 229 ms Pre-paint cost on 138-pp extra-large.
+  const visiblePageIndexRange = useVisiblePageIndexRange({
+    pageMarkers,
+    overscanPages: 2,
+  });
+
+  // Push the visible range into the layout facet (which delegates to the
+  // runtime's viewport-culling machinery). Depend on `[start, end]` values
+  // (not the range object) so identity-preserving updates are a no-op.
+  useEffect(() => {
+    if (!layoutFacet) return;
+    layoutFacet.setVisibleBlockRange(visibleBlockRange);
+    layoutFacet.requestViewportRefresh();
+  }, [layoutFacet, visibleBlockRange.start, visibleBlockRange.end]);
+
+  return { pageMarkers, visibleBlockRange, visiblePageIndexRange };
+}

package/src/ui-tailwind/review-workspace/use-pm-surface-capture.ts

@@ -0,0 +1,60 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+export interface PmSurfaceCapture {
+  bodySlotRef: RefObject<HTMLDivElement | null>;
+  pmSurfaceElement: HTMLElement | null;
+}
+
+/**
+ * P8.11 — capture the PM surface DOM element. The ProseMirror surface
+ * mounts inside `bodySlotRef` on its own schedule (the PM constructor
+ * runs inside `TwProseMirrorSurface`). 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 the hook skips further updates unless PM is actually
+ * disconnected from the document (e.g. session / document swap tearing
+ * PM down).
+ */
+export function usePmSurfaceCapture(): PmSurfaceCapture {
+  const bodySlotRef = useRef<HTMLDivElement | null>(null);
+  const [pmSurfaceElement, setPmSurfaceElement] = useState<HTMLElement | null>(null);
+
+  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. 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` — only care when children of the
+    // body slot change (e.g. PM is added for the first time). Subtree
+    // mutations (PM's own edits) fire on every keystroke and are not
+    // our concern.
+    observer.observe(slot, { childList: true, subtree: false });
+    return () => observer.disconnect();
+  }, [pmSurfaceElement]);
+
+  return { bodySlotRef, pmSurfaceElement };
+}

package/src/ui-tailwind/review-workspace/use-review-rail-state.ts

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState } from "react";
+import type { Dispatch, SetStateAction } from "react";
+
+import {
+  getInitialReviewRailOpen,
+  isNarrowChromeViewport,
+} from "../chrome/responsive-chrome";
+import { readViewportWidth } from "./page-shell-metrics.ts";
+
+export interface UseReviewRailStateOptions {
+  reviewRailAvailable: boolean;
+  viewportWidth: number | undefined;
+}
+
+export interface ReviewRailState {
+  reviewRailOpen: boolean;
+  setReviewRailOpen: Dispatch<SetStateAction<boolean>>;
+}
+
+/**
+ * Review-rail open/close state + the responsive transition effect.
+ *
+ * When the responsive signature flips (narrow↔wide, or
+ * `reviewRailAvailable` changes), the rail resets to its default open
+ * state per `getInitialReviewRailOpen`. A ref guards the effect so it
+ * only fires on actual transitions, not every viewport resize.
+ *
+ * Drawer-mode Escape close is NOT handled here — it lives in the
+ * parent because `showDrawerReviewRail` flows from the chrome-policy
+ * hook which consumes `reviewRailOpen` from this hook (a cycle).
+ * Keep those effects in the caller.
+ */
+export function useReviewRailState(
+  options: UseReviewRailStateOptions,
+): ReviewRailState {
+  const { reviewRailAvailable, viewportWidth } = options;
+
+  const [reviewRailOpen, setReviewRailOpen] = useState(() =>
+    getInitialReviewRailOpen({
+      viewportWidth: readViewportWidth(),
+      reviewRailAvailable,
+    }),
+  );
+
+  const responsiveSignatureRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    const responsiveSignature = `${reviewRailAvailable ? "1" : "0"}:${isNarrowChromeViewport(viewportWidth) ? "n" : "d"}`;
+    if (responsiveSignatureRef.current === responsiveSignature) {
+      return;
+    }
+
+    responsiveSignatureRef.current = responsiveSignature;
+    setReviewRailOpen(
+      getInitialReviewRailOpen({
+        viewportWidth,
+        reviewRailAvailable,
+      }),
+    );
+  }, [reviewRailAvailable, viewportWidth]);
+
+  return { reviewRailOpen, setReviewRailOpen };
+}