@beyondwork/docx-react-component 1.0.104 → 1.0.106

package/src/runtime/workflow/overlay-lanes.ts

@@ -0,0 +1,228 @@
+import type {
+  CommentSidebarSnapshot,
+  SuggestionsSnapshot,
+  TrackedChangesSnapshot,
+  WorkflowMarkupSnapshot,
+  WorkflowScopeSnapshot,
+} from "../../api/public-types.ts";
+import { ISSUE_METADATA_ID } from "../../api/public-types.ts";
+import type {
+  UiOverlayLaneEntry,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+  UiOverlayLaneStatus,
+} from "../../api/v3/ui/index.ts";
+
+export type WorkflowReviewOverlayLaneKind = Extract<
+  UiOverlayLaneKind,
+  "redlines" | "comments" | "issues" | "field-scopes" | "broad-scopes" | "presence"
+>;
+
+export interface WorkflowReviewOverlayLaneInput {
+  readonly comments?: CommentSidebarSnapshot;
+  readonly trackedChanges?: TrackedChangesSnapshot;
+  readonly suggestions?: SuggestionsSnapshot | null;
+  readonly workflowScope?: WorkflowScopeSnapshot;
+  readonly workflowMarkup?: WorkflowMarkupSnapshot;
+  readonly revision?: number;
+}
+
+/**
+ * Layer-06 data handoff for L10/L11 PE2 overlay lanes.
+ *
+ * This projector emits plain lane snapshots only. It does not resolve geometry,
+ * read DOM state, subscribe to awareness, dispatch PM transactions, or wake
+ * layout. Presence is intentionally unavailable here because live cursor/
+ * collaborator state is sourced from Yjs awareness, not durable workflow truth.
+ */
+export function projectWorkflowReviewOverlayLane(
+  kind: WorkflowReviewOverlayLaneKind,
+  input: WorkflowReviewOverlayLaneInput,
+): UiOverlayLaneSnapshot {
+  if (kind === "presence") {
+    return {
+      kind,
+      status: "unavailable",
+      entries: [],
+      revision: input.revision ?? 0,
+      source: "awareness",
+      reason: "presence lane is sourced from Yjs awareness, not durable workflow/review state",
+    };
+  }
+
+  const entries = projectEntries(kind, input);
+  return {
+    kind,
+    status: summarizeStatus(entries),
+    entries,
+    revision: input.revision ?? 0,
+    source: "workflow",
+  };
+}
+
+function projectEntries(
+  kind: Exclude<WorkflowReviewOverlayLaneKind, "presence">,
+  input: WorkflowReviewOverlayLaneInput,
+): UiOverlayLaneEntry[] {
+  switch (kind) {
+    case "comments":
+      return (input.comments?.threads ?? []).map((thread) => ({
+        id: thread.commentId,
+        status: thread.status === "detached" ? "requires-rehydration" : "resolved",
+        anchor: { kind: "comment", value: thread.commentId },
+        reason: thread.detachedReason,
+        data: compactData({
+          laneItemKind: "comment",
+          commentId: thread.commentId,
+          editorAnchor: thread.anchor,
+          status: thread.status,
+          createdAt: thread.createdAt,
+          createdBy: thread.createdBy,
+          entryCount: thread.entryCount,
+          warningCount: thread.warningCount,
+          linkedRevisionId: thread.linkedRevisionId,
+          excerpt: thread.excerpt,
+          anchorLabel: thread.anchorLabel,
+        }),
+      }));
+    case "redlines":
+      return (input.trackedChanges?.revisions ?? []).map((revision) => ({
+        id: revision.revisionId,
+        status: revision.status === "detached" ? "requires-rehydration" : "resolved",
+        anchor: { kind: "revision", value: revision.revisionId },
+        reason: revision.preserveOnlyReason,
+        data: compactData({
+          laneItemKind: "revision",
+          revisionId: revision.revisionId,
+          editorAnchor: revision.anchor,
+          revisionKind: revision.kind,
+          semanticKind: revision.semanticKind,
+          suggestionId: revision.suggestionId,
+          status: revision.status,
+          actionability: revision.actionability,
+          authorId: revision.authorId,
+          createdAt: revision.createdAt,
+          label: revision.label,
+          excerpt: revision.excerpt,
+          storyTarget: revision.storyTarget,
+          canAccept: revision.canAccept,
+          canReject: revision.canReject,
+          warningCount: revision.warningCount,
+          commentThreadIds: revision.commentThreadIds,
+        }),
+      }));
+    case "issues":
+      return projectIssueEntries(input);
+    case "field-scopes":
+      return (input.workflowMarkup?.fields ?? []).map((field) => ({
+        id: `field:${field.fieldIndex}`,
+        status: "resolved",
+        data: compactData({
+          laneItemKind: "field",
+          fieldIndex: field.fieldIndex,
+          editorAnchor: field.anchor,
+          fieldFamily: field.fieldFamily,
+          fieldTarget: field.fieldTarget,
+          refreshStatus: field.refreshStatus,
+          displayText: field.displayText,
+          label: field.label,
+          storyTarget: field.storyTarget,
+        }),
+      }));
+    case "broad-scopes":
+      return [
+        ...(input.workflowScope?.scopes ?? []).map((scope) => ({
+          id: scope.scopeId,
+          status: "resolved" as const,
+          anchor: { kind: "scope" as const, value: scope.scopeId },
+          data: compactData({
+            laneItemKind: "workflow-scope",
+            scopeId: scope.scopeId,
+            editorAnchor: scope.anchor,
+            mode: scope.mode,
+            label: scope.label,
+            domain: scope.domain,
+            workItemId: scope.workItemId,
+            visibility: scope.visibility,
+            guardPolicy: scope.guardPolicy,
+            storyTarget: scope.storyTarget,
+            metadataRefs: scope.metadataRefs,
+          }),
+        })),
+        ...(input.workflowScope?.candidates ?? []).map((candidate) => ({
+          id: candidate.candidateId,
+          status: "resolved" as const,
+          data: compactData({
+            laneItemKind: "workflow-candidate",
+            candidateId: candidate.candidateId,
+            editorAnchor: candidate.anchor,
+            label: candidate.label,
+            source: candidate.source,
+            storyTarget: candidate.storyTarget,
+          }),
+        })),
+      ];
+  }
+}
+
+function projectIssueEntries(input: WorkflowReviewOverlayLaneInput): UiOverlayLaneEntry[] {
+  const suggestionGroupsByIssueId = new Map<string, string[]>();
+  for (const group of input.suggestions?.groups ?? []) {
+    if (!group.issueId) continue;
+    const ids = suggestionGroupsByIssueId.get(group.issueId) ?? [];
+    ids.push(group.groupId);
+    suggestionGroupsByIssueId.set(group.issueId, ids);
+  }
+
+  return (input.workflowMarkup?.metadata ?? [])
+    .filter((entry) => entry.metadataId === ISSUE_METADATA_ID)
+    .map((entry) => {
+      const issueValue = isRecord(entry.value) ? entry.value : undefined;
+      const issueId = typeof issueValue?.issueId === "string" ? issueValue.issueId : undefined;
+      return {
+        id: issueId ?? entry.entryId,
+        status: "resolved",
+        anchor: entry.scopeId ? { kind: "scope", value: entry.scopeId } : undefined,
+        data: compactData({
+          laneItemKind: "issue",
+          entryId: entry.entryId,
+          metadataId: entry.metadataId,
+          issueId,
+          editorAnchor: entry.anchor,
+          scopeId: entry.scopeId,
+          workItemId: entry.workItemId,
+          label: entry.label,
+          title: typeof issueValue?.title === "string" ? issueValue.title : undefined,
+          topic: typeof issueValue?.topic === "string" ? issueValue.topic : undefined,
+          severity: typeof issueValue?.severity === "string" ? issueValue.severity : undefined,
+          checklistState:
+            typeof issueValue?.checklistState === "string" ? issueValue.checklistState : undefined,
+          suggestionGroupIds: issueId ? suggestionGroupsByIssueId.get(issueId) ?? [] : [],
+          persistence: entry.persistence,
+          metadataPersistence: entry.metadataPersistence,
+          storageRef: entry.storageRef,
+          metadataVersion: entry.metadataVersion,
+        }),
+      };
+    });
+}
+
+function summarizeStatus(entries: readonly UiOverlayLaneEntry[]): UiOverlayLaneStatus {
+  return entries.some((entry) => entry.status === "requires-rehydration")
+    ? "requires-rehydration"
+    : "resolved";
+}
+
+function compactData(input: Record<string, unknown>): Readonly<Record<string, unknown>> {
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/ui/presence-overlay-lane.ts

@@ -0,0 +1,131 @@
+import {
+  getRemoteCursorStates,
+  type RemoteCursorState,
+} from "../api/v3/runtime/collab.ts";
+import type {
+  GeometryRect,
+  UiListener,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+  UiOverlayLaneStatus,
+  UiUnsubscribe,
+} from "../api/v3/ui/_types.ts";
+
+type AwarenessChangeListener = () => void;
+
+export interface PresenceAwarenessSource {
+  readonly clientID: number;
+  getStates(): Map<number, Record<string, unknown>>;
+  on(event: "change", listener: AwarenessChangeListener): void;
+  off(event: "change", listener: AwarenessChangeListener): void;
+}
+
+export type PresenceCursorProjection =
+  | { readonly status: "resolved"; readonly rects: readonly GeometryRect[]; readonly reason?: string }
+  | { readonly status: "requires-rehydration" | "unavailable"; readonly rects?: undefined; readonly reason?: string };
+
+export interface PresenceOverlayLaneSourceOptions {
+  readonly awareness: PresenceAwarenessSource;
+  readonly localClientId?: number;
+  readonly getRevision?: () => number;
+  readonly projectCursor?: (cursor: RemoteCursorState) => PresenceCursorProjection;
+}
+
+export interface PresenceOverlayLaneSource {
+  getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot;
+  subscribeLane(
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ): UiUnsubscribe;
+}
+
+function unavailable(kind: UiOverlayLaneKind, reason: string): UiOverlayLaneSnapshot {
+  return Object.freeze({
+    __mock: true,
+    kind,
+    status: "unavailable",
+    entries: Object.freeze([]),
+    revision: 0,
+    source: "unavailable",
+    reason,
+  } as const);
+}
+
+function coerceLaneStatus(
+  current: UiOverlayLaneStatus,
+  next: UiOverlayLaneStatus,
+): UiOverlayLaneStatus {
+  if (current === "unavailable" || next === "unavailable") return "unavailable";
+  if (current === "requires-rehydration" || next === "requires-rehydration") {
+    return "requires-rehydration";
+  }
+  return "resolved";
+}
+
+export function createPresenceOverlayLaneSource(
+  options: PresenceOverlayLaneSourceOptions,
+): PresenceOverlayLaneSource {
+  const localClientId = options.localClientId ?? options.awareness.clientID;
+
+  function readPresenceLane(): UiOverlayLaneSnapshot {
+    const cursors = getRemoteCursorStates(
+      options.awareness as Parameters<typeof getRemoteCursorStates>[0],
+      localClientId,
+    );
+    let laneStatus: UiOverlayLaneStatus = "resolved";
+    const entries = cursors.map((cursor) => {
+      const projection = options.projectCursor?.(cursor) ?? {
+        status: "requires-rehydration" as const,
+        reason: "presence cursor geometry projection is not wired",
+      };
+      laneStatus = coerceLaneStatus(laneStatus, projection.status);
+      return {
+        id: `presence:${cursor.userId}`,
+        status: projection.status,
+        ...(projection.rects ? { rects: projection.rects } : {}),
+        ...(projection.reason ? { reason: projection.reason } : {}),
+        data: {
+          kind: "remote-cursor",
+          userId: cursor.userId,
+          displayName: cursor.displayName,
+          color: cursor.color,
+          anchor: cursor.anchor,
+          head: cursor.head,
+          storyTarget: cursor.storyTarget,
+        },
+      };
+    });
+
+    return {
+      kind: "presence",
+      status: entries.length === 0 ? "resolved" : laneStatus,
+      entries,
+      revision: options.getRevision?.() ?? 0,
+      source: "awareness",
+    };
+  }
+
+  return {
+    getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot {
+      if (kind !== "presence") {
+        return unavailable(kind, "presence lane source only handles kind='presence'");
+      }
+      return readPresenceLane();
+    },
+    subscribeLane(
+      kind: UiOverlayLaneKind,
+      listener: UiListener<UiOverlayLaneSnapshot>,
+    ): UiUnsubscribe {
+      if (kind !== "presence") {
+        throw new Error(`presence lane source only handles kind='presence'; got "${kind}"`);
+      }
+      const onChange = (): void => {
+        listener(readPresenceLane());
+      };
+      options.awareness.on("change", onChange);
+      return () => {
+        options.awareness.off("change", onChange);
+      };
+    },
+  };
+}

package/src/ui/ui-controller-factory.ts

@@ -54,6 +54,9 @@ import type {
   ChromePosture,
   GeometryRect,
   OverlayAnchorQuery,
+  PageResidencySnapshot,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
   UiController,
   UiControllerFactory,
   UiListener,
@@ -111,6 +114,13 @@ export interface ShellUiControllerDeps {
    * dpr / container-resize. Returns unsubscribe.
    */
   readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /** PE2 page-residency policy read. */
+  readonly getPageResidency?: (pageIndex: number) => PageResidencySnapshot;
+  /** PE2 page-residency subscription channel. */
+  readonly subscribePageResidency?: (
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ) => UiUnsubscribe;
   /**
    * Overlay invalidation stream — fires when geometry invalidation overlaps
    * an attached overlay query (U7). Typically delegated to the render
@@ -119,6 +129,13 @@ export interface ShellUiControllerDeps {
   readonly subscribeOverlays?: (
     listener: UiListener<OverlayAnchorQuery>,
   ) => UiUnsubscribe;
+  /** PE2 overlay-lane snapshot resolver. */
+  readonly getOverlayLane?: (kind: UiOverlayLaneKind) => UiOverlayLaneSnapshot;
+  /** PE2 overlay-lane subscription channel. */
+  readonly subscribeOverlayLane?: (
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ) => UiUnsubscribe;
 }
 
 /**
@@ -145,7 +162,11 @@ export function makeShellUiControllerFactory(
       ...(deps.subscribeChrome ? { subscribeChrome: deps.subscribeChrome } : {}),
       ...(deps.getViewport ? { getViewport: deps.getViewport } : {}),
       ...(deps.subscribeViewport ? { subscribeViewport: deps.subscribeViewport } : {}),
+      ...(deps.getPageResidency ? { getPageResidency: deps.getPageResidency } : {}),
+      ...(deps.subscribePageResidency ? { subscribePageResidency: deps.subscribePageResidency } : {}),
       ...(deps.subscribeOverlays ? { subscribeOverlays: deps.subscribeOverlays } : {}),
+      ...(deps.getOverlayLane ? { getOverlayLane: deps.getOverlayLane } : {}),
+      ...(deps.subscribeOverlayLane ? { subscribeOverlayLane: deps.subscribeOverlayLane } : {}),
     };
     return controller;
   };