@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/core/commands/add-scope.ts

@@ -0,0 +1,257 @@
+import type {
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+  ScopeMarkerStartNode,
+  ScopeMarkerEndNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../state/editor-state.ts";
+
+export interface InsertScopeMarkersResult {
+  document: CanonicalDocumentEnvelope;
+  scopeId: string;
+}
+
+/**
+ * Pure helper — returns a new CanonicalDocumentEnvelope with a pair of
+ * scope-marker inline nodes inserted at the given position range.
+ *
+ * Supports the common case: `from` and `to` land in the same top-level
+ * paragraph. Cross-paragraph ranges are currently a no-op and return the
+ * document unchanged — multi-block scopes ship in a follow-up slice.
+ */
+export function insertScopeMarkers(
+  document: CanonicalDocumentEnvelope,
+  params: {
+    scopeId: string;
+    from: number;
+    to: number;
+  },
+): InsertScopeMarkersResult {
+  const { scopeId, from, to } = params;
+  const root = document.content as DocumentRootNode;
+  if (!root || root.type !== "doc") return { document, scopeId };
+
+  const normalizedFrom = Math.min(from, to);
+  const normalizedTo = Math.max(from, to);
+
+  let cursor = 0;
+  let inserted = false;
+  const children = root.children.map((block, blockIndex) => {
+    if (inserted) return block;
+    if (block.type !== "paragraph") {
+      cursor += 1;
+      if (blockIndex < root.children.length - 1) cursor += 1;
+      return block;
+    }
+
+    const paragraphFrom = cursor;
+    const paragraphLength = block.children.reduce(
+      (total, child) => total + inlineLength(child as InlineNode),
+      0,
+    );
+    const paragraphTo = paragraphFrom + paragraphLength;
+    cursor = paragraphTo + 1;
+
+    if (
+      normalizedFrom < paragraphFrom ||
+      normalizedTo > paragraphTo ||
+      normalizedFrom > paragraphTo
+    ) {
+      return block;
+    }
+
+    inserted = true;
+    const startOffset = normalizedFrom - paragraphFrom;
+    const endOffset = normalizedTo - paragraphFrom;
+    const newChildren = injectMarkersIntoInlineList(
+      block.children as InlineNode[],
+      scopeId,
+      startOffset,
+      endOffset,
+    );
+    return { ...block, children: newChildren } as ParagraphNode;
+  });
+
+  if (!inserted) return { document, scopeId };
+
+  return {
+    document: {
+      ...document,
+      content: { ...root, children },
+    },
+    scopeId,
+  };
+}
+
+/**
+ * Returns a new document with every scope_marker_* node whose scopeId matches
+ * removed. The containing paragraphs' other children are preserved in order.
+ */
+export function removeScopeMarkers(
+  document: CanonicalDocumentEnvelope,
+  scopeId: string,
+): CanonicalDocumentEnvelope {
+  const root = document.content as DocumentRootNode;
+  if (!root || root.type !== "doc") return document;
+
+  let mutated = false;
+  const children = root.children.map((block) => {
+    if (block.type !== "paragraph") return block;
+    const kept = block.children.filter((child) => {
+      if (
+        (child.type === "scope_marker_start" ||
+          child.type === "scope_marker_end") &&
+        child.scopeId === scopeId
+      ) {
+        mutated = true;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length === block.children.length) return block;
+    return { ...block, children: kept } as ParagraphNode;
+  });
+
+  if (!mutated) return document;
+
+  return {
+    ...document,
+    content: { ...root, children },
+  };
+}
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+function injectMarkersIntoInlineList(
+  inlines: InlineNode[],
+  scopeId: string,
+  startOffset: number,
+  endOffset: number,
+): InlineNode[] {
+  const start: ScopeMarkerStartNode = {
+    type: "scope_marker_start",
+    scopeId,
+  };
+  const end: ScopeMarkerEndNode = {
+    type: "scope_marker_end",
+    scopeId,
+  };
+
+  const output: InlineNode[] = [];
+  let cursor = 0;
+  let startEmitted = false;
+  let endEmitted = false;
+
+  for (const node of inlines) {
+    const length = inlineLength(node);
+    const nodeStart = cursor;
+    const nodeEnd = cursor + length;
+
+    const startInside = !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
+    const endInside = !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
+
+    if (!startInside && !endInside) {
+      output.push(node);
+      cursor = nodeEnd;
+      continue;
+    }
+
+    // Currently only text nodes support splitting for an internal cut.
+    if (node.type !== "text") {
+      // For non-text nodes, markers land at the node boundary closest to the
+      // target offset — avoids mid-atom splits which would corrupt the node.
+      if (startInside && !startEmitted && startOffset <= nodeStart) {
+        output.push(start);
+        startEmitted = true;
+      }
+      if (endInside && !endEmitted && endOffset <= nodeStart) {
+        output.push(end);
+        endEmitted = true;
+      }
+      output.push(node);
+      if (startInside && !startEmitted && startOffset >= nodeEnd) {
+        output.push(start);
+        startEmitted = true;
+      }
+      if (endInside && !endEmitted && endOffset >= nodeEnd) {
+        output.push(end);
+        endEmitted = true;
+      }
+      cursor = nodeEnd;
+      continue;
+    }
+
+    const text = node.text;
+    const chars = Array.from(text);
+    const marks = node.marks;
+    const pieces: {
+      cut: number;
+      emit: "start" | "end";
+    }[] = [];
+
+    if (startInside) pieces.push({ cut: startOffset - nodeStart, emit: "start" });
+    if (endInside) pieces.push({ cut: endOffset - nodeStart, emit: "end" });
+    pieces.sort((a, b) => a.cut - b.cut || (a.emit === "start" ? -1 : 1));
+
+    let priorCut = 0;
+    for (const piece of pieces) {
+      const segment = chars.slice(priorCut, piece.cut).join("");
+      if (segment.length > 0) {
+        output.push(
+          marks !== undefined
+            ? { type: "text", text: segment, marks }
+            : { type: "text", text: segment },
+        );
+      }
+      if (piece.emit === "start") {
+        output.push(start);
+        startEmitted = true;
+      } else {
+        output.push(end);
+        endEmitted = true;
+      }
+      priorCut = piece.cut;
+    }
+    const tail = chars.slice(priorCut).join("");
+    if (tail.length > 0) {
+      output.push(
+        marks !== undefined
+          ? { type: "text", text: tail, marks }
+          : { type: "text", text: tail },
+      );
+    }
+
+    cursor = nodeEnd;
+  }
+
+  // Append markers that were at the very end of the paragraph.
+  if (!startEmitted) {
+    output.push(start);
+    startEmitted = true;
+  }
+  if (!endEmitted) {
+    output.push(end);
+    endEmitted = true;
+  }
+
+  return output;
+}

package/src/core/commands/formatting-commands.ts

@@ -1048,6 +1048,8 @@ function inlineNodeLength(node: InlineNode): number {
       );
     case "bookmark_start":
     case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
       return 0;
   }
 }

package/src/core/commands/index.ts

@@ -50,6 +50,7 @@ import type {
   SectionBreakType,
   SectionLayoutPatch,
   SectionPageNumberingPatch,
+  TextFormattingDirective,
   WorkflowMetadataDefinition,
   WorkflowMetadataEntry,
   WorkflowOverlay,
@@ -136,6 +137,13 @@ export type EditorCommand =
   | {
       type: "text.insert";
       text: string;
+      /**
+       * I7 — optional directive controlling which character-level marks the inserted
+       * text carries. Defaults to `{ mode: "paragraph-default" }` (today's behavior:
+       * no inherited run marks). See `src/api/public-types.ts` `TextFormattingDirective`
+       * for semantics.
+       */
+      formatting?: TextFormattingDirective;
       origin?: CommandOrigin;
     }
   | {
@@ -556,7 +564,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertText(document, selection, command.text, context),
+        insertText(document, selection, command.text, context, command.formatting),
       );
     }
     case "text.delete-backward": {

package/src/core/commands/text-commands.ts

@@ -1,4 +1,4 @@
-import type { InsertTableOptions } from "../../api/public-types";
+import type { InsertTableOptions, TextFormattingDirective } from "../../api/public-types";
 import type {
   DocumentRootNode,
   ParagraphNode,
@@ -126,6 +126,7 @@ export function insertText(
   selection: SelectionSnapshot,
   text: string,
   context: TextCommandContext,
+  formatting?: TextFormattingDirective,
 ): TextTransactionResult {
   return applyTextTransaction(
     document,
@@ -138,6 +139,7 @@ export function insertText(
           text,
         },
       ],
+      formatting,
     },
     context,
   );

package/src/core/schema/text-schema.ts

@@ -26,6 +26,7 @@ export type StoryUnit =
   | ImageUnit
   | OpaqueInlineUnit
   | OpaqueBlockUnit
+  | ScopeMarkerUnit
   | ParagraphBreakUnit;
 
 export interface TextCharacterUnit {
@@ -69,6 +70,18 @@ export interface ParagraphBreakUnit {
   nextParagraph: ParagraphProperties;
 }
 
+/**
+ * Zero-width inline unit that preserves S1 scope-marker nodes through text
+ * transactions. Without this unit, scope markers would be silently dropped
+ * during `parseTextStory` / `serializeTextStory`, and any `text.insert` /
+ * `text.delete-*` dispatch would vaporize the structural scope anchors.
+ */
+export interface ScopeMarkerUnit {
+  kind: "scope_marker";
+  boundary: "start" | "end";
+  scopeId: string;
+}
+
 export function parseTextStory(content: unknown): TextStory {
   const root = normalizeDocumentRoot(content);
   const firstParagraphNode = root.children.find(isParagraphNode);
@@ -111,10 +124,60 @@ export function parseTextStory(content: unknown): TextStory {
   return {
     firstParagraph,
     units,
-    size: units.length,
+    size: countLogicalPositions(units),
   };
 }
 
+/**
+ * Story positions are logical — scope-marker units are preserved in the
+ * `units` array for round-trip fidelity but they do NOT consume a position.
+ * This matches the surface-projection treatment (markers = 0 width, same as
+ * bookmark_start / bookmark_end) so a position 3 set via `selection.set`
+ * resolves to the same character in both views.
+ */
+export function countLogicalPositions(units: StoryUnit[]): number {
+  let size = 0;
+  for (const unit of units) {
+    if (unit.kind !== "scope_marker") size += 1;
+  }
+  return size;
+}
+
+/**
+ * Translate a logical (scope-marker-skipping) position into a unit-array
+ * index. Walks units and increments the unit cursor once per non-marker unit;
+ * scope markers are passed over transparently. Returns `units.length` when
+ * the logical position is at or beyond end-of-story.
+ *
+ * When `startBias === "after"` (default), the returned unit index is the
+ * first position AFTER any scope markers that sit exactly at the logical
+ * boundary — useful when slicing units as "...before this cursor". When
+ * `startBias === "before"`, markers at the boundary are included in the
+ * "after" slice.
+ */
+export function logicalPositionToUnitIndex(
+  units: StoryUnit[],
+  logicalPos: number,
+  startBias: "before" | "after" = "after",
+): number {
+  let logicalCursor = 0;
+  let unitIndex = 0;
+  while (unitIndex < units.length) {
+    if (logicalCursor === logicalPos && startBias === "before") {
+      return unitIndex;
+    }
+    const unit = units[unitIndex]!;
+    if (unit.kind !== "scope_marker") {
+      if (logicalCursor === logicalPos && startBias === "after") {
+        return unitIndex;
+      }
+      logicalCursor += 1;
+    }
+    unitIndex += 1;
+  }
+  return unitIndex;
+}
+
 export function serializeTextStory(story: TextStory): DocumentRootNode {
   const blocks: Array<ParagraphNode | OpaqueBlockNode> = [];
   let currentParagraph: ParagraphNode | undefined = createParagraph(story.firstParagraph);
@@ -272,6 +335,15 @@ export function serializeTextStory(story: TextStory): DocumentRootNode {
           warningId: unit.warningId,
         });
         break;
+      case "scope_marker":
+        pushInlineNode({
+          type:
+            unit.boundary === "start"
+              ? "scope_marker_start"
+              : "scope_marker_end",
+          scopeId: unit.scopeId,
+        });
+        break;
     }
   }
 
@@ -305,6 +377,8 @@ export function createPlainText(story: TextStory): string {
           return "\uFFF9";
         case "opaque_block":
           return "\uFFFA";
+        case "scope_marker":
+          return "";
       }
     })
     .join("");
