@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/io/export/serialize-settings.ts

@@ -0,0 +1,421 @@
+/**
+ * Serialize a `DocumentSettings` to an OOXML `<w:settings>` document.
+ *
+ * Two modes:
+ *
+ *   1. **Synthesis** (`serializeSettingsXml(settings)`): emit a complete
+ *      `<w:settings>` document from canonical fields only. Drops every
+ *      unmodelled top-level child (`<w:defaultTabStop>`, etc.) — so this
+ *      mode is safe ONLY for synthetic / green-field documents that never
+ *      had those fields to begin with.
+ *
+ *   2. **Graft** (`serializeSettingsXml(settings, sourceXml)`): walk the
+ *      source's top-level children and decide per child:
+ *        - **Modelled child whose source-derived canonical projection
+ *          equals the current canonical projection** → keep source bytes
+ *          verbatim (byte-preservation). This preserves multi-line
+ *          whitespace inside `<w:compat>`, source child ordering inside
+ *          `<w:compat>`, unknown attributes on modelled elements (e.g.
+ *          `<w:zoom w:percent="120%" w:newAttr="..."/>`), and empty
+ *          self-closing forms like `<w:compat/>`.
+ *        - **Modelled child that canonical mutated** → rebuild from
+ *          synthesis. This is where unknown attributes on the mutated
+ *          element are dropped (documented limitation: the canonical
+ *          model only carries the attributes the parser captured).
+ *        - **Modelled child that canonical removed** → drop element AND
+ *          its leading interstitial whitespace.
+ *        - **Unmodelled child** → preserve source bytes verbatim.
+ *      Modelled fields canonical has but source lacks are appended at
+ *      the end of the body.
+ *
+ * Critical invariant proven by the CCEP fixture sweep in
+ * `test/io/parse-settings-ccep.test.ts`: when canonical equals
+ * `parseSettingsXml(sourceXml)`, the grafted output is byte-identical
+ * to `sourceXml`. The sweep dynamically discovers every fixture under
+ * `test/fixtures/docx/F*.docx` that ships a `/word/settings.xml` part
+ * and asserts the no-op round-trip plus an `unmodelledSettingsChildren`
+ * symmetry check.
+ *
+ * Known limitation: a canonical mutation on a modelled element rebuilds
+ * the element from the typed fields, dropping any unknown attributes the
+ * source carried. The trade-off is acceptable because the alternative
+ * (preserving unknown attrs across mutations) would require the parser
+ * to track raw attribute bags. For the no-mutation case, byte-
+ * preservation kicks in and unknown attrs survive.
+ *
+ * **WIRED INTO THE EXPORT PIPELINE** as of Lane 3 O4 Phase 3c. The
+ * `exportDocxEditorSession` flow in `src/io/docx-session.ts` adds
+ * `/word/settings.xml` to `ownedOutputPaths` whenever the source
+ * package carried one (or canonical surfaces `subParts.settings`)
+ * and routes the bytes through `serializeSettingsXml(settings,
+ * sourceXml)`. The `sourceXml` argument comes from
+ * `state.sourceSettingsXml`, captured at import time. The CCEP
+ * integration test at `test/io/ccep-roundtrip-settings.test.ts`
+ * proves both the byte-reuse short-circuit AND the forced-reserialize
+ * path (`DOCX_VALIDATOR_FORCE_REGEN=1`) keep settings.xml byte-clean
+ * across the full settings-bearing CCEP fixture set.
+ *
+ * Authority for emit shape: ECMA-376 §17.15 (settings.xml schema) plus
+ * the LibreOffice settings serializer at
+ * vendor/libreoffice/sw/source/writerfilter/dmapper/SettingsTable.cxx for
+ * compatSetting triple emission.
+ */
+
+import type {
+  CompatSetting,
+  DocumentSettings,
+} from "../../model/canonical-document.ts";
+import {
+  parseSettingsXml,
+  ROOT_COMPAT_FLAG_NAMES,
+} from "../ooxml/parse-settings.ts";
+import {
+  parseSettingsBlueprint,
+  type SettingsBlueprintChild,
+} from "../ooxml/parse-settings-blueprint.ts";
+import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
+
+export const WORD_SETTINGS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml";
+
+const WORDPROCESSINGML_2006_MAIN_NS =
+  "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+/**
+ * Render a complete `<w:settings>` XML document from canonical
+ * `DocumentSettings`. The output is the standard XML declaration plus a
+ * `<w:settings>` root carrying every modelled field.
+ *
+ * Emit order is OOXML-schema-friendly to maximize Word's tolerance:
+ *   1. <w:evenAndOddHeaders>
+ *   2. <w:zoom>
+ *   3. root-level compat-adjacent flags (e.g. <w:doNotEmbedSmartTags/>)
+ *   4. <w:compat> wrapping flags then compatSetting triples
+ *   5. <w:themeFontLang>
+ *
+ * Insertion order of `compatSettings` array entries and `compatFlags` /
+ * `rootCompatFlags` / `themeFontLang` keys is preserved so a byte-stable
+ * diff is achievable on round-trip when caller-supplied data is itself
+ * stable.
+ */
+export function serializeSettingsXml(
+  settings: DocumentSettings,
+  sourceXml?: string,
+): string {
+  if (sourceXml !== undefined) {
+    return graftSettingsXml(settings, sourceXml);
+  }
+  return synthesizeSettingsXml(settings);
+}
+
+function synthesizeSettingsXml(settings: DocumentSettings): string {
+  const parts: string[] = [];
+  parts.push(emitEvenAndOddHeaders(settings));
+  parts.push(emitZoom(settings));
+  parts.push(emitRootCompatFlags(settings));
+  parts.push(emitCompatBlock(settings));
+  parts.push(emitThemeFontLang(settings));
+
+  const body = parts.filter((p) => p.length > 0).join("");
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<w:settings xmlns:w="${WORDPROCESSINGML_2006_MAIN_NS}">${body}</w:settings>`,
+  ].join("");
+}
+
+/**
+ * Graft canonical fields onto a source settings.xml. Walks the source's
+ * top-level children: replaces modelled names with canonical re-emission
+ * (or removes them when canonical drops the field), keeps unmodelled
+ * children byte-identical to the source. Modelled fields the canonical
+ * has but the source lacks are appended at the end of the body.
+ *
+ * Critical invariant: when canonical equals `parseSettingsXml(sourceXml)`,
+ * the output is byte-identical to `sourceXml`. This is the no-edit
+ * round-trip guarantee that lets the export pipeline take ownership of
+ * `/word/settings.xml` without introducing validator regressions.
+ */
+function graftSettingsXml(
+  settings: DocumentSettings,
+  sourceXml: string,
+): string {
+  const blueprint = parseSettingsBlueprint(sourceXml);
+
+  // Track which top-level modelled names we already emitted in place so we
+  // don't double-emit them in the append-at-end pass.
+  const emittedTopLevel = new Set<string>();
+
+  // Mutable copy of canonical rootCompatFlags so we can "consume" entries as
+  // we replace them in place; what's left at the end gets appended.
+  const pendingRootFlags = new Map<string, boolean>(
+    Object.entries(settings.rootCompatFlags ?? {}),
+  );
+
+  const childParts: string[] = [];
+  for (const child of blueprint.topLevelChildren) {
+    const replacement = computeChildReplacement(
+      settings,
+      child,
+      pendingRootFlags,
+    );
+    // Mark modelled names as encountered in source so the append-at-end pass
+    // does not duplicate them. Root flags are tracked via pendingRootFlags
+    // (computeChildReplacement deletes them as it handles each one), so we
+    // only need to track the four named modelled top-level elements here.
+    if (
+      replacement.kind !== "drop" &&
+      MODELLED_TOP_LEVEL_NAMES.has(child.localName)
+    ) {
+      emittedTopLevel.add(child.localName);
+    }
+    if (replacement.kind === "keep") {
+      childParts.push(child.interstitialBefore + child.rawXml);
+      continue;
+    }
+    if (replacement.kind === "drop") {
+      // Skip both raw and interstitial — leaving interstitial would create
+      // dangling whitespace.
+      continue;
+    }
+    // replacement.kind === "replace"
+    childParts.push(child.interstitialBefore + replacement.xml);
+  }
+
+  // Append modelled elements canonical has that source did NOT.
+  const appendedParts: string[] = [];
+  if (
+    !emittedTopLevel.has("evenAndOddHeaders") &&
+    settings.evenAndOddHeaders !== undefined
+  ) {
+    appendedParts.push(emitEvenAndOddHeaders(settings));
+  }
+  if (
+    !emittedTopLevel.has("zoom") &&
+    settings.zoomLevel !== undefined
+  ) {
+    appendedParts.push(emitZoom(settings));
+  }
+  // Any rootCompatFlags entries that didn't have a source counterpart.
+  for (const [name, value] of pendingRootFlags) {
+    appendedParts.push(emitOnOffElement(name, value));
+  }
+  if (!emittedTopLevel.has("compat")) {
+    const compatXml = emitCompatBlock(settings);
+    if (compatXml.length > 0) appendedParts.push(compatXml);
+  }
+  if (
+    !emittedTopLevel.has("themeFontLang") &&
+    settings.themeFontLang !== undefined
+  ) {
+    appendedParts.push(emitThemeFontLang(settings));
+  }
+
+  return (
+    blueprint.prelude +
+    blueprint.settingsOpenTag +
+    childParts.join("") +
+    appendedParts.join("") +
+    blueprint.trailingWhitespace +
+    blueprint.settingsCloseTag
+  );
+}
+
+/**
+ * Modelled top-level <w:settings> children that the graft loop tracks via
+ * `emittedTopLevel`. Root compat flags (`<w:doNotEmbedSmartTags/>`, etc.)
+ * are NOT in this set — they're tracked via `pendingRootFlags` because
+ * canonical can carry an arbitrary set of them.
+ */
+const MODELLED_TOP_LEVEL_NAMES: ReadonlySet<string> = new Set([
+  "evenAndOddHeaders",
+  "zoom",
+  "compat",
+  "themeFontLang",
+]);
+
+type ChildReplacement =
+  | { kind: "keep" }
+  | { kind: "drop" }
+  | { kind: "replace"; xml: string };
+
+/**
+ * Decide what graft does with a single top-level source child.
+ *
+ * Byte-preservation precedence: for any modelled child whose source-derived
+ * canonical projection equals the current canonical projection, return
+ * `{ kind: "keep" }` so the source rawXml survives untouched. This preserves
+ *
+ *   - multi-line whitespace inside `<w:compat>` (reviewer C2(a))
+ *   - source child ordering inside `<w:compat>` (reviewer C2(b))
+ *   - unknown attributes on modelled elements like
+ *     `<w:compatSetting w:name=… w:uri=… w:val=… w:futureAttr=…/>` or
+ *     `<w:zoom w:percent="120%" w:newAttr=…/>` (reviewer C2(c))
+ *   - empty self-closing `<w:compat/>` source (reviewer Risk #6)
+ *
+ * Only when canonical genuinely mutates a modelled field does the byte
+ * form get rebuilt from synthesis. The trade-off is documented: a
+ * mutation drops unknown attributes on the mutated element, because the
+ * canonical model only carries the attributes the parser captured.
+ */
+function computeChildReplacement(
+  settings: DocumentSettings,
+  child: SettingsBlueprintChild,
+  pendingRootFlags: Map<string, boolean>,
+): ChildReplacement {
+  switch (child.localName) {
+    case "evenAndOddHeaders": {
+      if (
+        emitEvenAndOddHeaders(parseModelledChild(child.rawXml)) ===
+        emitEvenAndOddHeaders(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitEvenAndOddHeaders(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+    case "zoom": {
+      if (
+        emitZoom(parseModelledChild(child.rawXml)) === emitZoom(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitZoom(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+    case "compat": {
+      if (
+        emitCompatBlock(parseModelledChild(child.rawXml)) ===
+        emitCompatBlock(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitCompatBlock(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+    case "themeFontLang": {
+      if (
+        emitThemeFontLang(parseModelledChild(child.rawXml)) ===
+        emitThemeFontLang(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitThemeFontLang(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+  }
+  // Root compat flag?
+  if (ROOT_COMPAT_FLAG_NAMES.has(child.localName)) {
+    if (pendingRootFlags.has(child.localName)) {
+      const value = pendingRootFlags.get(child.localName)!;
+      pendingRootFlags.delete(child.localName);
+      // Byte-preserve when canonical value matches the source-encoded value.
+      const sourceParsed = parseModelledChild(child.rawXml);
+      if (sourceParsed.rootCompatFlags?.[child.localName] === value) {
+        return { kind: "keep" };
+      }
+      return { kind: "replace", xml: emitOnOffElement(child.localName, value) };
+    }
+    // Canonical dropped it.
+    return { kind: "drop" };
+  }
+  // Unmodelled — keep verbatim.
+  return { kind: "keep" };
+}
+
+/**
+ * Re-parse a single top-level source child element by wrapping it in a
+ * synthetic `<w:settings>` envelope and feeding it through the canonical
+ * parser. Used to compare source-derived canonical projection against the
+ * caller-supplied canonical for byte-preservation eligibility.
+ *
+ * Tiny string allocation per child; fine for settings.xml-sized inputs.
+ */
+function parseModelledChild(rawXml: string): DocumentSettings {
+  const wrapped =
+    `<w:settings xmlns:w="${WORDPROCESSINGML_2006_MAIN_NS}">` +
+    rawXml +
+    `</w:settings>`;
+  return parseSettingsXml(wrapped);
+}
+
+function emitEvenAndOddHeaders(settings: DocumentSettings): string {
+  if (settings.evenAndOddHeaders === undefined) return "";
+  if (settings.evenAndOddHeaders) {
+    return `<w:evenAndOddHeaders/>`;
+  }
+  return `<w:evenAndOddHeaders w:val="false"/>`;
+}
+
+function emitZoom(settings: DocumentSettings): string {
+  const { zoomLevel } = settings;
+  if (zoomLevel === undefined) return "";
+  if (zoomLevel === "pageWidth") {
+    return `<w:zoom w:val="bestFit"/>`;
+  }
+  if (zoomLevel === "onePage") {
+    return `<w:zoom w:val="fullPage"/>`;
+  }
+  if (typeof zoomLevel === "number" && Number.isFinite(zoomLevel)) {
+    return `<w:zoom w:percent="${Math.round(zoomLevel)}"/>`;
+  }
+  return "";
+}
+
+function emitRootCompatFlags(settings: DocumentSettings): string {
+  const flags = settings.rootCompatFlags;
+  if (!flags) return "";
+  return Object.entries(flags)
+    .map(([name, value]) => emitOnOffElement(name, value))
+    .join("");
+}
+
+function emitCompatBlock(settings: DocumentSettings): string {
+  const flags = settings.compatFlags;
+  const triples = settings.compatSettings;
+  const hasFlags = flags && Object.keys(flags).length > 0;
+  const hasTriples = triples && triples.length > 0;
+  if (!hasFlags && !hasTriples) return "";
+
+  const flagXml = hasFlags
+    ? Object.entries(flags!)
+        .map(([name, value]) => emitOnOffElement(name, value))
+        .join("")
+    : "";
+  const triplesXml = hasTriples
+    ? triples!.map((cs) => emitCompatSetting(cs)).join("")
+    : "";
+
+  return `<w:compat>${flagXml}${triplesXml}</w:compat>`;
+}
+
+function emitCompatSetting(cs: CompatSetting): string {
+  return (
+    `<w:compatSetting` +
+    ` w:name="${escapeXmlAttribute(cs.name)}"` +
+    ` w:uri="${escapeXmlAttribute(cs.uri)}"` +
+    ` w:val="${escapeXmlAttribute(cs.value)}"` +
+    `/>`
+  );
+}
+
+function emitThemeFontLang(settings: DocumentSettings): string {
+  const lang = settings.themeFontLang;
+  if (!lang) return "";
+  const attrs = Object.entries(lang)
+    .map(([name, value]) => ` ${name}="${escapeXmlAttribute(value)}"`)
+    .join("");
+  if (attrs.length === 0) {
+    return `<w:themeFontLang/>`;
+  }
+  return `<w:themeFontLang${attrs}/>`;
+}
+
+/**
+ * Emit a ST_OnOff element. true → bare self-closing tag; false → explicit
+ * `w:val="false"` so the parser doesn't infer the default-true. Symmetric
+ * with `readOnOffValue` in `parse-settings.ts`.
+ */
+function emitOnOffElement(localName: string, value: boolean): string {
+  if (value) return `<w:${localName}/>`;
+  return `<w:${localName} w:val="false"/>`;
+}

package/src/io/export/serialize-styles.ts

@@ -73,6 +73,10 @@ function buildParagraphStyleXml(
   const nextEl = style.nextStyle
     ? `<w:next w:val="${escXml(style.nextStyle)}"/>`
     : "";
+  // ECMA-376 §17.7 emit order: name → basedOn → next → link → ...
+  const linkEl = style.linkedStyleId
+    ? `<w:link w:val="${escXml(style.linkedStyleId)}"/>`
+    : "";
 
   // Build pPr: may contain numPr (from numbering) and any canonical formatting.
   // We reconstruct the pPr children in canonical order:
@@ -95,6 +99,7 @@ function buildParagraphStyleXml(
     nameEl +
     basedOnEl +
     nextEl +
+    linkEl +
     pPrBodyXml +
     rPrXml +
     `</w:style>`
@@ -175,12 +180,17 @@ function buildCharacterStyleXml(
   const basedOnEl = style.basedOn
     ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
     : "";
+  // ECMA-376 §17.7 emit order: name → basedOn → link → ... → rPr
+  const linkEl = style.linkedStyleId
+    ? `<w:link w:val="${escXml(style.linkedStyleId)}"/>`
+    : "";
   const rPrXml = buildRunPropertiesXml(style.runProperties);
 
   return (
     `<w:style w:type="character" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
     nameEl +
     basedOnEl +
+    linkEl +
     rPrXml +
     `</w:style>`
   );

package/src/io/normalize/normalize-text.ts

@@ -482,6 +482,7 @@ function normalizeInlineChildren(
         normalized.push({
           type: "chart_preview",
           ...(node.previewMediaId ? { previewMediaId: node.previewMediaId } : {}),
+          ...(node.parsedData ? { parsedData: node.parsedData } : {}),
           rawXml: node.rawXml,
         });
         state.cursor += 1;