@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/runtime/surface-projection.ts

@@ -1,5 +1,7 @@
 import type {
+  EditorStoryTarget,
   EditorSurfaceSnapshot,
+  SecondaryStorySurface,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
   SurfaceTableCellSnapshot,
@@ -20,6 +22,7 @@ import type {
   SdtNode,
   ShapeNode,
   SmartArtPreviewNode,
+  TableCellBorders,
   TableNode,
   TextMark,
   VmlShapeNode,
@@ -29,10 +32,16 @@ import {
   describeOpaqueFragment,
   getOpaqueFragment,
 } from "../preservation/store.ts";
+import { getStoryBlocks } from "./story-targeting.ts";
 import {
   createNumberingPrefixResolver,
   type NumberingPrefixResolver,
 } from "./numbering-prefix.ts";
+import {
+  collectSectionContexts,
+  findHeaderFooterDocumentEntry,
+  resolveSectionVariants,
+} from "./story-context.ts";
 
 interface ParagraphAccumulator {
   blockId: string;
@@ -42,14 +51,20 @@ interface ParagraphAccumulator {
   styleId?: string;
   numbering?: ParagraphNode["numbering"];
   numberingPrefix?: string;
+  numberingSuffix?: "tab" | "space" | "nothing";
+  contextualSpacing?: boolean;
   segments: SurfaceInlineSegment[];
 }
 
 export function createEditorSurfaceSnapshot(
   document: CanonicalDocumentEnvelope,
   _selection: SelectionSnapshot,
+  activeStory: EditorStoryTarget = { kind: "main" },
 ): EditorSurfaceSnapshot {
-  const root = normalizeDocumentRoot(document.content);
+  const root = normalizeDocumentRoot({
+    type: "doc",
+    children: [...getStoryBlocks(document, activeStory)],
+  });
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
@@ -79,13 +94,14 @@ export function createEditorSurfaceSnapshot(
     }
   }
 
-  blocks.push(...createSecondaryStoryPreviewBlocks(document, cursor));
+  const secondaryStories = createSecondaryStorySurfaces(document);
 
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
     blocks,
     lockedFragmentIds,
+    secondaryStories,
   };
 }
 
@@ -263,16 +279,27 @@ function createTableBlock(
         lockedFragmentIds.push(...result.lockedFragmentIds);
         innerCursor = result.nextCursor;
       }
+      const cellBorders = resolveCellBorderStyles(cell.borders);
       cells.push({
         gridSpan: cell.gridSpan ?? 1,
         verticalMerge: cell.verticalMerge ?? null,
         colspan: cell.gridSpan ?? 1,
         rowspan: rowSpans.get(`${rowIndex}:${cellIndex}`) ?? 1,
         ...(cell.shading?.fill ? { backgroundColor: `#${cell.shading.fill}` } : {}),
+        ...(cell.verticalAlign ? { verticalAlign: cell.verticalAlign } : {}),
+        ...(cellBorders.borderTop ? { borderTop: cellBorders.borderTop } : {}),
+        ...(cellBorders.borderRight ? { borderRight: cellBorders.borderRight } : {}),
+        ...(cellBorders.borderBottom ? { borderBottom: cellBorders.borderBottom } : {}),
+        ...(cellBorders.borderLeft ? { borderLeft: cellBorders.borderLeft } : {}),
         content: cellContent,
       });
     }