@@ -355,6 +429,12 @@ export function cloneStoryUnit(unit: StoryUnit): StoryUnit {
         kind: "paragraph_break",
         nextParagraph: cloneParagraphProperties(unit.nextParagraph),
       };
+    case "scope_marker":
+      return {
+        kind: "scope_marker",
+        boundary: unit.boundary,
+        scopeId: unit.scopeId,
+      };
   }
 }
 
@@ -442,6 +522,20 @@ function flattenInlineNodes(
           warningId: node.warningId,
         });
         break;
+      case "scope_marker_start":
+        units.push({
+          kind: "scope_marker",
+          boundary: "start",
+          scopeId: node.scopeId,
+        });
+        break;
+      case "scope_marker_end":
+        units.push({
+          kind: "scope_marker",
+          boundary: "end",
+          scopeId: node.scopeId,
+        });
+        break;
     }
   }
 

package/src/core/selection/anchor-conversion.ts

@@ -0,0 +1,112 @@
+/**
+ * Canonical boundary between the internal `EditorAnchorProjection` shape
+ * (`src/core/selection/mapping.ts` — `{ kind: "range", range: DocRange,
+ * assoc }`) and the public `EditorAnchorProjection` shape
+ * (`src/api/public-types.ts` — `{ kind: "range", from, to, assoc }`).
+ *
+ * Two shapes stay split intentionally: the internal shape uses `DocRange`
+ * so mapping helpers compose ranges independently of assoc semantics;
+ * the public shape is flat so host consumers can destructure without
+ * reaching through a nested `range` member.
+ *
+ * Every conversion MUST go through this module. Every creation of a
+ * public-shape anchor MUST go through this module. A regression test
+ * in `test/api/anchor-boundary-invariants.test.ts` enforces the "no
+ * ad-hoc helpers outside this file" rule.
+ */
+
+import type { EditorAnchorProjection as PublicEditorAnchorProjection } from "../../api/public-types";
+import {
+  DEFAULT_BOUNDARY_ASSOC,
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+  normalizeRange,
+  type DocRange,
+  type EditorAnchorProjection as InternalEditorAnchorProjection,
+} from "./mapping.ts";
+
+/**
+ * Default boundary-associativity used by public-shape range anchors
+ * when the caller does not provide one. Matches the inline default the
+ * three ad-hoc `createPublicRangeAnchor` helpers all used before this
+ * module existed (`{ start: -1, end: 1 }` — the "outward-biased"
+ * selection).
+ */
+export const DEFAULT_PUBLIC_ASSOC: { start: -1 | 1; end: -1 | 1 } = {
+  start: -1,
+  end: 1,
+};
+
+type PublicRangeAssoc = { start: -1 | 1; end: -1 | 1 };
+
+export function createPublicRangeAnchor(
+  from: number,
+  to: number,
+  assoc: PublicRangeAssoc = DEFAULT_PUBLIC_ASSOC,
+): PublicEditorAnchorProjection {
+  const range = normalizeRange({ from, to });
+  return {
+    kind: "range",
+    from: range.from,
+    to: range.to,
+    assoc,
+  };
+}
+
+export function createPublicNodeAnchor(
+  at: number,
+  assoc: -1 | 1 = 1,
+): PublicEditorAnchorProjection {
+  return { kind: "node", at, assoc };
+}
+
+export function createPublicDetachedAnchor(
+  lastKnownRange: DocRange,
+  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity",
+): PublicEditorAnchorProjection {
+  return {
+    kind: "detached",
+    lastKnownRange: normalizeRange(lastKnownRange),
+    reason,
+  };
+}
+
+export function toPublicAnchorProjection(
+  anchor: InternalEditorAnchorProjection,
+): PublicEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        kind: "range",
+        from: anchor.range.from,
+        to: anchor.range.to,
+        assoc: anchor.assoc,
+      };
+    case "node":
+      return { kind: "node", at: anchor.at, assoc: anchor.assoc };
+    case "detached":
+      return {
+        kind: "detached",
+        lastKnownRange: anchor.lastKnownRange,
+        reason: anchor.reason,
+      };
+  }
+}
+
+export function toInternalAnchorProjection(
+  anchor: PublicEditorAnchorProjection,
+): InternalEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(
+        anchor.from,
+        anchor.to,
+        anchor.assoc ?? DEFAULT_BOUNDARY_ASSOC,
+      );
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}

