@beyondwork/docx-react-component 1.0.56 → 1.0.57

package/src/runtime/paragraph-style-resolver.ts

@@ -11,11 +11,13 @@
  */
 
 import type {
+  CanonicalFontTable,
   CanonicalParagraphFormatting,
   CanonicalRunFormatting,
   CharacterStyleDefinition,
   ParagraphStyleDefinition,
   StylesCatalog,
+  TableStyleDefinition,
 } from "../model/canonical-document.ts";
 
 export function resolveParagraphStyleChain(
@@ -192,3 +194,106 @@ export function resolveNumberingMarkerRunFormatting(
   acc = mergeRun(acc, input.levelRunProperties);
   return acc ?? {};
 }
+
+/**
+ * Return the `w:next` style ID for `styleId` — the paragraph style Word
+ * applies after pressing Enter at the end of a paragraph of this style.
+ * Used by Lane 1's suggest-paragraph-split command.
+ */
+export function getNextStyleId(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string | undefined {
+  return catalog?.paragraphs[styleId]?.nextStyle;
+}
+
+/**
+ * Resolve the effective font family name for a run.
+ *
+ * Walks the ECMA-376 §17.3.2.26 precedence for `<w:rFonts>`: `ascii` →
+ * `hAnsi` → `eastAsia` → `cs`. When none of those resolve on the direct
+ * run formatting, layers the paragraph/character style cascade for the
+ * same four fields, then falls back to the caller-supplied
+ * `themeMinorFont` (ECMA-376 default for body text).
+ *
+ * `fontTable`, when supplied, is consulted only for presence — an entry
+ * whose `w:name` does not appear in `fontTable.fonts` is still returned
+ * as-is (Word behavior: substitute at render time, not at model resolve).
+ * Lane 3a's measurement backend owns the substitution decision.
+ *
+ * Returns undefined only when no source in the cascade supplies a family
+ * name (rare — production docs always hit docDefaults or the theme).
+ */
+export function resolveRunFontFamily(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+  themeMinorFont: string | undefined,
+  fontTable?: CanonicalFontTable | undefined,
+): string | undefined {
+  // `fontTable` is currently unused inside this resolver; the ECMA-376
+  // rFonts precedence does not require consulting the package's fontTable
+  // to pick a name. It is reserved so Lane 3a's measurement backend can
+  // layer substitution (e.g. pick a monospace fallback when the resolved
+  // name has `pitch === "fixed"`) by threading the same table through.
+  void fontTable;
+  const resolved = resolveEffectiveRunFormatting(input, catalog);
+  const name =
+    resolved.fontFamilyAscii ??
+    resolved.fontFamilyHAnsi ??
+    resolved.fontFamilyEastAsia ??
+    resolved.fontFamilyCs ??
+    resolved.fontFamily ??
+    themeMinorFont;
+  return name;
+}
+
+function resolveTableStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): TableStyleDefinition[] {
+  const chain: TableStyleDefinition[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: TableStyleDefinition | undefined = catalog.tables[current];
+    if (!def) break;
+    chain.push(def);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+/**
+ * Resolve the paragraph + run formatting that applies to a cell's body text
+ * when only the table style is known (no cell-paragraph-level overrides).
+ *
+ * Cascade (lowest to highest priority):
+ *   1. `catalog.docDefaults.paragraph` / `.run`
+ *   2. Table style's `basedOn` chain, walked root-to-leaf, projecting each
+ *      style's `formatting.paragraphProperties` / `.runProperties`.
+ *
+ * Conditional-region pPr/rPr (`<w:tblStylePr w:type="...">`) is intentionally
+ * NOT layered here — callers that need region-aware cell-text cascade must
+ * extend this once the conditional region parser captures pPr/rPr (Lane 3a
+ * follow-up). Per-paragraph and per-run formatting from the cell's content
+ * is layered by `resolveEffectiveParagraphFormatting` /
+ * `resolveEffectiveRunFormatting`; this function only returns the floor.
+ */
+export function resolveTableCellTextFormatting(
+  tableStyleId: string | undefined,
+  catalog: StylesCatalog | undefined,
+): { paragraph: CanonicalParagraphFormatting; run: CanonicalRunFormatting } {
+  let paragraph: CanonicalParagraphFormatting | undefined = catalog?.docDefaults?.paragraph;
+  let run: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+  if (catalog && tableStyleId) {
+    const chain = resolveTableStyleChain(tableStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const formatting = chain[i]!.formatting;
+      paragraph = mergeParagraph(paragraph, formatting?.paragraphProperties);
+      run = mergeRun(run, formatting?.runProperties);
+    }
+  }
+  return { paragraph: paragraph ?? {}, run: run ?? {} };
+}

package/src/runtime/resolved-numbering-geometry.ts

@@ -12,16 +12,28 @@ import type {
 
 export const DEFAULT_NUMBERING_START_AT = 1;
 
+/**
+ * Resolved numbering geometry. **All numeric distance values are in OOXML
+ * twips (1/1440 in)** — the same unit `w:ind`/`w:tabs`/`w:spacing` carry on
+ * the parse side. Render consumers convert to display units at the boundary
+ * (`pt = twips / 20`, `px = twips × FRAME_PX_PER_TWIP_AT_96DPI`) — see
+ * `src/ui-tailwind/editor-surface/pm-schema.ts:331` and
+ * `tw-page-block-view.helpers.ts:179` for the canonical conversion sites.
+ * Do not pre-convert here; the runtime stays in OOXML units so cache keys
+ * and serializer round-trips stay byte-identical.
+ */
 export interface ResolvedNumberingGeometry {
   markerJustification?: NumberingLevelParagraphGeometry["justification"];
   spacing?: ParagraphSpacing;
   indentation?: ParagraphIndentation;
   tabStops?: TabStop[];
+  /** All fields in twips. */
   markerLane?: {
     start: number;
     width: number;
     textStart: number;
   };
+  /** All fields in twips. */
   textColumn?: {
     start: number;
     right?: number;

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

@@ -1,27 +1,27 @@
 /**
- * R.1 Phase 6a — SelectionLayer cursor primitives.
+ * R.1 SelectionLayer cursor primitives.
+ *
+ * Phase 6a (shipped) — layout-independent primitives over
+ * `(DocumentRootNode, CursorSelection, op) → CursorSelection` using the
+ * canonical story layer (`createPlainText(parseTextStory(doc))`) and
+ * `Intl.Segmenter` for word boundaries.
+ *
+ * Phase 6b (this module) — layout-aware primitives (`moveUp` / `moveDown` /
+ * `moveLineStart` / `moveLineEnd`) that consult a `RenderAnchorIndex` from
+ * Lane 3a P9 to resolve line boundaries. When no index is supplied the
+ * primitives degrade gracefully (see per-function docs).
  *
- * 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.
+ * Positions are 0-based logical positions per the canonical story layer.
+ * Scope markers are zero-width; paragraph breaks are 1 wide; text / tab /
+ * hard_break / image / opaque are 1 wide.
  */
 
 import { createPlainText, parseTextStory } from "../../core/schema/text-schema.ts";
 import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import type { RenderAnchorIndex, RenderFrameRect } from "../render/render-frame-types.ts";
 
 export interface CursorSelection {
   anchor: number;
@@ -35,6 +35,13 @@ export interface CursorMoveOptions {
    * anchor and head land at the new head, collapsing any range selection.
    */
   extend?: boolean;
+  /**
+   * R.1 Phase 6b — optional. Layout-aware primitives
+   * (`moveUp` / `moveDown` / `moveLineStart` / `moveLineEnd`) consult this
+   * index to resolve line boundaries via `byRuntimeOffset(offset)`. Absent
+   * in pure unit-test contexts; primitives degrade gracefully without it.
+   */
+  anchorIndex?: RenderAnchorIndex;
 }
 
 export function moveCharLeft(
@@ -148,6 +155,170 @@ export function moveWordLeft(
   return finalize(selection, prevBoundary, options);
 }
 
+// ─── Phase 6b — layout-aware primitives ────────────────────────────────────
+
+/**
+ * Move the head to the character on the next line at the nearest column X
+ * to the current head. Requires an anchor index; without one, this is a
+ * no-op (graceful degradation for pure unit-test contexts).
+ *
+ * Algorithm: probe the current head's rect for its `topPx` + `leftPx` (the
+ * anchor column). Scan forward through offsets; the first offset whose
+ * rect has a strictly-greater `topPx` marks the start of the next line.
+ * From that offset, continue while `topPx` matches the next-line top,
+ * tracking which offset has the smallest `|leftPx - anchorLeftPx|`.
+ */
+export function moveDown(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, selection.head, options);
+
+  const text = documentPlainText(doc);
+  const startHead = options.extend
+    ? selection.head
+    : Math.max(selection.anchor, selection.head);
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const anchorLeft = currentRect.leftPx;
+  const currentTop = currentRect.topPx;
+
+  // Find first offset with a different (higher) topPx.
+  let nextLineStart = -1;
+  let nextLineTop = Number.POSITIVE_INFINITY;
+  for (let i = startHead + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx > currentTop) {
+      nextLineStart = i;
+      nextLineTop = r.topPx;
+      break;
+    }
+  }
+  if (nextLineStart < 0) return finalize(selection, startHead, options);
+
+  // Scan the next line for the offset with leftPx closest to anchorLeft.
+  let bestOffset = nextLineStart;
+  let bestDelta = Math.abs((index.byRuntimeOffset(nextLineStart)?.leftPx ?? 0) - anchorLeft);
+  for (let i = nextLineStart + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r || r.topPx !== nextLineTop) break;
+    const delta = Math.abs(r.leftPx - anchorLeft);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestOffset = i;
+    }
+  }
+  return finalize(selection, bestOffset, options);
+}
+
+/** Mirror of `moveDown`, scanning upward. */
+export function moveUp(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, selection.head, options);
+
+  const startHead = options.extend
+    ? selection.head
+    : Math.min(selection.anchor, selection.head);
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const anchorLeft = currentRect.leftPx;
+  const currentTop = currentRect.topPx;
+
+  let prevLineEnd = -1;
+  let prevLineTop = Number.NEGATIVE_INFINITY;
+  for (let i = startHead - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx < currentTop) {
+      prevLineEnd = i;
+      prevLineTop = r.topPx;
+      break;
+    }
+  }
+  if (prevLineEnd < 0) return finalize(selection, startHead, options);
+
+  let bestOffset = prevLineEnd;
+  let bestDelta = Math.abs((index.byRuntimeOffset(prevLineEnd)?.leftPx ?? 0) - anchorLeft);
+  for (let i = prevLineEnd - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r || r.topPx !== prevLineTop) break;
+    const delta = Math.abs(r.leftPx - anchorLeft);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestOffset = i;
+    }
+  }
+  return finalize(selection, bestOffset, options);
+}
+
+/**
+ * Move the head to the first offset on the current visual line. Requires an
+ * anchor index; without one, collapses to document start (offset 0), which
+ * is a common keyboard fallback (matches "Home" at the start of an unwrapped
+ * document).
+ */
+export function moveLineStart(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, 0, options);
+
+  const startHead = selection.head;
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const currentTop = currentRect.topPx;
+  let lineStart = startHead;
+  for (let i = startHead - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx !== currentTop) break;
+    lineStart = i;
+  }
+  return finalize(selection, lineStart, options);
+}
+
+/**
+ * Move the head to the last offset on the current visual line. Without an
+ * anchor index, collapses to document end.
+ */
+export function moveLineEnd(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, text.length, options);
+
+  const startHead = selection.head;
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const currentTop = currentRect.topPx;
+  let lineEnd = startHead;
+  for (let i = startHead + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx !== currentTop) break;
+    lineEnd = i;
+  }
+  return finalize(selection, lineEnd, options);
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
 function finalize(
   selection: CursorSelection,
   head: number,

package/src/runtime/selection/index.ts

@@ -15,8 +15,12 @@ import type { CanonicalDocumentEnvelope, SelectionSnapshot } from "../../core/st
 import {
   moveCharLeft,
   moveCharRight,
+  moveDown,
+  moveLineEnd,
+  moveLineStart,
   moveParagraphEnd,
   moveParagraphStart,
+  moveUp,
   moveWordLeft,
   moveWordRight,
   type CursorMoveOptions,
@@ -39,7 +43,11 @@ export type CursorMoveOp =
   | "word-left"
   | "word-right"
   | "paragraph-start"
-  | "paragraph-end";
+  | "paragraph-end"
+  | "up"
+  | "down"
+  | "line-start"
+  | "line-end";
 
 export interface SelectionLayer {
   /**
@@ -83,6 +91,14 @@ export const selectionLayer: SelectionLayer = {
         return moveParagraphStart(doc, selection, options);
       case "paragraph-end":
         return moveParagraphEnd(doc, selection, options);
+      case "up":
+        return moveUp(doc, selection, options);
+      case "down":
+        return moveDown(doc, selection, options);
+      case "line-start":
+        return moveLineStart(doc, selection, options);
+      case "line-end":
+        return moveLineEnd(doc, selection, options);
     }
   },
   validate(doc, selection, maxOffset) {

package/src/runtime/structure-ops/index.ts

@@ -0,0 +1,77 @@
+/**
+ * R.3 StructureLayer — named shell module for structural mutations. See
+ * `docs/plans/lane-1-editing-foundation.md` §R.3.
+ *
+ * Mirrors R.2 EditLayer's pattern: a thin named entry point over existing
+ * pure functions. The layer's purpose is to be the single site where callers
+ * reach for table / list / section / fragment-splice concerns, so R.5.b
+ * (post-edit validation hook) and R.5.a (action bracketing) can attach to a
+ * single seam instead of a fanout of helper call-sites.
+ *
+ * Phase 6/Item-2 scope: expose `applyFragmentInsert` (shipped in I2 Tier B
+ * Slice 1). Adding list/table/section-op wrappers is deferred because those
+ * existing command helpers already have rich type surfaces that don't need a
+ * named re-export to be callable — reach for them directly via
+ * `src/core/commands/{list,table,section}-commands.ts` until a specific case
+ * surfaces requiring the seam. Keeping this interface minimal avoids the
+ * "enumeration trap" that larger shell refactors fall into.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import type {
+  CanonicalDocumentEnvelope,
+  SelectionSnapshot,
+} from "../../core/state/editor-state.ts";
+import type { StructuralMutationResult } from "../../core/commands/structural-helpers.ts";
+import type { TextCommandContext } from "../../core/commands/text-commands.ts";
+import { countLogicalPositions, parseTextStory } from "../../core/schema/text-schema.ts";
+import { validateSelectionAgainstDocument } from "../selection/post-edit-validator.ts";
+import { applyFragmentInsert } from "./fragment-insert.ts";
+
+export interface StructureLayer {
+  /**
+   * Splice a `CanonicalDocumentFragment` at the current selection. Baseline
+   * semantic: the caret paragraph is split; fragment blocks are inserted
+   * between the two halves; range selections are deleted first. Empty
+   * fragments are no-ops.
+   */
+  applyFragmentInsert(
+    doc: CanonicalDocumentEnvelope,
+    selection: SelectionSnapshot,
+    fragment: CanonicalDocumentFragment,
+    context: TextCommandContext,
+  ): StructuralMutationResult;
+}
+
+/**
+ * R.5.b — every StructureLayer return passes through the post-edit selection
+ * validator before leaving the layer. Structural mutations can legitimately
+ * shrink the document (fragment with empty trailing paragraphs, etc.), so
+ * clamping here is a defense-in-depth hook matching the EditLayer's.
+ *
+ * `StructuralMutationResult` doesn't carry a pre-computed `storyText`, so
+ * we compute the post-mutation story size via `countLogicalPositions` over
+ * the parsed story. That's one parse per structural op — acceptable; these
+ * ops are off the typing hot path.
+ */
+function validateResult(result: StructuralMutationResult): StructuralMutationResult {
+  if (!result.changed) {
+    return result;
+  }
+  const story = parseTextStory(result.document.content);
+  const maxOffset = countLogicalPositions(story.units);
+  const validated = validateSelectionAgainstDocument(result.document, result.selection, maxOffset);
+  if (validated === result.selection) {
+    return result;
+  }
+  return { ...result, selection: validated };
+}
+
+/**
+ * Default stateless StructureLayer instance. Safe to share across runtimes.
+ */
+export const structureLayer: StructureLayer = {
+  applyFragmentInsert(doc, selection, fragment, context) {
+    return validateResult(applyFragmentInsert(doc, selection, fragment, context));
+  },
+};

package/src/runtime/styles-cascade.ts

@@ -0,0 +1,33 @@
+/**
+ * Central entry point for OOXML style cascade resolution.
+ *
+ * Re-exports the paragraph, character, run, numbering-marker, and table style
+ * resolvers from their individual modules so downstream consumers (Lane 3a
+ * measurement, Lane 1 style picker, agent tooling) can import from a single,
+ * stable location.
+ *
+ * Adding a new resolver? Add it to its feature module (paragraph, table, etc.)
+ * and re-export from here. Do not define new cascade logic in this file.
+ */
+
+export {
+  resolveParagraphStyleChain,
+  resolveCharacterStyleChain,
+  resolveEffectiveParagraphFormatting,
+  resolveEffectiveRunFormatting,
+  resolveNumberingMarkerRunFormatting,
+  resolveTableCellTextFormatting,
+  resolveRunFontFamily,
+  getNextStyleId,
+  type ParagraphResolveInput,
+  type RunResolveInput,
+  type MarkerResolveInput,
+} from "./paragraph-style-resolver.ts";
+
+export {
+  resolveTableStyleResolution,
+  type ResolvedTableCellStyle,
+  type ResolvedTableRowStyle,
+  type ResolvedTableLevelProperties,
+  type ResolvedTableStyleResolution,
+} from "./table-style-resolver.ts";