@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/ui-tailwind/review-workspace/use-workspace-side-effects.ts

@@ -0,0 +1,150 @@
+import { useCallback, useEffect } from "react";
+import type { Dispatch, SetStateAction } from "react";
+
+import { createCanvasBackend } from "../../runtime/layout/index.ts";
+import type { RuntimeRenderSnapshot } from "../../api/public-types.ts";
+import {
+  incrementInvalidationCounter,
+  recordPerfSample,
+} from "../editor-surface/perf-probe.ts";
+
+import type { ActiveParagraphLayout } from "./paragraph-layout.ts";
+import type { PageChromeModel } from "./page-chrome.ts";
+import type { PageShellMetrics } from "./page-shell-metrics.ts";
+
+export interface UseWorkspaceSideEffectsOptions {
+  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  activeParagraphLayout: ActiveParagraphLayout | null;
+  pageChromeModel: PageChromeModel;
+  pageShellMetrics: PageShellMetrics;
+  isPageWorkspace: boolean;
+  activeStoryKind: RuntimeRenderSnapshot["activeStory"]["kind"];
+  setLayoutToolsOpen: Dispatch<SetStateAction<boolean>>;
+  showDrawerReviewRail: boolean;
+  setReviewRailOpen: Dispatch<SetStateAction<boolean>>;
+  onOpenHeaderStory?: () => void;
+  onOpenFooterStory?: () => void;
+  onDismissSelectionToolbar?: () => void;
+}
+
+export interface WorkspaceSideEffectsResult {
+  dismissSelectionToolbar: () => void;
+  runWithSelectionToolbarDismiss: (action?: () => void) => () => void;
+}
+
+/**
+ * Bundle the small, observation-only or external-side-effect hooks the
+ * review workspace needs:
+ *
+ *   - Perf sample + invalidation counter on each chrome recompute.
+ *   - Auto-open the layout-tools panel when the workspace enters a
+ *     non-main story (header / footer / footnotes canvas mode).
+ *   - Deprecation shim for the legacy `onOpenHeaderStory` /
+ *     `onOpenFooterStory` props.
+ *   - Escape-key close when the review rail is rendered as a drawer.
+ *   - Font-load-gated canvas-backend swap for the layout facet's
+ *     measurement provider.
+ *   - Selection-toolbar dismiss callbacks.
+ *
+ * Every hook is an isolated effect + callback — no shared state. They
+ * live in one module because the parent workspace would otherwise carry
+ * six separately-declared effects for side-effects that individually
+ * don't warrant their own module.
+ */
+export function useWorkspaceSideEffects(
+  options: UseWorkspaceSideEffectsOptions,
+): WorkspaceSideEffectsResult {
+  const {
+    layoutFacet,
+    activeParagraphLayout,
+    pageChromeModel,
+    pageShellMetrics,
+    isPageWorkspace,
+    activeStoryKind,
+    setLayoutToolsOpen,
+    showDrawerReviewRail,
+    setReviewRailOpen,
+    onOpenHeaderStory,
+    onOpenFooterStory,
+    onDismissSelectionToolbar,
+  } = options;
+
+  useEffect(() => {
+    recordPerfSample("workspace.chrome");
+    incrementInvalidationCounter("workspace.chrome.recomputes");
+  }, [activeParagraphLayout, pageChromeModel, pageShellMetrics]);
+
+  useEffect(() => {
+    if (isPageWorkspace && activeStoryKind !== "main") {
+      setLayoutToolsOpen(true);
+    }
+  }, [isPageWorkspace, activeStoryKind, setLayoutToolsOpen]);
+
+  // 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 (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 (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 (!showDrawerReviewRail || typeof window === "undefined") {
+      return;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      setReviewRailOpen(false);
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [showDrawerReviewRail, setReviewRailOpen]);
+
+  useEffect(() => {
+    if (!layoutFacet) return;
+    const facet = layoutFacet;
+    const fontSet = document.fonts;
+    if (!fontSet?.ready) {
+      facet.swapMeasurementProvider(createCanvasBackend());
+      return;
+    }
+    void fontSet.ready.then(() => {
+      facet.swapMeasurementProvider(createCanvasBackend());
+    });
+  }, [layoutFacet]);
+
+  const dismissSelectionToolbar = useCallback(() => {
+    onDismissSelectionToolbar?.();
+  }, [onDismissSelectionToolbar]);
+
+  const runWithSelectionToolbarDismiss = useCallback(
+    (action?: () => void) => () => {
+      dismissSelectionToolbar();
+      action?.();
+    },
+    [dismissSelectionToolbar],
+  );
+
+  return { dismissSelectionToolbar, runWithSelectionToolbarDismiss };
+}

