@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/runtime/document-locations.ts

@@ -0,0 +1,521 @@
+import type {
+  CommentSidebarSnapshot,
+  DocumentChunkSnapshot,
+  DocumentLocationSnapshot,
+  DocumentNavigationSnapshot,
+  DocumentSectionSnapshot,
+  DocumentTextToken,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+  RestorePointSnapshot,
+  ReviewWorkSnapshot,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+  StoryTextStreamSnapshot,
+  TrackedChangesSnapshot,
+  WorkflowMarkupSnapshot,
+} from "../api/public-types";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import {
+  createDocumentSectionSnapshots,
+  findBookmarkNameForOffset,
+  resolveHeadingPath,
+} from "./document-outline.ts";
+import { storyTargetKey } from "./story-targeting.ts";
+
+function getAnchorOffset(anchor: EditorAnchorProjection): number | undefined {
+  switch (anchor.kind) {
+    case "range":
+      return anchor.from;
+    case "node":
+      return anchor.at;
+    case "detached":
+      return anchor.lastKnownRange.from;
+  }
+}
+
+function createLocationId(anchor: EditorAnchorProjection, storyTarget?: EditorStoryTarget): string {
+  switch (anchor.kind) {
+    case "range":
+      return `location:${storyTargetKey(storyTarget ?? MAIN_STORY_TARGET)}:range:${anchor.from}:${anchor.to}`;
+    case "node":
+      return `location:${storyTargetKey(storyTarget ?? MAIN_STORY_TARGET)}:node:${anchor.at}`;
+    case "detached":
+      return `location:${storyTargetKey(storyTarget ?? MAIN_STORY_TARGET)}:detached:${anchor.lastKnownRange.from}:${anchor.lastKnownRange.to}:${anchor.reason}`;
+  }
+}
+
+function createPublicRangeAnchor(from: number, to: number): EditorAnchorProjection {
+  return {
+    kind: "range",
+    from,
+    to,
+    assoc: { start: -1, end: 1 },
+  };
+}
+
+function resolveOffsetMetadata(
+  navigation: DocumentNavigationSnapshot,
+  offset: number,
+): { pageIndex?: number; sectionIndex?: number } {
+  const page = navigation.pages.find(
+    (entry) => offset >= entry.startOffset && offset < entry.endOffset,
+  );
+  return {
+    ...(typeof page?.pageIndex === "number" ? { pageIndex: page.pageIndex } : {}),
+    ...(typeof page?.sectionIndex === "number"
+      ? { sectionIndex: page.sectionIndex }
+      : {}),
+  };
+}
+
+export function createDocumentLocationSnapshot(input: {
+  document: CanonicalDocumentEnvelope;
+  navigation: DocumentNavigationSnapshot;
+  sections?: DocumentSectionSnapshot[];
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  source: DocumentLocationSnapshot["source"];
+}): DocumentLocationSnapshot {
+  const storyTarget = input.storyTarget ?? MAIN_STORY_TARGET;
+  const offset = getAnchorOffset(input.anchor);
+
+  if (storyTarget.kind !== "main") {
+    return {
+      locationId: createLocationId(input.anchor, storyTarget),
+      anchor: input.anchor,
+      storyTarget,
+      ...("sectionIndex" in storyTarget && typeof storyTarget.sectionIndex === "number"
+        ? { sectionIndex: storyTarget.sectionIndex }
+        : {}),
+      source: input.source,
+    };
+  }
+
+  const page = input.navigation.pages.find(
+    (entry) => offset !== undefined && offset >= entry.startOffset && offset < entry.endOffset,
+  );
+  const section =
+    input.sections?.find((entry) => entry.sectionIndex === page?.sectionIndex) ??
+    createDocumentSectionSnapshots(input.document, input.navigation).find(
+      (entry) => entry.sectionIndex === page?.sectionIndex,
+    );
+  const headingContext = resolveHeadingPath(input.navigation.headings, offset);
+  const bookmarkName = findBookmarkNameForOffset(input.document, offset);
+
+  return {
+    locationId: createLocationId(input.anchor, storyTarget),
+    anchor: input.anchor,
+    storyTarget,
+    ...(section ? { sectionIndex: section.sectionIndex } : {}),
+    ...(typeof page?.pageIndex === "number" ? { pageIndex: page.pageIndex } : {}),
+    ...(headingContext.headingId ? { headingId: headingContext.headingId } : {}),
+    ...(headingContext.headingPath.length > 0
+      ? { headingPath: headingContext.headingPath }
+      : {}),
+    ...(bookmarkName ? { bookmarkName } : {}),
+    source: input.source,
+  };
+}
+
+export function createSelectionFromAnchor(
+  anchor: EditorAnchorProjection,
+  storyTarget?: EditorStoryTarget,
+): SelectionSnapshot {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        anchor: anchor.from,
+        head: anchor.to,
+        isCollapsed: anchor.from === anchor.to,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+    case "node":
+      return {
+        anchor: anchor.at,
+        head: anchor.at,
+        isCollapsed: true,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+    case "detached":
+      return {
+        anchor: anchor.lastKnownRange.from,
+        head: anchor.lastKnownRange.to,
+        isCollapsed: anchor.lastKnownRange.from === anchor.lastKnownRange.to,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+  }
+}
+
+function pushParagraphTokens(
+  tokens: DocumentTextToken[],
+  block: Extract<EditorSurfaceSnapshot["blocks"][number], { kind: "paragraph" }>,
+  storyTarget: EditorStoryTarget,
+  navigation: DocumentNavigationSnapshot,
+): void {
+  const location = resolveOffsetMetadata(navigation, block.from);
+
+  tokens.push({
+    tokenId: `${block.blockId}:boundary`,
+    storyTarget,
+    blockId: block.blockId,
+    blockKind: block.kind,
+    kind: "paragraph_boundary",
+    from: block.from,
+    to: block.from,
+    ...(typeof location.pageIndex === "number" ? { pageIndex: location.pageIndex } : {}),
+    ...(typeof location.sectionIndex === "number"
+      ? { sectionIndex: location.sectionIndex }
+      : {}),
+  });
+
+  for (const segment of block.segments) {
+    tokens.push({
+      tokenId: `${block.blockId}:${segment.segmentId}`,
+      storyTarget,
+      blockId: block.blockId,
+      blockKind: block.kind,
+      segmentId: segment.segmentId,
+      kind: segment.kind,
+      from: segment.from,
+      to: segment.to,
+      ...("text" in segment && segment.text ? { text: segment.text } : {}),
+      ...("marks" in segment && segment.marks ? { marks: segment.marks } : {}),
+      ...(typeof location.pageIndex === "number" ? { pageIndex: location.pageIndex } : {}),
+      ...(typeof location.sectionIndex === "number"
+        ? { sectionIndex: location.sectionIndex }
+        : {}),
+    });
+  }
+}
+
+function flattenParagraphText(
+  block: Extract<EditorSurfaceSnapshot["blocks"][number], { kind: "paragraph" }>,
+): string {
+  return block.segments
+    .map((segment) => {
+      switch (segment.kind) {
+        case "text":
+          return segment.text;
+        case "tab":
+          return "\t";
+        case "hard_break":
+          return "\n";
+        case "image":
+          return segment.altText ?? "[image]";
+        case "note_ref":
+        case "field_ref":
+          return segment.label;
+        case "opaque_inline":
+          return segment.label;
+      }
+    })
+    .join("");
+}
+
+function getChunkHeadingPath(
+  navigation: DocumentNavigationSnapshot,
+  offset: number,
+): string[] {
+  return resolveHeadingPath(navigation.headings, offset).headingPath;
+}
+
+function getChunkCautionFlags(
+  block: EditorSurfaceSnapshot["blocks"][number],
+): DocumentChunkSnapshot["cautionFlags"] {
+  switch (block.kind) {
+    case "table":
+      return ["contains_table"];
+    case "opaque_block":
+      return ["contains_preserve_only"];
+    case "paragraph":
+      return block.segments.some((segment) => segment.kind === "opaque_inline")
+        ? ["contains_preserve_only"]
+        : [];
+    case "sdt_block":
+      return [];
+  }
+}
+
+export function createDocumentTextStreamSnapshots(input: {
+  surface: EditorSurfaceSnapshot;
+  navigation: DocumentNavigationSnapshot;
+}): StoryTextStreamSnapshot[] {
+  const streams: StoryTextStreamSnapshot[] = [];
+  const stories = [
+    {
+      target: MAIN_STORY_TARGET,
+      label: "Main document",
+      storySize: input.surface.storySize,
+      blocks: input.surface.blocks,
+    },
+    ...input.surface.secondaryStories,
+  ];
+
+  for (const story of stories) {
+    const tokens: DocumentTextToken[] = [];
+    for (const block of story.blocks) {
+      if (block.kind === "paragraph") {
+        pushParagraphTokens(tokens, block, story.target, input.navigation);
+        continue;
+      }
+      if (block.kind === "table") {
+        tokens.push({
+          tokenId: `${block.blockId}:table`,
+          storyTarget: story.target,
+          blockId: block.blockId,
+          blockKind: block.kind,
+          kind: "table_boundary",
+          from: block.from,
+          to: block.to,
+        });
+        continue;
+      }
+      if (block.kind === "sdt_block") {
+        for (const child of block.children) {
+          if (child.kind === "paragraph") {
+            pushParagraphTokens(tokens, child, story.target, input.navigation);
+          }
+        }
+      }
+    }
+    streams.push({
+      target: story.target,
+      label: story.label,
+      storySize: story.storySize,
+      tokens,
+    });
+  }
+
+  return streams;
+}
+
+export function createDocumentChunks(input: {
+  document: CanonicalDocumentEnvelope;
+  renderSnapshot: RuntimeRenderSnapshot;
+  navigation: DocumentNavigationSnapshot;
+}): DocumentChunkSnapshot[] {
+  const surface = input.renderSnapshot.surface;
+  if (!surface) {
+    return [];
+  }
+
+  const chunks: DocumentChunkSnapshot[] = [];
+  for (const block of surface.blocks) {
+    const publicAnchor = createPublicRangeAnchor(block.from, block.to);
+    const location = createDocumentLocationSnapshot({
+      document: input.document,
+      navigation: input.navigation,
+      anchor: publicAnchor,
+      storyTarget: MAIN_STORY_TARGET,
+      source: { kind: "navigation" },
+    });
+    const headingPath = getChunkHeadingPath(input.navigation, block.from);
+
+    if (block.kind === "paragraph") {
+      chunks.push({
+        chunkId: `chunk:${block.blockId}`,
+        kind: "retrieval",
+        label: headingPath.at(-1) ?? "Paragraph",
+        text: flattenParagraphText(block),
+        storyTarget: MAIN_STORY_TARGET,
+        anchor: publicAnchor,
+        ...(typeof location.sectionIndex === "number"
+          ? { sectionIndex: location.sectionIndex }
+          : {}),
+        ...(typeof location.pageIndex === "number"
+          ? { pageRange: { start: location.pageIndex, end: location.pageIndex } }
+          : {}),
+        headingPath,
+        blockRefs: [{ blockId: block.blockId, kind: block.kind }],
+        source: { type: "surface" },
+        cautionFlags: getChunkCautionFlags(block),
+      });
+      continue;
+    }
+
+    if (block.kind === "table") {
+      chunks.push({
+        chunkId: `chunk:${block.blockId}`,
+        kind: "retrieval",
+        label: headingPath.at(-1) ?? "Table",
+        text: "[table]",
+        storyTarget: MAIN_STORY_TARGET,
+        anchor: publicAnchor,
+        ...(typeof location.sectionIndex === "number"
+          ? { sectionIndex: location.sectionIndex }
+          : {}),
+        ...(typeof location.pageIndex === "number"
+          ? { pageRange: { start: location.pageIndex, end: location.pageIndex } }
+          : {}),
+        headingPath,
+        blockRefs: [{ blockId: block.blockId, kind: block.kind }],
+        source: { type: "surface" },
+        cautionFlags: getChunkCautionFlags(block),
+      });
+      continue;
+    }
+
+    if (block.kind === "opaque_block") {
+      chunks.push({
+        chunkId: `chunk:${block.blockId}`,
+        kind: "retrieval",
+        label: block.label,
+        text: block.detail,
+        storyTarget: MAIN_STORY_TARGET,
+        anchor: publicAnchor,
+        ...(typeof location.sectionIndex === "number"
+          ? { sectionIndex: location.sectionIndex }
+          : {}),
+        ...(typeof location.pageIndex === "number"
+          ? { pageRange: { start: location.pageIndex, end: location.pageIndex } }
+          : {}),
+        headingPath,
+        blockRefs: [{ blockId: block.blockId, kind: block.kind }],
+        source: { type: "surface" },
+        cautionFlags: getChunkCautionFlags(block),
+      });
+    }
+  }
+
+  return chunks;
+}
+
+export function createWorkflowChunks(input: {
+  document: CanonicalDocumentEnvelope;
+  navigation: DocumentNavigationSnapshot;
+  workflowMarkup: WorkflowMarkupSnapshot;
+}): DocumentChunkSnapshot[] {
+  return input.workflowMarkup.items.map((item) => {
+    const location = createDocumentLocationSnapshot({
+      document: input.document,
+      navigation: input.navigation,
+      anchor: item.anchor,
+      storyTarget: item.storyTarget,
+      source: { kind: "workflow", markupId: item.markupId },
+    });
+    return {
+      chunkId: `workflow:${item.markupId}`,
+      kind: "workflow",
+      label: item.label,
+        text: item.excerpt ?? item.label,
+      ...(item.storyTarget ? { storyTarget: item.storyTarget } : {}),
+      anchor: item.anchor,
+      ...(typeof location.sectionIndex === "number"
+        ? { sectionIndex: location.sectionIndex }
+        : {}),
+      ...(typeof location.pageIndex === "number"
+        ? { pageRange: { start: location.pageIndex, end: location.pageIndex } }
+        : {}),
+      headingPath: location.headingPath ?? [],
+      blockRefs: [],
+      source: { type: "workflow", markupId: item.markupId, candidateId: item.markupId },
+      cautionFlags:
+        item.anchor.kind === "detached"
+          ? ["contains_detached_anchor"]
+          : item.kind === "protected_range"
+            ? ["contains_protected_range"]
+            : item.kind === "opaque_fragment"
+              ? ["contains_preserve_only"]
+              : [],
+    };
+  });
+}
+
+export function createReviewWorkSnapshot(input: {
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+  workflowMarkup: WorkflowMarkupSnapshot;
+  document: CanonicalDocumentEnvelope;
+  navigation: DocumentNavigationSnapshot;
+}): ReviewWorkSnapshot {
+  const items = input.workflowMarkup.items
+    .filter((item) =>
+      item.kind === "comment" ||
+      item.kind === "revision" ||
+      item.kind === "protected_range" ||
+      item.kind === "opaque_fragment",
+    )
+    .map((item) => {
+      const location = createDocumentLocationSnapshot({
+        document: input.document,
+        navigation: input.navigation,
+        anchor: item.anchor,
+        storyTarget: item.storyTarget,
+        source: { kind: "workflow", markupId: item.markupId },
+      });
+      return {
+        workId: item.markupId,
+        kind: item.kind,
+        label: item.label,
+        excerpt: item.excerpt ?? item.label,
+        anchor: item.anchor,
+        ...(item.storyTarget ? { storyTarget: item.storyTarget } : {}),
+        ...(typeof location.sectionIndex === "number"
+          ? { sectionIndex: location.sectionIndex }
+          : {}),
+        ...(typeof location.pageIndex === "number"
+          ? { pageIndex: location.pageIndex }
+          : {}),
+      };
+    });
+
+  return {
+    openCommentCount: input.comments.openCommentIds.length,
+    actionableRevisionCount: input.trackedChanges.actionableChangeIds.length,
+    items,
+  };
+}
+
+export function createRestorePoint(input: {
+  location: DocumentLocationSnapshot;
+  revisionToken: string;
+  createdAt: string;
+  checkpointType: RestorePointSnapshot["checkpointType"];
+}): RestorePointSnapshot {
+  return {
+    restorePointId: `restore:${input.revisionToken}:${input.location.locationId}`,
+    location: input.location,
+    revisionToken: input.revisionToken,
+    createdAt: input.createdAt,
+    checkpointType: input.checkpointType,
+  };
+}
+
+export function createCurrentLocation(input: {
+  document: CanonicalDocumentEnvelope;
+  renderSnapshot: RuntimeRenderSnapshot;
+  navigation: DocumentNavigationSnapshot;
+  sections?: DocumentSectionSnapshot[];
+}): DocumentLocationSnapshot | null {
+  const selection = input.renderSnapshot.selection;
+  return createDocumentLocationSnapshot({
+    document: input.document,
+    navigation: input.navigation,
+    sections: input.sections,
+    anchor: selection.activeRange,
+    storyTarget: selection.storyTarget ?? input.renderSnapshot.activeStory,
+    source: { kind: "selection" },
+  });
+}
+
+export function createLocationFromSelection(input: {
+  document: CanonicalDocumentEnvelope;
+  navigation: DocumentNavigationSnapshot;
+  sections?: DocumentSectionSnapshot[];
+  selection: SelectionSnapshot;
+}): DocumentLocationSnapshot | null {
+  return createDocumentLocationSnapshot({
+    document: input.document,
+    navigation: input.navigation,
+    sections: input.sections,
+    anchor: input.selection.activeRange,
+    storyTarget: input.selection.storyTarget ?? MAIN_STORY_TARGET,
+    source: { kind: "selection" },
+  });
+}