@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/ui/headless/chrome-registry.ts

@@ -0,0 +1,501 @@
+import type {
+  EditorRole,
+  WordReviewEditorChromePreset,
+} from "../../api/public-types";
+import type { SelectionToolKind } from "./selection-tool-types";
+
+export type ChromeSurface = "top-toolbar" | "selection-tool";
+export type ChromeDensity = "compact";
+export type ToolbarChromePlacement = "inline" | "overflow" | "hidden";
+
+export type ToolbarChromeItemId =
+  // Universal formatting + history
+  | "history"
+  | "text-style-selectors"
+  | "inline-formatting"
+  | "text-colors"
+  | "paragraph-alignment"
+  | "list-actions"
+  | "indentation"
+  | "list-continuation"
+  | "insert-actions"
+  | "update-actions"
+  | "scope-status"
+  | "story-breadcrumb"
+  | "sidebar-toggle"
+  | "comment"
+  | "tracked-changes-toggle"
+  | "workspace-mode"
+  | "zoom"
+  | "health"
+  | "export"
+  // R1: role-scoped action region entries
+  | "editor-scope-posture-menu"
+  | "review-queue-prev"
+  | "review-queue-next"
+  | "review-queue-counts"
+  | "review-queue-active-label"
+  | "review-accept"
+  | "review-reject"
+  | "review-accept-all"
+  | "review-reject-all"
+  | "review-markup-mode"
+  | "workflow-prev"
+  | "workflow-next"
+  | "workflow-mark-complete"
+  | "workflow-claim"
+  | "workflow-skip"
+  | "workflow-mark-blocked"
+  | "workflow-jump-to-scope";
+
+export interface ChromeRegistryEntryBase {
+  id: string;
+  surfaces: ReadonlyArray<ChromeSurface>;
+  group: string;
+}
+
+export interface SelectionToolRegistryEntry extends ChromeRegistryEntryBase {
+  id: SelectionToolKind;
+  surfaces: ["selection-tool"];
+  precedence: number;
+}
+
+export interface ToolbarChromeRegistryEntry extends ChromeRegistryEntryBase {
+  id: ToolbarChromeItemId;
+  surfaces: ["top-toolbar"];
+  presets: ReadonlyArray<WordReviewEditorChromePreset>;
+  /**
+   * Roles in which this entry appears.  Empty = appears in every role.
+   * R1 uses this to filter the inline action set down to the per-role
+   * matrix described in the chrome-phase plan.
+   */
+  roles: ReadonlyArray<EditorRole>;
+  fullPlacement: Exclude<ToolbarChromePlacement, "hidden">;
+  compactPlacement: ToolbarChromePlacement;
+  runtimeBehavior: "always" | "formatting" | "structure" | "comment";
+  scopeBehavior?: "default" | "scoped-only" | "hidden-when-scoped";
+  /**
+   * Optional per-role placement override.  When a role overrides the
+   * placement (for instance, "text-style-selectors" is `inline` in editor
+   * but `overflow` in review/workflow), list the role-specific placement
+   * here.  Missing roles inherit `fullPlacement` / `compactPlacement`.
+   */
+  rolePlacement?: Partial<
+    Record<EditorRole, Exclude<ToolbarChromePlacement, "hidden">>
+  >;
+}
+
+const ALL_ROLES: ReadonlyArray<EditorRole> = ["editor", "review", "workflow"];
+const EDITOR_ONLY: ReadonlyArray<EditorRole> = ["editor"];
+const REVIEW_ONLY: ReadonlyArray<EditorRole> = ["review"];
+const WORKFLOW_ONLY: ReadonlyArray<EditorRole> = ["workflow"];
+const EDITOR_AND_REVIEW: ReadonlyArray<EditorRole> = ["editor", "review"];
+
+export const SELECTION_TOOL_REGISTRY: ReadonlyArray<SelectionToolRegistryEntry> = [
+  { id: "suggestion-review", surfaces: ["selection-tool"], group: "review", precedence: 10 },
+  { id: "comment-thread", surfaces: ["selection-tool"], group: "review", precedence: 20 },
+  { id: "workflow-task", surfaces: ["selection-tool"], group: "workflow", precedence: 30 },
+  { id: "structure-context", surfaces: ["selection-tool"], group: "structure", precedence: 40 },
+  { id: "formatting-inline", surfaces: ["selection-tool"], group: "formatting", precedence: 50 },
+  { id: "blocked-explainer", surfaces: ["selection-tool"], group: "blocked", precedence: 60 },
+];
+
+export const TOOLBAR_CHROME_REGISTRY: ReadonlyArray<ToolbarChromeRegistryEntry> = [
+  {
+    id: "history",
+    surfaces: ["top-toolbar"],
+    group: "history",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "text-style-selectors",
+    surfaces: ["top-toolbar"],
+    group: "text",
+    presets: ["advanced", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+      workflow: "overflow",
+    },
+  },
+  {
+    id: "inline-formatting",
+    surfaces: ["top-toolbar"],
+    group: "text",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+      workflow: "overflow",
+    },
+  },
+  {
+    id: "text-colors",
+    surfaces: ["top-toolbar"],
+    group: "text",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_AND_REVIEW,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+    },
+  },
+  {
+    id: "paragraph-alignment",
+    surfaces: ["top-toolbar"],
+    group: "paragraph",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_AND_REVIEW,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+    },
+  },
+  {
+    id: "list-actions",
+    surfaces: ["top-toolbar"],
+    group: "paragraph",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_AND_REVIEW,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+    },
+  },
+  {
+    id: "indentation",
+    surfaces: ["top-toolbar"],
+    group: "paragraph",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_AND_REVIEW,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "formatting",
+    rolePlacement: {
+      editor: "inline",
+      review: "overflow",
+    },
+  },
+  {
+    id: "list-continuation",
+    surfaces: ["top-toolbar"],
+    group: "paragraph",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "formatting",
+  },
+  {
+    id: "insert-actions",
+    surfaces: ["top-toolbar"],
+    group: "document",
+    presets: ["simple", "advanced"],
+    roles: EDITOR_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "structure",
+    scopeBehavior: "hidden-when-scoped",
+  },
+  {
+    id: "update-actions",
+    surfaces: ["top-toolbar"],
+    group: "document",
+    presets: ["advanced"],
+    roles: EDITOR_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "structure",
+    scopeBehavior: "hidden-when-scoped",
+  },
+  {
+    id: "scope-status",
+    surfaces: ["top-toolbar"],
+    group: "scope",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+    scopeBehavior: "scoped-only",
+  },
+  {
+    id: "story-breadcrumb",
+    surfaces: ["top-toolbar"],
+    group: "scope",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "sidebar-toggle",
+    surfaces: ["top-toolbar"],
+    group: "review",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "comment",
+    surfaces: ["top-toolbar"],
+    group: "review",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "comment",
+  },
+  {
+    id: "tracked-changes-toggle",
+    surfaces: ["top-toolbar"],
+    group: "review",
+    // R1 promotes this toggle to every preset that shows a toolbar so the
+    // editor role can see inline tracked changes without switching preset.
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workspace-mode",
+    surfaces: ["top-toolbar"],
+    group: "view",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "zoom",
+    surfaces: ["top-toolbar"],
+    group: "view",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "health",
+    surfaces: ["top-toolbar"],
+    group: "status",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "export",
+    surfaces: ["top-toolbar"],
+    group: "status",
+    presets: ["simple", "advanced", "review", "workflow"],
+    roles: ALL_ROLES,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+
+  // ───── R1: Editor-role primaries ──────────────────────────────────────
+  {
+    id: "editor-scope-posture-menu",
+    surfaces: ["top-toolbar"],
+    group: "scope",
+    presets: ["advanced", "review", "workflow"],
+    roles: EDITOR_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+
+  // ───── R1: Review-role primaries ──────────────────────────────────────
+  {
+    id: "review-queue-prev",
+    surfaces: ["top-toolbar"],
+    group: "review-queue",
+    presets: ["review", "workflow"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-queue-next",
+    surfaces: ["top-toolbar"],
+    group: "review-queue",
+    presets: ["review", "workflow"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-queue-counts",
+    surfaces: ["top-toolbar"],
+    group: "review-queue",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-queue-active-label",
+    surfaces: ["top-toolbar"],
+    group: "review-queue",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-accept",
+    surfaces: ["top-toolbar"],
+    group: "review-action",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-reject",
+    surfaces: ["top-toolbar"],
+    group: "review-action",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-accept-all",
+    surfaces: ["top-toolbar"],
+    group: "review-action",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-reject-all",
+    surfaces: ["top-toolbar"],
+    group: "review-action",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "review-markup-mode",
+    surfaces: ["top-toolbar"],
+    group: "review-action",
+    presets: ["review"],
+    roles: REVIEW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+
+  // ───── R1: Workflow-role primaries ────────────────────────────────────
+  {
+    id: "workflow-prev",
+    surfaces: ["top-toolbar"],
+    group: "workflow-queue",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-next",
+    surfaces: ["top-toolbar"],
+    group: "workflow-queue",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-mark-complete",
+    surfaces: ["top-toolbar"],
+    group: "workflow-action",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-claim",
+    surfaces: ["top-toolbar"],
+    group: "workflow-action",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "inline",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-skip",
+    surfaces: ["top-toolbar"],
+    group: "workflow-action",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-mark-blocked",
+    surfaces: ["top-toolbar"],
+    group: "workflow-action",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+  {
+    id: "workflow-jump-to-scope",
+    surfaces: ["top-toolbar"],
+    group: "workflow-action",
+    presets: ["workflow"],
+    roles: WORKFLOW_ONLY,
+    fullPlacement: "inline",
+    compactPlacement: "overflow",
+    runtimeBehavior: "always",
+  },
+];

package/src/ui/headless/scoped-chrome-policy.ts

@@ -0,0 +1,183 @@
+import type {
+  ActiveListContext,
+  EditorRole,
+  InteractionGuardSnapshot,
+  WorkflowScopeSnapshot,
+  WordReviewEditorChromePreset,
+} from "../../api/public-types";
+import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import {
+  TOOLBAR_CHROME_REGISTRY,
+  type ToolbarChromeItemId,
+  type ToolbarChromePlacement,
+} from "./chrome-registry";
+import type { SelectionToolKind } from "./selection-tool-types";
+
+export interface ToolbarChromeItemPolicy {
+  visible: boolean;
+  enabled: boolean;
+  placement: ToolbarChromePlacement;
+}
+
+export interface ScopedChromePolicy {
+  density: "compact";
+  activeScopeId?: string;
+  activeWorkItemId?: string | null;
+  scopeStatusLabel?: string;
+  toolbar: Record<ToolbarChromeItemId, ToolbarChromeItemPolicy>;
+  selection: {
+    hiddenKinds: ReadonlyArray<SelectionToolKind>;
+  };
+}
+
+export interface ResolveScopedChromePolicyInput {
+  preset: WordReviewEditorChromePreset;
+  compactMode: boolean;
+  capabilities?: SessionCapabilities;
+  interactionGuardSnapshot?: InteractionGuardSnapshot;
+  workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
+  activeListContext?: ActiveListContext | null;
+  /**
+   * Active chrome role (spec §6.4).  When supplied, the policy filters
+   * registry entries whose `roles` array excludes the active role.  When
+   * omitted, the preset filter alone drives visibility (back-compat for
+   * callers that haven't adopted the role model yet).
+   */
+  role?: EditorRole;
+}
+
+export function resolveScopedChromePolicy(
+  input: ResolveScopedChromePolicyInput,
+): ScopedChromePolicy {
+  const effectiveMode = input.interactionGuardSnapshot?.effectiveMode ?? "edit";
+  const canFormatText = Boolean(input.capabilities?.canEdit) && effectiveMode === "edit";
+  const canInsertStructural = Boolean(input.capabilities?.canEdit) && effectiveMode === "edit";
+  const canAddComment =
+    Boolean(input.capabilities?.canAddComment) &&
+    effectiveMode !== "view" &&
+    effectiveMode !== "blocked";
+  const activeScopeId = input.interactionGuardSnapshot?.matchedScopeId;
+  const activeWorkItemId = input.workflowScopeSnapshot?.activeWorkItemId ?? null;
+  const hasScopedContext = Boolean(activeScopeId || activeWorkItemId);
+  const scopeStatusLabel =
+    input.workflowScopeSnapshot?.activeWorkItem?.title ??
+    input.workflowScopeSnapshot?.scopes.find((scope) => scope.scopeId === activeScopeId)?.label ??
+    (activeScopeId && input.interactionGuardSnapshot?.matchedScopeMode
+      ? `Scoped ${input.interactionGuardSnapshot.matchedScopeMode}`
+      : undefined);
+
+  const toolbar = Object.fromEntries(
+    TOOLBAR_CHROME_REGISTRY.map((entry) => {
+      let visible = entry.presets.includes(input.preset);
+
+      // Role filter — apply only when the caller supplied a role so existing
+      // host apps that haven't adopted the role model keep the pre-R1
+      // behavior (preset + capability only).
+      if (visible && input.role !== undefined) {
+        visible = entry.roles.includes(input.role);
+      }
+
+      if (visible) {
+        switch (entry.runtimeBehavior) {
+          case "formatting":
+            visible = canFormatText;
+            break;
+          case "structure":
+            visible = canInsertStructural;
+            break;
+          case "comment":
+            visible = canAddComment;
+            break;
+          default:
+            visible = true;
+            break;
+        }
+      }
+
+      if (visible && entry.id === "list-continuation") {
+        visible = Boolean(input.activeListContext);
+      }
+      if (visible && entry.id === "scope-status") {
+        visible = Boolean(scopeStatusLabel);
+      }
+
+      if (visible && entry.scopeBehavior === "scoped-only") {
+        visible = hasScopedContext;
+      }
+      if (visible && entry.scopeBehavior === "hidden-when-scoped") {
+        visible = !hasScopedContext;
+      }
+
+      // Resolve placement: when the entry overrides placement for the
+      // active role, that wins over the preset-density default.
+      const fullPlacement =
+        (input.role && entry.rolePlacement?.[input.role]) ?? entry.fullPlacement;
+      const placement = visible
+        ? (input.compactMode ? entry.compactPlacement : fullPlacement)
+        : "hidden";
+      const enabled =
+        visible &&
+        (entry.id !== "tracked-changes-toggle" || Boolean(input.capabilities?.trackChangesSupported)) &&
+        (entry.id !== "export" || Boolean(input.capabilities?.canExport));
+
+      return [
+        entry.id,
+        {
+          visible,
+          enabled,
+          placement,
+        } satisfies ToolbarChromeItemPolicy,
+      ];
+    }),
+  ) as Record<ToolbarChromeItemId, ToolbarChromeItemPolicy>;
+
+  const hiddenKinds = resolveHiddenSelectionToolKinds(effectiveMode);
+
+  return {
+    density: "compact",
+    ...(activeScopeId ? { activeScopeId } : {}),
+    activeWorkItemId,
+    ...(scopeStatusLabel ? { scopeStatusLabel } : {}),
+    toolbar,
+    selection: {
+      hiddenKinds,
+    },
+  };
+}
+
+export function isToolbarChromeItemVisible(
+  policy: ScopedChromePolicy,
+  itemId: ToolbarChromeItemId,
+): boolean {
+  return policy.toolbar[itemId]?.visible ?? false;
+}
+
+export function getToolbarChromePlacement(
+  policy: ScopedChromePolicy,
+  itemId: ToolbarChromeItemId,
+): ToolbarChromePlacement {
+  return policy.toolbar[itemId]?.placement ?? "hidden";
+}
+
+export function shouldRenderSelectionToolKind(
+  policy: ScopedChromePolicy | undefined,
+  kind: SelectionToolKind,
+): boolean {
+  return !policy?.selection.hiddenKinds.includes(kind);
+}
+
+function resolveHiddenSelectionToolKinds(
+  effectiveMode: InteractionGuardSnapshot["effectiveMode"] | "edit",
+): ReadonlyArray<SelectionToolKind> {
+  switch (effectiveMode) {
+    case "suggest":
+      return ["formatting-inline", "structure-context"];
+    case "comment":
+      return ["formatting-inline", "structure-context"];
+    case "view":
+    case "blocked":
+      return ["formatting-inline", "structure-context", "suggestion-review"];
+    default:
+      return [];
+  }
+}

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

@@ -5,6 +5,7 @@ import type {
   StyleCatalogSnapshot,
 } from "../../api/public-types";
 import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { ScopedChromePolicy } from "./scoped-chrome-policy";
 import type { SelectionToolResolverContext } from "./selection-tool-types";
 
 export interface SelectionToolResolverInput extends SelectionToolResolverContext {
@@ -16,4 +17,5 @@ export interface SelectionToolResolverInput extends SelectionToolResolverContext
   preferListStructureContext?: boolean;
   addCommentDisabledReason?: string;
   suppressedSuggestionRevisionId?: string | null;
+  scopedChromePolicy?: ScopedChromePolicy;
 }