@beyondwork/docx-react-component 1.0.14 → 1.0.16

package/src/runtime/numbering-prefix.ts

@@ -0,0 +1,195 @@
+import type {
+  NumberingCatalog,
+  NumberingLevelDefinition,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+
+interface NumberingSequenceState {
+  counters: Array<number | undefined>;
+  lastLevel: number | null;
+}
+
+export interface NumberingPrefixResolver {
+  resolve(numbering: ParagraphNode["numbering"] | undefined): string | null;
+}
+
+const DEFAULT_START_AT = 1;
+
+export function createNumberingPrefixResolver(
+  catalog: NumberingCatalog,
+): NumberingPrefixResolver {
+  const sequenceStates = new Map<string, NumberingSequenceState>();
+
+  return {
+    resolve(numbering) {
+      if (!numbering) {
+        return null;
+      }
+
+      const instance = catalog.instances[numbering.numberingInstanceId];
+      if (!instance) {
+        return null;
+      }
+
+      const definition = catalog.abstractDefinitions[instance.abstractNumberingId];
+      if (!definition) {
+        return null;
+      }
+
+      const levelDefinitions = new Map(
+        definition.levels.map((level) => [level.level, level] as const),
+      );
+      const levelDefinition = levelDefinitions.get(numbering.level);
+      if (!levelDefinition || levelDefinition.format === "none") {
+        return null;
+      }
+
+      const sequenceState = getSequenceState(sequenceStates, numbering.numberingInstanceId);
+      advanceSequence(sequenceState, numbering.level, levelDefinitions, instance.overrides);
+
+      return renderLevelText(levelDefinition.text, sequenceState.counters, levelDefinitions);
+    },
+  };
+}
+
+function getSequenceState(
+  states: Map<string, NumberingSequenceState>,
+  numberingInstanceId: string,
+): NumberingSequenceState {
+  const existing = states.get(numberingInstanceId);
+  if (existing) {
+    return existing;
+  }
+
+  const created: NumberingSequenceState = {
+    counters: [],
+    lastLevel: null,
+  };
+  states.set(numberingInstanceId, created);
+  return created;
+}
+
+function advanceSequence(
+  state: NumberingSequenceState,
+  currentLevel: number,
+  levelDefinitions: Map<number, NumberingLevelDefinition>,
+  overrides: NumberingCatalog["instances"][string]["overrides"],
+): void {
+  if (state.lastLevel !== null && currentLevel <= state.lastLevel) {
+    state.counters.length = currentLevel + 1;
+  }
+
+  const startAt = getLevelStartAt(currentLevel, levelDefinitions, overrides);
+  const currentValue = state.counters[currentLevel];
+  state.counters[currentLevel] =
+    currentValue === undefined ? startAt : currentValue + 1;
+  state.lastLevel = currentLevel;
+}
+
+function getLevelStartAt(
+  level: number,
+  levelDefinitions: Map<number, NumberingLevelDefinition>,
+  overrides: NumberingCatalog["instances"][string]["overrides"],
+): number {
+  const override = overrides.find((entry) => entry.level === level);
+  if (override?.startAt !== undefined) {
+    return override.startAt;
+  }
+
+  return levelDefinitions.get(level)?.startAt ?? DEFAULT_START_AT;
+}
+
+function renderLevelText(
+  text: string,
+  counters: Array<number | undefined>,
+  levelDefinitions: Map<number, NumberingLevelDefinition>,
+): string | null {
+  if (!text) {
+    return null;
+  }
+
+  if (!text.includes("%")) {
+    return text;
+  }
+
+  const rendered = text.replace(/%([1-9])/g, (_match, token) => {
+    const level = Number.parseInt(token, 10) - 1;
+    const counter = counters[level];
+    if (counter === undefined) {
+      return "";
+    }
+
+    const format = levelDefinitions.get(level)?.format ?? "decimal";
+    return formatCounter(counter, format);
+  });
+
+  return rendered.trim().length > 0 ? rendered : null;
+}
+
+function formatCounter(value: number, format: string): string {
+  switch (format) {
+    case "decimal":
+      return String(value);
+    case "decimalZero":
+      return String(value).padStart(2, "0");
+    case "upperLetter":
+      return toAlphabetic(value).toUpperCase();
+    case "lowerLetter":
+      return toAlphabetic(value).toLowerCase();
+    case "upperRoman":
+      return toRoman(value).toUpperCase();
+    case "lowerRoman":
+      return toRoman(value).toLowerCase();
+    case "none":
+      return "";
+    default:
+      return String(value);
+  }
+}
+
+function toAlphabetic(value: number): string {
+  if (value <= 0) {
+    return String(value);
+  }
+
+  let remainder = value;
+  let result = "";
+  while (remainder > 0) {
+    remainder -= 1;
+    result = String.fromCharCode(65 + (remainder % 26)) + result;
+    remainder = Math.floor(remainder / 26);
+  }
+  return result;
+}
+
+function toRoman(value: number): string {
+  if (value <= 0 || value >= 4000) {
+    return String(value);
+  }
+
+  const numerals: Array<[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"],
+  ];
+
+  let remaining = value;
+  let result = "";
+  for (const [amount, numeral] of numerals) {
+    while (remaining >= amount) {
+      remaining -= amount;
+      result += numeral;
+    }
+  }
+  return result;
+}

package/src/runtime/surface-projection.ts

@@ -29,6 +29,10 @@ import {
   describeOpaqueFragment,
   getOpaqueFragment,
 } from "../preservation/store.ts";
+import {
+  createNumberingPrefixResolver,
+  type NumberingPrefixResolver,
+} from "./numbering-prefix.ts";
 
 interface ParagraphAccumulator {
   blockId: string;
@@ -37,6 +41,7 @@ interface ParagraphAccumulator {
   to: number;
   styleId?: string;
   numbering?: ParagraphNode["numbering"];
+  numberingPrefix?: string;
   segments: SurfaceInlineSegment[];
 }
 
@@ -47,6 +52,7 @@ export function createEditorSurfaceSnapshot(
   const root = normalizeDocumentRoot(document.content);
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
+  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
   let cursor = 0;
   const counters = {
     paragraph: 0,
@@ -58,7 +64,13 @@ export function createEditorSurfaceSnapshot(
   };
 
   for (let index = 0; index < root.children.length; index += 1) {
-    const surfaceBlock = createSurfaceBlock(root.children[index], document, cursor, counters);
+    const surfaceBlock = createSurfaceBlock(
+      root.children[index],
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
     blocks.push(surfaceBlock.block);
     lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
     cursor = surfaceBlock.nextCursor;
@@ -67,6 +79,8 @@ export function createEditorSurfaceSnapshot(
     }
   }
 
+  blocks.push(...createSecondaryStoryPreviewBlocks(document, cursor));
+
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
@@ -87,6 +101,7 @@ function createSurfaceBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   if (block.type === "opaque_block") {
     const fragment = getOpaqueFragment(document.preservation as never, block.fragmentId);
@@ -115,13 +130,27 @@ function createSurfaceBlock(
   if (block.type === "table") {
     const tableIndex = counters.table;
     counters.table += 1;
-    return createTableBlock(tableIndex, block, document, cursor, counters);
+    return createTableBlock(
+      tableIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
   }
 
   if (block.type === "sdt") {
     const sdtIndex = counters.sdt;
     counters.sdt += 1;
-    return createSdtBlock(sdtIndex, block, document, cursor, counters);
+    return createSdtBlock(
+      sdtIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
   }
 
   if (block.type === "custom_xml") {
@@ -189,7 +218,13 @@ function createSurfaceBlock(
 
   const paragraphIndex = counters.paragraph;
   counters.paragraph += 1;
-  return createParagraphBlock(paragraphIndex, block, document, cursor);
+  return createParagraphBlock(
+    paragraphIndex,
+    block,
+    document,
+    cursor,
+    numberingPrefixResolver,
+  );
 }
 
 function createTableBlock(
@@ -205,6 +240,7 @@ function createTableBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
@@ -216,7 +252,13 @@ function createTableBlock(
     for (const [cellIndex, cell] of row.cells.entries()) {
       const cellContent: SurfaceBlockSnapshot[] = [];
       for (const child of cell.children) {
-        const result = createSurfaceBlock(child, document, innerCursor, counters);
+        const result = createSurfaceBlock(
+          child,
+          document,
+          innerCursor,
+          counters,
+          numberingPrefixResolver,
+        );
         cellContent.push(result.block);
         lockedFragmentIds.push(...result.lockedFragmentIds);
         innerCursor = result.nextCursor;
@@ -310,13 +352,20 @@ function createSdtBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const children: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
 
   for (const child of block.children) {
-    const result = createSurfaceBlock(child, document, innerCursor, counters);
+    const result = createSurfaceBlock(
+      child,
+      document,
+      innerCursor,
+      counters,
+      numberingPrefixResolver,
+    );
     children.push(result.block);
     lockedFragmentIds.push(...result.lockedFragmentIds);
     innerCursor = result.nextCursor;
@@ -344,6 +393,7 @@ function createParagraphBlock(
   paragraph: ParagraphNode,
   document: CanonicalDocumentEnvelope,
   start: number,
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): {
   block: SurfaceBlockSnapshot;
   nextCursor: number;
@@ -356,12 +406,20 @@ function createParagraphBlock(
     to: start,
     ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
     ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
+    ...(paragraph.numbering
+      ? {
+          numberingPrefix:
+            numberingPrefixResolver.resolve(paragraph.numbering) ?? undefined,
+        }
+      : {}),
     ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
     ...(paragraph.spacing ? { spacing: paragraph.spacing } : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
     ...(paragraph.shading ? { shading: paragraph.shading } : {}),
-    ...(paragraph.tabStops && paragraph.tabStops.length > 0 ? { tabStops: paragraph.tabStops } : {}),
+    ...(paragraph.tabStops && paragraph.tabStops.length > 0
+      ? { tabStops: paragraph.tabStops.map((tabStop) => toSurfaceTabStop(tabStop)) }
+      : {}),
     ...(paragraph.keepNext ? { keepNext: true } : {}),
     ...(paragraph.keepLines ? { keepLines: true } : {}),
     ...(paragraph.pageBreakBefore ? { pageBreakBefore: true } : {}),
@@ -459,6 +517,7 @@ function appendInlineSegments(
     case "opaque_inline": {
       const fragment = getOpaqueFragment(document.preservation as never, node.fragmentId);
       const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+      const preview = fragment ? describePreservedInlinePreview(fragment.payloadReference) : null;
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "opaque_inline",
@@ -466,8 +525,9 @@ function appendInlineSegments(
         to: start + 1,
         fragmentId: node.fragmentId,
         warningId: node.warningId,
-        label: descriptor?.label ?? "Unsupported inline OOXML",
+        label: preview?.label ?? descriptor?.label ?? "Unsupported inline OOXML",
         detail:
+          preview?.detail ??
           descriptor?.detail ??
           "Locked whole-unit to keep unsupported inline OOXML intact through export.",
         state: "locked-preserve-only",
@@ -612,12 +672,19 @@ function createPlainText(
   const text: string[] = [];
   for (const block of blocks) {
     if (block.kind === "opaque_block") {
+      if (block.fragmentId.startsWith("preview:")) {
+        continue;
+      }
       text.push("\uFFFA");
       continue;
     }
 
     if (block.kind === "table") {
-      text.push("\uFFFA"); // placeholder for table in plain text
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          text.push(createPlainText(cell.content));
+        }
+      }
       continue;
     }
 
@@ -650,6 +717,222 @@ function createPlainText(
   return text.join("");
 }
 
+function createSecondaryStoryPreviewBlocks(
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+): SurfaceBlockSnapshot[] {
+  const previews: SurfaceBlockSnapshot[] = [];
+  const subParts = document.subParts;
+  if (!subParts) {
+    return previews;
+  }
+
+  for (const header of subParts.headers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Header · ${header.variant}`,
+        `header:${header.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(header.partPath, header.blocks),
+      ),
+    );
+  }
+
+  for (const footer of subParts.footers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footer · ${footer.variant}`,
+        `footer:${footer.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(footer.partPath, footer.blocks),
+      ),
+    );
+  }
+
+  const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
+  for (const note of footnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footnote ${note.noteId}`,
+        `footnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/footnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
+  for (const note of endnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Endnote ${note.noteId}`,
+        `endnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/endnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  return previews;
+}
+
+function createSecondaryStoryPreviewBlock(
+  label: string,
+  previewId: string,
+  cursor: number,
+  detail: string,
+): Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }> {
+  return {
+    blockId: `secondary-story-${previewId.replace(/[^a-z0-9._:-]+/gi, "-")}`,
+    kind: "opaque_block",
+    from: cursor,
+    to: cursor,
+    fragmentId: `preview:${previewId}`,
+    warningId: `preview:${previewId}`,
+    label,
+    detail,
+    state: "locked-preserve-only",
+  };
+}
+
+function createSecondaryStoryPreviewDetail(
+  sourceLabel: string,
+  blocks: readonly BlockNode[],
+): string {
+  const previewLines = blocks
+    .map((block) => summarizePreviewBlock(block))
+    .filter((line) => line.trim().length > 0);
+  const previewText = previewLines.length > 0 ? previewLines.join("\n\n") : "Empty story.";
+  return `Read-only preview from ${sourceLabel}.\n${previewText}`;
+}
+
+function summarizePreviewBlock(block: BlockNode): string {
+  switch (block.type) {
+    case "paragraph": {
+      const text = block.children.map((child) => summarizePreviewInline(child)).join("");
+      return text.trim().length > 0 ? text : "¶";
+    }
+    case "table":
+      return "[Table preserved in secondary story]";
+    case "opaque_block":
+      return "[Locked block preserved for export]";
+    case "sdt":
+      return "[Content control preview]";
+    case "custom_xml":
+      return "[Custom XML preview]";
+    case "alt_chunk":
+      return "[AltChunk preview]";
+    case "section_break":
+      return "[Section boundary]";
+  }
+}
+
+function summarizePreviewInline(node: InlineNode): string {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "tab":
+      return "\t";
+    case "hard_break":
+      return "\n";
+    case "hyperlink":
+      return node.children.map((child) => summarizePreviewInline(child)).join("");
+    case "footnote_ref":
+      return node.noteKind === "footnote" ? `[fn ${node.noteId}]` : `[en ${node.noteId}]`;
+    case "field": {
+      const instruction = node.instruction.trim();
+      return instruction.length > 0 ? `[Field: ${instruction}]` : "[Field]";
+    }
+    case "bookmark_start":
+      return node.name ? `[Bookmark: ${node.name}]` : "[Bookmark]";
+    case "bookmark_end":
+      return "";
+    case "image":
+      return node.altText ? `[Image: ${node.altText}]` : "[Image]";
+    case "opaque_inline":
+      return "[Locked inline content]";
+    case "symbol":
+      return node.char ? String.fromCodePoint(parseInt(node.char, 16)) : "\uFFFD";
+    case "column_break":
+      return "[Column break]";
+    case "chart_preview":
+      return "[Chart]";
+    case "smartart_preview":
+      return "[SmartArt]";
+    case "shape":
+      return node.text ? `[Shape: ${node.text}]` : "[Shape]";
+    case "wordart":
+      return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
+    case "vml_shape":
+      return node.text ? `[VML: ${node.text}]` : "[VML shape]";
+  }
+}
+
+function compareNoteIds(
+  left: { noteId: string },
+  right: { noteId: string },
+): number {
+  return Number.parseInt(left.noteId, 10) - Number.parseInt(right.noteId, 10);
+}
+
+function toSurfaceTabStop(
+  tabStop: NonNullable<ParagraphNode["tabStops"]>[number],
+): { pos: number; val?: string; leader?: string } {
+  return {
+    pos: tabStop.position,
+    ...(tabStop.align ? { val: tabStop.align } : {}),
+    ...(tabStop.leader ? { leader: tabStop.leader } : {}),
+  };
+}
+
+function describePreservedInlinePreview(
+  payloadReference: string,
+): { label: string; detail: string } | null {
+  if (/\b(?:w:)?bookmarkStart\b/u.test(payloadReference)) {
+    const name = /\bw:name="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: name ? `Bookmark · ${name}` : "Bookmark",
+      detail: name
+        ? `Bookmark anchor \"${name}\" is preserved as a read-only inline token for export safety.`
+        : "Bookmark anchor is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?bookmarkEnd\b/u.test(payloadReference)) {
+    return {
+      label: "Bookmark end",
+      detail: "Bookmark end marker is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?fldSimple\b|\b(?:w:)?fldChar\b|\b(?:w:)?instrText\b/u.test(payloadReference)) {
+    const simpleInstruction = /\bw:instr="([^"]*)"/u.exec(payloadReference)?.[1];
+    const complexInstruction = [...payloadReference.matchAll(/<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu)]
+      .map((match) => decodeXmlEntities(match[1] ?? ""))
+      .join("")
+      .trim();
+    const instruction = (simpleInstruction ?? complexInstruction ?? "").trim();
+    return {
+      label: "Field",
+      detail:
+        instruction.length > 0
+          ? `Read-only field preserved for export safety. Instruction: ${instruction}.`
+          : "Read-only field preserved for export safety.",
+    };
+  }
+
+  return null;
+}
+
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
 function cloneMarks(marks: TextMark[]): {
   marks: SurfaceTextMark[];
   markAttrs?: {