@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/io/ooxml/parse-settings-blueprint.ts

@@ -0,0 +1,349 @@
+/**
+ * Decompose a `settings.xml` document into a verbatim-preserving blueprint
+ * so the export-side serializer can perform graft mode: replace modelled
+ * top-level children with re-emitted XML while leaving every unmodelled
+ * child (`<w:defaultTabStop>`, `<w:characterSpacingControl>`,
+ * `<w:documentProtection>`, mail-merge state, etc.) byte-identical to the
+ * source.
+ *
+ * This is intentionally a separate, narrower scanner from the canonical
+ * parser at `parse-settings.ts`. The canonical parser throws away raw text;
+ * this scanner keeps every byte. The two run independently — neither
+ * affects the other — because the blueprint is a serializer-side concern.
+ *
+ * Authority: ECMA-376 §17.15 (settings.xml schema). Comments and the XML
+ * declaration are preserved as part of the prelude / interstitial strings,
+ * so a no-edit graft round-trips byte-identically to the source.
+ */
+
+export interface SettingsBlueprintChild {
+  /**
+   * Local name of the top-level child (e.g. "compat", "compatSetting",
+   * "themeFontLang", "defaultTabStop").
+   */
+  localName: string;
+  /**
+   * Verbatim XML for the child element including its full content (for
+   * non-self-closing elements). Does NOT include any leading/trailing
+   * whitespace — that lives on `interstitialBefore`.
+   */
+  rawXml: string;
+  /**
+   * Whitespace + comments that appear between the previous boundary (the
+   * settings open tag for the first child, the previous child's `rawXml`
+   * end for subsequent children) and the start of this child's `rawXml`.
+   * The serializer must re-emit this verbatim before each child.
+   */
+  interstitialBefore: string;
+}
+
+export interface SettingsBlueprint {
+  /**
+   * Everything before the `<w:settings>` opening tag — the XML declaration
+   * if present plus any leading whitespace. Empty string when neither is
+   * present.
+   */
+  prelude: string;
+  /**
+   * The `<w:settings ...>` opening tag verbatim, including every xmlns
+   * declaration and any other root attributes. If the source uses a
+   * self-closing form (`<w:settings ... />`), this captures the full
+   * self-closing tag and `settingsCloseTag` is the empty string.
+   */
+  settingsOpenTag: string;
+  /**
+   * Top-level children of `<w:settings>` in document order with their
+   * verbatim raw XML and the interstitial whitespace/comments before each.
+   */
+  topLevelChildren: SettingsBlueprintChild[];
+  /**
+   * Whitespace + comments between the last child's `rawXml` end and the
+   * `</w:settings>` closing tag. The serializer must re-emit this verbatim
+   * after the last child.
+   */
+  trailingWhitespace: string;
+  /**
+   * The `</w:settings>` closing tag verbatim. Empty string when the source
+   * used a self-closing `<w:settings/>` form.
+   */
+  settingsCloseTag: string;
+}
+
+/**
+ * Scan a settings.xml document and decompose it into a verbatim-preserving
+ * blueprint. Throws if the document does not contain a `<w:settings>`
+ * root element.
+ */
+export function parseSettingsBlueprint(xml: string): SettingsBlueprint {
+  const settingsTagStart = findSettingsOpenTagStart(xml);
+  if (settingsTagStart < 0) {
+    throw new Error("parseSettingsBlueprint: no <w:settings> element found");
+  }
+
+  const prelude = xml.slice(0, settingsTagStart);
+  const settingsTagEnd = findTagEnd(xml, settingsTagStart);
+  if (settingsTagEnd < 0) {
+    throw new Error("parseSettingsBlueprint: unterminated <w:settings> tag");
+  }
+  const settingsOpenTag = xml.slice(settingsTagStart, settingsTagEnd + 1);
+  const isSelfClosing = settingsOpenTag.endsWith("/>");
+
+  if (isSelfClosing) {
+    return {
+      prelude,
+      settingsOpenTag,
+      topLevelChildren: [],
+      trailingWhitespace: "",
+      settingsCloseTag: "",
+    };
+  }
+
+  // Walk children inside <w:settings>...</w:settings>.
+  const closeTagInfo = findSettingsCloseTag(xml, settingsTagEnd + 1);
+  if (!closeTagInfo) {
+    throw new Error("parseSettingsBlueprint: missing </w:settings> closing tag");
+  }
+  const innerStart = settingsTagEnd + 1;
+  const innerEnd = closeTagInfo.start;
+
+  const { children, trailing } = scanTopLevelChildren(xml, innerStart, innerEnd);
+
+  return {
+    prelude,
+    settingsOpenTag,
+    topLevelChildren: children,
+    trailingWhitespace: trailing,
+    settingsCloseTag: closeTagInfo.tag,
+  };
+}
+
+function findSettingsOpenTagStart(xml: string): number {
+  // Scan past <?xml ... ?> and <!-- comments --> until we hit a < that
+  // begins an element. Then verify that element is <w:settings.
+  let cursor = 0;
+  while (cursor < xml.length) {
+    if (xml.startsWith("<?", cursor)) {
+      const end = xml.indexOf("?>", cursor);
+      if (end < 0) return -1;
+      cursor = end + 2;
+      continue;
+    }
+    if (xml.startsWith("<!--", cursor)) {
+      const end = xml.indexOf("-->", cursor);
+      if (end < 0) return -1;
+      cursor = end + 3;
+      continue;
+    }
+    const lt = xml.indexOf("<", cursor);
+    if (lt < 0) return -1;
+    if (xml.startsWith("<?", lt) || xml.startsWith("<!--", lt)) {
+      cursor = lt;
+      continue;
+    }
+    // First real element. Confirm it's <w:settings (or fallback `settings`).
+    if (xml.startsWith("<w:settings", lt) || xml.startsWith("<settings", lt)) {
+      // Verify the next char is whitespace, '>', or '/' — not a longer name like <w:settingsExtra.
+      const after = lt + (xml.startsWith("<w:settings", lt) ? "<w:settings".length : "<settings".length);
+      const ch = xml[after];
+      if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === ">" || ch === "/") {
+        return lt;
+      }
+    }
+    return -1;
+  }
+  return -1;
+}
+
+function findTagEnd(xml: string, tagStart: number): number {
+  // Skip until we find the closing > that terminates THIS tag.
+  // Attribute values cannot contain unescaped '>' so a naive scan works.
+  for (let i = tagStart; i < xml.length; i++) {
+    if (xml[i] === ">") return i;
+  }
+  return -1;
+}
+
+function findSettingsCloseTag(
+  xml: string,
+  startFrom: number,
+): { start: number; tag: string } | null {
+  // Find the LAST </w:settings> (or </settings>) — the document body cannot
+  // legally contain a nested settings element, so the first occurrence is
+  // also the last; we still scan to end-of-string defensively.
+  const candidates: Array<"</w:settings>" | "</settings>"> = [
+    "</w:settings>",
+    "</settings>",
+  ];
+  let bestIdx = -1;
+  let bestTag = "";
+  for (const candidate of candidates) {
+    const idx = xml.indexOf(candidate, startFrom);
+    if (idx >= 0 && (bestIdx < 0 || idx < bestIdx)) {
+      bestIdx = idx;
+      bestTag = candidate;
+    }
+  }
+  if (bestIdx < 0) return null;
+  return { start: bestIdx, tag: bestTag };
+}
+
+function scanTopLevelChildren(
+  xml: string,
+  innerStart: number,
+  innerEnd: number,
+): { children: SettingsBlueprintChild[]; trailing: string } {
+  const children: SettingsBlueprintChild[] = [];
+  let cursor = innerStart;
+
+  while (cursor < innerEnd) {
+    // Capture interstitial: whitespace + comments + processing instructions
+    // until the next element start.
+    const interstitialStart = cursor;
+    cursor = skipInterstitial(xml, cursor, innerEnd);
+    const interstitial = xml.slice(interstitialStart, cursor);
+
+    if (cursor >= innerEnd) {
+      // Pure trailing whitespace — no more children.
+      return { children, trailing: interstitial };
+    }
+
+    if (xml[cursor] !== "<") {
+      // Bare text content at the top level isn't legal in settings.xml;
+      // surface it via interstitial-as-trailing and stop.
+      return { children, trailing: interstitial + xml.slice(cursor, innerEnd) };
+    }
+
+    // Begin scanning an element.
+    const elementStart = cursor;
+    const tagEnd = findTagEnd(xml, elementStart);
+    if (tagEnd < 0 || tagEnd >= innerEnd) {
+      throw new Error(
+        "parseSettingsBlueprint: unterminated tag inside <w:settings>",
+      );
+    }
+    const openTag = xml.slice(elementStart, tagEnd + 1);
+    const localName = readLocalNameFromOpenTag(openTag);
+
+    let elementEnd: number;
+    if (openTag.endsWith("/>")) {
+      // Self-closing.
+      elementEnd = tagEnd + 1;
+    } else {
+      // Find matching closing tag, accounting for nested same-named elements.
+      const closingPattern = `</${getQualifiedName(openTag)}>`;
+      const matchEnd = findMatchingClose(
+        xml,
+        tagEnd + 1,
+        innerEnd,
+        getQualifiedName(openTag),
+      );
+      if (matchEnd < 0) {
+        throw new Error(
+          `parseSettingsBlueprint: missing closing ${closingPattern}`,
+        );
+      }
+      elementEnd = matchEnd;
+    }
+
+    const rawXml = xml.slice(elementStart, elementEnd);
+    children.push({ localName, rawXml, interstitialBefore: interstitial });
+    cursor = elementEnd;
+  }
+
+  return { children, trailing: "" };
+}
+
+function skipInterstitial(xml: string, from: number, end: number): number {
+  let cursor = from;
+  while (cursor < end) {
+    if (xml.startsWith("<!--", cursor)) {
+      const stop = xml.indexOf("-->", cursor);
+      if (stop < 0 || stop + 3 > end) return cursor;
+      cursor = stop + 3;
+      continue;
+    }
+    if (xml.startsWith("<?", cursor)) {
+      const stop = xml.indexOf("?>", cursor);
+      if (stop < 0 || stop + 2 > end) return cursor;
+      cursor = stop + 2;
+      continue;
+    }
+    const ch = xml[cursor];
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      cursor++;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
+function readLocalNameFromOpenTag(tag: string): string {
+  // tag looks like '<w:foo attr="bar"/>' or '<foo>' or '<w:foo>'.
+  const inside = tag.slice(1, tag.endsWith("/>") ? -2 : -1).trim();
+  const space = inside.search(/\s/u);
+  const qualified = space < 0 ? inside : inside.slice(0, space);
+  const colon = qualified.indexOf(":");
+  return colon < 0 ? qualified : qualified.slice(colon + 1);
+}
+
+function getQualifiedName(tag: string): string {
+  const inside = tag.slice(1, tag.endsWith("/>") ? -2 : -1).trim();
+  const space = inside.search(/\s/u);
+  return space < 0 ? inside : inside.slice(0, space);
+}
+
+function findMatchingClose(
+  xml: string,
+  from: number,
+  end: number,
+  qualifiedName: string,
+): number {
+  // Walk forward, tracking nesting depth for elements with the same
+  // qualifiedName so nested same-name elements don't terminate early.
+  const openPattern = `<${qualifiedName}`;
+  const closePattern = `</${qualifiedName}>`;
+  let cursor = from;
+  let depth = 1;
+  while (cursor < end) {
+    // Skip comments + PIs so a '<' inside a comment doesn't count.
+    if (xml.startsWith("<!--", cursor)) {
+      const stop = xml.indexOf("-->", cursor);
+      if (stop < 0 || stop + 3 > end) return -1;
+      cursor = stop + 3;
+      continue;
+    }
+    if (xml.startsWith("<?", cursor)) {
+      const stop = xml.indexOf("?>", cursor);
+      if (stop < 0 || stop + 2 > end) return -1;
+      cursor = stop + 2;
+      continue;
+    }
+    if (xml.startsWith(closePattern, cursor)) {
+      depth--;
+      if (depth === 0) {
+        return cursor + closePattern.length;
+      }
+      cursor += closePattern.length;
+      continue;
+    }
+    if (xml.startsWith(openPattern, cursor)) {
+      // Verify the next char makes this a real same-name open tag (not e.g.
+      // <w:compatSetting when looking for <w:compat).
+      const after = cursor + openPattern.length;
+      const ch = xml[after];
+      if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === ">" || ch === "/") {
+        // Find tag end to know whether it's self-closing.
+        const tagEnd = findTagEnd(xml, cursor);
+        if (tagEnd < 0 || tagEnd >= end) return -1;
+        if (xml[tagEnd - 1] !== "/") {
+          depth++;
+        }
+        cursor = tagEnd + 1;
+        continue;
+      }
+    }
+    cursor++;
+  }
+  return -1;
+}

package/src/io/ooxml/parse-settings.ts

@@ -1,4 +1,7 @@
-import type { DocumentSettings } from "../../model/canonical-document.ts";
+import type {
+  CompatSetting,
+  DocumentSettings,
+} from "../../model/canonical-document.ts";
 
 interface XmlElementNode {
   type: "element";
@@ -27,6 +30,11 @@ export function parseSettingsXml(xml: string): DocumentSettings {
 
   const evenAndOddHeaders = findChildElementOptional(settingsElement, "evenAndOddHeaders");
   const zoom = findChildElementOptional(settingsElement, "zoom");
+  const compat = findChildElementOptional(settingsElement, "compat");
+  const compatPartition = compat ? partitionCompat(compat) : undefined;
+  const rootCompatFlags = readRootCompatFlags(settingsElement);
+  const themeFontLangElement = findChildElementOptional(settingsElement, "themeFontLang");
+  const unmodelled = readUnmodelledSettingsChildren(settingsElement);
 
   return {
     ...(evenAndOddHeaders
@@ -35,9 +43,97 @@ export function parseSettingsXml(xml: string): DocumentSettings {
         }
       : {}),
     ...(zoom ? readZoomLevel(zoom) : {}),
+    ...(compatPartition && compatPartition.compatSettings.length > 0
+      ? { compatSettings: compatPartition.compatSettings }
+      : {}),
+    ...(compatPartition && Object.keys(compatPartition.compatFlags).length > 0
+      ? { compatFlags: compatPartition.compatFlags }
+      : {}),
+    ...(Object.keys(rootCompatFlags).length > 0 ? { rootCompatFlags } : {}),
+    ...(themeFontLangElement
+      ? { themeFontLang: { ...themeFontLangElement.attributes } }
+      : {}),
+    ...(unmodelled.length > 0 ? { unmodelledSettingsChildren: unmodelled } : {}),
   };
 }
 
+/**
+ * Modelled top-level <w:settings> child local names. Anything not in this
+ * set (and not in ROOT_COMPAT_FLAG_NAMES) ends up in
+ * `unmodelledSettingsChildren` for the Phase 2 serializer to validate.
+ */
+const MODELLED_SETTINGS_CHILD_NAMES = new Set<string>([
+  "evenAndOddHeaders",
+  "zoom",
+  "compat",
+  "themeFontLang",
+]);
+
+function readUnmodelledSettingsChildren(
+  settingsElement: XmlElementNode,
+): string[] {
+  const names: string[] = [];
+  for (const child of settingsElement.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+    if (MODELLED_SETTINGS_CHILD_NAMES.has(local)) continue;
+    if (ROOT_COMPAT_FLAG_NAMES.has(local)) continue;
+    names.push(local);
+  }
+  return names;
+}
+
+/**
+ * Settings-level compat-adjacent flag elements (NOT inside <w:compat>) that
+ * the strict OpenXML SDK validator flags. Kept as a small allow-list; extend
+ * as the corpus reveals more.
+ *
+ * Exported because the export-side graft serializer
+ * (`src/io/export/serialize-settings.ts`) needs the same allow-list to know
+ * which top-level source children are "modelled" and therefore subject to
+ * canonical replacement.
+ */
+export const ROOT_COMPAT_FLAG_NAMES: ReadonlySet<string> = new Set<string>([
+  "doNotEmbedSmartTags",
+]);
+
+function readRootCompatFlags(
+  settingsElement: XmlElementNode,
+): Record<string, boolean> {
+  const flags: Record<string, boolean> = {};
+  for (const child of settingsElement.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+    if (!ROOT_COMPAT_FLAG_NAMES.has(local)) continue;
+    flags[local] = readOnOffValue(child, true);
+  }
+  return flags;
+}
+
+interface CompatPartition {
+  compatSettings: CompatSetting[];
+  compatFlags: Record<string, boolean>;
+}
+
+function partitionCompat(compatElement: XmlElementNode): CompatPartition {
+  const compatSettings: CompatSetting[] = [];
+  const compatFlags: Record<string, boolean> = {};
+  for (const child of compatElement.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+    if (local === "compatSetting") {
+      compatSettings.push({
+        name: child.attributes["w:name"] ?? child.attributes.name ?? "",
+        uri: child.attributes["w:uri"] ?? child.attributes.uri ?? "",
+        value: child.attributes["w:val"] ?? child.attributes.val ?? "",
+      });
+      continue;
+    }
+    compatFlags[local] = readOnOffValue(child, true);
+  }
+  return { compatSettings, compatFlags };
+}
+
 function findChildElementOptional(
   node: XmlElementNode,
   childLocalName: string,

package/src/io/ooxml/parse-styles.ts

@@ -153,6 +153,7 @@ export function parseStylesXml(xml: string): ParseStylesResult {
       switch (styleType) {
         case "paragraph": {
           const nextStyle = readLinkedStyleId(child, "next");
+          const linkedStyleId = readLinkedStyleId(child, "link");
           const outlineLevel = readParagraphStyleOutlineLevel(child);
           const numbering = readParagraphStyleNumbering(child);
           const pPrNode = findChildElementOptional(child, "pPr");
@@ -170,10 +171,12 @@ export function parseStylesXml(xml: string): ParseStylesResult {
             ...(numbering ? { numbering } : {}),
             ...(paragraphProperties ? { paragraphProperties } : {}),
             ...(runProperties ? { runProperties } : {}),
+            ...(linkedStyleId ? { linkedStyleId } : {}),
           };
           break;
         }
         case "character": {
+          const linkedStyleId = readLinkedStyleId(child, "link");
           const rPrNode = findChildElementOptional(child, "rPr");
           const runProperties = readRunProperties(rPrNode);
           characters[styleId] = {
@@ -183,6 +186,7 @@ export function parseStylesXml(xml: string): ParseStylesResult {
             isDefault,
             ...(basedOn ? { basedOn } : {}),
             ...(runProperties ? { runProperties } : {}),
+            ...(linkedStyleId ? { linkedStyleId } : {}),
           };
           break;
         }
@@ -209,6 +213,8 @@ export function parseStylesXml(xml: string): ParseStylesResult {
     }
   }
 
+  resolveStyleLinkReciprocals(paragraphs, characters, diagnostics);
+
   const hasLatent = Object.keys(latentStyles).length > 0;
   diagnostics.push(
     `parsed ${Object.keys(paragraphs).length} paragraph, ` +
@@ -250,6 +256,65 @@ function readLinkedStyleId(
   return el.attributes["w:val"] ?? el.attributes.val ?? undefined;
 }
 
+/**
+ * Second-pass resolver for `<w:link>` on paragraph ↔ character style pairs.
+ *
+ * Mirrors LibreOffice's StyleSheetTable.cxx around line 1533 ("Update the
+ * styles that were created before their linked styles"): after every style
+ * is ingested, walk the two catalogs and synthesize the reciprocal
+ * `linkedStyleId` on a partner whose source XML declared no `<w:link>` of
+ * its own. This makes the canonical catalog symmetric regardless of source
+ * declaration order.
+ *
+ * Conflict handling is conservative: if a style already declares its own
+ * linkedStyleId pointing at a different target, the existing value is left
+ * intact and a diagnostic is emitted so a future debugger can trace the
+ * conflicting source-side assertions.
+ *
+ * Dangling references (a `<w:link>` that points at a styleId not in either
+ * catalog) are preserved verbatim and logged as a diagnostic — matching
+ * LibreOffice's "keep the XML, warn the author" stance.
+ */
+function resolveStyleLinkReciprocals(
+  paragraphs: Record<string, ParagraphStyleDefinition>,
+  characters: Record<string, CharacterStyleDefinition>,
+  diagnostics: string[],
+): void {
+  const walkers: Array<{
+    catalog:
+      | Record<string, ParagraphStyleDefinition>
+      | Record<string, CharacterStyleDefinition>;
+    partnerCatalog:
+      | Record<string, ParagraphStyleDefinition>
+      | Record<string, CharacterStyleDefinition>;
+    label: string;
+  }> = [
+    { catalog: paragraphs, partnerCatalog: characters, label: "paragraph" },
+    { catalog: characters, partnerCatalog: paragraphs, label: "character" },
+  ];
+
+  for (const { catalog, partnerCatalog, label } of walkers) {
+    for (const style of Object.values(catalog)) {
+      const target = style.linkedStyleId;
+      if (!target) continue;
+      const partner = partnerCatalog[target];
+      if (!partner) {
+        diagnostics.push(
+          `style ${label} "${style.styleId}" declares <w:link w:val="${target}"/> but no matching ${label === "paragraph" ? "character" : "paragraph"} style was found; link preserved as dangling`,
+        );
+        continue;
+      }
+      if (partner.linkedStyleId === undefined) {
+        partner.linkedStyleId = style.styleId;
+      } else if (partner.linkedStyleId !== style.styleId) {
+        diagnostics.push(
+          `style ${label} "${style.styleId}" links to "${target}" but partner already links to "${partner.linkedStyleId}"; partner link retained`,
+        );
+      }
+    }
+  }
+}
+
 function readParagraphStyleOutlineLevel(
   styleNode: XmlElementNode,
 ): number | undefined {