@beyondwork/docx-react-component 1.0.29 → 1.0.31

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

@@ -0,0 +1,639 @@
+/**
+ * Parse styles.xml into the canonical StylesCatalog.
+ *
+ * Reads paragraph, character, and table style definitions plus latent-style
+ * metadata from the package styles part. This makes styles.xml the canonical
+ * source of style truth instead of synthesizing display names from referenced
+ * styleId values.
+ */
+
+import type {
+  CellShading,
+  CharacterStyleDefinition,
+  LatentStyleDefinition,
+  ParagraphStyleDefinition,
+  StylesCatalog,
+  TableBorders,
+  TableCellBorders,
+  TableCellMargins,
+  TableLook,
+  TableStyleConditionalRegion,
+  TableStyleDefinition,
+  TableStyleFormatting,
+  TableWidth,
+} from "../../model/canonical-document.ts";
+import {
+  readCellBorders,
+  readCellShading,
+  readCellVerticalAlign,
+  readCellWidth,
+  readRowHeight,
+  readRowHeightRule,
+  readRowIsHeader,
+  readTableAlignment,
+  readTableBorders,
+  readTableCellMargins,
+  readTableLook,
+  readTableWidth,
+} from "./parse-tables.ts";
+import { toCanonicalNumberingInstanceId } from "./parse-numbering.ts";
+
+// ---------------------------------------------------------------------------
+// Inline XML node types (same pattern as parse-numbering.ts)
+// ---------------------------------------------------------------------------
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+  start: number;
+  end: number;
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+  start: number;
+  end: number;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface ParseStylesResult {
+  catalog: StylesCatalog;
+  /** True when the catalog was parsed from actual styles.xml content. */
+  fromPackage: boolean;
+  /** Diagnostic notes for logging/proof. */
+  diagnostics: string[];
+}
+
+/**
+ * Parse a styles.xml string into a canonical StylesCatalog.
+ *
+ * Returns `fromPackage: false` when the input is empty or structurally empty,
+ * in which case the catalog fields will be empty records.
+ */
+export function parseStylesXml(xml: string): ParseStylesResult {
+  const diagnostics: string[] = [];
+
+  if (!xml || xml.trim().length === 0) {
+    diagnostics.push("styles.xml is empty; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  let root: XmlElementNode;
+  try {
+    root = parseXml(xml);
+  } catch {
+    diagnostics.push("styles.xml could not be parsed; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  const stylesElement = findChildElementOptional(root, "styles");
+  if (!stylesElement) {
+    diagnostics.push("styles.xml has no <w:styles> root; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  const paragraphs: Record<string, ParagraphStyleDefinition> = {};
+  const characters: Record<string, CharacterStyleDefinition> = {};
+  const tables: Record<string, TableStyleDefinition> = {};
+  const latentStyles: Record<string, LatentStyleDefinition> = {};
+
+  for (const child of stylesElement.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+
+    if (local === "style") {
+      const styleType = child.attributes["w:type"] ?? child.attributes.type;
+      const styleId = child.attributes["w:styleId"] ?? child.attributes.styleId;
+      if (!styleId) continue;
+
+      const displayName = readStyleDisplayName(child) ?? styleId;
+      const basedOn = readLinkedStyleId(child, "basedOn");
+      const isDefault = (child.attributes["w:default"] ?? child.attributes.default) === "1";
+
+      switch (styleType) {
+        case "paragraph": {
+          const nextStyle = readLinkedStyleId(child, "next");
+          const outlineLevel = readParagraphStyleOutlineLevel(child);
+          const numbering = readParagraphStyleNumbering(child);
+          paragraphs[styleId] = {
+            styleId,
+            displayName,
+            kind: "paragraph",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+            ...(nextStyle ? { nextStyle } : {}),
+            ...(outlineLevel !== undefined ? { outlineLevel } : {}),
+            ...(numbering ? { numbering } : {}),
+          };
+          break;
+        }
+        case "character": {
+          characters[styleId] = {
+            styleId,
+            displayName,
+            kind: "character",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+          };
+          break;
+        }
+        case "table": {
+          const formatting = readTableStyleFormatting(child);
+          const conditionalFormatting = readTableConditionalFormatting(child);
+          tables[styleId] = {
+            styleId,
+            displayName,
+            kind: "table",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+            ...(formatting ? { formatting } : {}),
+            ...(conditionalFormatting ? { conditionalFormatting } : {}),
+          };
+          break;
+        }
+        default:
+          // numbering/list styles are not part of the canonical catalog
+          break;
+      }
+    } else if (local === "latentStyles") {
+      readLatentStyles(child, latentStyles);
+    }
+  }
+
+  const hasLatent = Object.keys(latentStyles).length > 0;
+  diagnostics.push(
+    `parsed ${Object.keys(paragraphs).length} paragraph, ` +
+      `${Object.keys(characters).length} character, ` +
+      `${Object.keys(tables).length} table styles` +
+      (hasLatent ? `, ${Object.keys(latentStyles).length} latent styles` : ""),
+  );
+
+  return {
+    catalog: {
+      paragraphs,
+      characters,
+      tables,
+      ...(hasLatent ? { latentStyles } : {}),
+    },
+    fromPackage: true,
+    diagnostics,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readStyleDisplayName(styleNode: XmlElementNode): string | undefined {
+  const nameEl = findChildElementOptional(styleNode, "name");
+  if (!nameEl) return undefined;
+  return nameEl.attributes["w:val"] ?? nameEl.attributes.val ?? undefined;
+}
+
+function readLinkedStyleId(
+  styleNode: XmlElementNode,
+  elementLocalName: string,
+): string | undefined {
+  const el = findChildElementOptional(styleNode, elementLocalName);
+  if (!el) return undefined;
+  return el.attributes["w:val"] ?? el.attributes.val ?? undefined;
+}
+
+function readParagraphStyleOutlineLevel(
+  styleNode: XmlElementNode,
+): number | undefined {
+  const paragraphProperties = findChildElementOptional(styleNode, "pPr");
+  if (!paragraphProperties) {
+    return undefined;
+  }
+
+  const outlineLevel = findChildElementOptional(paragraphProperties, "outlineLvl");
+  if (!outlineLevel) {
+    return undefined;
+  }
+
+  const rawValue = outlineLevel.attributes["w:val"] ?? outlineLevel.attributes.val;
+  const parsed = rawValue !== undefined ? Number.parseInt(rawValue, 10) : Number.NaN;
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function readParagraphStyleNumbering(
+  styleNode: XmlElementNode,
+): ParagraphStyleDefinition["numbering"] | undefined {
+  const paragraphProperties = findChildElementOptional(styleNode, "pPr");
+  if (!paragraphProperties) {
+    return undefined;
+  }
+
+  const numberingProperties = findChildElementOptional(paragraphProperties, "numPr");
+  if (!numberingProperties) {
+    return undefined;
+  }
+
+  const levelNode = findChildElementOptional(numberingProperties, "ilvl");
+  const instanceNode = findChildElementOptional(numberingProperties, "numId");
+  const rawInstanceId = instanceNode?.attributes["w:val"] ?? instanceNode?.attributes.val;
+  if (!rawInstanceId) {
+    return undefined;
+  }
+  if (rawInstanceId === "0") {
+    return undefined;
+  }
+
+  const rawLevel = levelNode?.attributes["w:val"] ?? levelNode?.attributes.val;
+  const parsedLevel =
+    rawLevel !== undefined ? Number.parseInt(rawLevel, 10) : Number.NaN;
+
+  return {
+    numberingInstanceId: toCanonicalNumberingInstanceId(rawInstanceId),
+    ...(Number.isInteger(parsedLevel) && parsedLevel >= 0 ? { level: parsedLevel } : {}),
+  };
+}
+function readTableStyleFormatting(styleNode: XmlElementNode): TableStyleFormatting | undefined {
+  const tableProperties = findChildElementOptional(styleNode, "tblPr");
+  const rowProperties = findChildElementOptional(styleNode, "trPr");
+  const cellProperties = findChildElementOptional(styleNode, "tcPr");
+  const formatting: TableStyleFormatting = {};
+
+  if (tableProperties) {
+    const table: NonNullable<TableStyleFormatting["table"]> = {};
+    const width = readTableWidth(tableProperties);
+    const alignment = readTableAlignment(tableProperties);
+    const borders = readTableBorders(tableProperties);
+    const cellMargins = readTableCellMargins(tableProperties);
+    const tblLook = readTableLook(tableProperties);
+
+    if (width) table.width = width as TableWidth;
+    if (alignment) table.alignment = alignment;
+    if (borders) table.borders = borders as TableBorders;
+    if (cellMargins) table.cellMargins = cellMargins as TableCellMargins;
+    if (tblLook) table.tblLook = tblLook as TableLook;
+
+    if (Object.keys(table).length > 0) {
+      formatting.table = table;
+    }
+  }
+
+  if (rowProperties) {
+    const row: NonNullable<TableStyleFormatting["row"]> = {};
+    const height = readRowHeight(rowProperties);
+    const heightRule = readRowHeightRule(rowProperties);
+    const isHeader = readRowIsHeader(rowProperties);
+
+    if (height !== undefined) row.height = height;
+    if (heightRule) row.heightRule = heightRule;
+    if (isHeader !== undefined) row.isHeader = isHeader;
+
+    if (Object.keys(row).length > 0) {
+      formatting.row = row;
+    }
+  }
+
+  if (cellProperties) {
+    const cell: NonNullable<TableStyleFormatting["cell"]> = {};
+    const width = readCellWidth(cellProperties);
+    const borders = readCellBorders(cellProperties);
+    const shading = readCellShading(cellProperties);
+    const verticalAlign = readCellVerticalAlign(cellProperties);
+
+    if (width) cell.width = width as TableWidth;
+    if (borders) cell.borders = borders as TableCellBorders;
+    if (shading) cell.shading = shading as CellShading;
+    if (verticalAlign) cell.verticalAlign = verticalAlign;
+
+    if (Object.keys(cell).length > 0) {
+      formatting.cell = cell;
+    }
+  }
+
+  return Object.keys(formatting).length > 0 ? formatting : undefined;
+}
+
+function readTableConditionalFormatting(
+  styleNode: XmlElementNode,
+): Partial<Record<TableStyleConditionalRegion, TableStyleFormatting>> | undefined {
+  const conditionalFormatting: Partial<Record<TableStyleConditionalRegion, TableStyleFormatting>> = {};
+
+  for (const child of styleNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "tblStylePr") {
+      continue;
+    }
+
+    const region = mapTableConditionalRegion(child.attributes["w:type"] ?? child.attributes.type);
+    if (!region) {
+      continue;
+    }
+
+    const formatting = readTableStyleFormatting(child);
+    if (formatting) {
+      conditionalFormatting[region] = formatting;
+    }
+  }
+
+  return Object.keys(conditionalFormatting).length > 0 ? conditionalFormatting : undefined;
+}
+
+function mapTableConditionalRegion(value: string | undefined): TableStyleConditionalRegion | undefined {
+  switch (value) {
+    case "firstRow":
+    case "lastRow":
+    case "band1Horz":
+    case "band2Horz":
+    case "band1Vert":
+    case "band2Vert":
+      return value;
+    case "firstCol":
+      return "firstColumn";
+    case "lastCol":
+      return "lastColumn";
+    default:
+      return undefined;
+  }
+}
+
+function readLatentStyles(
+  latentNode: XmlElementNode,
+  out: Record<string, LatentStyleDefinition>,
+): void {
+  for (const child of latentNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "lsdException") continue;
+
+    const name = child.attributes["w:name"] ?? child.attributes.name;
+    if (!name) continue;
+
+    const locked = readBoolAttr(child, "locked");
+    const semiHidden = readBoolAttr(child, "semiHidden");
+    const unhideWhenUsed = readBoolAttr(child, "unhideWhenUsed");
+    const qFormat = readBoolAttr(child, "qFormat");
+    const rawPriority = child.attributes["w:uiPriority"] ?? child.attributes.uiPriority;
+    const uiPriority = rawPriority !== undefined ? Number.parseInt(rawPriority, 10) : undefined;
+
+    out[name] = {
+      name,
+      ...(locked !== undefined ? { locked } : {}),
+      ...(semiHidden !== undefined ? { semiHidden } : {}),
+      ...(unhideWhenUsed !== undefined ? { unhideWhenUsed } : {}),
+      ...(qFormat !== undefined ? { qFormat } : {}),
+      ...(uiPriority !== undefined && !Number.isNaN(uiPriority) ? { uiPriority } : {}),
+    };
+  }
+}
+
+function readBoolAttr(node: XmlElementNode, attrLocalName: string): boolean | undefined {
+  const val = node.attributes[`w:${attrLocalName}`] ?? node.attributes[attrLocalName];
+  if (val === undefined) return undefined;
+  return val === "1" || val === "true";
+}
+
+// ---------------------------------------------------------------------------
+// Inline XML parser (same implementation as parse-numbering.ts)
+// ---------------------------------------------------------------------------
+
+function findChildElementOptional(
+  node: XmlElementNode,
+  childLocalName: string,
+): XmlElementNode | undefined {
+  return node.children.find(
+    (entry): entry is XmlElementNode =>
+      entry.type === "element" && localName(entry.name) === childLocalName,
+  );
+}
+
+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;
+    }
+    const rawValue = tagBody.slice(valueStart, cursor);
+    attributes[key] = decodeXmlEntities(rawValue);
+    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;
+    }
+  });
+}