-    rows.push({ cells });
+    rows.push({
+      cells,
+      ...(row.height !== undefined ? { height: row.height } : {}),
+      ...(row.heightRule ? { heightRule: row.heightRule } : {}),
+      ...(row.isHeader ? { isHeader: row.isHeader } : {}),
+    });
   }
 
   return {
@@ -283,6 +310,8 @@ function createTableBlock(
       to: innerCursor,
       styleId: table.styleId,
       gridColumns: table.gridColumns,
+      ...(table.alignment ? { alignment: table.alignment } : {}),
+      ...(table.tblLook ? { tblLook: table.tblLook } : {}),
       rows,
     },
     lockedFragmentIds,
@@ -339,6 +368,23 @@ function computeTableRowSpans(table: TableNode): Map<string, number> {
   return rowSpans;
 }
 
+function resolveCellBorderStyles(
+  borders: TableCellBorders | undefined,
+): { borderTop?: string; borderRight?: string; borderBottom?: string; borderLeft?: string } {
+  if (!borders) return {};
+  const result: { borderTop?: string; borderRight?: string; borderBottom?: string; borderLeft?: string } = {};
+  const sides = [["top", "borderTop"], ["right", "borderRight"], ["bottom", "borderBottom"], ["left", "borderLeft"]] as const;
+  for (const [side, key] of sides) {
+    const spec = borders[side];
+    if (!spec || spec.value === "none" || spec.value === "nil") continue;
+    const width = spec.size ? `${Math.max(1, Math.round(spec.size / 8))}px` : "1px";
+    const style = spec.value === "double" ? "double" : spec.value === "dashed" || spec.value === "dashSmallGap" ? "dashed" : spec.value === "dotted" ? "dotted" : "solid";
+    const color = spec.color && spec.color !== "auto" ? `#${spec.color}` : "currentColor";
+    result[key] = `${width} ${style} ${color}`;
+  }
+  return result;
+}
+
 function createSdtBlock(
   sdtIndex: number,
   block: SdtNode,
@@ -381,6 +427,11 @@ function createSdtBlock(
       ...(block.properties.alias ? { alias: block.properties.alias } : {}),
       ...(block.properties.tag ? { tag: block.properties.tag } : {}),
       ...(block.properties.lock ? { lock: block.properties.lock } : {}),
+      ...(block.properties.checkbox ? { checkboxChecked: block.properties.checkbox.checked } : {}),
+      ...(block.properties.datePicker?.fullDate ? { dateValue: block.properties.datePicker.fullDate } : {}),
+      ...(block.properties.dropdownList ? { dropdownItems: block.properties.dropdownList } : {}),
+      ...(block.properties.comboBox ? { comboBoxItems: block.properties.comboBox } : {}),
+      ...(block.properties.showingPlcHdr ? { showingPlcHdr: true } : {}),
       children,
     },
     lockedFragmentIds,
@@ -407,13 +458,21 @@ function createParagraphBlock(
     ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
     ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
     ...(paragraph.numbering
-      ? {
-          numberingPrefix:
-            numberingPrefixResolver.resolve(paragraph.numbering) ?? undefined,
-        }
+      ? (() => {
+          const detailed = numberingPrefixResolver.resolveDetailed(paragraph.numbering);
+          return detailed
+            ? {
+                numberingPrefix: detailed.text,
+                ...(detailed.suffix ? { numberingSuffix: detailed.suffix } : {}),
+              }
+            : {};
+        })()
       : {}),
     ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
     ...(paragraph.spacing ? { spacing: paragraph.spacing } : {}),
+    ...(paragraph.contextualSpacing !== undefined
+      ? { contextualSpacing: paragraph.contextualSpacing }
+      : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
     ...(paragraph.shading ? { shading: paragraph.shading } : {}),
@@ -425,6 +484,7 @@ function createParagraphBlock(
     ...(paragraph.pageBreakBefore ? { pageBreakBefore: true } : {}),
     ...(paragraph.outlineLevel !== undefined ? { outlineLevel: paragraph.outlineLevel } : {}),
     ...(paragraph.bidi ? { bidi: true } : {}),
+    ...(paragraph.suppressLineNumbers ? { suppressLineNumbers: true } : {}),
     segments: [],
   };
   const lockedFragmentIds: string[] = [];
@@ -530,20 +590,22 @@ function appendInlineSegments(
           preview?.detail ??
           descriptor?.detail ??
           "Locked whole-unit to keep unsupported inline OOXML intact through export.",
+        ...(preview?.presentation ? { presentation: preview.presentation } : {}),
         state: "locked-preserve-only",
       });
       return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
     }
     case "chart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "Chart", createChartDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node));
     case "smartart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt", createSmartArtDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node));
     case "shape":
-      return appendComplexPreviewSegment(paragraph, node, start, "Shape", createShapeDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start,
+        node.isTextBox ? "Text box" : "Drawing shape", createShapeDetail(node));
     case "wordart":
       return appendComplexPreviewSegment(paragraph, node, start, "WordArt", createWordArtDetail(node));
     case "vml_shape":
