@beyondwork/docx-react-component 1.0.56 → 1.0.58

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";

package/src/runtime/surface-projection.ts

@@ -3,7 +3,9 @@ import type {
   EditorSurfaceSnapshot,
   SecondaryStorySurface,
   SurfaceBlockSnapshot,
+  SurfaceDrawingAnchor,
   SurfaceInlineSegment,
+  SurfacePictureEffects,
   SurfaceTableCellSnapshot,
   SurfaceTableRowSnapshot,
   SurfaceTextMark,
@@ -30,6 +32,9 @@ import type {
   TableCellBorders,
   TableNode,
   TextMark,
+  DrawingFrameNode,
+  PictureContent,
+  ShapeContent,
   VmlShapeNode,
   WordArtNode,
 } from "../model/canonical-document.ts";
@@ -57,7 +62,7 @@ import {
   resolveNumberingMarkerRunFormatting,
 } from "./paragraph-style-resolver.ts";
 import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
-import { concretizeThemeColors } from "./theme-color-resolver.ts";
+import { concretizeThemeColors, ThemeColorResolver } from "./theme-color-resolver.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 interface ParagraphAccumulator {
@@ -93,6 +98,13 @@ export function createEditorSurfaceSnapshot(
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+  // Open a chartModelStore build pass tagged with the document envelope.
+  // Every `chart_preview` node populated during the pass records its id
+  // in the pass's seen-set; `endBuildPass()` below evicts store entries
+  // from previous documents (different owner) and stale entries from
+  // earlier builds (same owner, not seen this pass). Previously the
+  // store grew unbounded across document loads — documented v1 gap.
+  chartModelStore.beginBuildPass(document);
   let cursor = 0;
   const counters = {
     paragraph: 0,
@@ -157,6 +169,12 @@ export function createEditorSurfaceSnapshot(
 
   const secondaryStories = createSecondaryStorySurfaces(document, numberingPrefixResolver);
 
+  // Close the chartModelStore build pass. Evicts entries from previous
+  // documents + stale entries whose ids no longer appear in the current
+  // document. Must happen AFTER secondary stories (they may also contain
+  // chart_preview nodes).
+  chartModelStore.endBuildPass();
+
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
@@ -712,6 +730,12 @@ function createParagraphBlock(
   const lockedFragmentIds: string[] = [];
   let cursor = start;
   const children = Array.isArray(paragraph.children) ? paragraph.children : [];
+  // Build once per paragraph block — ThemeColorResolver is a thin wrapper
+  // around CanonicalTheme that applies clrMap remapping. Constructed here so
+  // it is not recreated on every text segment (inner hot loop).
+  const themeResolver = document.subParts?.canonicalTheme
+    ? new ThemeColorResolver(document.subParts.canonicalTheme)
+    : undefined;
 
   for (const child of children) {
     const result = appendInlineSegments(
@@ -722,6 +746,7 @@ function createParagraphBlock(
       promoteSecondaryStoryTextBoxes,
       undefined,
       cullBuild,
+      themeResolver,
     );
     cursor = result.nextCursor;
     lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -885,6 +910,7 @@ function appendInlineSegments(
   promoteSecondaryStoryTextBoxes: boolean,
   hyperlinkHref?: string,
   cullBuild: boolean = false,
+  themeResolver?: ThemeColorResolver,
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   switch (node.type) {
     case "text": {
@@ -919,11 +945,11 @@ function appendInlineSegments(
           ? resolveHyperlinkRunFormatting(
               runResolveInput,
               document.styles,
-              document.subParts?.resolvedTheme,
+              themeResolver,
             )
           : concretizeThemeColors(
               resolveEffectiveRunFormatting(runResolveInput, document.styles),
-              document.subParts?.resolvedTheme,
+              themeResolver,
             );
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -967,6 +993,7 @@ function appendInlineSegments(
           promoteSecondaryStoryTextBoxes,
           node.href,
           cullBuild,
+          themeResolver,
         );
         cursor = result.nextCursor;
       }
@@ -1020,15 +1047,18 @@ function appendInlineSegments(
       let parsedChartId: string | undefined;
       if (node.parsedData) {
         parsedChartId = stableChartId(node.rawXml);
-        if (!chartModelStore.has(parsedChartId)) {
-          const { widthPx, heightPx } = extractChartDimensions(node.rawXml);
-          chartModelStore.set(parsedChartId, {
-            model: node.parsedData,
-            widthPx,
-            heightPx,
-            theme: undefined,
-          });
-        }
+        // Always call `set` (even when the entry exists) so the active
+        // `chartModelStore` build pass records the id in its seen-set —
+        // the pass uses the seen-set to evict stale entries from earlier
+        // builds. The entry object is a tiny reference so the set cost
+        // is negligible.
+        const { widthPx, heightPx } = extractChartDimensions(node.rawXml);
+        chartModelStore.set(parsedChartId, {
+          model: node.parsedData,
+          widthPx,
+          heightPx,
+          theme: undefined,
+        });
       }
       return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node), {
         previewMediaId: node.previewMediaId,
@@ -1064,6 +1094,58 @@ function appendInlineSegments(
         );
       }
       return appendComplexPreviewSegment(paragraph, node, start, "Legacy VML drawing", createVmlDetail(node));
+    case "drawing_frame": {
+      const c = node.content;
+      if (c.type === "picture") {
+        const mediaId = c.mediaId ?? `drawing-frame-${start}`;
+        const state: "editable" | "missing" = c.mediaId ? "editable" : "missing";
+        const anchor = surfaceAnchorFromGeometry(node.anchor);
+        const pictureEffects = surfacePictureEffectsFromContent(c);
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "image",
+          from: start,
+          to: start + 1,
+          mediaId,
+          state,
+          display: node.anchor.display,
+          detail: `Drawing frame image (${node.anchor.extent.widthEmu}\u00d7${node.anchor.extent.heightEmu} EMU).`,
+          ...(anchor ? { anchor } : {}),
+          ...(pictureEffects ? { pictureEffects } : {}),
+        });
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
+      if (c.type === "shape") {
+        const label = c.isTextBox ? "Text box" : "Drawing shape";
+        const detail = `DrawingFrame shape (${node.anchor.wrapMode}).`;
+        const anchor = surfaceAnchorFromGeometry(node.anchor);
+        const txbxText = c.isTextBox ? extractTxbxFirstText(c.txbxBlocks) : undefined;
+        const surfaceFill = c.fill;
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "shape",
+          from: start,
+          to: start + 1,
+          label,
+          detail,
+          ...(anchor ? { anchor } : {}),
+          ...(c.geometry !== undefined ? { geometry: c.geometry } : {}),
+          ...(surfaceFill ? { fill: surfaceFill } : {}),
+          ...(c.line ? { line: c.line } : {}),
+          ...(c.isTextBox ? { isTextBox: true } : {}),
+          ...(txbxText ? { txbxText } : {}),
+        });
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
+      const rawXml = "rawXml" in c ? c.rawXml : "";
+      const label =
+        c.type === "chart_preview"
+          ? "Embedded chart"
+          : c.type === "smartart_preview"
+            ? "SmartArt diagram"
+            : "Drawing frame";
+      return appendComplexPreviewSegment(paragraph, { rawXml } as DrawingFrameNode["content"] & { rawXml: string }, start, label, `DrawingFrame ${c.type} (${node.anchor.wrapMode}).`);
+    }
     case "symbol":
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -1126,6 +1208,7 @@ function appendInlineSegments(
             promoteSecondaryStoryTextBoxes,
             refHyperlinkHref ?? hyperlinkHref,
             cullBuild,
+            themeResolver,
           );
           cursor = result.nextCursor;
           lockedIds.push(...result.lockedFragmentIds);
@@ -1181,6 +1264,101 @@ function appendInlineSegments(
   }
 }
 
+/**
+ * V2c.4 — Map a canonical `AnchorGeometry` onto the surface anchor type.
+ * Returns `undefined` when the anchor carries only the trivial inline
+ * defaults (no positioning / wrap / dist data) so the emitted segment
+ * stays minimal for the common inline-image case.
+ */
+function surfaceAnchorFromGeometry(
+  anchor: DrawingFrameNode["anchor"],
+): SurfaceDrawingAnchor | undefined {
+  // Cheap inline-default short-circuit: inline pictures with no extra
+  // metadata (no positionH/V, no distMargins, no docPr, no behindDoc/etc.)
+  // don't need the anchor bag — N9 float-wrap consumers only care about
+  // floating drawings or anchors with custom positioning.
+  const trivialInline =
+    anchor.display === "inline" &&
+    anchor.wrapMode === "none" &&
+    !anchor.positionH &&
+    !anchor.positionV &&
+    !anchor.distMargins &&
+    anchor.relativeHeight === undefined &&
+    anchor.behindDoc === undefined &&
+    anchor.layoutInCell === undefined &&
+    anchor.allowOverlap === undefined &&
+    anchor.simplePos === undefined &&
+    !anchor.docPr;
+  if (trivialInline) return undefined;
+  return {
+    display: anchor.display,
+    wrapMode: anchor.wrapMode,
+    extent: { ...anchor.extent },
+    ...(anchor.positionH ? { positionH: { ...anchor.positionH } } : {}),
+    ...(anchor.positionV ? { positionV: { ...anchor.positionV } } : {}),
+    ...(anchor.distMargins ? { distMargins: { ...anchor.distMargins } } : {}),
+    ...(anchor.relativeHeight !== undefined ? { relativeHeight: anchor.relativeHeight } : {}),
+    ...(anchor.behindDoc !== undefined ? { behindDoc: anchor.behindDoc } : {}),
+    ...(anchor.layoutInCell !== undefined ? { layoutInCell: anchor.layoutInCell } : {}),
+    ...(anchor.allowOverlap !== undefined ? { allowOverlap: anchor.allowOverlap } : {}),
+    ...(anchor.simplePos !== undefined ? { simplePos: anchor.simplePos } : {}),
+    ...(anchor.docPr ? { docPr: { ...anchor.docPr } } : {}),
+  };
+}
+
+/**
+ * V2c.4 — Project picture-effect fields from `PictureContent`.  Returns
+ * `undefined` when none of the effect fields are set so consumers can
+ * fast-path image rendering.
+ */
+function surfacePictureEffectsFromContent(
+  content: PictureContent,
+): SurfacePictureEffects | undefined {
+  const has =
+    content.srcRect !== undefined ||
+    content.rotation !== undefined ||
+    content.flipH !== undefined ||
+    content.flipV !== undefined ||
+    content.presetGeom !== undefined ||
+    content.stretch !== undefined ||
+    content.softEdgeRadius !== undefined ||
+    content.outerShadow !== undefined ||
+    content.glow !== undefined;
+  if (!has) return undefined;
+  return {
+    ...(content.srcRect ? { srcRect: { ...content.srcRect } } : {}),
+    ...(content.rotation !== undefined ? { rotation: content.rotation } : {}),
+    ...(content.flipH !== undefined ? { flipH: content.flipH } : {}),
+    ...(content.flipV !== undefined ? { flipV: content.flipV } : {}),
+    ...(content.presetGeom !== undefined ? { presetGeom: content.presetGeom } : {}),
+    ...(content.stretch !== undefined ? { stretch: content.stretch } : {}),
+    ...(content.softEdgeRadius !== undefined ? { softEdgeRadius: content.softEdgeRadius } : {}),
+    ...(content.outerShadow !== undefined ? { outerShadow: { ...content.outerShadow } } : {}),
+    ...(content.glow !== undefined ? { glow: { ...content.glow } } : {}),
+  };
+}
+
+/**
+ * V2c.5 — Extract the first paragraph's plain text from a parsed
+ * `txbxBlocks` tree for the `txbxText` segment preview.  The recursion
+ * is shallow — we only walk paragraph-shaped blocks at the top level
+ * and read the immediate run content.  Returns `undefined` when no text
+ * is present.
+ */
+function extractTxbxFirstText(
+  blocks: ShapeContent["txbxBlocks"],
+): string | undefined {
+  if (!blocks || blocks.length === 0) return undefined;
+  for (const block of blocks) {
+    if (block.type !== "paragraph") continue;
+    const runs = (block as { runs?: ReadonlyArray<{ text?: string }> }).runs;
+    if (!runs) continue;
+    const text = runs.map((r) => r.text ?? "").join("").trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
 function appendComplexPreviewSegment(
   paragraph: ParagraphAccumulator,
   node: { rawXml: string },
@@ -1616,6 +1794,8 @@ function summarizePreviewInline(node: InlineNode): string {
       return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
     case "vml_shape":
       return node.text ? `[VML: ${node.text}]` : "[Legacy VML drawing]";
+    case "drawing_frame":
+      return node.content.type === "picture" ? "[Image]" : "[Drawing]";
   }
 }