package/src/core/selection/review-anchors.ts

@@ -103,20 +103,125 @@ export function rangeStaysWithinSingleParagraph(
   return true;
 }
 
+/**
+ * I8 — "mid-run-near-table" guard. Comment anchors whose endpoints
+ * land strictly inside a paragraph that sits adjacent to a table
+ * block are rejected: the serializer's per-paragraph offset walker
+ * (Lane 3 §O8) produces invalid OOXML for these anchors. Removed
+ * once O8 ships.
+ */
+export const TABLE_ADJACENT_WINDOW = 1;
+
+export type CommentAnchorRejectionReason =
+  | "invalid_comment_anchor"
+  | "comment_anchor_table_adjacent";
+
 export function canCreateDocxCommentAnchor(
   content: unknown,
   anchor: ReviewAnchor,
 ): boolean {
+  return commentAnchorRejectionReason(content, anchor) === null;
+}
+
+export function commentAnchorRejectionReason(
+  content: unknown,
+  anchor: ReviewAnchor,
+): CommentAnchorRejectionReason | null {
   if (anchor.kind !== "range") {
-    return false;
+    return "invalid_comment_anchor";
   }
 
   const normalized = normalizeRange(anchor.range);
   if (normalized.from === normalized.to) {
-    return false;
+    return "invalid_comment_anchor";
+  }
+
+  if (!rangeStaysWithinCommentableStory(content, normalized)) {
+    return "invalid_comment_anchor";
+  }
+
+  if (rangeLandsMidRunNearTableBoundary(content, normalized)) {
+    return "comment_anchor_table_adjacent";
   }
 
-  return rangeStaysWithinCommentableStory(content, normalized);
+  return null;
+}
+
+/**
+ * I8.3 — Snap a rejected mid-run-near-table anchor to paragraph
+ * boundaries so downstream serialization stays safe. Returns `null`
+ * if the anchor cannot be rescued (e.g. crosses an opaque block).
+ */
+export function snapCommentAnchorAwayFromTable(
+  content: unknown,
+  anchor: ReviewAnchor,
+): ReviewAnchor | null {
+  if (anchor.kind !== "range") return null;
+
+  const normalized = normalizeRange(anchor.range);
+  if (normalized.from === normalized.to) return null;
+
+  const reason = commentAnchorRejectionReason(content, anchor);
+  if (reason === null) return anchor;
+  if (reason !== "comment_anchor_table_adjacent") return null;
+
+  const surfaceBlocks = readSurfaceBlocks(content);
+  if (!surfaceBlocks) return null;
+
+  const fromOwner = findContainingParagraphForEndpoint(surfaceBlocks, normalized.from, "start");
+  const toOwner = findContainingParagraphForEndpoint(surfaceBlocks, normalized.to, "end");
+  if (!fromOwner || !toOwner) return null;
+
+  const snappedFrom = normalized.from > fromOwner.from && normalized.from < fromOwner.to
+    ? fromOwner.from
+    : normalized.from;
+  const snappedTo = normalized.to > toOwner.from && normalized.to < toOwner.to
+    ? toOwner.to
+    : normalized.to;
+
+  if (snappedFrom === snappedTo) return null;
+
+  const snapped = createRangeAnchor(snappedFrom, snappedTo);
+  return canCreateDocxCommentAnchor(content, snapped) ? snapped : null;
+}
+
+function rangeLandsMidRunNearTableBoundary(
+  content: unknown,
+  range: DocRange,
+): boolean {
+  const surfaceBlocks = readSurfaceBlocks(content);
+  if (!surfaceBlocks) return false;
+
+  const tableBlocks = surfaceBlocks.filter((block) => block.kind === "table");
+  if (tableBlocks.length === 0) return false;
+
+  const fromOwner = findContainingParagraphForEndpoint(surfaceBlocks, range.from, "start");
+  const toOwner = findContainingParagraphForEndpoint(surfaceBlocks, range.to, "end");
+  if (!fromOwner || !toOwner) return false;
+
+  const fromMidRun = range.from > fromOwner.from && range.from < fromOwner.to;
+  const toMidRun = range.to > toOwner.from && range.to < toOwner.to;
+  if (!fromMidRun && !toMidRun) return false;
+
+  const fromAdjacent = fromMidRun && paragraphIsTableAdjacent(fromOwner, tableBlocks);
+  const toAdjacent = toMidRun && paragraphIsTableAdjacent(toOwner, tableBlocks);
+  return fromAdjacent || toAdjacent;
+}
+
+function paragraphIsTableAdjacent(
+  paragraph: FlattenedSurfaceBlock,
+  tableBlocks: readonly FlattenedSurfaceBlock[],
+): boolean {
+  return tableBlocks.some((table) => {
+    if (table.tableId !== null && table.tableId === paragraph.tableId) {
+      // Skip: a table block at the same cell scope would be a
+      // descendant of the paragraph's containing cell, not a sibling.
+      return false;
+    }
+    const leftGap = Math.abs(paragraph.from - table.to);
+    const rightGap = Math.abs(paragraph.to - table.from);
+    return leftGap <= TABLE_ADJACENT_WINDOW || rightGap <= TABLE_ADJACENT_WINDOW;
+  });
 }
 
 export function rangeStaysWithinCommentableStory(