-      return appendComplexPreviewSegment(paragraph, node, start, "VML shape", createVmlDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "Legacy VML drawing", createVmlDetail(node));
     case "symbol":
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -569,14 +631,20 @@ function appendInlineSegments(
     case "footnote_ref":
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
-        kind: "text",
+        kind: "note_ref",
         from: start,
         to: start + 1,
-        text: node.noteId ?? "*",
-        marks: ["superscript" as SurfaceTextMark],
+        noteKind: node.noteKind ?? "footnote",
+        noteId: node.noteId ?? "",
+        label: node.noteId ?? "*",
       });
       return { nextCursor: start + 1, lockedFragmentIds: [] };
     case "field": {
+      const isSupportedField =
+        node.fieldFamily === "REF" ||
+        node.fieldFamily === "PAGEREF" ||
+        node.fieldFamily === "NOTEREF" ||
+        node.fieldFamily === "TOC";
       if (node.children && node.children.length > 0) {
         let cursor = start;
         const lockedIds: string[] = [];
@@ -587,6 +655,25 @@ function appendInlineSegments(
         }
         return { nextCursor: cursor, lockedFragmentIds: lockedIds };
       }
+      if (isSupportedField) {
+        // Supported field with no resolved content — show as field chip
+        const fieldLabel =
+          node.fieldFamily === "TOC"
+            ? "Table of Contents"
+            : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "field_ref",
+          from: start,
+          to: start + 1,
+          fieldFamily: node.fieldFamily!,
+          fieldTarget: node.fieldTarget,
+          instruction: node.instruction,
+          refreshStatus: node.refreshStatus ?? "stale",
+          label: fieldLabel,
+        } as SurfaceInlineSegment);
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "opaque_inline",
@@ -595,7 +682,7 @@ function appendInlineSegments(
         fragmentId: "",
         warningId: "",
         label: "Field",
-        detail: "Field code preserved for export.",
+        detail: `Preserve-only field: ${node.instruction.trim()}`,
         state: "locked-preserve-only",
       });
       return { nextCursor: start + 1, lockedFragmentIds: [] };
@@ -631,38 +718,54 @@ function appendComplexPreviewSegment(
 }
 
 function createChartDetail(node: ChartPreviewNode): string {
-  return node.previewMediaId
-    ? `Chart read-only preview. Fallback image ${node.previewMediaId}. Original XML preserved for export.`
-    : "Chart read-only preview. Original XML preserved for export.";
+  const parts = ["Embedded chart."];
+  if (node.previewMediaId) {
+    parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
+  } else {
+    parts.push("No fallback preview image found; chart data preserved in package.");
+  }
+  parts.push("Edit in Word to modify chart data. Original DrawingML preserved for lossless export.");
+  return parts.join(" ");
 }
 
 function createSmartArtDetail(node: SmartArtPreviewNode): string {
-  return node.previewMediaId
-    ? `SmartArt diagram read-only preview. Fallback image ${node.previewMediaId}. Original XML preserved for export.`
-    : "SmartArt diagram read-only preview. Original XML preserved for export.";
+  const parts = ["SmartArt diagram."];
+  if (node.previewMediaId) {
+    parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
+  } else {
+    parts.push("No fallback preview image found; diagram structure preserved in package.");
+  }
+  parts.push("Edit in Word to modify diagram layout and content. Original DrawingML preserved for lossless export.");
+  return parts.join(" ");
 }
 
 function createShapeDetail(node: ShapeNode): string {
-  const parts = ["Shape read-only preview."];
+  if (node.isTextBox) {
+    const parts = ["Text box."];
+    if (node.text) parts.push(`Content: "${node.text}".`);
+    parts.push("Text content is visible; formatting and geometry preserved for export.");
+    return parts.join(" ");
+  }
+  const parts = ["Drawing shape."];
   if (node.geometry) parts.push(`Geometry: ${node.geometry}.`);
-  if (node.text) parts.push(`Text: "${node.text}".`);
-  parts.push("Original XML preserved for export.");
+  if (node.text) parts.push(`Text content: "${node.text}".`);
+  parts.push("Visual geometry is preview-only. Original DrawingML preserved for export.");
   return parts.join(" ");
 }
 
 function createWordArtDetail(node: WordArtNode): string {
-  const parts = ["WordArt read-only preview."];
+  const parts = ["WordArt decorative text."];
   if (node.text) parts.push(`Text: "${node.text}".`);
   if (node.geometry) parts.push(`Effect: ${node.geometry}.`);
-  parts.push("Original XML preserved for export.");
+  parts.push("Text effect is preview-only. Edit in Word for full formatting. Original DrawingML preserved for export.");
   return parts.join(" ");
 }
 
 function createVmlDetail(node: VmlShapeNode): string {
-  const parts = ["VML shape read-only preview."];
+  const parts = ["Legacy VML drawing."];
   if (node.shapeType) parts.push(`Type: ${node.shapeType}.`);
-  if (node.text) parts.push(`Text: "${node.text}".`);
-  parts.push("Legacy VML; original XML preserved for export.");
+  if (node.text) parts.push(`Text content: "${node.text}".`);
+  parts.push("VML content is preview-only. Edit in Word for full control. Original VML XML preserved for export.");
   return parts.join(" ");
 }
 
