@beyondwork/docx-react-component 1.0.37 → 1.0.39

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";
+  }
+}