@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/io/ooxml/parse-scope-markers.ts

@@ -0,0 +1,184 @@
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+} from "../../model/canonical-document.ts";
+
+/**
+ * Reserved OOXML bookmark-name prefix used to discriminate S1 scope markers
+ * from user-authored bookmarks. On export, each scope marker emits as
+ * `<w:bookmarkStart w:name="bw:scope:<scopeId>"/>` / `<w:bookmarkEnd/>`. On
+ * import, any bookmark whose name starts with this prefix is extracted as a
+ * `scope_marker_*` inline node pair and removed from the regular bookmark
+ * list so user-facing bookmark APIs stay clean.
+ */
+export const SCOPE_MARKER_BOOKMARK_PREFIX = "bw:scope:";
+
+export interface ScopeMarkerBookmark {
+  /** Serialized bookmark id (shared between start + end in the OOXML pair). */
+  bookmarkId: string;
+  /** `bw:scope:<scopeId>` — caller applies the prefix via the exported constant. */
+  name: string;
+  boundary: "start" | "end";
+  scopeId: string;
+}
+
+/**
+ * Walk a canonical document in pre-order and return one pair of bookmark
+ * descriptors for each scope-marker pair found. The returned objects are
+ * OOXML-flavor (paired `w:id`, `w:name` on start only, end references id)
+ * so callers can weave them straight into the `<w:bookmarkStart>` /
+ * `<w:bookmarkEnd>` emit path.
+ */
+export function serializeScopeMarkersToBookmarks(
+  document: CanonicalDocument | Pick<CanonicalDocument, "content">,
+): ScopeMarkerBookmark[] {
+  const root = ("content" in document
+    ? (document.content as DocumentRootNode)
+    : (document as unknown as DocumentRootNode));
+  const out: ScopeMarkerBookmark[] = [];
+  let bookmarkIdCounter = 0;
+  const scopeIdToBookmarkId = new Map<string, string>();
+
+  walkInlineNodes(root, (node) => {
+    if (node.type === "scope_marker_start") {
+      const bookmarkId = String(bookmarkIdCounter);
+      bookmarkIdCounter += 1;
+      scopeIdToBookmarkId.set(node.scopeId, bookmarkId);
+      out.push({
+        bookmarkId,
+        name: `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`,
+        boundary: "start",
+        scopeId: node.scopeId,
+      });
+    } else if (node.type === "scope_marker_end") {
+      const bookmarkId = scopeIdToBookmarkId.get(node.scopeId) ?? String(bookmarkIdCounter++);
+      out.push({
+        bookmarkId,
+        name: `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`,
+        boundary: "end",
+        scopeId: node.scopeId,
+      });
+    }
+  });
+
+  return out;
+}
+
+export interface ParsedScopeMarkerPair {
+  scopeId: string;
+  bookmarkId: string;
+  startIndex: number;
+  endIndex: number;
+}
+
+export interface RawBookmark {
+  readonly type: "bookmark_start" | "bookmark_end";
+  readonly bookmarkId: string;
+  readonly name?: string;
+  readonly index: number;
+}
+
+/**
+ * Split an OOXML bookmark list into (a) scope-marker pairs extracted via the
+ * `bw:scope:` prefix convention and (b) the remaining user bookmarks. The
+ * extraction is id-paired — a start with a prefix name pairs with the
+ * matching end by `bookmarkId`.
+ */
+export function parseScopeMarkersFromBookmarks(
+  rawBookmarks: readonly RawBookmark[],
+): { scopeMarkers: ParsedScopeMarkerPair[]; remainingBookmarks: RawBookmark[] } {
+  const scopeStartsById = new Map<
+    string,
+    { scopeId: string; startIndex: number }
+  >();
+  const scopeMarkers: ParsedScopeMarkerPair[] = [];
+  const remainingBookmarks: RawBookmark[] = [];
+
+  for (const bm of rawBookmarks) {
+    if (bm.type === "bookmark_start") {
+      const name = bm.name ?? "";
+      if (name.startsWith(SCOPE_MARKER_BOOKMARK_PREFIX)) {
+        const scopeId = name.slice(SCOPE_MARKER_BOOKMARK_PREFIX.length);
+        scopeStartsById.set(bm.bookmarkId, {
+          scopeId,
+          startIndex: bm.index,
+        });
+        continue;
+      }
+      remainingBookmarks.push(bm);
+      continue;
+    }
+
+    const open = scopeStartsById.get(bm.bookmarkId);
+    if (open) {
+      scopeMarkers.push({
+        scopeId: open.scopeId,
+        bookmarkId: bm.bookmarkId,
+        startIndex: open.startIndex,
+        endIndex: bm.index,
+      });
+      scopeStartsById.delete(bm.bookmarkId);
+      continue;
+    }
+
+    remainingBookmarks.push(bm);
+  }
+
+  return { scopeMarkers, remainingBookmarks };
+}
+
+function walkInlineNodes(
+  node: DocumentRootNode | InlineNode | { children?: unknown; rows?: unknown; cells?: unknown; type?: string },
+  visit: (inline: InlineNode) => void,
+): void {
+  if (!node || typeof node !== "object") return;
+  const nt = (node as { type?: string }).type;
+
+  // Inline leaf node: visit it.
+  if (
+    nt === "text" ||
+    nt === "tab" ||
+    nt === "hard_break" ||
+    nt === "column_break" ||
+    nt === "symbol" ||
+    nt === "image" ||
+    nt === "bookmark_start" ||
+    nt === "bookmark_end" ||
+    nt === "scope_marker_start" ||
+    nt === "scope_marker_end" ||
+    nt === "opaque_inline" ||
+    nt === "footnote_ref" ||
+    nt === "chart_preview" ||
+    nt === "smartart_preview" ||
+    nt === "shape" ||
+    nt === "wordart" ||
+    nt === "vml_shape"
+  ) {
+    visit(node as InlineNode);
+    return;
+  }
+
+  const children = (node as { children?: unknown }).children;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      walkInlineNodes(child as InlineNode, visit);
+    }
+  }
+
+  if (nt === "table") {
+    const rows = (node as { rows?: unknown }).rows;
+    if (Array.isArray(rows)) {
+      for (const row of rows) {
+        walkInlineNodes(row as InlineNode, visit);
+      }
+    }
+  } else if (nt === "table_row") {
+    const cells = (node as { cells?: unknown }).cells;
+    if (Array.isArray(cells)) {
+      for (const cell of cells) {
+        walkInlineNodes(cell as InlineNode, visit);
+      }
+    }
+  }
+}

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,