@beyondwork/docx-react-component 1.0.58 → 1.0.59

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

@@ -16,6 +16,9 @@ export interface XmlTextNode {
 
 export type XmlNode = XmlElementNode | XmlTextNode;
 
+import { parseXmlWithOffsets } from "./xml-parser.ts";
+import { localName, readStringAttr } from "./xml-attr-helpers.ts";
+
 export interface ParsedBorderSpec {
   value?: string;
   size?: number;
@@ -50,6 +53,13 @@ export interface ParsedCellShading {
   fill?: string;
   color?: string;
   val?: string;
+  /** SOW gap G3 — theme-fill references kept verbatim for runtime resolve + round-trip. */
+  themeFill?: string;
+  themeFillTint?: string;
+  themeFillShade?: string;
+  themeColor?: string;
+  themeColorTint?: string;
+  themeColorShade?: string;
 }
 
 export interface ParsedCellMargins {
@@ -143,7 +153,7 @@ export interface ParsedTableCell {
 }
 
 export function parseTablesFromDocumentXml(xml: string): ParsedTableDocument {
-  const root = parseXml(xml);
+  const root = parseXmlWithOffsets(xml) as XmlElementNode;
   const documentElement = findChildElement(root, "document");
   const bodyElement = findChildElement(documentElement, "body");
 
@@ -241,7 +251,7 @@ function parseCell(node: XmlElementNode, sourceXml: string): ParsedTableCell {
 
   return {
     ...(propertiesNode ? { propertiesXml: sourceXml.slice(propertiesNode.start, propertiesNode.end) } : {}),
-    ...(gridSpanNode ? { gridSpan: parsePositiveInteger(gridSpanNode.attributes["w:val"] ?? gridSpanNode.attributes.val) } : {}),
+    ...(gridSpanNode ? { gridSpan: parsePositiveInteger(readStringAttr(gridSpanNode, "w:val")) } : {}),
     ...(verticalMergeNode ? { verticalMerge: readVerticalMerge(verticalMergeNode) } : {}),
     blocksXml,
     rawXml: sourceXml.slice(node.start, node.end),
@@ -260,11 +270,11 @@ function parseCell(node: XmlElementNode, sourceXml: string): ParsedTableCell {
 export function readGridColumns(node: XmlElementNode): number[] {
   return node.children
     .filter((child): child is XmlElementNode => child.type === "element" && localName(child.name) === "gridCol")
-    .map((child) => parsePositiveInteger(child.attributes["w:w"] ?? child.attributes.w ?? "0"));
+    .map((child) => parsePositiveInteger(readStringAttr(child, "w:w") ?? "0"));
 }
 
 function readVerticalMerge(node: XmlElementNode): "restart" | "continue" {
-  const value = (node.attributes["w:val"] ?? node.attributes.val ?? "continue").toLowerCase();
+  const value = (readStringAttr(node, "w:val") ?? "continue").toLowerCase();
   return value === "restart" ? "restart" : "continue";
 }
 
@@ -289,229 +299,14 @@ function findFirstChild(node: XmlElementNode, childLocalName: string): XmlElemen
   );
 }
 
-function localName(name: string): string {
-  const separatorIndex = name.indexOf(":");
-  return separatorIndex >= 0 ? name.slice(separatorIndex + 1) : name;
-}
-
-function parseXml(xml: string): XmlElementNode {
-  const root: XmlElementNode = {
-    type: "element",
-    name: "__root__",
-    attributes: {},
-    children: [],
-    start: 0,
-    end: xml.length,
-  };
-  const stack: XmlElementNode[] = [root];
-  let cursor = 0;
-
-  while (cursor < xml.length) {
-    if (xml.startsWith("<!--", cursor)) {
-      const end = xml.indexOf("-->", cursor);
-      cursor = end >= 0 ? end + 3 : xml.length;
-      continue;
-    }
-
-    if (xml.startsWith("<?", cursor)) {
-      const end = xml.indexOf("?>", cursor);
-      cursor = end >= 0 ? end + 2 : xml.length;
-      continue;
-    }
-
-    if (xml.startsWith("<![CDATA[", cursor)) {
-      const end = xml.indexOf("]]>", cursor);
-      const textEnd = end >= 0 ? end : xml.length;
-      stack[stack.length - 1]?.children.push({
-        type: "text",
-        text: xml.slice(cursor + 9, textEnd),
-        start: cursor,
-        end: end >= 0 ? end + 3 : xml.length,
-      });
-      cursor = end >= 0 ? end + 3 : xml.length;
-      continue;
-    }
-
-    if (xml[cursor] !== "<") {
-      const nextTag = xml.indexOf("<", cursor);
-      const end = nextTag >= 0 ? nextTag : xml.length;
-      const text = decodeXmlEntities(xml.slice(cursor, end));
-      if (text.length > 0) {
-        stack[stack.length - 1]?.children.push({
-          type: "text",
-          text,
-          start: cursor,
-          end,
-        });
-      }
-      cursor = end;
-      continue;
-    }
-
-    if (xml[cursor + 1] === "/") {
-      const end = xml.indexOf(">", cursor);
-      if (end < 0) {
-        throw new Error("Malformed XML: missing closing >.");
-      }
-
-      const name = xml.slice(cursor + 2, end).trim();
-      const current = stack.pop();
-      if (!current || localName(current.name) !== localName(name)) {
-        throw new Error(`Malformed XML: unexpected closing tag </${name}>.`);
-      }
-      current.end = end + 1;
-      cursor = end + 1;
-      continue;
-    }
-
-    const tagEnd = findTagEnd(xml, cursor);
-    const tagBody = xml.slice(cursor + 1, tagEnd);
-    const selfClosing = /\/\s*$/.test(tagBody);
-    const { name, attributes } = parseTag(tagBody.replace(/\/\s*$/, "").trim());
-    const element: XmlElementNode = {
-      type: "element",
-      name,
-      attributes,
-      children: [],
-      start: cursor,
-      end: tagEnd + 1,
-    };
-    stack[stack.length - 1]?.children.push(element);
-
-    if (!selfClosing) {
-      stack.push(element);
-    }
-
-    cursor = tagEnd + 1;
-  }
-
-  if (stack.length !== 1) {
-    throw new Error("Malformed XML: unclosed element.");
-  }
-
-  return root;
-}
-
-function parseTag(tagBody: string): { name: string; attributes: Record<string, string> } {
-  let cursor = 0;
-  while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-    cursor += 1;
-  }
-
-  const nameStart = cursor;
-  while (cursor < tagBody.length && !/\s/.test(tagBody[cursor] ?? "")) {
-    cursor += 1;
-  }
-  const name = tagBody.slice(nameStart, cursor);
-  const attributes: Record<string, string> = {};
-
-  while (cursor < tagBody.length) {
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-    if (cursor >= tagBody.length) {
-      break;
-    }
-
-    const keyStart = cursor;
-    while (cursor < tagBody.length && !/[\s=]/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-    const key = tagBody.slice(keyStart, cursor);
-
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-
-    if (tagBody[cursor] !== "=") {
-      attributes[key] = "";
-      continue;
-    }
-    cursor += 1;
-
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-
-    const quote = tagBody[cursor];
-    if (quote !== `"` && quote !== `'`) {
-      throw new Error(`Malformed XML attribute ${key}.`);
-    }
-    cursor += 1;
-
-    const valueStart = cursor;
-    while (cursor < tagBody.length && tagBody[cursor] !== quote) {
-      cursor += 1;
-    }
-    attributes[key] = decodeXmlEntities(tagBody.slice(valueStart, cursor));
-    cursor += 1;
-  }
-
-  return { name, attributes };
-}
-
-function findTagEnd(xml: string, start: number): number {
-  let cursor = start + 1;
-  let quote: string | null = null;
-
-  while (cursor < xml.length) {
-    const current = xml[cursor];
-    if (quote) {
-      if (current === quote) {
-        quote = null;
-      }
-      cursor += 1;
-      continue;
-    }
-
-    if (current === `"` || current === `'`) {
-      quote = current;
-      cursor += 1;
-      continue;
-    }
-
-    if (current === ">") {
-      return cursor;
-    }
-
-    cursor += 1;
-  }
-
-  throw new Error("Malformed XML: missing >.");
-}
-
-function decodeXmlEntities(value: string): string {
-  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (match, entity) => {
-    switch (entity) {
-      case "amp":
-        return "&";
-      case "lt":
-        return "<";
-      case "gt":
-        return ">";
-      case "quot":
-        return `"`;
-      case "apos":
-        return "'";
-      default:
-        if (entity.startsWith("#x")) {
-          return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
-        }
-        if (entity.startsWith("#")) {
-          return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
-        }
-        return match;
-    }
-  });
-}
 
 // Cell property readers
 
 export function readCellWidth(propertiesNode: XmlElementNode): ParsedTableWidth | undefined {
   const widthNode = findFirstChild(propertiesNode, "tcW");
   if (!widthNode) return undefined;
-  const value = parsePositiveInteger(widthNode.attributes["w:w"] ?? widthNode.attributes.w);
-  const rawType = (widthNode.attributes["w:type"] ?? widthNode.attributes.type ?? "dxa").toLowerCase();
+  const value = parsePositiveInteger(readStringAttr(widthNode, "w:w"));
+  const rawType = (readStringAttr(widthNode, "w:type") ?? "dxa").toLowerCase();
   const type: ParsedTableWidth["type"] =
     rawType === "auto" ? "auto" : rawType === "pct" ? "pct" : rawType === "nil" ? "nil" : "dxa";
   return { value, type };
@@ -534,21 +329,46 @@ export function readCellBorders(propertiesNode: XmlElementNode): ParsedTableCell
 export function readCellShading(propertiesNode: XmlElementNode): ParsedCellShading | undefined {
   const shdNode = findFirstChild(propertiesNode, "shd");
   if (!shdNode) return undefined;
-  const fill = shdNode.attributes["w:fill"] ?? shdNode.attributes.fill;
-  const color = shdNode.attributes["w:color"] ?? shdNode.attributes.color;
-  const val = shdNode.attributes["w:val"] ?? shdNode.attributes.val;
-  if (!fill && !color && !val) return undefined;
+  const fill = readStringAttr(shdNode, "w:fill");
+  const color = readStringAttr(shdNode, "w:color");
+  const val = readStringAttr(shdNode, "w:val");
+  // SOW gap G3 — theme-shading refs. The CCEP SOW uses
+  // `<w:shd w:themeFill="accent5" w:themeFillTint="33"/>` on the Appendix-1
+  // mid-table sub-rows; when `w:fill` is absent or "auto", the runtime
+  // resolves the paint via ThemeColorResolver.resolveWordThemeColor so the
+  // cell picks up the theme cascade rather than rendering unshaded.
+  const themeFill = readStringAttr(shdNode, "w:themeFill");
+  const themeFillTint = readStringAttr(shdNode, "w:themeFillTint");
+  const themeFillShade = readStringAttr(shdNode, "w:themeFillShade");
+  const themeColor = readStringAttr(shdNode, "w:themeColor");
+  const themeColorTint = readStringAttr(shdNode, "w:themeColorTint");
+  const themeColorShade = readStringAttr(shdNode, "w:themeColorShade");
+  if (
+    !fill &&
+    !color &&
+    !val &&
+    !themeFill &&
+    !themeColor
+  ) {
+    return undefined;
+  }
   const result: ParsedCellShading = {};
   if (fill) result.fill = fill;
   if (color) result.color = color;
   if (val) result.val = val;
+  if (themeFill) result.themeFill = themeFill;
+  if (themeFillTint) result.themeFillTint = themeFillTint;
+  if (themeFillShade) result.themeFillShade = themeFillShade;
+  if (themeColor) result.themeColor = themeColor;
+  if (themeColorTint) result.themeColorTint = themeColorTint;
+  if (themeColorShade) result.themeColorShade = themeColorShade;
   return result;
 }
 
 export function readCellVerticalAlign(propertiesNode: XmlElementNode): "top" | "center" | "bottom" | undefined {
   const vAlignNode = findFirstChild(propertiesNode, "vAlign");
   if (!vAlignNode) return undefined;
-  const val = vAlignNode.attributes["w:val"] ?? vAlignNode.attributes.val;
+  const val = readStringAttr(vAlignNode, "w:val");
   if (val === "center" || val === "top" || val === "bottom") return val;
   return undefined;
 }
@@ -558,8 +378,8 @@ export function readCellVerticalAlign(propertiesNode: XmlElementNode): "top" | "
 export function readTableWidth(propertiesNode: XmlElementNode): ParsedTableWidth | undefined {
   const widthNode = findFirstChild(propertiesNode, "tblW");
   if (!widthNode) return undefined;
-  const value = parsePositiveInteger(widthNode.attributes["w:w"] ?? widthNode.attributes.w);
-  const rawType = (widthNode.attributes["w:type"] ?? widthNode.attributes.type ?? "dxa").toLowerCase();
+  const value = parsePositiveInteger(readStringAttr(widthNode, "w:w"));
+  const rawType = (readStringAttr(widthNode, "w:type") ?? "dxa").toLowerCase();
   const type: ParsedTableWidth["type"] =
     rawType === "auto" ? "auto" : rawType === "pct" ? "pct" : rawType === "nil" ? "nil" : "dxa";
   return { value, type };
@@ -568,7 +388,7 @@ export function readTableWidth(propertiesNode: XmlElementNode): ParsedTableWidth
 export function readTableAlignment(propertiesNode: XmlElementNode): "left" | "center" | "right" | undefined {
   const jcNode = findFirstChild(propertiesNode, "jc");
   if (!jcNode) return undefined;
-  const val = jcNode.attributes["w:val"] ?? jcNode.attributes.val;
+  const val = readStringAttr(jcNode, "w:val");
   if (val === "left" || val === "center" || val === "right") return val;
   return undefined;
 }
@@ -576,7 +396,7 @@ export function readTableAlignment(propertiesNode: XmlElementNode): "left" | "ce
 export function readTableStyleId(propertiesNode: XmlElementNode): string | undefined {
   const styleNode = findFirstChild(propertiesNode, "tblStyle");
   if (!styleNode) return undefined;
-  return styleNode.attributes["w:val"] ?? styleNode.attributes.val;
+  return readStringAttr(styleNode, "w:val");
 }
 
 export function readTableLook(propertiesNode: XmlElementNode): ParsedTableLook | undefined {
@@ -584,7 +404,7 @@ export function readTableLook(propertiesNode: XmlElementNode): ParsedTableLook |
   if (!tblLookNode) return undefined;
 
   const tableLook: ParsedTableLook = {};
-  const val = tblLookNode.attributes["w:val"] ?? tblLookNode.attributes.val;
+  const val = readStringAttr(tblLookNode, "w:val");
   if (val) {
     tableLook.val = val;
   }
@@ -627,7 +447,7 @@ export function readTableCellMargins(propertiesNode: XmlElementNode): ParsedCell
   const readSide = (name: string): number | undefined => {
     const node = findFirstChild(marginsNode, name);
     if (!node) return undefined;
-    return parsePositiveInteger(node.attributes["w:w"] ?? node.attributes.w);
+    return parsePositiveInteger(readStringAttr(node, "w:w"));
   };
   const top = readSide("top");
   const bottom = readSide("bottom");
@@ -650,13 +470,13 @@ export function readTableCellMargins(propertiesNode: XmlElementNode): ParsedCell
 export function readRowHeight(propertiesNode: XmlElementNode): number | undefined {
   const heightNode = findFirstChild(propertiesNode, "trHeight");
   if (!heightNode) return undefined;
-  return parsePositiveInteger(heightNode.attributes["w:val"] ?? heightNode.attributes.val);
+  return parsePositiveInteger(readStringAttr(heightNode, "w:val"));
 }
 
 export function readRowHeightRule(propertiesNode: XmlElementNode): "auto" | "atLeast" | "exact" | undefined {
   const heightNode = findFirstChild(propertiesNode, "trHeight");
   if (!heightNode) return undefined;
-  const raw = (heightNode.attributes["w:hRule"] ?? heightNode.attributes.hRule ?? "").toLowerCase();
+  const raw = (readStringAttr(heightNode, "w:hRule") ?? "").toLowerCase();
   if (raw === "atleast") return "atLeast";
   if (raw === "exact") return "exact";
   if (raw === "auto") return "auto";
@@ -666,17 +486,17 @@ export function readRowHeightRule(propertiesNode: XmlElementNode): "auto" | "atL
 export function readRowIsHeader(propertiesNode: XmlElementNode): boolean | undefined {
   const headerNode = findFirstChild(propertiesNode, "tblHeader");
   if (!headerNode) return undefined;
-  const val = headerNode.attributes["w:val"] ?? headerNode.attributes.val;
+  const val = readStringAttr(headerNode, "w:val");
   return val !== "false" && val !== "0";
 }
 
 export function readTableIndent(propertiesNode: XmlElementNode): ParsedTableIndent | undefined {
   const indentNode = findFirstChild(propertiesNode, "tblInd");
   if (!indentNode) return undefined;
-  const valueRaw = indentNode.attributes["w:w"] ?? indentNode.attributes.w;
+  const valueRaw = readStringAttr(indentNode, "w:w");
   const value = valueRaw !== undefined ? Number.parseInt(valueRaw, 10) : 0;
   if (!Number.isFinite(value)) return undefined;
-  const rawType = (indentNode.attributes["w:type"] ?? indentNode.attributes.type ?? "dxa").toLowerCase();
+  const rawType = (readStringAttr(indentNode, "w:type") ?? "dxa").toLowerCase();
   const type: ParsedTableIndent["type"] =
     rawType === "auto" ? "auto" : rawType === "pct" ? "pct" : rawType === "nil" ? "nil" : "dxa";
   return { value, type };
@@ -685,7 +505,7 @@ export function readTableIndent(propertiesNode: XmlElementNode): ParsedTableInde
 export function readTableLayoutMode(propertiesNode: XmlElementNode): "fixed" | "autofit" | undefined {
   const layoutNode = findFirstChild(propertiesNode, "tblLayout");
   if (!layoutNode) return undefined;
-  const raw = (layoutNode.attributes["w:type"] ?? layoutNode.attributes.type ?? "").toLowerCase();
+  const raw = (readStringAttr(layoutNode, "w:type") ?? "").toLowerCase();
   if (raw === "fixed") return "fixed";
   if (raw === "autofit") return "autofit";
   return undefined;
@@ -694,10 +514,10 @@ export function readTableLayoutMode(propertiesNode: XmlElementNode): "fixed" | "
 export function readTableCellSpacing(propertiesNode: XmlElementNode): ParsedTableWidth | undefined {
   const spacingNode = findFirstChild(propertiesNode, "tblCellSpacing");
   if (!spacingNode) return undefined;
-  const valueRaw = spacingNode.attributes["w:w"] ?? spacingNode.attributes.w;
+  const valueRaw = readStringAttr(spacingNode, "w:w");
   const value = valueRaw !== undefined ? Number.parseInt(valueRaw, 10) : 0;
   if (!Number.isFinite(value)) return undefined;
-  const rawType = (spacingNode.attributes["w:type"] ?? spacingNode.attributes.type ?? "dxa").toLowerCase();
+  const rawType = (readStringAttr(spacingNode, "w:type") ?? "dxa").toLowerCase();
   const type: ParsedTableWidth["type"] =
     rawType === "auto" ? "auto" : rawType === "pct" ? "pct" : rawType === "nil" ? "nil" : "dxa";
   return { value, type };
@@ -706,19 +526,19 @@ export function readTableCellSpacing(propertiesNode: XmlElementNode): ParsedTabl
 export function readTableCaption(propertiesNode: XmlElementNode): string | undefined {
   const captionNode = findFirstChild(propertiesNode, "tblCaption");
   if (!captionNode) return undefined;
-  return captionNode.attributes["w:val"] ?? captionNode.attributes.val;
+  return readStringAttr(captionNode, "w:val");
 }
 
 export function readTableDescription(propertiesNode: XmlElementNode): string | undefined {
   const descriptionNode = findFirstChild(propertiesNode, "tblDescription");
   if (!descriptionNode) return undefined;
-  return descriptionNode.attributes["w:val"] ?? descriptionNode.attributes.val;
+  return readStringAttr(descriptionNode, "w:val");
 }
 
 export function readTableBidiVisual(propertiesNode: XmlElementNode): boolean | undefined {
   const bidiNode = findFirstChild(propertiesNode, "bidiVisual");
   if (!bidiNode) return undefined;
-  const val = bidiNode.attributes["w:val"] ?? bidiNode.attributes.val;
+  const val = readStringAttr(bidiNode, "w:val");
   return val !== "false" && val !== "0" && val !== "off";
 }
 
@@ -773,7 +593,7 @@ export function readTableFloating(propertiesNode: XmlElementNode): ParsedTableFl
   }
 
   if (overlapNode) {
-    const val = (overlapNode.attributes["w:val"] ?? overlapNode.attributes.val ?? "overlap").toLowerCase();
+    const val = (readStringAttr(overlapNode, "w:val") ?? "overlap").toLowerCase();
     floating.overlap = val === "overlap";
   }
 
@@ -783,14 +603,14 @@ export function readTableFloating(propertiesNode: XmlElementNode): ParsedTableFl
 export function readRowCantSplit(propertiesNode: XmlElementNode): boolean | undefined {
   const cantSplitNode = findFirstChild(propertiesNode, "cantSplit");
   if (!cantSplitNode) return undefined;
-  const val = cantSplitNode.attributes["w:val"] ?? cantSplitNode.attributes.val;
+  const val = readStringAttr(cantSplitNode, "w:val");
   return val !== "false" && val !== "0" && val !== "off";
 }
 
 export function readRowHorizontalAlignment(propertiesNode: XmlElementNode): "left" | "center" | "right" | undefined {
   const jcNode = findFirstChild(propertiesNode, "jc");
   if (!jcNode) return undefined;
-  const val = jcNode.attributes["w:val"] ?? jcNode.attributes.val;
+  const val = readStringAttr(jcNode, "w:val");
   if (val === "left" || val === "center" || val === "right") return val;
   return undefined;
 }
@@ -798,13 +618,13 @@ export function readRowHorizontalAlignment(propertiesNode: XmlElementNode): "lef
 export function readRowCnfStyle(propertiesNode: XmlElementNode): string | undefined {
   const cnfNode = findFirstChild(propertiesNode, "cnfStyle");
   if (!cnfNode) return undefined;
-  return cnfNode.attributes["w:val"] ?? cnfNode.attributes.val;
+  return readStringAttr(cnfNode, "w:val");
 }
 
 export function readCellTextDirection(propertiesNode: XmlElementNode): "lrTb" | "tbRl" | "btLr" | undefined {
   const dirNode = findFirstChild(propertiesNode, "textDirection");
   if (!dirNode) return undefined;
-  const val = dirNode.attributes["w:val"] ?? dirNode.attributes.val;
+  const val = readStringAttr(dirNode, "w:val");
   if (val === "lrTb" || val === "tbRl" || val === "btLr") return val;
   return undefined;
 }
@@ -812,14 +632,14 @@ export function readCellTextDirection(propertiesNode: XmlElementNode): "lrTb" |
 export function readCellNoWrap(propertiesNode: XmlElementNode): boolean | undefined {
   const noWrapNode = findFirstChild(propertiesNode, "noWrap");
   if (!noWrapNode) return undefined;
-  const val = noWrapNode.attributes["w:val"] ?? noWrapNode.attributes.val;
+  const val = readStringAttr(noWrapNode, "w:val");
   return val !== "false" && val !== "0" && val !== "off";
 }
 
 export function readCellFitText(propertiesNode: XmlElementNode): boolean | undefined {
   const fitNode = findFirstChild(propertiesNode, "tcFitText");
   if (!fitNode) return undefined;
-  const val = fitNode.attributes["w:val"] ?? fitNode.attributes.val;
+  const val = readStringAttr(fitNode, "w:val");
   return val !== "false" && val !== "0" && val !== "off";
 }
 
@@ -829,7 +649,7 @@ export function readCellMargins(propertiesNode: XmlElementNode): ParsedCellMargi
   const readSide = (name: string): number | undefined => {
     const sideNode = findFirstChild(marginsNode, name);
     if (!sideNode) return undefined;
-    const raw = sideNode.attributes["w:w"] ?? sideNode.attributes.w;
+    const raw = readStringAttr(sideNode, "w:w");
     if (raw === undefined) return undefined;
     const parsed = Number.parseInt(raw, 10);
     return Number.isFinite(parsed) ? parsed : undefined;
@@ -852,14 +672,14 @@ export function readCellMargins(propertiesNode: XmlElementNode): ParsedCellMargi
 export function readCellCnfStyle(propertiesNode: XmlElementNode): string | undefined {
   const cnfNode = findFirstChild(propertiesNode, "cnfStyle");
   if (!cnfNode) return undefined;
-  return cnfNode.attributes["w:val"] ?? cnfNode.attributes.val;
+  return readStringAttr(cnfNode, "w:val");
 }
 
 function parseBorderSpec(child: XmlElementNode): ParsedBorderSpec | undefined {
-  const value = child.attributes["w:val"] ?? child.attributes.val;
-  const sizeRaw = child.attributes["w:sz"] ?? child.attributes.sz;
-  const spaceRaw = child.attributes["w:space"] ?? child.attributes.space;
-  const color = child.attributes["w:color"] ?? child.attributes.color;
+  const value = readStringAttr(child, "w:val");
+  const sizeRaw = readStringAttr(child, "w:sz");
+  const spaceRaw = readStringAttr(child, "w:space");
+  const color = readStringAttr(child, "w:color");
   if (!value && !sizeRaw && !spaceRaw && !color) return undefined;
   const spec: ParsedBorderSpec = {};
   if (value) spec.value = value;

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

@@ -8,6 +8,7 @@ import type {
 } from "../../model/canonical-document.ts";
 import type { XmlElementNode } from "./xml-element.ts";
 import { parseXml } from "./xml-parser.ts";
+import { localName } from "./xml-attr-helpers.ts";
 
 // ---- Well-known DrawingML color slot names ----
 
@@ -274,8 +275,4 @@ function findChildElementOptional(
   );
 }
 
-function localName(name: string): string {
-  const idx = name.indexOf(":");
-  return idx >= 0 ? name.slice(idx + 1) : name;
-}
 

package/src/io/ooxml/property-grab-bag.ts

@@ -23,6 +23,9 @@
  * `modelledChildNames`.
  */
 
+import type { SerializableXmlElement } from "./xml-element-serialize.ts";
+import { serializeXmlElementToString } from "./xml-element-serialize.ts";
+
 /**
  * Input node shape accepted by `capturePropertyGrabBag`. Intentionally
  * minimal so every caller can adapt their own scanner output — per-file
@@ -56,14 +59,10 @@ export interface GrabBagSourceChild {
  * the correct trade-off — unmodelled children's semantic content
  * survives, which closes the silent-drop gap.
  */
-export function buildGrabBagSourceChildFromParsed(node: {
-  name: string;
-  attributes: Record<string, string>;
-  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
-}): GrabBagSourceChild {
+export function buildGrabBagSourceChildFromParsed(node: SerializableXmlElement): GrabBagSourceChild {
   return {
     localName: localNameOf(node.name),
-    rawXml: serializeElementToString(node),
+    rawXml: serializeXmlElementToString(node),
   };
 }
 
@@ -72,47 +71,6 @@ function localNameOf(qualified: string): string {
   return colon < 0 ? qualified : qualified.slice(colon + 1);
 }
 
-function escapeAttr(value: string): string {
-  return value
-    .replace(/&/gu, "&amp;")
-    .replace(/</gu, "&lt;")
-    .replace(/>/gu, "&gt;")
-    .replace(/"/gu, "&quot;");
-}
-
-function escapeText(value: string): string {
-  return value
-    .replace(/&/gu, "&amp;")
-    .replace(/</gu, "&lt;")
-    .replace(/>/gu, "&gt;");
-}
-
-function serializeElementToString(node: {
-  name: string;
-  attributes: Record<string, string>;
-  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
-}): string {
-  const attrs = Object.entries(node.attributes)
-    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
-    .join("");
-  if (node.children.length === 0) {
-    return `<${node.name}${attrs}/>`;
-  }
-  const body = node.children
-    .map((child) => {
-      if (child.type === "text") return escapeText(child.text);
-      return serializeElementToString(
-        child as {
-          name: string;
-          attributes: Record<string, string>;
-          children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
-        },
-      );
-    })
-    .join("");
-  return `<${node.name}${attrs}>${body}</${node.name}>`;
-}
-
 /**
  * Descriptor a per-container parser supplies to the helper to declare
  * which child element names it dispatches into its modelled fields.

package/src/io/ooxml/xml-element-serialize.ts

@@ -0,0 +1,32 @@
+export interface SerializableXmlElement {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<SerializableXmlElement | { type: "text"; text: string }>;
+}
+
+export function serializeXmlElementToString(node: SerializableXmlElement): string {
+  const attrs = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeXmlAttr(value)}"`)
+    .join("");
+  if (node.children.length === 0) {
+    return `<${node.name}${attrs}/>`;
+  }
+  const body = node.children
+    .map((child) =>
+      "text" in child ? escapeXmlText(child.text) : serializeXmlElementToString(child),
+    )
+    .join("");
+  return `<${node.name}${attrs}>${body}</${node.name}>`;
+}
+
+function escapeXmlAttr(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function escapeXmlText(value: string): string {
+  return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}