@beyondwork/docx-react-component 1.0.54 → 1.0.55

package/src/runtime/chart/chart-snapshot.ts

@@ -0,0 +1,239 @@
+/**
+ * Public read-model for chart data. Projected from a `ChartModel` parsed during
+ * DOCX import. Agents consume this without re-parsing `rawXml`.
+ */
+
+import type {
+  ChartModel,
+  BarChartModel,
+  LineChartModel,
+  PieChartModel,
+  AreaChartModel,
+  ScatterChartModel,
+  BubbleChartModel,
+  ComboChartModel,
+} from "../../io/ooxml/chart/types.ts";
+
+export interface ChartSnapshot {
+  chartId: string;
+  kind: ChartModel["kind"];
+  title?: string;
+  seriesCount: number;
+  categoryCount: number;
+  data: ChartSnapshotData;
+}
+
+export type ChartSnapshotData =
+  | {
+      kind: "bar";
+      direction: "bar" | "column";
+      grouping: "clustered" | "stacked" | "percentStacked" | "standard";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "line";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "pie";
+      doughnut: boolean;
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "area";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | { kind: "scatter"; series: ChartSnapshotScatterSeries[] }
+  | { kind: "bubble"; series: ChartSnapshotBubbleSeries[] }
+  | {
+      kind: "combo";
+      groups: Array<{ kind: "bar" | "line" | "area"; series: ChartSnapshotSeries[] }>;
+      categories: string[];
+    }
+  | { kind: "unsupported"; reason: string };
+
+export interface ChartSnapshotSeries {
+  name?: string;
+  values: Array<number | null>;
+}
+
+export interface ChartSnapshotScatterSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+}
+
+export interface ChartSnapshotBubbleSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  sizes: Array<number | null>;
+}
+
+export function projectChartSnapshot(chartId: string, model: ChartModel): ChartSnapshot {
+  switch (model.kind) {
+    case "bar": {
+      const m = model as BarChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "bar",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "bar",
+          direction: m.direction,
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "line": {
+      const m = model as LineChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "line",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "line",
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "pie": {
+      const m = model as PieChartModel;
+      return {
+        chartId,
+        kind: "pie",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: m.categoryLabels.length,
+        data: {
+          kind: "pie",
+          doughnut: m.doughnut,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories: m.categoryLabels,
+        },
+      };
+    }
+    case "area": {
+      const m = model as AreaChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "area",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "area",
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "scatter": {
+      const m = model as ScatterChartModel;
+      return {
+        chartId,
+        kind: "scatter",
+        seriesCount: m.series.length,
+        categoryCount: 0,
+        data: {
+          kind: "scatter",
+          series: m.series.map((s) => ({
+            name: s.name,
+            xValues: s.xValues,
+            yValues: s.yValues,
+          })),
+        },
+      };
+    }
+    case "bubble": {
+      const m = model as BubbleChartModel;
+      return {
+        chartId,
+        kind: "bubble",
+        seriesCount: m.series.length,
+        categoryCount: 0,
+        data: {
+          kind: "bubble",
+          series: m.series.map((s) => ({
+            name: s.name,
+            xValues: s.xValues,
+            yValues: s.yValues,
+            sizes: s.sizes,
+          })),
+        },
+      };
+    }
+    case "combo": {
+      const m = model as ComboChartModel;
+      const firstGroup = m.groups[0];
+      const categories =
+        firstGroup && "categoryAxis" in firstGroup &&
+        firstGroup.categoryAxis?.kind === "category"
+          ? firstGroup.categoryAxis.categoryLabels
+          : [];
+      return {
+        chartId,
+        kind: "combo",
+        title: m.title?.text,
+        seriesCount: m.groups.reduce((acc, g) => acc + g.series.length, 0),
+        categoryCount: categories.length,
+        data: {
+          kind: "combo",
+          groups: m.groups.map((g) => ({
+            kind: g.kind as "bar" | "line" | "area",
+            series: "series" in g
+              ? g.series.map((s) => ({
+                  name: s.name,
+                  values: "values" in s ? s.values : [],
+                }))
+              : [],
+          })),
+          categories,
+        },
+      };
+    }
+    case "unsupported": {
+      return {
+        chartId,
+        kind: "unsupported",
+        seriesCount: 0,
+        categoryCount: 0,
+        data: { kind: "unsupported", reason: model.detail },
+      };
+    }
+    default: {
+      const _exhaustive: never = model;
+      return {
+        chartId,
+        kind: (_exhaustive as ChartModel).kind,
+        seriesCount: 0,
+        categoryCount: 0,
+        data: { kind: "unsupported", reason: "unknown chart kind" },
+      };
+    }
+  }
+}

package/src/runtime/document-runtime.ts

@@ -160,7 +160,6 @@ import {
   createDocumentSectionSnapshots,
   createSectionLocations,
   createTocSnapshot,
-  findBookmarkNameForOffset,
   findDocumentSectionSnapshot,
 } from "./document-outline.ts";
 import {
@@ -210,7 +209,6 @@ import type {
   BlockNode,
   FieldNode,
   FieldRefreshStatus,
-  HyperlinkNode,
   InlineNode,
   PageMargins,
   ParagraphNode,
@@ -244,6 +242,7 @@ import type {
 import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
 import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
+import { formatPageNumber } from "./page-number-format.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
  *  editorState payload from the runtime to the docx serializer. */
@@ -5198,6 +5197,32 @@ function refreshDocumentTableOfContents(
   protectionSelection?: import("../core/state/editor-state.ts").SelectionSnapshot;
 } {
   const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
+  // Build a single O(N) map from paragraph offset → bookmark name so the
+  // per-heading lookup below is O(1) instead of O(N) per heading.
+  const bookmarkNameByOffset = new Map<number, string>();
+  {
+    let runningOffset = 0;
+    for (const block of document.content.children) {
+      if (block.type !== "paragraph") {
+        continue;
+      }
+      const paragraphStart = runningOffset;
+      for (const child of block.children) {
+        if (child.type === "text") {
+          runningOffset += child.text.length;
+        } else if (child.type === "tab" || child.type === "hard_break") {
+          runningOffset += 1;
+        }
+      }
+      const bookmarkStart = block.children.find(
+        (child): child is Extract<typeof child, { type: "bookmark_start" }> =>
+          child.type === "bookmark_start" && Boolean(child.name),
+      );
+      if (bookmarkStart?.name) {
+        bookmarkNameByOffset.set(paragraphStart, bookmarkStart.name);
+      }
+    }
+  }
   let changed = false;
   let resultEntries: Array<{ level: number; text: string; pageIndex: number; bookmarkName?: string }> = [];
   let changedFrom: number | undefined;
@@ -5212,7 +5237,7 @@ function refreshDocumentTableOfContents(
     const entries = navigation.headings
       .filter((heading) => heading.level >= levelRange.from && heading.level <= levelRange.to)
       .map((heading) => {
-        const bookmarkName = findBookmarkNameForOffset(document, heading.offset);
+        const bookmarkName = bookmarkNameByOffset.get(heading.offset);
         return {
           level: heading.level,
           text: heading.text,
@@ -5426,7 +5451,7 @@ function buildTocInlineNodes(
         type: "hyperlink",
         href: `#${entry.bookmarkName}`,
         children: [{ type: "text", text: entry.text }],
-      } as HyperlinkNode);
+      });
     } else {
       children.push({ type: "text", text: entry.text });
     }
@@ -5485,6 +5510,38 @@ function collectFieldsFromSubParts(
   return nextIndex;
 }
 
+function resolveStyleRefFieldText(
+  styleQuery: string,
+  paragraphs: readonly ParagraphContext[],
+  styles: CanonicalDocumentEnvelope["styles"],
+): { text: string; refreshStatus: FieldRefreshStatus } {
+  const normalized = styleQuery.trim().toLowerCase();
+
+  // Look up styleId: first by direct id match, then by displayName
+  const styleId = (() => {
+    const byId = Object.keys(styles.paragraphs).find(
+      (id) => id.toLowerCase() === normalized,
+    );
+    if (byId) return byId;
+    const byName = Object.values(styles.paragraphs).find(
+      (s) => s.displayName?.toLowerCase() === normalized,
+    );
+    return byName?.styleId;
+  })();
+
+  if (!styleId) return { text: "", refreshStatus: "unresolvable" };
+
+  // Walk paragraphs top-down for the first matching styleId
+  for (const ctx of paragraphs) {
+    if (ctx.paragraph.styleId === styleId) {
+      const text = flattenInlineDisplayText(ctx.paragraph.children);
+      if (text.trim()) return { text: text.trim(), refreshStatus: "current" };
+    }
+  }
+
+  return { text: "", refreshStatus: "unresolvable" };
+}
+
 function resolveSupportedFieldDisplay(
   field: FieldNode,
   document: CanonicalDocumentEnvelope,
@@ -5499,13 +5556,30 @@ function resolveSupportedFieldDisplay(
   if (field.fieldFamily === "TOC") {
     return undefined;
   }
+  if (field.fieldFamily === "STYLEREF") {
+    if (!field.fieldTarget) return { displayText: "", refreshStatus: "unresolvable" };
+    const result = resolveStyleRefFieldText(field.fieldTarget, paragraphs, document.styles);
+    return { displayText: result.text, refreshStatus: result.refreshStatus };
+  }
+  if (field.fieldFamily === "SECTIONPAGES") {
+    const sectionIndex = "sectionIndex" in storyTarget && typeof storyTarget.sectionIndex === "number"
+      ? storyTarget.sectionIndex
+      : navigation.activeSectionIndex;
+    const sectionPages = navigation.pages.filter((p) => p.sectionIndex === sectionIndex);
+    if (sectionPages.length === 0) return { displayText: "", refreshStatus: "unresolvable" };
+    const fmt = sectionPages[0]?.layout.pageNumbering?.format;
+    return {
+      displayText: formatPageNumber(sectionPages.length, fmt),
+      refreshStatus: "current",
+    };
+  }
   if (field.fieldFamily === "PAGE") {
     const page = resolveRepresentativePageForStory(navigation, storyTarget);
     if (!page) {
       return { displayText: "", refreshStatus: "unresolvable" };
     }
     return {
-      displayText: String(resolveDisplayedPageNumber(page)),
+      displayText: resolveDisplayedPageNumber(page),
       refreshStatus: "current",
     };
   }
@@ -5536,10 +5610,23 @@ function resolveSupportedFieldDisplay(
     if (!paragraph) {
       return { displayText: "", refreshStatus: "unresolvable" };
     }
+
+    // \p switch: emit relative position text ("above" / "below" / "on this page")
+    if (field.switches?.relativePosition === true) {
+      const fieldPage = resolveRepresentativePageForStory(navigation, storyTarget);
+      const targetPageIndex = findPageForOffset(navigation.pages, paragraph.startOffset);
+      const fieldPageIndex = fieldPage
+        ? navigation.pages.indexOf(fieldPage)
+        : navigation.activePageIndex;
+      if (targetPageIndex < fieldPageIndex) return { displayText: "above", refreshStatus: "current" };
+      if (targetPageIndex > fieldPageIndex) return { displayText: "below", refreshStatus: "current" };
+      return { displayText: "on this page", refreshStatus: "current" };
+    }
+
     const pageIndex = findPageForOffset(navigation.pages, paragraph.startOffset);
     const page = navigation.pages[pageIndex] ?? navigation.pages[0];
     return page
-      ? { displayText: String(resolveDisplayedPageNumber(page)), refreshStatus: "current" }
+      ? { displayText: resolveDisplayedPageNumber(page), refreshStatus: "current" }
       : { displayText: "", refreshStatus: "unresolvable" };
   }
   if (field.fieldFamily === "NOTEREF") {
@@ -5598,8 +5685,9 @@ function isDefaultHeaderFooterPage(
 
 function resolveDisplayedPageNumber(
   page: DocumentNavigationSnapshot["pages"][number],
-): number {
-  return (page.layout.pageNumbering?.start ?? 1) + page.pageInSection;
+): string {
+  const n = (page.layout.pageNumbering?.start ?? 1) + page.pageInSection;
+  return formatPageNumber(n, page.layout.pageNumbering?.format);
 }
 
 interface ParagraphContext {

package/src/runtime/page-number-format.ts

@@ -0,0 +1,207 @@
+/**
+ * OOXML page number format codes (ECMA-376 §17.18.59).
+ *
+ * This module is intentionally dependency-free so it can be unit-tested
+ * without any runtime or model imports.
+ */
+
+const ROMAN_PAIRS: [number, string][] = [
+  [1000, "M"],
+  [900, "CM"],
+  [500, "D"],
+  [400, "CD"],
+  [100, "C"],
+  [90, "XC"],
+  [50, "L"],
+  [40, "XL"],
+  [10, "X"],
+  [9, "IX"],
+  [5, "V"],
+  [4, "IV"],
+  [1, "I"],
+];
+
+function toRoman(n: number): string {
+  if (n <= 0 || n >= 4000) {
+    return String(n);
+  }
+  let result = "";
+  let remainder = n;
+  for (const [value, numeral] of ROMAN_PAIRS) {
+    while (remainder >= value) {
+      result += numeral;
+      remainder -= value;
+    }
+  }
+  return result;
+}
+
+function toAlphabetic(n: number): string {
+  if (n <= 0) {
+    return String(n);
+  }
+  let result = "";
+  let remainder = n;
+  while (remainder > 0) {
+    remainder -= 1;
+    result = String.fromCharCode(65 + (remainder % 26)) + result;
+    remainder = Math.floor(remainder / 26);
+  }
+  return result;
+}
+
+function toOrdinal(n: number): string {
+  const abs = Math.abs(n);
+  const mod100 = abs % 100;
+  const mod10 = abs % 10;
+  if (mod100 >= 11 && mod100 <= 13) {
+    return `${n}th`;
+  }
+  if (mod10 === 1) return `${n}st`;
+  if (mod10 === 2) return `${n}nd`;
+  if (mod10 === 3) return `${n}rd`;
+  return `${n}th`;
+}
+
+const ONES = [
+  "",
+  "one",
+  "two",
+  "three",
+  "four",
+  "five",
+  "six",
+  "seven",
+  "eight",
+  "nine",
+  "ten",
+  "eleven",
+  "twelve",
+  "thirteen",
+  "fourteen",
+  "fifteen",
+  "sixteen",
+  "seventeen",
+  "eighteen",
+  "nineteen",
+];
+
+const TENS = [
+  "",
+  "",
+  "twenty",
+  "thirty",
+  "forty",
+  "fifty",
+  "sixty",
+  "seventy",
+  "eighty",
+  "ninety",
+];
+
+function toCardinalText(n: number): string {
+  if (n <= 0 || n >= 100) {
+    return String(n);
+  }
+  if (n < 20) {
+    return ONES[n]!;
+  }
+  const tensWord = TENS[Math.floor(n / 10)]!;
+  const onesDigit = n % 10;
+  if (onesDigit === 0) {
+    return tensWord;
+  }
+  return `${tensWord}-${ONES[onesDigit]}`;
+}
+
+const ORDINAL_IRREGULARS: Record<string, string> = {
+  one: "first",
+  two: "second",
+  three: "third",
+  four: "fourth",
+  five: "fifth",
+  six: "sixth",
+  seven: "seventh",
+  eight: "eighth",
+  nine: "ninth",
+  ten: "tenth",
+  eleven: "eleventh",
+  twelve: "twelfth",
+  thirteen: "thirteenth",
+  fifteen: "fifteenth",
+  twenty: "twentieth",
+  thirty: "thirtieth",
+  forty: "fortieth",
+  fifty: "fiftieth",
+  sixty: "sixtieth",
+  seventy: "seventieth",
+  eighty: "eightieth",
+  ninety: "ninetieth",
+};
+
+function toOrdinalText(n: number): string {
+  if (n <= 0 || n >= 100) {
+    return `${n}th`;
+  }
+  const cardinal = toCardinalText(n);
+  // Check if it's a hyphenated compound like "twenty-one"
+  const hyphenIdx = cardinal.lastIndexOf("-");
+  if (hyphenIdx !== -1) {
+    const prefix = cardinal.slice(0, hyphenIdx + 1);
+    const suffix = cardinal.slice(hyphenIdx + 1);
+    const ordinalSuffix = ORDINAL_IRREGULARS[suffix] ?? `${suffix}th`;
+    return `${prefix}${ordinalSuffix}`;
+  }
+  return ORDINAL_IRREGULARS[cardinal] ?? `${cardinal}th`;
+}
+
+const CHICAGO_SYMBOLS = ["*", "†", "‡", "§", "‖", "¶"];
+
+function toChicago(n: number): string {
+  if (n <= 0) {
+    return String(n);
+  }
+  const symbolCount = CHICAGO_SYMBOLS.length;
+  // Which cycle: 1-6 → repeat 1×, 7-12 → repeat 2×, etc.
+  const cycleIndex = Math.ceil(n / symbolCount) - 1; // 0-based repeat count
+  const symbolIndex = ((n - 1) % symbolCount);
+  const symbol = CHICAGO_SYMBOLS[symbolIndex]!;
+  return symbol.repeat(cycleIndex + 1);
+}
+
+/**
+ * Format a page number integer using an OOXML ST_NumberFormat code.
+ *
+ * @param n - The raw page number (1-based within section).
+ * @param format - The OOXML format code from `<w:pgNumType w:fmt="…"/>`.
+ * @returns Formatted string for display.
+ */
+export function formatPageNumber(n: number, format: string | undefined): string {
+  switch (format) {
+    case undefined:
+    case "decimal":
+      return String(n);
+    case "upperRoman":
+      return toRoman(n);
+    case "lowerRoman":
+      return toRoman(n).toLowerCase();
+    case "upperLetter":
+      return toAlphabetic(n);
+    case "lowerLetter":
+      return toAlphabetic(n).toLowerCase();
+    case "none":
+      return "";
+    case "ordinal":
+      return toOrdinal(n);
+    case "cardinalText":
+      return toCardinalText(n);
+    case "ordinalText":
+      return toOrdinalText(n);
+    case "hex":
+      return n.toString(16).toUpperCase();
+    case "chicago":
+      return toChicago(n);
+    default:
+      return String(n);
+  }
+}

package/src/runtime/surface-projection.ts

@@ -8,6 +8,11 @@ import type {
   SurfaceTableRowSnapshot,
   SurfaceTextMark,
 } from "../api/public-types";
+import {
+  chartModelStore,
+  extractChartDimensions,
+  stableChartId,
+} from "./chart/chart-model-store.ts";
 import type {
   CanonicalDocumentEnvelope,
   SelectionSnapshot,
@@ -1011,10 +1016,25 @@ function appendInlineSegments(
       });
       return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
     }
-    case "chart_preview":
+    case "chart_preview": {
+      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,
+          });
+        }
+      }
       return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node), {
         previewMediaId: node.previewMediaId,
+        parsedChartId,
       });
+    }
     case "smartart_preview":
       return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node), {
         previewMediaId: node.previewMediaId,
@@ -1087,6 +1107,14 @@ function appendInlineSegments(
         node.fieldFamily === "PAGE" ||
         node.fieldFamily === "NUMPAGES";
       if (node.children && node.children.length > 0) {
+        // For REF \h, pass the bookmark as a hyperlink href so child text gets hyperlink styling
+        const refHyperlinkHref =
+          node.fieldFamily === "REF" &&
+          node.switches?.hyperlink === true &&
+          node.fieldTarget
+            ? `#${node.fieldTarget}`
+            : undefined;
+
         let cursor = start;
         const lockedIds: string[] = [];
         for (const child of node.children) {
@@ -1096,7 +1124,7 @@ function appendInlineSegments(
             document,
             cursor,
             promoteSecondaryStoryTextBoxes,
-            undefined,
+            refHyperlinkHref ?? hyperlinkHref,
             cullBuild,
           );
           cursor = result.nextCursor;
@@ -1159,7 +1187,7 @@ function appendComplexPreviewSegment(
   start: number,
   label: string,
   detail: string,
-  extras: { previewMediaId?: string } = {},
+  extras: { previewMediaId?: string; parsedChartId?: string } = {},
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   paragraph.segments.push({
     segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -1171,6 +1199,7 @@ function appendComplexPreviewSegment(
     label,
     detail,
     ...(extras.previewMediaId ? { previewMediaId: extras.previewMediaId } : {}),
+    ...(extras.parsedChartId ? { parsedChartId: extras.parsedChartId } : {}),
     state: "locked-preserve-only",
   });
   return { nextCursor: start + 1, lockedFragmentIds: [] };