package/src/ui-tailwind/theme/editor-theme.css

@@ -1149,6 +1149,31 @@
   }
 }
 
+/*
+ * U3 fix — font-smoothing baseline for the entire editor shell.
+ *
+ * Previously `-webkit-font-smoothing` / `-moz-osx-font-smoothing` /
+ * `text-rendering` lived ONLY on `.wre-page-surface` and
+ * `.wre-canvas-surface`, so chrome elements (shell header, toolbar,
+ * rails, status bar, overlays) inherited smoothing from the host
+ * `body` — which consumers may not set.  Embedding the editor in a
+ * host without `-webkit-font-smoothing: antialiased` left chrome text
+ * rendering with subpixel/default AA while the document surface was
+ * antialiased, producing the visible mismatch the U3 report flagged.
+ *
+ * Declaring the tokens on `.wre-editor` (the single shell-root class
+ * every surface below is nested under) makes smoothing the editor's
+ * own baseline instead of a host concern.  The inner
+ * `.wre-page-surface` / `.wre-canvas-surface` rules are kept so
+ * headless-service / Playwright captures still see explicit
+ * declarations on the document surface.
+ */
+.wre-editor {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
 /*
  * §6.23 — Scrollbar grammar (Lane 6c.S10)
  * Thin track, thumb low-contrast until hover. Consistent across

package/src/ui-tailwind/toolbar/tw-role-action-region.tsx

@@ -45,11 +45,11 @@ import type {
   ReviewQueueSnapshot,
   ScopeRailPosture,
 } from "../../api/public-types";
-import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { SessionCapabilities } from "../../api/public-types";
 import type { ScopedChromePolicy } from "../../ui/headless/scoped-chrome-policy";
 import type { ToolbarChromeItemId } from "../../ui/headless/chrome-registry";
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
-import { ROLE_ACTION_SETS } from "../chrome/role-action-sets";
+import { ROLE_ACTION_SETS } from "../../ui/headless/role-action-sets";
 import { TwScopePostureMenu } from "./tw-scope-posture-menu";
 
 /**

package/src/ui-tailwind/toolbar/tw-toolbar.tsx

@@ -61,7 +61,7 @@ import type {
   WorkspaceMode,
   ZoomLevel,
 } from "../../api/public-types";
-import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { SessionCapabilities } from "../../api/public-types";
 import {
   getToolbarChromePlacement,
   isChromeItemOwnedByRoleRegion,
@@ -70,12 +70,7 @@ import {
   type ScopedChromePolicy,
 } from "../../ui/headless/scoped-chrome-policy";
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
-import { TwHealthPanel } from "../review/tw-health-panel";
-import {
-  TwRoleActionRegion,
-  type MarkupDisplayMode,
-  type WorkflowWorkItemSnapshot,
-} from "./tw-role-action-region";
+import { type MarkupDisplayMode } from "./tw-role-action-region";
 import { TwDetachHandle } from "../chrome/tw-detach-handle";
 import { TwToolbarIconButton } from "./tw-toolbar-icon-button";
 
@@ -137,15 +132,15 @@ export interface TwToolbarProps {
 
   // ───── R1: role-scoped inline action region (spec §6.4) ──────────────
   /**
-   * Active editor role.  When supplied, the toolbar renders the inline
-   * `TwRoleActionRegion` between the left formatting cluster and the
-   * right view cluster.  Omit to keep the pre-R1 layout.
+   * Active editor role. Since Chrome Closure Pass Task 1 (2026-04-22) the
+   * role-action region renders inside `<TwContextBand>` — the toolbar
+   * itself no longer mounts `<TwRoleActionRegion>`. The `role` prop is
+   * retained here only so the formatting cluster can defer items owned
+   * by the role-region via `isChromeItemOwnedByRoleRegion`.
    */
   role?: EditorRole;
-  /** Review-queue snapshot for the review role's inline prev/next/counts. */
+  /** Review-queue snapshot — consumed only by the view-cluster change-counter chip. */
   reviewQueue?: ReviewQueueSnapshot;
-  /** Active work item for the workflow role's inline queue. */
-  workflowItem?: WorkflowWorkItemSnapshot | null;
   /** Markup display mode for the review role. */
   markupDisplay?: MarkupDisplayMode;
 
@@ -154,22 +149,13 @@ export interface TwToolbarProps {
   onReviewSidebarComments?: () => void;
   // Workflow + review role: scope posture
   onMarkScopePosture?: (posture: ScopeRailPosture) => void;
-  // Review role
+  // Review role — inline prev/next + accept/reject stay on the toolbar for
+  // the view-cluster mount (queue counter chip); batch ops moved with the
+  // role-region to <TwContextBand> and are threaded there, not here.
   onReviewPrev?: () => void;
   onReviewNext?: () => void;
   onReviewAccept?: () => void;
   onReviewReject?: () => void;
-  onReviewAcceptAll?: () => void;
-  onReviewRejectAll?: () => void;
-  onReviewMarkupMode?: (mode: MarkupDisplayMode) => void;
-  // Workflow role
-  onWorkflowPrev?: () => void;
-  onWorkflowNext?: () => void;
-  onWorkflowMarkComplete?: () => void;
-  onWorkflowClaim?: () => void;
-  onWorkflowSkip?: () => void;
-  onWorkflowMarkBlocked?: () => void;
-  onWorkflowJumpToScope?: () => void;
   /** Current chrome pin state; when supplied enables the topnav detach handle. */
   chromePins?: ChromePinsState;
   /** Called when the user detaches or re-attaches the topnav. */
@@ -208,6 +194,15 @@ export interface TwToolbarProps {
     image?: string;
     sectionBreak?: string;
   };
+
+  /**
+   * Phase E.3 — handoff to the management rail's Health tab.  Clicking
+   * the signal-only health chip fires this callback so the workspace can
+   * open the rail via the chrome-host controller's `openRailTab` method.
+   * Diagnostics detail no longer lives inside a toolbar popover (audit
+   * §2.10); the chip surfaces severity + count only.
+   */
+  onOpenHealthRail?: () => void;
 }
 
 export interface ToolbarInteractionPolicy {
@@ -593,39 +588,16 @@ export function TwToolbar(props: TwToolbarProps) {
         ) : null}
       </div>
 
-      {/* R1: role-scoped inline action region (spec §6.4) */}
-      {props.role ? (
-        <TwRoleActionRegion
-          role={props.role}
-          policy={scopedChromePolicy}
-          compactMode={isCompact}
-          reviewQueue={props.reviewQueue}
-          workflowItem={props.workflowItem}
-          markupDisplay={props.markupDisplay}
-          canAddComment={canAddComment}
-          showTrackedChanges={props.showTrackedChanges}
-          capabilities={caps}
-          onAddComment={props.onAddComment}
-          onShowTrackedChangesChange={props.onShowTrackedChangesChange}
-          onReviewSidebarTrackedChanges={props.onReviewSidebarTrackedChanges}
-          onReviewSidebarComments={props.onReviewSidebarComments}
-          onMarkScopePosture={props.onMarkScopePosture}
-          onReviewPrev={props.onReviewPrev}
-          onReviewNext={props.onReviewNext}
-          onReviewAccept={props.onReviewAccept}
-          onReviewReject={props.onReviewReject}
-          onReviewAcceptAll={props.onReviewAcceptAll}
-          onReviewRejectAll={props.onReviewRejectAll}
-          onReviewMarkupMode={props.onReviewMarkupMode}
-          onWorkflowPrev={props.onWorkflowPrev}
-          onWorkflowNext={props.onWorkflowNext}
-          onWorkflowMarkComplete={props.onWorkflowMarkComplete}
-          onWorkflowClaim={props.onWorkflowClaim}
-          onWorkflowSkip={props.onWorkflowSkip}
-          onWorkflowMarkBlocked={props.onWorkflowMarkBlocked}
-          onWorkflowJumpToScope={props.onWorkflowJumpToScope}
-        />
-      ) : null}
+      {/*
+       * Chrome Closure Pass · Task 1 (designsystem.md §6.3) — the
+       * role-action region used to render here as the toolbar's center
+       * subregion. It now lives inside `TwContextBand` (rendered as a
+       * sibling above the toolbar) so the workspace row is
+       *   [shell] · [TwContextBand carrying role actions] · [TwToolbar]
+       * The toolbar still consumes `props.role` above for
+       * `isChromeItemOwnedByRoleRegion` deferral so it does not
+       * duplicate controls the band already exposes (§6.2 "Do not").
+       */}
 
       {/* Right cluster: comment, track changes, markup, view, export */}
       <div className={`flex items-center gap-0.5 ${isCompact ? "ml-auto flex-wrap justify-end" : ""}`}>
@@ -868,47 +840,38 @@ export function TwToolbar(props: TwToolbarProps) {
 
         {showHealth ? (
           <>
-            <Popover.Root>
-              <Tooltip.Root>
-                <Tooltip.Trigger asChild>
-                  <Popover.Trigger asChild>
-                    <button
-                      type="button"
-                      aria-label="Document health"
-                      onMouseDown={preserveEditorSelectionMouseDown}
-                      className={`relative inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface hover:text-primary outline-none ${focusRingClass}`}
-                    >
-                      <AlertCircle className="h-3.5 w-3.5" />
-                      {(caps?.healthIssueCount ?? 0) > 0 ? (
-                        <span className="absolute -top-0.5 -right-0.5 flex h-3 min-w-[12px] items-center justify-center rounded-full bg-tertiary text-[8px] font-medium text-white">
-                          {caps?.healthIssueCount}
-                        </span>
-                      ) : null}
-                    </button>
-                  </Popover.Trigger>
-                </Tooltip.Trigger>
-                <Tooltip.Portal>
-                  <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
-                    {(caps?.healthIssueCount ?? 0) > 0
-                      ? `Document health — ${caps?.healthIssueCount} issue${(caps?.healthIssueCount ?? 0) !== 1 ? "s" : ""}`
-                      : "Document health — no issues"}
-                  </Tooltip.Content>
-                </Tooltip.Portal>
-              </Tooltip.Root>
-              <Popover.Portal>
-                <Popover.Content
-                  className="w-[360px] max-h-[480px] overflow-y-auto rounded-lg bg-canvas shadow-lg ring-1 ring-border p-3 z-50"
-                  sideOffset={8}
-                  align="end"
+            {/*
+             * Phase E.3 — signal-only chip.  The Radix Popover that
+             * previously wrapped this button is retired (audit §2.10);
+             * detail now lives in the rail `health` tab.  Clicking the
+             * chip fires `onOpenHealthRail` so the workspace can pivot
+             * the rail via the chrome-host controller's `openRailTab`.
+             */}
+            <Tooltip.Root>
+              <Tooltip.Trigger asChild>
+                <button
+                  type="button"
+                  aria-label="Document health"
+                  onMouseDown={preserveEditorSelectionMouseDown}
+                  onClick={props.onOpenHealthRail}
+                  className={`relative inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface hover:text-primary outline-none ${focusRingClass}`}
                 >
-                  <TwHealthPanel
-                    blockedReasons={props.blockedReasons}
-                    compatibility={props.compatibility!}
-                    warnings={props.warnings!}
-                  />
-                </Popover.Content>
-              </Popover.Portal>
-            </Popover.Root>
+                  <AlertCircle className="h-3.5 w-3.5" />
+                  {(caps?.healthIssueCount ?? 0) > 0 ? (
+                    <span className="absolute -top-0.5 -right-0.5 flex h-3 min-w-[12px] items-center justify-center rounded-full bg-tertiary text-[8px] font-medium text-white">
+                      {caps?.healthIssueCount}
+                    </span>
+                  ) : null}
+                </button>
+              </Tooltip.Trigger>
+              <Tooltip.Portal>
+                <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
+                  {(caps?.healthIssueCount ?? 0) > 0
+                    ? `Document health — ${caps?.healthIssueCount} issue${(caps?.healthIssueCount ?? 0) !== 1 ? "s" : ""} (opens rail)`
+                    : "Document health — no issues"}
+                </Tooltip.Content>
+              </Tooltip.Portal>
+            </Tooltip.Root>
             <div className="mx-1 h-4 w-px bg-border" />
           </>
         ) : null}