@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/ui/headless/selection-tool-resolver.ts

@@ -17,27 +17,26 @@ import type {
   SuggestionReviewSelectionToolModel,
   WorkflowTaskSelectionToolModel,
 } from "./selection-tool-types";
+import {
+  SELECTION_TOOL_REGISTRY,
+  type SelectionToolRegistryEntry,
+} from "./chrome-registry";
+import { shouldRenderSelectionToolKind } from "./scoped-chrome-policy";
 
 export function resolveActiveSelectionTool(
   input: SelectionToolResolverInput,
 ): ActiveSelectionToolModel | null {
-  const suggestionTool = buildSuggestionReviewSelectionToolModel(input);
-  const commentTool = buildCommentThreadSelectionToolModel(input);
-  const workflowTool = buildWorkflowTaskSelectionToolModel(input);
-  const structureTool = buildStructureContextSelectionToolModel(input);
-  // Semantic targets beat generic range formatting so structure tools do not
-  // leak preview text when the user is acting on a table, image, or object.
-  const formattingTool = buildFormattingInlineSelectionToolModel(input);
-  const blockedTool = buildBlockedExplainerSelectionToolModel(input);
-  const resolvedTool =
-    suggestionTool ??
-    commentTool ??
-    workflowTool ??
-    structureTool ??
-    formattingTool ??
-    blockedTool;
-
-  return resolvedTool;
+  for (const entry of SELECTION_TOOL_REGISTRY) {
+    if (!shouldRenderSelectionToolKind(input.scopedChromePolicy, entry.id)) {
+      continue;
+    }
+    const resolvedTool = buildSelectionToolFromRegistryEntry(entry, input);
+    if (resolvedTool) {
+      return resolvedTool;
+    }
+  }
+
+  return null;
 }
 
 export function buildFormattingInlineSelectionToolModel(
@@ -273,6 +272,26 @@ function selectionMatchesSuggestion(
   );
 }
 
