@beyondwork/docx-react-component 1.0.19 → 1.0.20

package/src/runtime/workflow-markup.ts

@@ -0,0 +1,349 @@
+import type {
+  CommentSidebarSnapshot,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  FieldSnapshot,
+  ProtectionSnapshot,
+  RuntimeRenderSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  TrackedChangesSnapshot,
+  WorkflowCandidateRange,
+  WorkflowCandidateRangeOptions,
+  WorkflowFieldMarkup,
+  WorkflowHighlightMarkup,
+  WorkflowMarkupItem,
+  WorkflowMarkupSnapshot,
+  WorkflowOpaqueFragmentMarkup,
+  WorkflowProtectedRangeMarkup,
+  WorkflowRevisionMarkup,
+  WorkflowCommentMarkup,
+} from "../api/public-types";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { searchSurfaceBlocks } from "../core/search/search-text.ts";
+import { describeOpaqueFragment } from "../preservation/store.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+
+const BLOCKED_IMPORT_FEATURE_KEYS = new Set(["alt-chunk", "alternate-content", "custom-xml"]);
+
+export function collectWorkflowMarkupSnapshot(input: {
+  renderSnapshot: RuntimeRenderSnapshot;
+  fieldSnapshot: FieldSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+}): WorkflowMarkupSnapshot {
+  const highlights: WorkflowHighlightMarkup[] = [];
+  const fields: WorkflowFieldMarkup[] = [];
+  const opaqueFragments: WorkflowOpaqueFragmentMarkup[] = [];
+  const surface = input.renderSnapshot.surface;
+
+  if (surface) {
+    collectSurfaceMarkup(
+      surface.blocks,
+      MAIN_STORY_TARGET,
+      input.preservation,
+      highlights,
+      opaqueFragments,
+    );
+    for (const story of surface.secondaryStories) {
+      collectSurfaceMarkup(
+        story.blocks,
+        story.target,
+        input.preservation,
+        highlights,
+        opaqueFragments,
+      );
+    }
+
+    fields.push(...collectFieldMarkup(surface, input.fieldSnapshot));
+  }
+  opaqueFragments.push(...collectOpaqueFragmentMarkup(input.preservation, opaqueFragments));
+
+  const comments = input.renderSnapshot.comments.threads.map((thread): WorkflowCommentMarkup => ({
+    markupId: `comment:${thread.commentId}`,
+    kind: "comment",
+    commentId: thread.commentId,
+    anchor: thread.anchor,
+    label: thread.anchorLabel,
+    excerpt: thread.excerpt,
+    status: thread.status,
+    warningCount: thread.warningCount,
+    entryCount: thread.entryCount,
+    createdAt: thread.createdAt,
+    createdBy: thread.createdBy,
+  }));
+
+  const revisions = input.renderSnapshot.trackedChanges.revisions.map(
+    (revision): WorkflowRevisionMarkup => ({
+      markupId: `revision:${revision.revisionId}`,
+      kind: "revision",
+      revisionId: revision.revisionId,
+      revisionKind: revision.kind,
+      anchor: revision.anchor,
+      label: revision.label,
+      excerpt: revision.excerpt,
+      status: revision.status,
+      actionability: revision.actionability,
+      authorId: revision.authorId,
+      createdAt: revision.createdAt,
+      preserveOnlyReason: revision.preserveOnlyReason,
+    }),
+  );
+
+  const protectedRanges = input.protectionSnapshot.ranges
+    .filter(
+      (range): range is typeof range & { start: number; end: number } =>
+        typeof range.start === "number" && typeof range.end === "number",
+    )
+    .map(
+      (range): WorkflowProtectedRangeMarkup => ({
+        markupId: `protected-range:${range.rangeId}`,
+        kind: "protected_range",
+        rangeId: range.rangeId,
+        anchor: createRangeAnchor(range.start, range.end),
+        storyTarget: MAIN_STORY_TARGET,
+        label: `Protected range ${range.rangeId}`,
+        excerpt: range.enforcementReason,
+        enforced: range.enforced,
+        enforcementReason: range.enforcementReason,
+        editorGroup: range.editorGroup,
+        editor: range.editor,
+      }),
+    );
+
+  const items: WorkflowMarkupItem[] = [
+    ...highlights,
+    ...comments,
+    ...revisions,
+    ...fields,
+    ...protectedRanges,
+    ...opaqueFragments,
+  ];
+
+  return {
+    totalCount: items.length,
+    items,
+    highlights,
+    comments,
+    revisions,
+    fields,
+    protectedRanges,
+    opaqueFragments,
+  };
+}
+
+export function deriveWorkflowCandidateRangesFromMarkup(
+  snapshot: WorkflowMarkupSnapshot,
+  options: WorkflowCandidateRangeOptions = {},
+): WorkflowCandidateRange[] {
+  const allowedKinds = options.kinds ? new Set(options.kinds) : null;
+  const includeDetached = options.includeDetached === true;
+
+  return snapshot.items
+    .filter((item) => (allowedKinds ? allowedKinds.has(item.kind) : true))
+    .filter((item) => includeDetached || item.anchor.kind !== "detached")
+    .map(
+      (item): WorkflowCandidateRange => ({
+        candidateId: item.markupId,
+        storyTarget: item.storyTarget,
+        anchor: item.anchor,
+        label: item.label,
+        source: options.source ?? "host",
+      }),
+    );
+}
+
+function collectSurfaceMarkup(
+  blocks: readonly SurfaceBlockSnapshot[],
+  storyTarget: EditorStoryTarget,
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  highlights: WorkflowHighlightMarkup[],
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[],
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        collectSegmentMarkup(segment, storyTarget, preservation, highlights, opaqueFragments);
+      }
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectSurfaceMarkup(cell.content, storyTarget, preservation, highlights, opaqueFragments);
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      collectSurfaceMarkup(block.children, storyTarget, preservation, highlights, opaqueFragments);
+      continue;
+    }
+
+    const fragment = preservation.opaqueFragments[block.fragmentId];
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    const blockedReasonCode =
+      fragment && BLOCKED_IMPORT_FEATURE_KEYS.has(descriptor?.featureKey ?? "")
+        ? "workflow_blocked_import"
+        : "workflow_preserve_only";
+    opaqueFragments.push({
+      markupId: `opaque:${block.fragmentId}`,
+      kind: "opaque_fragment",
+      fragmentId: block.fragmentId,
+      warningId: block.warningId,
+      anchor: createRangeAnchor(block.from, block.to),
+      storyTarget,
+      label: block.label,
+      excerpt: block.detail,
+      detail: block.detail,
+      blockedReasonCode,
+    });
+  }
+}
+
+function collectSegmentMarkup(
+  segment: SurfaceInlineSegment,
+  storyTarget: EditorStoryTarget,
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  highlights: WorkflowHighlightMarkup[],
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[],
+): void {
+  if (segment.kind === "text" && segment.markAttrs?.backgroundColor) {
+    highlights.push({
+      markupId: `highlight:${storyTargetKey(storyTarget)}:${segment.from}:${segment.to}:${segment.markAttrs.backgroundColor}`,
+      kind: "highlight",
+      anchor: createRangeAnchor(segment.from, segment.to),
+      storyTarget,
+      label: `Highlight ${segment.markAttrs.backgroundColor}`,
+      excerpt: segment.text,
+      color: segment.markAttrs.backgroundColor,
+      text: segment.text,
+    });
+    return;
+  }
+
+  if (segment.kind === "opaque_inline") {
+    const fragment = preservation.opaqueFragments[segment.fragmentId];
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    const blockedReasonCode =
+      fragment && BLOCKED_IMPORT_FEATURE_KEYS.has(descriptor?.featureKey ?? "")
+        ? "workflow_blocked_import"
+        : "workflow_preserve_only";
+    opaqueFragments.push({
+      markupId: `opaque:${segment.fragmentId}`,
+      kind: "opaque_fragment",
+      fragmentId: segment.fragmentId,
+      warningId: segment.warningId,
+      anchor: createRangeAnchor(segment.from, segment.to),
+      storyTarget,
+      label: segment.label,
+      excerpt: segment.detail,
+      detail: segment.detail,
+      blockedReasonCode,
+    });
+  }
+}
+
+function collectFieldMarkup(
+  surface: RuntimeRenderSnapshot["surface"],
+  fieldSnapshot: FieldSnapshot,
+): WorkflowFieldMarkup[] {
+  if (!surface) {
+    return [];
+  }
+
+  const stories = [
+    { blocks: surface.blocks, storyTarget: MAIN_STORY_TARGET },
+    ...surface.secondaryStories.map((story) => ({
+      blocks: story.blocks,
+      storyTarget: story.target,
+    })),
+  ];
+
+  return fieldSnapshot.fields.flatMap((field) => {
+    const displayText = field.displayText.trim();
+    if (!displayText) {
+      return [];
+    }
+
+    for (const story of stories) {
+      const matches = searchSurfaceBlocks(story.blocks, displayText, { limit: 2 });
+      if (matches.length === 1) {
+        const match = matches[0]!;
+        return [
+          {
+            markupId: `field:${field.index}`,
+            kind: "field",
+            anchor: createRangeAnchor(match.from, match.to),
+            storyTarget: story.storyTarget,
+            label: displayText,
+            excerpt: field.instruction,
+            fieldIndex: field.index,
+            fieldFamily: field.fieldFamily,
+            fieldTarget: field.fieldTarget,
+            refreshStatus: field.refreshStatus,
+            displayText: field.displayText,
+          } satisfies WorkflowFieldMarkup,
+        ];
+      }
+    }
+
+    return [];
+  });
+}
+
+function collectOpaqueFragmentMarkup(
+  preservation: CanonicalDocumentEnvelope["preservation"],
+  existing: WorkflowOpaqueFragmentMarkup[],
+): WorkflowOpaqueFragmentMarkup[] {
+  const seen = new Set(existing.map((item) => item.fragmentId));
+
+  return Object.values(preservation.opaqueFragments)
+    .filter((fragment) => !seen.has(fragment.fragmentId))
+    .map((fragment) => {
+      const descriptor = describeOpaqueFragment(fragment);
+      const blockedReasonCode = BLOCKED_IMPORT_FEATURE_KEYS.has(descriptor.featureKey)
+        ? "workflow_blocked_import"
+        : "workflow_preserve_only";
+
+      return {
+        markupId: `opaque:${fragment.fragmentId}`,
+        kind: "opaque_fragment",
+        fragmentId: fragment.fragmentId,
+        warningId: fragment.warningId,
+        anchor: createRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
+        storyTarget: MAIN_STORY_TARGET,
+        label: descriptor.label,
+        excerpt: descriptor.detail,
+        detail: descriptor.detail,
+        blockedReasonCode,
+      } satisfies WorkflowOpaqueFragmentMarkup;
+    });
+}
+
+function createRangeAnchor(from: number, to: number): EditorAnchorProjection {
+  return {
+    kind: "range",
+    from,
+    to,
+    assoc: {
+      start: -1,
+      end: 1,
+    },
+  };
+}
+
+function storyTargetKey(storyTarget: EditorStoryTarget): string {
+  switch (storyTarget.kind) {
+    case "main":
+      return "main";
+    case "header":
+    case "footer":
+      return `${storyTarget.kind}:${storyTarget.relationshipId}:${storyTarget.variant}:${storyTarget.sectionIndex ?? "none"}`;
+    case "footnote":
+    case "endnote":
+      return `${storyTarget.kind}:${storyTarget.noteId}`;
+  }
+}