@@ -717,6 +820,131 @@ function createPlainText(
   return text.join("");
 }
 
+function createSecondaryStorySurfaces(
+  document: CanonicalDocumentEnvelope,
+): SecondaryStorySurface[] {
+  const surfaces: SecondaryStorySurface[] = [];
+  const subParts = document.subParts;
+  if (!subParts) {
+    return surfaces;
+  }
+
+  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+
+  for (const section of collectSectionContexts(document)) {
+    const headerVariants = resolveSectionVariants(
+      "header",
+      section.index,
+      section.properties?.headerReferences,
+      subParts.headers ?? [],
+    );
+    for (const headerVariant of headerVariants) {
+      const target: EditorStoryTarget = {
+        kind: "header",
+        relationshipId: headerVariant.relationshipId,
+        variant: headerVariant.variant,
+        sectionIndex: section.index,
+      };
+      const header = findHeaderFooterDocumentEntry(document, target);
+      if (!header) {
+        continue;
+      }
+      surfaces.push(
+        createStorySurface(
+          target,
+          `Header · ${headerVariant.variant}`,
+          header.blocks,
+          document,
+          numberingPrefixResolver,
+        ),
+      );
+    }
+
+    const footerVariants = resolveSectionVariants(
+      "footer",
+      section.index,
+      section.properties?.footerReferences,
+      subParts.footers ?? [],
+    );
+    for (const footerVariant of footerVariants) {
+      const target: EditorStoryTarget = {
+        kind: "footer",
+        relationshipId: footerVariant.relationshipId,
+        variant: footerVariant.variant,
+        sectionIndex: section.index,
+      };
+      const footer = findHeaderFooterDocumentEntry(document, target);
+      if (!footer) {
+        continue;
+      }
+      surfaces.push(
+        createStorySurface(
+          target,
+          `Footer · ${footerVariant.variant}`,
+          footer.blocks,
+          document,
+          numberingPrefixResolver,
+        ),
+      );
+    }
+  }
+
+  const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
+  for (const note of footnotes) {
+    const target: EditorStoryTarget = { kind: "footnote", noteId: note.noteId };
+    surfaces.push(createStorySurface(target, `Footnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+  }
+
+  const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
+  for (const note of endnotes) {
+    const target: EditorStoryTarget = { kind: "endnote", noteId: note.noteId };
+    surfaces.push(createStorySurface(target, `Endnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+  }
+
+  return surfaces;
+}
+
+function createStorySurface(
+  target: EditorStoryTarget,
+  label: string,
+  blocks: readonly BlockNode[],
+  document: CanonicalDocumentEnvelope,
+  numberingPrefixResolver: NumberingPrefixResolver,
+): SecondaryStorySurface {
+  const surfaceBlocks: SurfaceBlockSnapshot[] = [];
+  let cursor = 0;
+  const counters = {
+    paragraph: 0,
+    table: 0,
+    opaque: 0,
+    sdt: 0,
+    customXml: 0,
+    altChunk: 0,
+  };
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const surfaceBlock = createSurfaceBlock(
+      blocks[index],
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
+    surfaceBlocks.push(surfaceBlock.block);
+    cursor = surfaceBlock.nextCursor;
+    if (index < blocks.length - 1 && blocks[index + 1]?.type === "paragraph") {
+      cursor += 1;
+    }
+  }
+
+  return {
+    target,
+    label,
+    storySize: cursor,
+    blocks: surfaceBlocks,
+  };
+}
+
 function createSecondaryStoryPreviewBlocks(
   document: CanonicalDocumentEnvelope,
   cursor: number,
@@ -856,15 +1084,16 @@ function summarizePreviewInline(node: InlineNode): string {
     case "column_break":
       return "[Column break]";
     case "chart_preview":
-      return "[Chart]";
+      return "[Embedded chart]";
     case "smartart_preview":
-      return "[SmartArt]";
+      return "[SmartArt diagram]";
     case "shape":
-      return node.text ? `[Shape: ${node.text}]` : "[Shape]";
+      if (node.isTextBox && node.text) return `[Text box: ${node.text}]`;
+      return node.text ? `[Shape: ${node.text}]` : "[Drawing shape]";
     case "wordart":
       return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
     case "vml_shape":
-      return node.text ? `[VML: ${node.text}]` : "[VML shape]";
+      return node.text ? `[VML: ${node.text}]` : "[Legacy VML drawing]";
   }
 }
 
@@ -887,7 +1116,51 @@ function toSurfaceTabStop(
 
 function describePreservedInlinePreview(
   payloadReference: string,
-): { label: string; detail: string } | null {
+): {
+  label: string;
+  detail: string;
+  presentation?: "inline-chip" | "quiet-marker";
+} | null {
+  if (/\b(?:w:)?proofErr\b/u.test(payloadReference)) {
+    const proofType = /\bw:type="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: "Proofing marker",
+      detail:
+        proofType && proofType.trim().length > 0
+          ? `Word proofing marker (${proofType}) preserved for export safety.`
+          : "Word proofing marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?lastRenderedPageBreak\b/u.test(payloadReference)) {
+    return {
+      label: "Rendered page break",
+      detail: "Word rendered page-break marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?permStart\b/u.test(payloadReference)) {
+    const editorGroup = /\bw:edGrp="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: "Protected range start",
+      detail:
+        editorGroup && editorGroup.trim().length > 0
+          ? `Protected range start for ${editorGroup} preserved for export safety.`
+          : "Protected range start preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?permEnd\b/u.test(payloadReference)) {
+    return {
+      label: "Protected range end",
+      detail: "Protected range end preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
   if (/\b(?:w:)?bookmarkStart\b/u.test(payloadReference)) {
     const name = /\bw:name="([^"]+)"/u.exec(payloadReference)?.[1];
     return {
@@ -912,8 +1185,15 @@ function describePreservedInlinePreview(
       .join("")
       .trim();
     const instruction = (simpleInstruction ?? complexInstruction ?? "").trim();
+    const family = /^([A-Z]+)/i.exec(instruction)?.[1]?.toUpperCase();
+    const label =
+      family === "TOC"
+        ? "Table of Contents field"
+        : family
+          ? `${family} field`
+          : "Field";
     return {
-      label: "Field",
+      label,
       detail:
         instruction.length > 0
           ? `Read-only field preserved for export safety. Instruction: ${instruction}.`
@@ -955,6 +1235,8 @@ function cloneMarks(marks: TextMark[]): {
     fontSize?: number;
     textColor?: string;
   } = {};
+  let shadingColor: string | undefined;
+  let highlightColor: string | undefined;
   for (const mark of marks) {
     switch (mark.type) {
       case "bold":
@@ -973,7 +1255,10 @@ function cloneMarks(marks: TextMark[]): {
         else if (mark.val < 0) supported.push("subscript");
         break;
       case "backgroundColor":
-        attrs.backgroundColor = mark.color;
+        shadingColor = mark.color;
+        break;
+      case "highlight":
+        highlightColor = mark.color;
         break;
       case "charSpacing":
         attrs.charSpacing = mark.val;
@@ -1004,6 +1289,9 @@ function cloneMarks(marks: TextMark[]): {
         break;
     }
   }
+  if (highlightColor || shadingColor) {
+    attrs.backgroundColor = highlightColor ?? shadingColor;
+  }
   const hasAttrs = Object.keys(attrs).length > 0;
   return hasAttrs ? { marks: supported, markAttrs: attrs } : { marks: supported };
 }