@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/core/state/text-transaction.ts

@@ -3,7 +3,9 @@ import type { TransactionMapping } from "../selection/mapping.ts";
 import {
   cloneParagraphProperties,
   cloneStoryUnit,
+  countLogicalPositions,
   createPlainText,
+  logicalPositionToUnitIndex,
   parseTextStory,
   serializeTextStory,
   type ParagraphProperties,
@@ -11,7 +13,8 @@ import {
   type TextStory,
 } from "../schema/text-schema.ts";
 import { createEditorSurfaceSnapshot } from "../../runtime/surface-projection.ts";
-import type { DocumentRootNode, ParagraphNode, SdtNode, TableNode } from "../../model/canonical-document.ts";
+import type { DocumentRootNode, ParagraphNode, SdtNode, TableNode, TextMark } from "../../model/canonical-document.ts";
+import type { TextFormattingDirective } from "../../api/public-types.ts";
 
 export type TextInsertion =
   | {
@@ -36,6 +39,13 @@ export type TextTransactionIntent =
         to: number;
       };
       insertion: TextInsertion[];
+      /**
+       * I7 — optional formatting directive governing which `marks` the inserted text
+       * units carry. Resolved against `story` + `normalizedRange` inside
+       * `applyLinearTextTransaction`. `undefined` (or `{ mode: "paragraph-default" }`)
+       * preserves pre-I7 behavior (no inherited run marks).
+       */
+      formatting?: TextFormattingDirective;
     }
   | {
       type: "delete_backward";
@@ -115,14 +125,21 @@ function applyLinearTextTransaction(
 ): TextTransactionResult {
   const story = parseTextStory(document.content);
   const normalizedRange = resolveRange(selection, story.size, intent);
-  const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from);
+  const resolvedMarks = resolveMarksForInsertion(intent, story, normalizedRange);
+  const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from, resolvedMarks);
 
