@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/api/v3/ui/chrome-composition.ts

@@ -0,0 +1,342 @@
+/**
+ * resolveChromeComposition — canonical chrome-composition seam (layer 10, §U5.b).
+ *
+ * Relocated from `src/ui-tailwind/chrome/chrome-composition-model.ts` by
+ * refactor/10 Slice 8 so the UI API owns chrome composition end-to-end
+ * (architecture 10 §U5). `ui.chrome.getComposition(input)` wraps this
+ * function in refactor/10 Slice 9. A re-export shim remains at the old
+ * path during consumer migration.
+ *
+ * Normative references:
+ *   - docs/reference/designsystem.md §2.3 (chrome hierarchy: Shell / Workspace /
+ *     Local context / Management rail)
+ *   - docs/reference/designsystem.md §8.3 (three-axis rule — runtime/surface/chrome)
+ *   - docs/architecture/10-ui-api.md §U5.b (ChromeComposition target shape)
+ *
+ * Perf discipline (CLAUDE.md §Performance Invariants #4 + #7):
+ *   - Pure function. No DOM reads, no runtime calls, no observers.
+ *   - Structurally equal on equal inputs, but each call allocates a NEW
+ *     outer object + NEW Sets + NEW arrays. Callers that want referential
+ *     stability MUST wrap the call in `useMemo` with an explicit
+ *     dependency list. The memoization hook at
+ *     `src/ui-tailwind/review-workspace/use-workspace-composition.ts`
+ *     handles this for the mounted workspace consumer.
+ */
+
+import type {
+  EditorRole,
+  WordReviewEditorChromeOptions,
+  WordReviewEditorChromePreset,
+  WordReviewEditorChromeVisibility,
+} from "../../public-types";
+import {
+  resolveChromePresetOptions,
+  resolveChromeVisibilityForPreset,
+} from "./chrome-preset-model";
+
+/**
+ * Pure breakpoint resolver — inlined at layer 10 so chrome composition does
+ * not reach into layer 11 for presentation helpers. The React hook
+ * `useContainerBreakpoint` (layer 11, `src/ui-tailwind/chrome/use-container-breakpoint.ts`)
+ * carries its own copy for its ResizeObserver wiring. Keeping them in sync
+ * is trivial — this is a 5-line mapping over a threshold record.
+ */
+type BreakpointMap = Readonly<Record<string, number>>;
+function resolveBreakpoint<T extends BreakpointMap>(
+  width: number,
+  thresholds: T,
+): keyof T | null {
+  let best: keyof T | null = null;
+  let bestThreshold = -Infinity;
+  for (const name of Object.keys(thresholds) as (keyof T)[]) {
+    const t = thresholds[name] as number;
+    if (width >= t && t > bestThreshold) {
+      best = name;
+      bestThreshold = t;
+    }
+  }
+  return best;
+}
+
+export type EditorChromeMode = "edit" | "review" | "workflow" | "more";
+export type EditorRailTab = "comments" | "changes" | "workflow" | "health";
+
+/**
+ * LocalSurfaceKind enumerates every surface type the global local-surface
+ * arbiter (Phase F) knows about. Phase A ships the enum so consumers can
+ * begin typing against it; Phase F wires the arbiter that consumes it.
+ */
+export type LocalSurfaceKind =
+  | "none"
+  | "selection-format"
+  | "comment-preview"
+  | "suggestion-card"
+  | "workflow-card"
+  | "blocked-card"
+  | "scope-card"
+  | "context-menu";
+
+export type DiagnosticsSeverity = "none" | "info" | "warning" | "blocked";
+export type ChromeDensity = "compact" | "standard" | "comfortable";
+export type ChromeResponsiveTier = "compact" | "standard" | "wide";
+
+export interface DiagnosticsSignal {
+  readonly severity: DiagnosticsSeverity;
+  readonly count: number;
+}
+
+export interface WorkspaceRowComposition {
+  readonly left: readonly string[];
+  readonly contextBand: {
+    readonly owner: EditorChromeMode;
+    readonly items: readonly string[];
+  };
+  readonly right: readonly string[];
+}
+
+export interface RailComposition {
+  readonly open: boolean;
+  readonly activeTab: EditorRailTab | null;
+  readonly visibleTabs: ReadonlySet<EditorRailTab>;
+  readonly pinnedTabs: ReadonlySet<EditorRailTab>;
+}
+
+export interface ChromeComposition {
+  readonly mode: EditorChromeMode;
+  readonly shell: {
+    readonly visible: true;
+    readonly modeSwitcher: "always";
+  };
+  readonly workspaceRow: WorkspaceRowComposition;
+  readonly rail: RailComposition;
+  readonly diagnostics: DiagnosticsSignal;
+  readonly density: ChromeDensity;
+  readonly responsiveTier: ChromeResponsiveTier;
+  readonly visibility: WordReviewEditorChromeVisibility;
+}
+
+export interface ChromeCompositionInput {
+  readonly chromePreset: WordReviewEditorChromePreset;
+  readonly chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  readonly chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
+  readonly reviewMode?: "editing" | "review";
+  readonly role?: EditorRole;
+  readonly readOnly?: boolean;
+  readonly markupDisplay?:
+    | "all-markup"
+    | "simple-markup"
+    | "no-markup"
+    | "original"
+    | "clean"
+    | "simple"
+    | "all";
+  readonly activeRailTab?: EditorRailTab | null;
+  readonly pinnedRailTabs?: ReadonlySet<EditorRailTab>;
+  readonly density?: ChromeDensity;
+  readonly containerWidth?: number;
+  readonly diagnosticsSignal?: DiagnosticsSignal;
+  /**
+   * Shell-owned mode override. The shell passes `"more"` here when it
+   * opens the diagnostics / search surface. All other modes are derived
+   * from runtime signals (role, reviewMode); this field exists so
+   * `resolveChromeComposition` can produce `mode: "more"` without
+   * conflating it with the other three runtime-derived modes.
+   * Layer 10 (`src/api/v3/ui/chrome.ts`) will wrap this seam.
+   */
+  readonly modeOverride?: EditorChromeMode;
+}
+
+/**
+ * Container-driven responsive tier thresholds (per designsystem.md §2.13:
+ * "Responsive rules are container-driven, not viewport-only"). The named
+ * set mirrors the `compact | standard | wide` triple used across shell,
+ * workspace row, and rail.
+ */
+export const CHROME_RESPONSIVE_THRESHOLDS = {
+  compact: 0,
+  standard: 720,
+  wide: 1200,
+} as const;
+
+/**
+ * Derive the `mode` field from the richest posture signal available:
+ *   - explicit shell override (`modeOverride`) wins — used for "more"
+ *   - explicit workflow role (runtime authority) comes next
+ *   - reviewMode="review" (session signal) comes next
+ *   - default is "edit"
+ */
+function deriveMode(input: ChromeCompositionInput): EditorChromeMode {
+  if (input.modeOverride) return input.modeOverride;
+  if (input.role === "workflow") return "workflow";
+  if (input.reviewMode === "review") return "review";
+  return "edit";
+}
+
+/**
+ * Context-band item tables per audit §2.5. Each table names the item ids
+ * that the band exposes in that mode; ordering is the render order.
+ *
+ * These are contract with Phase B (TwContextBand). The band reads this
+ * array and renders a button per id through a shared registry.
+ */
+const CONTEXT_BAND_ITEMS_BY_MODE: Record<EditorChromeMode, readonly string[]> = {
+  edit: [
+    "paragraph-style",
+    "bold",
+    "italic",
+    "underline",
+    "list-bullet",
+    "list-numbered",
+    "insert-menu",
+  ],
+  review: [
+    "review-current-label",
+    "review-prev",
+    "review-next",
+    "review-accept",
+    "review-reject",
+    "markup-display",
+  ],
+  workflow: [
+    "scope-current-label",
+    "scope-prev",
+    "scope-next",
+    "workflow-claim",
+    "workflow-skip",
+    "workflow-complete",
+    "workflow-blocked-explanation",
+  ],
+  more: [
+    "diagnostics-link",
+    "compatibility-link",
+    "outline-link",
+    "search-link",
+  ],
+};
+
+/**
+ * Left edge is the stable-utility cluster per audit §2.3. "Stable" means
+ * the same actions repeat across modes; paragraph style is edit-only since
+ * review/workflow modes do not expose structural formatting here.
+ */
+function resolveLeftEdge(mode: EditorChromeMode): readonly string[] {
+  if (mode === "edit") return ["undo", "redo", "paragraph-style"];
+  return ["undo", "redo"];
+}
+
+/**
+ * Right edge per audit §2.3: rail toggle + diagnostics signal (severity +
+ * count, not detail) + zoom + overflow.
+ *
+ * The right cluster is intentionally mode-agnostic today — "more" mode's
+ * command / search affordance lives in the shell header (§6.1), not in
+ * the workspace row's right edge.  If Phase D or later finds mode-
+ * dependent right-cluster items, add a `mode` parameter.
+ */
+function resolveRightEdge(
+  diagnosticsSignal: DiagnosticsSignal,
+): readonly string[] {
+  const items: string[] = ["rail-toggle"];
+  if (diagnosticsSignal.severity !== "none" || diagnosticsSignal.count > 0) {
+    items.push("diagnostics-signal");
+  }
+  items.push("zoom", "overflow");
+  return items;
+}
+
+/**
+ * Rail visibility rules per audit §2.9 and designsystem.md §6.11:
+ *   - comments/changes/workflow visible when rail is open
+ *   - health visible when diagnostics signal present
+ *   - empty tabs hide unless pinned
+ *   - pinned tabs always visible
+ */
+function resolveVisibleRailTabs(
+  railOpen: boolean,
+  diagnosticsSignal: DiagnosticsSignal,
+  pinned: ReadonlySet<EditorRailTab>,
+): ReadonlySet<EditorRailTab> {
+  const visible = new Set<EditorRailTab>();
+  if (railOpen) {
+    visible.add("comments");
+    visible.add("changes");
+    visible.add("workflow");
+    if (diagnosticsSignal.severity !== "none" || diagnosticsSignal.count > 0) {
+      visible.add("health");
+    }
+  }
+  // Pinned tabs survive even when the rail is closed or when the tab is empty.
+  for (const tab of pinned) {
+    visible.add(tab);
+  }
+  return visible;
+}
+
+/**
+ * Main entry. Pure, referentially stable for equal inputs.
+ */
+export function resolveChromeComposition(
+  input: ChromeCompositionInput,
+): ChromeComposition {
+  const mode = deriveMode(input);
+  const options = resolveChromePresetOptions(
+    input.chromePreset,
+    input.chromeOptions,
+    input.role,
+  );
+  const visibility = resolveChromeVisibilityForPreset({
+    chromePreset: input.chromePreset,
+    chromeOptions: input.chromeOptions,
+    chromeVisibility: input.chromeVisibility,
+  });
+  const diagnosticsSignal: DiagnosticsSignal =
+    input.diagnosticsSignal ?? { severity: "none", count: 0 };
+  const density: ChromeDensity = input.density ?? "standard";
+  const pinnedRailTabs: ReadonlySet<EditorRailTab> =
+    input.pinnedRailTabs ?? new Set<EditorRailTab>();
+  const railOpen = options.showReviewRail && visibility.reviewRail;
+  const visibleTabs = resolveVisibleRailTabs(
+    railOpen,
+    diagnosticsSignal,
+    pinnedRailTabs,
+  );
+
+  // Default active tab: honor caller; otherwise land on the mode-appropriate tab.
+  const defaultActive: EditorRailTab =
+    mode === "workflow" ? "workflow" : mode === "review" ? "changes" : "comments";
+  const activeTab: EditorRailTab | null =
+    input.activeRailTab !== undefined
+      ? input.activeRailTab
+      : railOpen
+        ? defaultActive
+        : null;
+
+  const responsiveTier: ChromeResponsiveTier =
+    (resolveBreakpoint(
+      input.containerWidth ?? CHROME_RESPONSIVE_THRESHOLDS.standard,
+      CHROME_RESPONSIVE_THRESHOLDS,
+    ) as ChromeResponsiveTier | null) ?? "standard";
+
+  return {
+    mode,
+    shell: { visible: true, modeSwitcher: "always" },
+    workspaceRow: {
+      left: resolveLeftEdge(mode),
+      contextBand: {
+        owner: mode,
+        items: CONTEXT_BAND_ITEMS_BY_MODE[mode],
+      },
+      right: resolveRightEdge(diagnosticsSignal),
+    },
+    rail: {
+      open: railOpen,
+      activeTab,
+      visibleTabs,
+      pinnedTabs: pinnedRailTabs,
+    },
+    diagnostics: diagnosticsSignal,
+    density,
+    responsiveTier,
+    visibility,
+  };
+}

package/src/{ui-tailwind/chrome → api/v3/ui}/chrome-preset-model.ts

@@ -1,10 +1,20 @@
+/**
+ * Chrome preset + visibility composition — layer 10.
+ *
+ * Relocated from `src/ui-tailwind/chrome/chrome-preset-model.ts` by
+ * refactor/10 Slice 8 so the UI API owns the chrome-composition seam
+ * end-to-end (architecture 10 §U5). Pure type-shape logic, no DOM, no
+ * React. Consumed by `chrome-composition.ts` (also layer 10) to compose
+ * `ChromeComposition`. A re-export shim remains at the old path during
+ * consumer migration.
+ */
 import type {
   EditorRole,
   WordReviewEditorChromeOptions,
   WordReviewEditorChromePreset,
   WordReviewEditorChromeVisibility,
   WordReviewEditorProps,
-} from "../../api/public-types";
+} from "../../public-types";
 
 export function resolveChromePreset(
   chromePreset: WordReviewEditorProps["chromePreset"],