@beyondwork/docx-react-component 1.0.49 → 1.0.51

package/src/runtime/selection/cursor-ops.ts

@@ -0,0 +1,202 @@
+/**
+ * R.1 Phase 6a — SelectionLayer cursor primitives.
+ *
+ * Pure functions over `(DocumentRootNode, CursorSelection, op) → CursorSelection`.
+ * `extend: true` keeps the anchor fixed and moves only the head — the
+ * LibreOffice `SwPaM` head/anchor split that matches Shift+arrow semantics.
+ *
+ * Positions are 0-based logical positions per the canonical story layer
+ * (`createPlainText(parseTextStory(doc))`). Scope markers are zero-width;
+ * paragraph breaks are 1 wide; text / tab / hard_break / image / opaque are 1
+ * wide. The plain-text string produced by `createPlainText` is a 1:1 mapping
+ * of those logical positions to characters, which makes position-math trivial
+ * and makes `Intl.Segmenter` (for word boundaries) a drop-in fit.
+ *
+ * What this module deliberately does NOT ship yet:
+ *   - `moveUp` / `moveDown` — genuinely layout-dependent (need column tracking
+ *     + line-wrap info). Follows Phase 6b once Lane 3a P9 exposes the per-run
+ *     layout facet needed for column-preserving movement.
+ *   - `moveLineStart` / `moveLineEnd` — same; these need soft-wrap info that
+ *     the canonical story layer does not expose.
+ */
+
+import { createPlainText, parseTextStory } from "../../core/schema/text-schema.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+
+export interface CursorSelection {
+  anchor: number;
+  head: number;
+}
+
+export interface CursorMoveOptions {
+  /**
+   * When true, the anchor stays fixed and only the head moves — matches
+   * Shift+arrow "extend selection" semantics. When false (default), both
+   * anchor and head land at the new head, collapsing any range selection.
+   */
+  extend?: boolean;
+}
+
+export function moveCharLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the LEFT edge
+  // without moving; only a collapsed caret actually decrements by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const leftEdge = Math.min(selection.anchor, selection.head);
+    return { anchor: leftEdge, head: leftEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.max(0, currentHead - 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveCharRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the RIGHT edge
+  // without moving; only a collapsed caret actually increments by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const rightEdge = Math.max(selection.anchor, selection.head);
+    return { anchor: rightEdge, head: rightEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.min(text.length, currentHead + 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveParagraphStart(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  // Walk backward until we find a paragraph break ('\n') or reach 0. The
+  // paragraph start is the character immediately after the break.
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor > 0 && text[cursor - 1] !== "\n") {
+    cursor -= 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+export function moveParagraphEnd(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor < text.length && text[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+/**
+ * `Intl.Segmenter` with `granularity: "word"` returns ICU word boundaries —
+ * the standards-backed equivalent of LibreOffice's `SwBreakIt`. We walk the
+ * boundary list (cached per-`doc` call) to find the next / previous
+ * word-start relative to the head, matching Word's Ctrl+arrow behavior.
+ *
+ * Word semantics:
+ *   - Ctrl+Right: jump to the end of the current word, OR to the end of the
+ *     next word if already at word-end. In practice we land on the next
+ *     word-boundary strictly greater than the current head.
+ *   - Ctrl+Left: jump to the start of the current word, OR to the start of
+ *     the previous word if already at word-start. We land on the previous
+ *     word-boundary strictly less than the current head.
+ */
+export function moveWordRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.max(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  const nextBoundary =
+    boundaries.find((pos) => pos > currentHead) ?? text.length;
+  return finalize(selection, nextBoundary, options);
+}
+
+export function moveWordLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.min(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  let prevBoundary = 0;
+  for (const pos of boundaries) {
+    if (pos >= currentHead) break;
+    prevBoundary = pos;
+  }
+  return finalize(selection, prevBoundary, options);
+}
+
+function finalize(
+  selection: CursorSelection,
+  head: number,
+  options: CursorMoveOptions,
+): CursorSelection {
+  if (options.extend) {
+    return { anchor: selection.anchor, head };
+  }
+  return { anchor: head, head };
+}
+
+function documentPlainText(doc: DocumentRootNode): string {
+  const story = parseTextStory(doc);
+  return createPlainText(story);
+}
+
+/**
+ * `Intl.Segmenter` is available in Node 16+ and all modern browsers. We lazy-
+ * init the default-locale instance; word segmentation is stateless, so one
+ * segmenter per process is fine.
+ */
+let cachedSegmenter: Intl.Segmenter | undefined;
+function wordSegmenter(): Intl.Segmenter {
+  if (!cachedSegmenter) {
+    cachedSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  }
+  return cachedSegmenter;
+}
+
+/**
+ * Produce the sorted list of word-boundary positions in `text`. A boundary is
+ * the start of any segment whose `isWordLike` is true, plus the end-of-text.
+ * Whitespace and punctuation segments are skipped so caret jumps land on
+ * word endpoints rather than stopping at every space — matching Word's
+ * Ctrl+arrow behavior.
+ */
+function wordBoundaries(text: string): number[] {
+  const segments = wordSegmenter().segment(text);
+  const boundaries: number[] = [];
+  for (const segment of segments) {
+    if (segment.isWordLike) {
+      // Add both the start and the end of each word-like segment so
+      // Ctrl+Right from "hello|world" (between two words) advances to the end
+      // of "world" rather than stopping at the start.
+      boundaries.push(segment.index);
+      boundaries.push(segment.index + segment.segment.length);
+    }
+  }
+  // Dedup + sort so callers can binary-search or linear-walk deterministically.
+  boundaries.push(text.length);
+  return Array.from(new Set(boundaries)).sort((a, b) => a - b);
+}

package/src/runtime/selection/index.ts

@@ -0,0 +1,91 @@
+/**
+ * R.1 SelectionLayer — named module for cursor movement, validation, and
+ * anchor projection. See `docs/plans/lane-1-editing-foundation.md` §R.1.
+ *
+ * This file is the layer's single entry point. Callers consume
+ * `SelectionLayer.move(doc, sel, op)` / `SelectionLayer.validate(doc, sel)`
+ * rather than reaching into individual helpers. Phase 6a ships the six
+ * layout-independent primitives (char/word/paragraph × left/right). Phase 6b
+ * adds `moveUp` / `moveDown` / `moveLineStart` / `moveLineEnd` once Lane 3a
+ * P9's layout facet exposes per-run column info.
+ */
+
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope, SelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  moveCharLeft,
+  moveCharRight,
+  moveParagraphEnd,
+  moveParagraphStart,
+  moveWordLeft,
+  moveWordRight,
+  type CursorMoveOptions,
+  type CursorSelection,
+} from "./cursor-ops.ts";
+import { validateSelectionAgainstDocument } from "./post-edit-validator.ts";
+
+export type {
+  CursorMoveOptions,
+  CursorSelection,
+} from "./cursor-ops.ts";
+
+/**
+ * Cursor-move operations supported by the layer. Phase 6b will extend this
+ * with `"up" | "down" | "line-start" | "line-end"`.
+ */
+export type CursorMoveOp =
+  | "char-left"
+  | "char-right"
+  | "word-left"
+  | "word-right"
+  | "paragraph-start"
+  | "paragraph-end";
+
+export interface SelectionLayer {
+  /**
+   * Apply a cursor-move operation and return the resulting selection. Pure;
+   * does not mutate any argument.
+   */
+  move(
+    doc: DocumentRootNode,
+    selection: CursorSelection,
+    op: CursorMoveOp,
+    options?: CursorMoveOptions,
+  ): CursorSelection;
+
+  /**
+   * Run the I5 post-edit selection validator. Snaps orphaned offsets into the
+   * nearest valid position. Pure; returns the (possibly adjusted) selection.
+   */
+  validate(
+    doc: CanonicalDocumentEnvelope,
+    selection: SelectionSnapshot,
+    maxOffset: number,
+  ): SelectionSnapshot;
+}
+
+/**
+ * Default SelectionLayer instance. Stateless — the same instance is safe to
+ * share across runtimes.
+ */
+export const selectionLayer: SelectionLayer = {
+  move(doc, selection, op, options) {
+    switch (op) {
+      case "char-left":
+        return moveCharLeft(doc, selection, options);
+      case "char-right":
+        return moveCharRight(doc, selection, options);
+      case "word-left":
+        return moveWordLeft(doc, selection, options);
+      case "word-right":
+        return moveWordRight(doc, selection, options);
+      case "paragraph-start":
+        return moveParagraphStart(doc, selection, options);
+      case "paragraph-end":
+        return moveParagraphEnd(doc, selection, options);
+    }
+  },
+  validate(doc, selection, maxOffset) {
+    return validateSelectionAgainstDocument(doc, selection, maxOffset);
+  },
+};

package/src/runtime/structure-ops/fragment-insert.ts

@@ -0,0 +1,134 @@
+/**
+ * Slice 1 of the I2 Tier B rich-paste sub-plan (`docs/plans/lane-1-i2-tier-b-rich-paste.md`).
+ *
+ * `applyFragmentInsert` is the canonical splicer for `CanonicalDocumentFragment` —
+ * the block-level payload that the HTML and Word-clipboard paste parsers (Slices 2+3)
+ * will produce. Slice 1 ships the shape and a baseline "split-and-splice" semantic
+ * without any parser in front of it, so the public `insertFragment` method can be
+ * driven directly from tests + future hosts.
+ *
+ * Baseline semantics:
+ *   1. Empty fragment → no-op (no revisionToken bump).
+ *   2. Range selection → the range is deleted first via `applyTextTransaction`, then
+ *      the caret is the range start.
+ *   3. Caret paragraph is split via `splitParagraph`; fragment blocks are spliced
+ *      between the two halves. Empty halves at document boundaries are preserved —
+ *      callers can trim them if desired.
+ *
+ * What Slice 1 deliberately does NOT do:
+ *   - Merge-intent (pre-Slice-1 drafts had `firstParagraphMergeIntent` on the type).
+ *     Merge semantics will land in a follow-up slice once we have a paste fixture
+ *     that demonstrates the need.
+ *   - Fragment insertion inside table cells beyond the trivial case. Table-cell
+ *     splicing is currently best-effort: the target paragraph within the cell is
+ *     split, but cross-cell fragments are rejected as a no-op.
+ *   - Comment/revision remapping across the fragment boundary — the splicer returns
+ *     an empty mapping; follow-up slices will produce richer mappings.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import {
+  type CanonicalDocumentEnvelope,
+  type SelectionSnapshot,
+  createSelectionSnapshot,
+} from "../../core/state/editor-state.ts";
+import { applyTextTransaction } from "../../core/state/text-transaction.ts";
+import { splitParagraph, type TextCommandContext } from "../../core/commands/text-commands.ts";
+import { resolveParagraphScope, type StructuralMutationResult } from "../../core/commands/structural-helpers.ts";
+import type { BlockNode, DocumentRootNode, ParagraphNode } from "../../model/canonical-document.ts";
+import { createEmptyMapping } from "../../core/selection/mapping.ts";
+
+export function applyFragmentInsert(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  fragment: CanonicalDocumentFragment,
+  context: TextCommandContext,
+): StructuralMutationResult {
+  if (fragment.blocks.length === 0) {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Collapse any range selection by first deleting the selected content. The
+  // resulting caret is at `min(anchor, head)`.
+  let workingDocument = document;
+  let workingSelection = selection;
+  if (selection.anchor !== selection.head) {
+    const collapseResult = applyTextTransaction(
+      workingDocument,
+      workingSelection,
+      { type: "replace", insertion: [] },
+      context,
+    );
+    workingDocument = collapseResult.document;
+    workingSelection = collapseResult.selection;
+  }
+
+  // Split the caret paragraph; the fragment blocks go between the two halves.
+  const splitResult = splitParagraph(workingDocument, workingSelection, context);
+  const splitRoot = splitResult.document.content;
+  if (!splitRoot || splitRoot.type !== "doc") {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Locate the split boundary by re-resolving the paragraph scope against the
+  // pre-split snapshot. The right-half index = scope.blockIndex + 1.
+  const scope = resolveParagraphScope(workingDocument, workingSelection);
+  if (!scope || scope.kind !== "top-level") {
+    // Table-cell fragment insert is out of scope for Slice 1.
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  const rightHalfIndex = scope.blockIndex + 1;
+  const splicedChildren: BlockNode[] = [
+    ...splitRoot.children.slice(0, rightHalfIndex),
+    ...fragment.blocks.map((block) => cloneBlock(block)),
+    ...splitRoot.children.slice(rightHalfIndex),
+  ];
+
+  const nextRoot: DocumentRootNode = {
+    ...splitRoot,
+    children: splicedChildren,
+  };
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...splitResult.document,
+    updatedAt: context.timestamp,
+    content: nextRoot,
+  };
+
+  // Caret lands at the end of the last fragment block. For Slice 1 we approximate
+  // this with a collapsed selection at position 0 of the new document — richer
+  // caret placement follows once parsers drive this.
+  const nextSelection = createSelectionSnapshot(0, 0);
+
+  return {
+    changed: true,
+    document: nextDocument,
+    selection: nextSelection,
+    mapping: createEmptyMapping(),
+  };
+}
+
+function cloneBlock(block: BlockNode): BlockNode {
+  // Slice 1 uses a structural clone; no need to deep-clone formatting attrs since
+  // fragment blocks are presumed freshly minted by the caller.
+  if (block.type === "paragraph") {
+    return {
+      ...block,
+      children: block.children.map((child) => ({ ...child })),
+    } as ParagraphNode;
+  }
+  return JSON.parse(JSON.stringify(block)) as BlockNode;
+}

package/src/runtime/surface-projection.ts

@@ -52,6 +52,7 @@ import {
   resolveNumberingMarkerRunFormatting,
 } from "./paragraph-style-resolver.ts";
 import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
+import { concretizeThemeColors } from "./theme-color-resolver.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 interface ParagraphAccumulator {
@@ -874,6 +875,11 @@ function appendInlineSegments(
         characterStyleId: undefined,
         direct: directRunFormatting,
       };
+      // L2.c — non-hyperlink body text also gets theme-color concretization
+      // so paragraph styles declaring `<w:color w:themeColor="accent1"/>`
+      // render with their theme slot's hex instead of falling back to
+      // default black. Hyperlink branch already resolves theme via the
+      // Hyperlink-style cascade; only the non-hyperlink path was missing.
       const resolvedRunFormatting = cullBuild
         ? {}
         : hyperlinkHref
@@ -882,7 +888,10 @@ function appendInlineSegments(
               document.styles,
               document.subParts?.resolvedTheme,
             )
-          : resolveEffectiveRunFormatting(runResolveInput, document.styles);
+          : concretizeThemeColors(
+              resolveEffectiveRunFormatting(runResolveInput, document.styles),
+              document.subParts?.resolvedTheme,
+            );
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "text",

package/src/runtime/theme-color-resolver.ts

@@ -57,6 +57,52 @@ export function resolveThemeColorHex(
   return applyThemeTintShade(baseHex, rPr.colorThemeTint, rPr.colorThemeShade);
 }
 
+/**
+ * Post-process a cascade of run formatting to concretize any
+ * theme-color-only reference into a paintable `colorHex`.
+ *
+ * L2.c body-text call site: `surface-projection.ts` runs the standard
+ * `resolveEffectiveRunFormatting` cascade, then pipes the result through
+ * this function with the document's resolved theme. Runs that declared
+ * `<w:color w:themeColor="accent1"/>` without a concrete `w:val` end up
+ * with `colorHex` set to the theme-resolved hex so downstream
+ * `pm-state-from-snapshot` can paint them.
+ *
+ * The theme-slot fields (`colorThemeSlot` / `Tint` / `Shade`) stay on
+ * the cascade so that the export path can re-emit the original theme
+ * reference — this function never overwrites them, it only adds
+ * `colorHex` when it was absent or `"auto"`.
+ *
+ * No-ops when:
+ *   - no theme-slot is declared (nothing to resolve),
+ *   - `colorHex` is already a concrete non-`"auto"` hex (direct wins),
+ *   - theme is missing or the slot is unknown (graceful fallback),
+ *   - resolver returns `undefined` (e.g. malformed tint/shade).
+ */
+export function concretizeThemeColors(
+  cascade: CanonicalRunFormatting,
+  theme: ResolvedTheme | undefined,
+): CanonicalRunFormatting {
+  if (!cascade.colorThemeSlot) return cascade;
+  if (cascade.colorHex && cascade.colorHex !== "auto") return cascade;
+  // When colorHex is "auto" we intentionally bypass it during theme
+  // resolution: Word's cascade treats `<w:color w:val="auto"
+  // w:themeColor="accent1"/>` as "paint with the theme slot; auto is
+  // the fallback if theme is missing." Pass a stripped input to the
+  // resolver so `colorHex === "auto"` doesn't short-circuit.
+  const resolved = resolveThemeColorHex(
+    {
+      colorThemeSlot: cascade.colorThemeSlot,
+      colorThemeTint: cascade.colorThemeTint,
+      colorThemeShade: cascade.colorThemeShade,
+    },
+    theme,
+  );
+  if (!resolved || resolved === "auto") return cascade;
+  if (resolved === cascade.colorHex) return cascade;
+  return { ...cascade, colorHex: resolved };
+}
+
 /**
  * Apply `w:themeTint` (shift toward white) and/or `w:themeShade` (shift
  * toward black) to a base hex colour. Pure function.

package/src/ui/WordReviewEditor.tsx

@@ -486,7 +486,8 @@ export function __createWordReviewEditorRefBridge(
     blur: () => runtime.blur(),
     undo: () => runtime.undo(),
     redo: () => runtime.redo(),
-    replaceText: (text, target) => runtime.replaceText(text, target),
+    replaceText: (text, target, formatting) => runtime.replaceText(text, target, formatting),
+    insertFragment: (fragment, target) => runtime.insertFragment(fragment, target),
     addComment: (params) => runtime.addComment(params),
     openComment: (commentId) => runtime.openComment(commentId),
     resolveComment: (commentId) => runtime.resolveComment(commentId),
@@ -1476,7 +1477,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         blur: () => activeRuntime.blur(),
         undo: () => activeRuntime.undo(),
         redo: () => activeRuntime.redo(),
-        replaceText: (text, target) => activeRuntime.replaceText(text, target),
+        replaceText: (text, target, formatting) => activeRuntime.replaceText(text, target, formatting),
+        insertFragment: (fragment, target) => activeRuntime.insertFragment(fragment, target),
         addComment: (params) =>
           activeRuntime.addComment({
             ...params,

package/src/ui/editor-runtime-boundary.ts

@@ -912,6 +912,7 @@ function createLoadingRuntimeBridge(input: {
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
     replaceText: () => undefined,
+    insertFragment: () => undefined,
     applyActiveStoryTextCommand: () => ({
       kind: "rejected",
       newRevisionToken: "",