-  ensureEditableRange(story.units.slice(normalizedRange.from, normalizedRange.to));
+  // `normalizedRange.{from,to}` are logical positions (scope markers = 0 width,
+  // matching surface-projection). Translate to unit-array indices so scope
+  // marker units preserved at the boundary stay intact on either side.
+  const unitFrom = logicalPositionToUnitIndex(story.units, normalizedRange.from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, normalizedRange.to, "after");
+
+  ensureEditableRange(story.units.slice(unitFrom, unitTo));
 
   const nextUnits = [
-    ...story.units.slice(0, normalizedRange.from).map(cloneStoryUnit),
+    ...story.units.slice(0, unitFrom).map(cloneStoryUnit),
     ...insertionUnits.map(cloneStoryUnit),
-    ...story.units.slice(normalizedRange.to).map(cloneStoryUnit),
+    ...story.units.slice(unitTo).map(cloneStoryUnit),
   ];
 
   const nextStory: TextStory = {
@@ -130,9 +147,13 @@ function applyLinearTextTransaction(
     units: normalizeStoryUnits(nextUnits),
     size: 0,
   };
-  nextStory.size = nextStory.units.length;
+  nextStory.size = countLogicalPositions(nextStory.units);
 
-  const caret = normalizedRange.from + insertionUnits.length;
+  // `normalizedRange.from` is the logical insertion point; count the logical
+  // positions added by `insertionUnits` (skipping any scope markers) to derive
+  // the post-insert caret.
+  const logicalInsertionSize = countLogicalPositions(insertionUnits);
+  const caret = normalizedRange.from + logicalInsertionSize;
 
   return {
     document: {
@@ -767,6 +788,7 @@ function createInsertionUnits(
   intent: TextTransactionIntent,
   story: TextStory,
   position: number,
+  marks: TextMark[] | undefined,
 ): StoryUnit[] {
   if (intent.type !== "replace") {
     return [];
@@ -780,6 +802,7 @@ function createInsertionUnits(
         return Array.from(entry.text).map<StoryUnit>((character) => ({
           kind: "text",
           value: character,
+          ...(marks && marks.length > 0 ? { marks: marks.map((mark) => ({ ...mark })) } : {}),
         }));
       case "tab":
         return [{ kind: "tab" }];
@@ -796,6 +819,79 @@ function createInsertionUnits(
   });
 }
 
+/**
+ * I7 — given a formatting directive, produce the `marks` array that inserted text
+ * units should carry. Returns `undefined` for the paragraph-default path (no marks).
+ *
+ * - `paragraph-default` / no directive → `undefined`.
+ * - `explicit` → caller-supplied marks verbatim.
+ * - `match-replaced-range`:
+ *   - If the range is collapsed, use the marks of the text unit immediately left of
+ *     the caret (Word-matching behavior for empty-range inserts).
+ *   - Otherwise walk text units in `[from, to)`. If every text unit shares the same
+ *     marks (by type), use them. Mixed → fall back to paragraph-default (`undefined`).
+ */
+function resolveMarksForInsertion(
+  intent: TextTransactionIntent,
+  story: TextStory,
+  range: { from: number; to: number },
+): TextMark[] | undefined {
+  if (intent.type !== "replace") {
+    return undefined;
+  }
+  const directive = intent.formatting;
+  if (!directive || directive.mode === "paragraph-default") {
+    return undefined;
+  }
+  if (directive.mode === "explicit") {
+    return directive.marks.map((mark) => ({ ...mark }));
+  }
+
+  // match-replaced-range
+  const unitFrom = logicalPositionToUnitIndex(story.units, range.from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, range.to, "after");
+
+  if (range.from === range.to) {
+    // Empty range — inherit from the text unit immediately left of the caret.
+    for (let i = unitFrom - 1; i >= 0; i -= 1) {
+      const unit = story.units[i];
+      if (unit?.kind === "text") {
+        return unit.marks ? unit.marks.map((mark) => ({ ...mark })) : undefined;
+      }
+      if (unit?.kind === "paragraph_break") {
+        break;
+      }
+    }
+    return undefined;
+  }
+
+  const textUnits: Array<{ marks?: TextMark[] }> = [];
+  for (let i = unitFrom; i < unitTo; i += 1) {
+    const unit = story.units[i];
+    if (unit?.kind === "text") {
+      textUnits.push(unit);
+    }
+  }
+  if (textUnits.length === 0) {
+    return undefined;
+  }
+  const firstMarks = textUnits[0].marks;
+  const uniform = textUnits.every((unit) => marksAreEqual(firstMarks, unit.marks));
+  if (!uniform) {
+    return undefined;
+  }
+  return firstMarks ? firstMarks.map((mark) => ({ ...mark })) : undefined;
+}
+
+function marksAreEqual(left: TextMark[] | undefined, right: TextMark[] | undefined): boolean {
+  if (!left && !right) return true;
+  if (!left || !right) return false;
+  if (left.length !== right.length) return false;
+  const sortedLeft = [...left].map((mark) => mark.type).sort();
+  const sortedRight = [...right].map((mark) => mark.type).sort();
+  return sortedLeft.every((type, index) => type === sortedRight[index]);
+}
+
 function resolveParagraphPropertiesAtPosition(
   story: TextStory,
   position: number,

package/src/internal/harness-debug-ports.ts

@@ -0,0 +1,168 @@
+/**
+ * @internal HARNESS-ONLY debug-ports token module.
+ *
+ * This module is **not listed in `package.json#exports`**, so
+ * downstream consumers of `@beyondwork/docx-react-component` cannot
+ * import it via any public entry point. The in-repo harness at
+ * `services/react-word-editor/` reaches it via a relative path
+ * (`../../../src/internal/harness-debug-ports`); that is the only
+ * supported caller.
+ *
+ * ## Why this exists
+ *
+ * It replaces the former public `showUnsupportedObjectPreviews?: boolean`
+ * prop on `WordReviewEditorProps`, which regressed to `true` three
+ * times through merges (PRs #124, #131, #160). Each regression leaked
+ * preserve-only preview chrome (charts, SmartArt, shapes, WordArt,
+ * VML, "N preserve-only features detected" banner, lock-callouts)
+ * into consumer applications.
+ *
+ * ## What the new shape buys us
+ *
+ * 1. **Type-level**: the `HarnessDebugPorts` brand uses a `unique
+ *    symbol` key that cannot be obtained outside this file, so
+ *    downstream TypeScript consumers cannot structurally construct a
+ *    valid token.
+ * 2. **Module-level**: this file is not in the package's export map.
+ *    External consumers would have to reach into the installed
+ *    package's internals via a non-guaranteed path to find it.
+ * 3. **Runtime gate**: even if a caller does manage to invoke
+ *    `__createHarnessDebugPorts`, the factory checks for a harness
+ *    environment marker (`globalThis.__DOCX_REACT_COMPONENT_HARNESS__`)
+ *    that only the harness sets via `__markHarnessEnvironment()`.
+ *    In a consumer app the flag is false; the returned token's
+ *    permissions are all `false` regardless of input.
+ * 4. **Intent assertion**: the factory input requires a literal
+ *    `confirmHarnessAuthor: "I-am-the-harness-dev-drawer"` string as
+ *    a self-documenting "I know what I'm doing" gate.
+ *
+ * Flipping any of (1)–(4) is the regression this module is designed
+ * to prevent. The invariant test at
+ * `test/ui/unsupported-previews-invariant.test.ts` locks them all.
+ */
+
+// NOT exported. The symbol's identity is what makes the brand
+// unobtainable from outside this module: `typeof` on a const symbol
+// gives TypeScript a `unique symbol` type that's only satisfiable
+// by the same `const` binding. Consumers that don't import this
+// module cannot satisfy the `[harnessDebugPortsBrand]: true` field.
+const harnessDebugPortsBrand = Symbol("harnessDebugPortsBrand");
+
+/**
+ * Opaque, brand-typed token passed through the internal
+ * `__harnessDebugPorts` editor prop. Cannot be constructed
+ * structurally — the brand key is a module-local `unique symbol`.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export interface HarnessDebugPorts {
+  readonly [harnessDebugPortsBrand]: true;
+  /**
+   * Sanitized. Only `true` when the token factory confirmed
+   * harness-env + debug-mode + literal author assertion.
+   */
+  readonly unsupportedObjectPreviews: boolean;
+}
+
+const HARNESS_GLOBAL_KEY = "__DOCX_REACT_COMPONENT_HARNESS__" as const;
+
+/**
+ * Input to the harness-debug-ports token factory.
+ *
+ * @internal
+ */
+export interface HarnessDebugPortsInput {
+  /**
+   * Self-documenting author gate. Must be the literal string
+   * `"I-am-the-harness-dev-drawer"`. Any other value fails the
+   * runtime check and the token's flags are all `false`.
+   */
+  readonly confirmHarnessAuthor: "I-am-the-harness-dev-drawer";
+  /**
+   * Harness dev-drawer debug-mode toggle. Even if `true`, the factory
+   * refuses to honor the request unless the harness environment is
+   * active (`__markHarnessEnvironment()` was called).
+   */
+  readonly debugMode: boolean;
+  /**
+   * Requested preview-rendering permission. Honored only when all
+   * runtime checks pass.
+   */
+  readonly unsupportedObjectPreviews: boolean;
+}
+
+/**
+ * Build a harness-debug-ports token.
+ *
+ * Runtime gate: the returned token's `unsupportedObjectPreviews`
+ * field is `true` **only** when all of the following hold:
+ *
+ *   - `__markHarnessEnvironment()` was called previously (sets the
+ *     `__DOCX_REACT_COMPONENT_HARNESS__` global to `true`);
+ *   - `input.confirmHarnessAuthor === "I-am-the-harness-dev-drawer"`;
+ *   - `input.debugMode === true`;
+ *   - `input.unsupportedObjectPreviews === true`.
+ *
+ * Any check failure produces a fully-disabled token (same brand, all
+ * flags `false`). The editor component reads the token's flag
+ * through `readHarnessDebugPortsFlag()` so downstream rendering code
+ * sees a plain `boolean`.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export function __createHarnessDebugPorts(
+  input: HarnessDebugPortsInput,
+): HarnessDebugPorts {
+  const harnessActive =
+    typeof globalThis !== "undefined" &&
+    (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY] === true;
+  const authorConfirmed =
+    input.confirmHarnessAuthor === "I-am-the-harness-dev-drawer";
+  const allow =
+    harnessActive && authorConfirmed && input.debugMode === true;
+  return Object.freeze({
+    [harnessDebugPortsBrand]: true as const,
+    unsupportedObjectPreviews:
+      allow && input.unsupportedObjectPreviews === true,
+  });
+}
+
+/**
+ * Mark the current JavaScript realm as a harness. MUST be called
+ * once, synchronously, before the first editor render so the token
+ * factory can confirm the environment.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export function __markHarnessEnvironment(): void {
+  if (typeof globalThis !== "undefined") {
+    (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY] = true;
+  }
+}
+
+/**
+ * Read a sanitized flag from a token. Always returns `false` for
+ * `undefined` tokens (consumer code paths).
+ *
+ * @internal
+ */
+export function readHarnessDebugPortsFlag(
+  token: HarnessDebugPorts | undefined,
+  flag: "unsupportedObjectPreviews",
+): boolean {
+  if (!token) return false;
+  return token[flag] === true;
+}
+
+/**
+ * Test-only: reset the harness environment flag. Exported so the
+ * invariant/factory tests can assert the "consumer app" path
+ * (factory called without `__markHarnessEnvironment`).
+ *
+ * @internal TEST-ONLY.
+ */
+export function __resetHarnessEnvironmentForTests(): void {
+  if (typeof globalThis !== "undefined") {
+    delete (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY];
+  }
+}

package/src/io/chart-preview-resolver.ts

@@ -24,6 +24,7 @@ import type {
   InlineNode,
   MediaItem,
   ParagraphNode,
+  ResolvedTheme,
 } from "../model/canonical-document.ts";
 import type {
   ChartPreviewResolveParams,
@@ -31,11 +32,34 @@ import type {
 } from "../api/public-types.ts";
 import type { OpcPackage } from "./opc/package-reader.ts";
 import { normalizePartPath, resolveRelationshipTarget } from "./ooxml/part-manifest.ts";
+import { parseThemeXml, resolveTheme } from "./ooxml/parse-theme.ts";
+
+/**
+ * Parse and resolve the workbook theme once, tolerating malformed XML.
+ * An unparseable theme must NOT abort the import — fall back to
+ * undefined so downstream renderers use the fallback palette.
+ */
+function tryParseTheme(themeXml: string): ResolvedTheme | undefined {
+  try {
+    return resolveTheme(parseThemeXml(themeXml));
+  } catch {
+    return undefined;
+  }
+}
 
 interface ResolveContext {
   readonly package: OpcPackage;
   readonly adapter: EditorHostAdapter;
   readonly themeXml: string | undefined;
+  /**
+   * Once-per-import cache of the workbook theme. Stage 2 wiring:
+   * in-tree renderers consume `parsedTheme` via
+   * `composeSeriesColor(model, parsedTheme, seriesIdx)` to resolve a
+   * series palette entry into a concrete sRGB string without re-parsing
+   * theme XML on every render. Undefined when the document has no
+   * theme1.xml or when parseThemeXml threw.
+   */
+  readonly parsedTheme: ResolvedTheme | undefined;
   /** Monotonic counter so we can generate unique media ids across one run. */
   seq: number;
 }
@@ -63,8 +87,15 @@ export async function resolveChartPreviewsForDocument(
   if (pending.length === 0) return doc;
 
   const themeXml = extractPartTextFromPackage(pkg, "/word/theme/theme1.xml");
+  const parsedTheme = themeXml ? tryParseTheme(themeXml) : undefined;
   const renderer = adapter.renderChartPreview;
-  const ctx: ResolveContext = { package: pkg, adapter, themeXml, seq: 0 };
+  const ctx: ResolveContext = {
+    package: pkg,
+    adapter,
+    themeXml,
+    parsedTheme,
+    seq: 0,
+  };
 
   const resolutions = await Promise.all(
     pending.map(async (entry) => {
@@ -214,6 +245,33 @@ function extractPartTextFromPackage(pkg: OpcPackage, path: string): string | und
   }
 }
 
+/**
+ * Build a chart-part lookup callback suitable for
+ * `parseMainDocumentXml(..., chartPartLookup)`.
+ *
+ * The callback is called synchronously during parsing with a chart
+ * relationship id (the `r:id` on a `<c:chart>` reference). It resolves
+ * the id to a chart-part target path via the document's relationship
+ * table, then decodes the matching package part's bytes as UTF-8. Unknown
+ * ids and missing parts return undefined, in which case the parser
+ * proceeds without a typed `ChartModel` (the drawing still produces a
+ * `ChartPreviewNode` with `rawXml`).
+ */
+export function createChartPartLookup(
+  pkg: OpcPackage,
+  documentPartPath: string,
+  documentRelationships: readonly import("./ooxml/part-manifest.ts").OpcRelationship[],
+): (rId: string) => string | undefined {
+  const relById = new Map(documentRelationships.map((r) => [r.id, r]));
+  return (rId: string): string | undefined => {
+    const rel = relById.get(rId);
+    if (!rel) return undefined;
+    const target = resolveRelationshipTarget(documentPartPath, rel);
+    if (!target) return undefined;
+    return extractPartTextFromPackage(pkg, normalizePartPath(target));
+  };
+}
+
 /**
  * Produce a new CanonicalDocument with the resolved chart_preview
  * nodes carrying previewMediaId + corresponding MediaCatalog entries.