@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/src/runtime/view-state.ts

@@ -19,13 +19,17 @@ import type {
   ActiveListContext,
   ActiveNoteContext,
   CaretAffinity,
+  ChromePinsState,
+  ChromePinSurface,
   DocumentMode,
+  EditorRole,
   EditorStoryTarget,
   EditorSurfaceSnapshot,
   EditorViewStateSnapshot,
   LayoutMeasurement,
   PageLayoutSnapshot,
   PageRegionHitTest,
+  PinState,
   SelectionSnapshot,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
@@ -44,6 +48,20 @@ export interface ViewState {
   caretAffinity: CaretAffinity;
   activePageRegion: PageRegionHitTest | null;
   activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
+  /**
+   * Role-scoped chrome dimension (spec §6.4).  Host apps drive the role via
+   * `setEditorRole`; the mounted shell reads this to pick a per-role
+   * toolbar action set.  Independent of `viewMode` — one user session may
+   * start in "review" role and switch to "editor" without changing
+   * workspace or document mode.
+   */
+  editorRole: EditorRole;
+  /**
+   * Pin state for detachable chrome surfaces (topnav, selection tier).
+   * Lives here so it survives snapshot rebuilds within one session.
+   * Absent key ⇒ docked default.
+   */
+  chromePins: ChromePinsState;
 }
 
 const MIN_ZOOM_PERCENT = 50;
@@ -58,6 +76,8 @@ const DEFAULT_VIEW_STATE: ViewState = {
   caretAffinity: "none",
   activePageRegion: null,
   activeObjectFrame: null,
+  editorRole: "editor",
+  chromePins: {},
 };
 
 export function createViewState(initial?: Partial<ViewState>): ViewState {
@@ -113,6 +133,37 @@ export function setActiveObjectFrame(
   return { ...state, activeObjectFrame: frame };
 }
 
+export function setEditorRole(state: ViewState, role: EditorRole): ViewState {
+  if (state.editorRole === role) return state;
+  return { ...state, editorRole: role };
+}
+
+export function setChromePin(
+  state: ViewState,
+  surface: ChromePinSurface,
+  pin: PinState | null,
+): ViewState {
+  const next: ChromePinsState = { ...state.chromePins };
+  if (pin === null) {
+    if (next[surface] === undefined) {
+      return state;
+    }
+    delete next[surface];
+  } else {
+    const current = next[surface];
+    if (
+      current &&
+      current.detached === pin.detached &&
+      current.offset.x === pin.offset.x &&
+      current.offset.y === pin.offset.y
+    ) {
+      return state;
+    }
+    next[surface] = pin;
+  }
+  return { ...state, chromePins: next };
+}
+
 /**
  * Derive list context from the surface block at the current selection head.
  */
@@ -219,9 +270,25 @@ export function createEditorViewStateSnapshot(
     activeObjectFrame: derivedViewState.activeObjectFrame,
     measurement,
     isFocused: derivedViewState.isFocused,
+    editorRole: derivedViewState.editorRole,
+    chromePins: cloneChromePins(derivedViewState.chromePins),
   };
 }
 
+function cloneChromePins(pins: ChromePinsState): ChromePinsState {
+  const out: ChromePinsState = {};
+  for (const key of Object.keys(pins) as ChromePinSurface[]) {
+    const pin = pins[key];
+    if (pin) {
+      out[key] = {
+        detached: pin.detached,
+        offset: { x: pin.offset.x, y: pin.offset.y },
+      };
+    }
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/src/runtime/workflow-markup.ts

@@ -341,11 +341,7 @@ function collectOpaqueFragmentMarkup(
   const seen = new Set(existing.map((item) => item.fragmentId));
 
   return Object.values(preservation.opaqueFragments)
-    .filter(
-      (fragment) =>
-        !seen.has(fragment.fragmentId)
-        && fragment.packagePartName === "/word/document.xml",
-    )
+    .filter((fragment) => !seen.has(fragment.fragmentId))
     .map((fragment) => {
       const descriptor = describeOpaqueFragment(fragment);
       const blockedReasonCode = isBlockedImportFeatureKey(descriptor.featureKey)

package/src/runtime/workflow-rail-segments.ts

@@ -0,0 +1,280 @@
+/**
+ * Workflow rail-segment projection.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §5, the action rail v2 renders
+ * OUTSIDE the PM NodeView tree as an overlay layer positioned from
+ * canonical scope data.  This module joins the host-supplied
+ * `WorkflowOverlay` (scopes, candidates) + blocked-reason ranges +
+ * locked-zone data with the runtime page graph to produce
+ * `ScopeRailSegment[]` — the shape chrome consumes to render the
+ * left-gutter label column and the flat block-tint.
+ *
+ * The segments are pure reads over canonical state; no DOM, no PM.
+ */
+
+import type {
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowLockedZone,
+  WorkflowScope,
+} from "../api/public-types";
+import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
+import type { RuntimePageGraph } from "./layout/page-graph.ts";
+import type { RenderFrameRect } from "./render/render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+export type ScopeRailPosture =
+  | "edit"
+  | "suggest"
+  | "comment"
+  | "view"
+  | "candidate"
+  | "preserve-only"
+  | "blocked-import";
+
+export interface ScopeRailSegment {
+  /** Identifier the chrome uses to sync with the Workflow rail tab. */
+  scopeId: string;
+  /** Visual+accessibility posture keyed off the scope mode or block reason. */
+  posture: ScopeRailPosture;
+  /** Human label; empty string when none was supplied by the host. */
+  label: string;
+  /** Runtime offsets (inclusive from, exclusive to) this segment spans on the active story. */
+  fromOffset: number;
+  toOffset: number;
+  /** Story the segment sits on. */
+  storyTarget: EditorStoryTarget;
+  /** Page index the segment renders on (may span multiple pages; emitted per page). */
+  pageIndex: number;
+  /** Section index derived from the page graph. */
+  sectionIndex: number;
+  /** True when the scope is the active work item. */
+  isActiveWorkItem: boolean;
+  /**
+   * Body-tint rect in overlay-space pixels, populated when the render kernel
+   * is available.  Chrome consumers read this directly instead of
+   * re-projecting per render via the overlay projector.  `null` when the
+   * segment is produced without a kernel (e.g., in tests or before the
+   * facet is bound to a page graph) — consumers fall back to per-render
+   * anchor resolution in that case.
+   */
+  bodyTintRect: RenderFrameRect | null;
+}
+
+// ---------------------------------------------------------------------------
+// Collector input
+// ---------------------------------------------------------------------------
+
+export interface CollectScopeRailSegmentsInput {
+  scopes: readonly WorkflowScope[] | undefined;
+  candidates?: readonly WorkflowCandidateRange[];
+  blockedReasons?: readonly WorkflowBlockedCommandReason[];
+  lockedZones?: readonly WorkflowLockedZone[];
+  activeWorkItemScopeIds?: readonly string[];
+  /** Active story scopes render on; segments for other stories are skipped. */
+  activeStory?: EditorStoryTarget;
+  pageGraph: RuntimePageGraph;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Build segments for every page in the graph.  Callers that only want a
+ * single page can filter by `segment.pageIndex` on the returned list.
+ */
+export function collectScopeRailSegments(
+  input: CollectScopeRailSegmentsInput,
+): ScopeRailSegment[] {
+  const segments: ScopeRailSegment[] = [];
+  const activeStory = input.activeStory ?? MAIN_STORY_TARGET;
+  const activeIds = new Set(input.activeWorkItemScopeIds ?? []);
+
+  for (const scope of input.scopes ?? []) {
+    const range = anchorToRuntimeRange(scope.anchor);
+    if (!range) continue;
+    const storyTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture = resolveScopePosture(scope);
+    const isActiveWorkItem = activeIds.has(scope.scopeId);
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: scope.scopeId,
+        posture,
+        label: scope.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Candidates render as a faint "candidate" posture so the reader knows
+  // where the host is proposing scopes before they're committed.
+  for (const candidate of input.candidates ?? []) {
+    const range = anchorToRuntimeRange(candidate.anchor);
+    if (!range) continue;
+    const storyTarget = candidate.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: candidate.candidateId,
+        posture: "candidate",
+        label: candidate.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Blocked-reason anchors: render a "blocked-import" or "preserve-only"
+  // posture so the rail signal matches the chrome message in image copy.png.
+  for (const reason of input.blockedReasons ?? []) {
+    if (!reason.anchor) continue;
+    const range = anchorToRuntimeRange(reason.anchor);
+    if (!range) continue;
+    const storyTarget = reason.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture: ScopeRailPosture =
+      reason.code === "workflow_blocked_import"
+        ? "blocked-import"
+        : reason.code === "workflow_preserve_only"
+          ? "preserve-only"
+          : "view";
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: `blocked:${reason.code}:${range.from}-${range.to}`,
+        posture,
+        label: reason.label ?? reason.message ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Locked zones project as their own preserve-only / blocked-import rails so
+  // locked cells, locked images, and locked runs show the lock posture in
+  // the gutter even without a workflow scope covering them.
+  for (const zone of input.lockedZones ?? []) {
+    const range = anchorToRuntimeRange(zone.anchor);
+    if (!range) continue;
+    const storyTarget = zone.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture: ScopeRailPosture =
+      zone.code === "workflow_blocked_import"
+        ? "blocked-import"
+        : "preserve-only";
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: zone.fragmentId ?? `locked:${range.from}-${range.to}`,
+        posture,
+        label: zone.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  return segments;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function anchorToRuntimeRange(
+  anchor: EditorAnchorProjection,
+): { from: number; to: number } | null {
+  if (anchor.kind === "range") {
+    const from = Math.min(anchor.from, anchor.to);
+    const to = Math.max(anchor.from, anchor.to);
+    return from < to ? { from, to } : null;
+  }
+  if (anchor.kind === "node") {
+    return { from: anchor.at, to: anchor.at + 1 };
+  }
+  // detached anchors cannot be rendered; use the last-known range as a
+  // best-effort ghost until the scope is re-anchored or dismissed.
+  if (anchor.lastKnownRange) {
+    const from = Math.min(anchor.lastKnownRange.from, anchor.lastKnownRange.to);
+    const to = Math.max(anchor.lastKnownRange.from, anchor.lastKnownRange.to);
+    return from < to ? { from, to } : null;
+  }
+  return null;
+}
+
+function pagesCoveringRange(
+  graph: RuntimePageGraph,
+  from: number,
+  to: number,
+): RuntimePageGraph["pages"] {
+  return graph.pages.filter(
+    (page) =>
+      !page.isBlankFiller &&
+      page.endOffset > from &&
+      page.startOffset < to,
+  );
+}
+
+function clipRangeToPage(
+  from: number,
+  to: number,
+  page: RuntimePageGraph["pages"][number],
+): { from: number; to: number } {
+  return {
+    from: Math.max(from, page.startOffset),
+    to: Math.min(to, page.endOffset),
+  };
+}
+
+function resolveScopePosture(scope: WorkflowScope): ScopeRailPosture {
+  switch (scope.mode) {
+    case "edit":
+      return "edit";
+    case "suggest":
+      return "suggest";
+    case "comment":
+      return "comment";
+    case "view":
+      return "view";
+    default:
+      return "view";
+  }
+}

package/src/ui/WordReviewEditor.tsx

@@ -48,6 +48,8 @@ import type {
   StyleCatalogSnapshot,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
+  TableOp,
+  TableOpResult,
   TrackedChangeEntrySnapshot,
   TocRefreshResult,
   UpdateFieldsResult,
@@ -113,6 +115,7 @@ import {
 import {
   applyTableStructureOperation,
   getTableStructureContext,
+  type TableStructureOperation,
 } from "../core/commands/table-structure-commands.ts";
 import {
   deleteSelectionOrBackward,
@@ -579,6 +582,7 @@ export function __createWordReviewEditorRefBridge(
       return clonePublicValue(runtime.getRuntimeContextAnalytics(query));
     },
     layout: runtime.layout,
+    tables: buildTablesFacet(runtime, mountedSurface ?? null),
     goToNextReviewItem: () => {
       return clonePublicValue(navigateReviewQueue(runtime, "next"));
     },
@@ -1394,6 +1398,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           return clonePublicValue(activeRuntime.getRuntimeContextAnalytics(query));
         },
         layout: activeRuntime.layout,
+        tables: buildTablesFacet(activeRuntime, surfaceRef.current ?? null),
         goToNextReviewItem: () => {
           return clonePublicValue(navigateMountedReviewQueue("next"));
         },
@@ -2300,6 +2305,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         activeRevisionId={activeRevisionId}
         showTrackedChanges={showTrackedChanges}
         workflowScopeSnapshot={workflowScopeSnapshot}
+        layoutFacet={activeRuntime.layout}
         interactionGuardSnapshot={interactionGuardSnapshot}
         chromePreset={effectiveChromePreset}
         chromeOptions={chromeOptions}
@@ -3388,28 +3394,19 @@ function applyRuntimeImageReposition(
 function applyRuntimeTableStructureOperation(
   runtime: WordReviewEditorRuntime,
   mountedSurface: TwProseMirrorSurfaceRef | null | undefined,
-  operation:
-    | { type: "add-row-before" }
-    | { type: "add-row-after" }
-    | { type: "add-column-before" }
-    | { type: "add-column-after" }
-    | { type: "delete-row" }
-    | { type: "delete-column" }
-    | { type: "delete-table" }
-    | { type: "merge-cells" }
-    | { type: "split-cell" }
-    | { type: "set-cell-background"; color: string },
-): void {
+  operation: TableStructureOperation,
+): { changed: boolean; coercedReason: string | null } {
   if (isSelectionSuggesting(runtime)) {
+    const coercedReason = `Table operation "${operation.type}" is not supported in suggesting mode.`;
     runtime.emitBlockedCommand(`table.${operation.type}`, [{
       code: "unsupported_surface",
-      message: `Table operation "${operation.type}" is not supported in suggesting mode.`,
+      message: coercedReason,
     }]);
-    return;
+    return { changed: false, coercedReason };
   }
   const context = getStoryMutationContext(runtime, `table.${operation.type}`);
   if (!context) {
-    return;
+    return { changed: false, coercedReason: "No active mutation context." };
   }
 
   const result = applyTableStructureOperation(
@@ -3419,6 +3416,78 @@ function applyRuntimeTableStructureOperation(
     operation,
   );
   dispatchStoryMutationResult(runtime, context, result, context.timestamp);
+  return {
+    changed: result.changed,
+    coercedReason: result.changed ? null : "Op was a no-op against the active selection.",
+  };
+}
+
+/**
+ * Translate a public-API `TableOp` (kebab-case `kind` discriminator) to
+ * the internal `TableStructureOperation` (`type` discriminator). The
+ * shape values are identical aside from the discriminator name.
+ */
+export function __publicTableOpToInternal(op: TableOp): TableStructureOperation {
+  return publicTableOpToInternal(op);
+}
+
+function publicTableOpToInternal(op: TableOp): TableStructureOperation {
+  const { kind, ...rest } = op as { kind: string } & Record<string, unknown>;
+  if (kind === "insert") {
+    throw new Error(
+      "TableOp kind \"insert\" is not routed through ref.tables.apply; use ref.insertTable(...).",
+    );
+  }
+  return { type: kind, ...rest } as TableStructureOperation;
+}
+
+/**
+ * Build the `ref.tables` facet: a typed dispatch boundary + capability
+ * read. Delegates every op through the same `applyRuntimeTableStructureOperation`
+ * helper the flat ref verbs use, so there is exactly one server-side path
+ * for every table mutation.
+ */
+function buildTablesFacet(
+  runtime: WordReviewEditorRuntime,
+  mountedSurface: TwProseMirrorSurfaceRef | null,
+) {
+  const getCapabilities = () => {
+    const snapshot = runtime.getRenderSnapshot();
+    const document = runtime.getSessionState().canonicalDocument;
+    return (
+      clonePublicValue(
+        getTableStructureContext(
+          document,
+          snapshot,
+          mountedSurface?.getTableSelection() ?? null,
+        ),
+      ) ?? null
+    );
+  };
+  return {
+    apply(op: TableOp): TableOpResult {
+      if (op.kind === "insert") {
+        applyRuntimeInsertTable(runtime, { rows: op.rows, columns: op.columns });
+        return {
+          changed: true,
+          coercedReason: null,
+          capabilities: getCapabilities(),
+        };
+      }
+      const internal = publicTableOpToInternal(op);
+      const outcome = applyRuntimeTableStructureOperation(
+        runtime,
+        mountedSurface,
+        internal,
+      );
+      return {
+        changed: outcome.changed,
+        coercedReason: outcome.coercedReason,
+        capabilities: getCapabilities(),
+      };
+    },
+    getCapabilities,
+  };
 }
 
 function applyRuntimeTextCommand(

package/src/ui/editor-shell-view.tsx

@@ -55,6 +55,12 @@ export interface EditorShellViewProps {
   activeRevisionId?: string;
   showTrackedChanges: boolean;
   workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
+  /**
+   * Runtime-owned layout facet passed through to the workspace so the
+   * ChromeOverlay (scope rail, workflow dock, etc.) can render over the
+   * document column and the review rail's Workflow tab can read segments.
+   */
+  layoutFacet?: import("../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;