+function buildSelectionToolFromRegistryEntry(
+  entry: SelectionToolRegistryEntry,
+  input: SelectionToolResolverInput,
+): ActiveSelectionToolModel | null {
+  switch (entry.id) {
+    case "suggestion-review":
+      return buildSuggestionReviewSelectionToolModel(input);
+    case "comment-thread":
+      return buildCommentThreadSelectionToolModel(input);
+    case "workflow-task":
+      return buildWorkflowTaskSelectionToolModel(input);
+    case "structure-context":
+      return buildStructureContextSelectionToolModel(input);
+    case "formatting-inline":
+      return buildFormattingInlineSelectionToolModel(input);
+    case "blocked-explainer":
+      return buildBlockedExplainerSelectionToolModel(input);
+  }
+}
+
 function findSelectionMatchingScope(
   activeRange: SelectionToolResolverInput["snapshot"]["selection"]["activeRange"] | null,
   activeStory: EditorStoryTarget,

package/src/ui/headless/selection-tool-types.ts

@@ -59,6 +59,16 @@ export interface FormattingInlineSelectionToolModel extends BaseSelectionToolMod
   italicActive: boolean;
   underlineActive: boolean;
   canAddComment: boolean;
+  /**
+   * One-click "apply" color for the text-color affordance.  R2.5 plumbs
+   * the current `formattingState.textColor` (or the user's most recent
+   * pick) here so the mini-toolbar reflects the active color instead of
+   * a hardcoded blue.  Consumers fall back to a fixed default when
+   * absent.
+   */
+  textColorDefault?: string;
+  /** Matching one-click highlight color.  See `textColorDefault`. */
+  highlightColorDefault?: string;
 }
 
 export interface SuggestionReviewSelectionToolModel extends BaseSelectionToolModel {

package/src/ui-tailwind/chrome/chrome-preset-model.ts

@@ -7,12 +7,15 @@ import type {
 
 export function resolveChromePreset(
   chromePreset: WordReviewEditorProps["chromePreset"],
-  _reviewMode: WordReviewEditorProps["reviewMode"] = "review",
+  reviewMode: WordReviewEditorProps["reviewMode"] = "review",
 ): WordReviewEditorChromePreset {
   if (chromePreset) {
     return chromePreset;
   }
-  return "advanced";
+  // When the host does not set an explicit preset, pick one from the
+  // review-mode signal so review sessions get the review strip inline
+  // with the toolbar (rather than the density default "advanced").
+  return reviewMode === "review" ? "review" : "advanced";
 }
 
 export function resolveChromePresetOptions(
@@ -40,6 +43,14 @@ export function resolveChromePresetOptions(
       showSectionTagAction: true,
       showReviewRail: true,
     },
+    workflow: {
+      // Workflow role consolidates prev/next + mark-section into the top
+      // toolbar via the role-action region, so the separate queue bar
+      // strip is suppressed.
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: true,
+    },
   };
 
   return {
@@ -95,6 +106,16 @@ export function resolveChromeVisibilityForPreset(input: {
       statusBar: true,
       reviewRail: options.showReviewRail,
     },
+    workflow: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: options.showReviewRail,
+    },
   };
 
   return {

package/src/ui-tailwind/chrome/role-action-sets.ts

@@ -0,0 +1,74 @@
+/**
+ * Role → ordered primary-action id mapping for the top-toolbar's inline
+ * role-action region (spec §6.4).
+ *
+ * The registry in `chrome-registry.ts` knows which ids exist per role;
+ * this module decides the *rendering order* so the role region presents
+ * a tight, task-focused set instead of the preset-density order.
+ *
+ * Consumers of `TwRoleActionRegion` look up the array for the active
+ * role, iterate it in order, and let `scoped-chrome-policy` filter out
+ * anything currently invisible (for instance, review-role accept/reject
+ * buttons disappear when there are no pending revisions).
+ */
+
+import type { EditorRole } from "../../api/public-types";
+import type { ToolbarChromeItemId } from "../../ui/headless/chrome-registry";
+
+/**
+ * Ordered role-action ids.  Each array covers the *role-primary* actions
+ * only — the general left cluster (history, formatting, style selectors)
+ * and right cluster (tracked-changes, workspace mode, zoom, health,
+ * export) stay in the base `TwToolbar` layout regardless of role.
+ */
+export const ROLE_ACTION_SETS: Record<
+  EditorRole,
+  ReadonlyArray<ToolbarChromeItemId>
+> = {
+  editor: [
+    // Posture menu replaces the flat "Mark section" button per spec §6.4.
+    "editor-scope-posture-menu",
+    // Insert menu (tables / images / page breaks / section breaks) — only
+    // meaningful for authoring, so it lives in the editor role's action
+    // region rather than the base toolbar.
+    "insert-actions",
+    "update-actions",
+    "list-continuation",
+  ],
+  review: [
+    // Queue navigation + counts, collapsed from the old TwReviewQueueBar.
+    "review-queue-prev",
+    "review-queue-next",
+    "review-queue-counts",
+    "review-queue-active-label",
+    // Per-item accept/reject — the canonical review actions.
+    "review-accept",
+    "review-reject",
+    // Batch + markup-mode live in the overflow popover.
+    "review-accept-all",
+    "review-reject-all",
+    "review-markup-mode",
+  ],
+  workflow: [
+    // Work-item navigation (distinct from review-queue nav).
+    "workflow-prev",
+    "workflow-next",
+    // Primary workflow actions.
+    "workflow-mark-complete",
+    "workflow-claim",
+    "workflow-skip",
+    "workflow-mark-blocked",
+    "workflow-jump-to-scope",
+  ],
+};
+
+/**
+ * Reverse lookup: role → entry order with registry details merged in.
+ * Consumers who need to iterate role actions with presets/runtimeBehavior
+ * import from here to avoid re-running `Array.find` per render.
+ */
+export function resolveRoleActionOrder(
+  role: EditorRole,
+): ReadonlyArray<ToolbarChromeItemId> {
+  return ROLE_ACTION_SETS[role];
+}

package/src/ui-tailwind/chrome/tw-detach-handle.tsx

@@ -0,0 +1,147 @@
+/**
+ * Shared detach/attach primitive for chrome surfaces that can float vs
+ * dock.  Extracted from the hand-rolled implementation in
+ * `tw-selection-tool-host.tsx` so the same UX works on the topnav, the
+ * selection tier, and any future overlay layer that opts in.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §6.3 every overlay child
+ * should consume this shape.  State is owned by `ViewState.chromePins`
+ * so pin offsets survive snapshot rebuilds within one session.
+ */
+
+import React, { useCallback, useEffect, useRef } from "react";
+import { GripHorizontal } from "lucide-react";
+
+import type {
+  ChromePinSurface,
+  PinState,
+} from "../../api/public-types";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+
+export interface TwDetachHandleProps {
+  /** Which chrome surface this handle controls; stored in ViewState. */
+  surface: ChromePinSurface;
+  /** Current pin state; `undefined` means docked-default. */
+  pin?: PinState;
+  /** Callback fired with the next pin state (null = clear). */
+  onChange: (surface: ChromePinSurface, pin: PinState | null) => void;
+  /** Human label rendered next to the status chip. */
+  label: string;
+  /** Optional test id override. */
+  "data-testid"?: string;
+  /** Optional className spliced onto the root. */
+  className?: string;
+}
+
+/**
+ * Compact grip + Float/Dock toggle row.  Consumers mount this inline
+ * above the surface's content; when `pin.detached === true` the consumer
+ * translates the surface by `pin.offset.x / y` itself (the handle does
+ * not wrap the payload).
+ */
+export function TwDetachHandle(props: TwDetachHandleProps): React.JSX.Element {
+  const { surface, pin, onChange, label } = props;
+  const isDetached = pin?.detached ?? false;
+  const offset = pin?.offset ?? { x: 0, y: 0 };
+  const dragState = useRef<
+    | {
+        startX: number;
+        startY: number;
+        originX: number;
+        originY: number;
+      }
+    | null
+  >(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return undefined;
+    }
+
+    const handleMove = (event: MouseEvent) => {
+      if (!dragState.current) return;
+      const nextX =
+        dragState.current.originX + (event.clientX - dragState.current.startX);
+      const nextY =
+        dragState.current.originY + (event.clientY - dragState.current.startY);
+      onChange(surface, { detached: true, offset: { x: nextX, y: nextY } });
+    };
+
+    const handleUp = () => {
+      dragState.current = null;
+    };
+
+    window.addEventListener("mousemove", handleMove);
+    window.addEventListener("mouseup", handleUp);
+    return () => {
+      window.removeEventListener("mousemove", handleMove);
+      window.removeEventListener("mouseup", handleUp);
+    };
+  }, [onChange, surface]);
+
+  const beginDrag = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      preserveEditorSelectionMouseDown(event);
+      dragState.current = {
+        startX: event.clientX,
+        startY: event.clientY,
+        originX: isDetached ? offset.x : 0,
+        originY: isDetached ? offset.y : 0,
+      };
+      if (!isDetached) {
+        onChange(surface, { detached: true, offset: { x: 0, y: 0 } });
+      }
+    },
+    [isDetached, offset.x, offset.y, onChange, surface],
+  );
+
+  const toggle = useCallback(() => {
+    if (isDetached) {
+      onChange(surface, null);
+    } else {
+      onChange(surface, { detached: true, offset: { x: 0, y: 0 } });
+    }
+  }, [isDetached, onChange, surface]);
+
+  return (
+    <div
+      className={[
+        "inline-flex items-center gap-1.5 self-center rounded-lg border border-border/70 bg-canvas/94 px-1.5 py-1 shadow-[0_8px_20px_-18px_var(--color-shadow-strong)]",
+        props.className ?? "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      data-testid={props["data-testid"] ?? `detach-handle-${surface}`}
+      data-surface={surface}
+    >
+      <button
+        type="button"
+        aria-label={isDetached ? "Drag floating menu" : "Drag to float menu"}
+        data-testid={`${surface}-detach-drag-handle`}
+        className="inline-flex h-6 items-center justify-center rounded-md border border-transparent px-1.5 text-tertiary transition-colors hover:border-border/60 hover:bg-surface hover:text-primary"
+        onMouseDown={beginDrag}
+      >
+        <GripHorizontal className="h-3 w-3" />
+      </button>
+      <span className="text-[9px] font-semibold uppercase tracking-[0.12em] text-tertiary">
+        {label}
+      </span>
+      <span className="rounded-full bg-surface px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-[0.08em] text-secondary">
+        {isDetached ? "Floating" : "Docked"}
+      </span>
+      <button
+        type="button"
+        aria-label={isDetached ? "Dock menu" : "Float menu"}
+        aria-pressed={isDetached}
+        data-testid={`${surface}-detach-toggle`}
+        className="inline-flex h-6 items-center rounded-md border border-border/60 px-2 text-[10px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary"
+        onMouseDown={preserveEditorSelectionMouseDown}
+        onClick={toggle}
+      >
+        {isDetached ? "Dock menu" : "Float menu"}
+      </button>
+    </div>
+  );
+}
+
+export default TwDetachHandle;

package/src/ui-tailwind/chrome/tw-selection-anchor-resolver.ts

@@ -0,0 +1,163 @@
+/**
+ * Selection anchor resolver — pure helper that turns a runtime selection
+ * into an overlay-space `RenderFrameRect` via the layout facet's render-
+ * kernel anchor index.
+ *
+ * Replaces the DOM-rect + zoomScale math that lived in
+ * `tw-review-workspace.tsx` (`resolveSelectionToolbarPlacement`, dropped
+ * in R2).  Per runtime-rendering-and-chrome-phase.md §6.2, every chrome
+ * surface reads anchors from the kernel — not DOM rects — so selection
+ * chrome stays glued to canonical positions through scroll, zoom, and
+ * predicted-text reconciliation.
+ *
+ * The resolver is intentionally pure: same facet + selection + tool kind
+ * returns the same rect.  Consumers compose it with the placement
+ * helper (`tw-selection-tool-placement.ts`) and the overlay projector.
+ */
+
+import type {
+  RenderFrameRect,
+  SelectionSnapshot,
+  TableStructureContextSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
+import type {
+  ActiveImageContext,
+  ActiveObjectContext,
+  ActiveSelectionToolModel,
+} from "../../ui/headless/selection-tool-types";
+
+export interface ResolveSelectionAnchorInput {
+  facet: WordReviewEditorLayoutFacet;
+  selection: SelectionSnapshot;
+  tool: ActiveSelectionToolModel | null;
+}
+
+/**
+ * Resolve the anchor rect for the currently active selection tool.
+ *
+ * - formatting / suggestion / comment / workflow / blocked → bySelection
+ *   over the selection's from/to offsets (collapsed selections fall
+ *   through to byRuntimeOffset).
+ * - structure(image) → byBlockId when the image has a mediaId that the
+ *   engine can map back to a block; else falls through to selection.
+ * - structure(object) → same as image.
+ * - structure(table) → (byTableCell from sibling plan P4 when shipped;
+ *   today we fall back to bySelection against the selected cells' range).
+ * - structure(list) → bySelection.
+ *
+ * Returns `null` when the facet has no render kernel installed or the
+ * selection does not resolve to any anchor.
+ */
+export function resolveSelectionAnchor(
+  input: ResolveSelectionAnchorInput,
+): RenderFrameRect | null {
+  const { facet, selection, tool } = input;
+  // No kernel, no anchor — caller falls back to DOM rects in that case.
+  const frame =
+    typeof facet.getRenderFrame === "function"
+      ? facet.getRenderFrame() ?? null
+      : null;
+  if (!frame) return null;
+
+  if (!tool) {
+    return anchorForSelection(frame.anchorIndex, selection);
+  }
+
+  switch (tool.kind) {
+    case "structure-context": {
+      const structural = resolveStructuralAnchor(frame, tool);
+      if (structural) return structural;
+      return anchorForSelection(frame.anchorIndex, selection);
+    }
+    case "formatting-inline":
+    case "suggestion-review":
+    case "comment-thread":
+    case "workflow-task":
+    case "blocked-explainer":
+      return anchorForSelection(frame.anchorIndex, selection);
+    default: {
+      const _exhaustive: never = tool;
+      void _exhaustive;
+      return anchorForSelection(frame.anchorIndex, selection);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function anchorForSelection(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  selection: SelectionSnapshot,
+): RenderFrameRect | null {
+  if (selection.activeRange.kind === "node") {
+    // Node selection — snap to the node's runtime offset.
+    return anchorIndex.byRuntimeOffset(selection.activeRange.at);
+  }
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  if (from === to) {
+    return anchorIndex.byRuntimeOffset(from);
+  }
+  return anchorIndex.bySelection(from, to);
+}
+
+function resolveStructuralAnchor(
+  frame: import("../../api/public-types").RenderFrame,
+  tool: ActiveSelectionToolModel & { kind: "structure-context" },
+): RenderFrameRect | null {
+  const { anchorIndex } = frame;
+  switch (tool.structureKind) {
+    case "image":
+      return resolveImageAnchor(anchorIndex, tool.activeImage);
+    case "object":
+      return resolveObjectAnchor(anchorIndex, tool.activeObject);
+    case "table":
+      return resolveTableAnchor(frame, tool.activeTable ?? undefined);
+    case "list":
+      return null;
+  }
+}
+
+function resolveImageAnchor(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  image: ActiveImageContext | undefined,
+): RenderFrameRect | null {
+  if (!image) return null;
+  // Images are identified by mediaId; the engine emits block fragments
+  // whose blockId ties back to the image's anchor block.  When the
+  // chrome has no better handle, fall back to byBlockId(mediaId) — which
+  // may or may not match depending on the engine's mapping.  If it
+  // doesn't, the outer caller falls through to bySelection.
+  const rect = anchorIndex.byBlockId(image.mediaId);
+  return rect;
+}
+
+function resolveObjectAnchor(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  _object: ActiveObjectContext | undefined,
+): RenderFrameRect | null {
+  void anchorIndex;
+  void _object;
+  // Shape/textbox anchors don't have a stable id today; fall through to
+  // the selection path.  Sibling plan P4 adds `byTableCell` and similar
+  // precise accessors for structural objects; this lane will adopt them.
+  return null;
+}
+
+function resolveTableAnchor(
+  frame: import("../../api/public-types").RenderFrame,
+  table: TableStructureContextSnapshot | undefined,
+): RenderFrameRect | null {
+  if (!table) return null;
+  // Sibling plan P4 will expose `byTableCell(tableBlockId, row, col)`
+  // and `byTableColumnEdge` / `byTableRowEdge` on the anchor index.
+  // Today we have only `tableBlockIndex` (ordinal), so the best-effort
+  // fallback is the selection path — callers chain to `anchorForSelection`
+  // when this returns null.
+  void frame;
+  void table;
+  return null;
+}