@lotics/xlsx 0.1.0

package/src/ooxml_drawing.ts

@@ -0,0 +1,287 @@
+// =============================================================================
+// OOXML Drawing Parser
+// =============================================================================
+//
+// Parses xl/drawings/drawingN.xml files to extract:
+// - Two-cell anchors with EMU offsets
+// - Chart references (rId → chart path)
+// - Shape/textbox/connector objects
+// - Image references
+// =============================================================================
+
+import type { DrawingAnchor, ParsedDrawing } from "./ooxml_chart_types";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DrawingRelation {
+  type: "chart" | "image" | "shape";
+  anchor: DrawingAnchor;
+  rId?: string;
+  drawing?: ParsedDrawing;
+}
+
+// =============================================================================
+// Parser
+// =============================================================================
+
+/**
+ * Parse a drawing XML file and extract all anchor objects.
+ */
+export function parseDrawingXml(
+  xml: string,
+  parseXml: (xml: string) => Record<string, unknown>,
+): DrawingRelation[] {
+  const doc = parseXml(xml);
+  const wsDrawing = doc["xdr:wsDr"] ?? doc["wsDr"] ?? doc;
+  if (!wsDrawing || typeof wsDrawing !== "object") return [];
+
+  const results: DrawingRelation[] = [];
+  const obj = wsDrawing as Record<string, unknown>;
+
+  // Two-cell anchors
+  const twoCellAnchors = ensureArray(obj["xdr:twoCellAnchor"] ?? obj["twoCellAnchor"]);
+  for (const anchorNode of twoCellAnchors) {
+    if (!anchorNode || typeof anchorNode !== "object") continue;
+    const anchor = parseTwoCellAnchor(anchorNode as Record<string, unknown>);
+    if (!anchor) continue;
+
+    const a = anchorNode as Record<string, unknown>;
+
+    // Check for chart frame
+    const graphicFrame = a["xdr:graphicFrame"] ?? a["graphicFrame"];
+    if (graphicFrame && typeof graphicFrame === "object") {
+      const rId = extractChartRId(graphicFrame as Record<string, unknown>);
+      if (rId) {
+        results.push({ type: "chart", anchor, rId });
+        continue;
+      }
+    }
+
+    // Check for shape
+    const sp = a["xdr:sp"] ?? a["sp"];
+    if (sp && typeof sp === "object") {
+      const drawing = parseShapeNode(sp as Record<string, unknown>, anchor);
+      results.push({ type: "shape", anchor, drawing });
+      continue;
+    }
+
+    // Check for picture (image)
+    const pic = a["xdr:pic"] ?? a["pic"];
+    if (pic && typeof pic === "object") {
+      const rId = extractPicRId(pic as Record<string, unknown>);
+      if (rId) {
+        results.push({ type: "image", anchor, rId });
+      }
+      continue;
+    }
+
+    // Check for connection shape (connector)
+    const cxnSp = a["xdr:cxnSp"] ?? a["cxnSp"];
+    if (cxnSp && typeof cxnSp === "object") {
+      const drawing = parseConnectorNode(cxnSp as Record<string, unknown>, anchor);
+      results.push({ type: "shape", anchor, drawing });
+    }
+  }
+
+  // One-cell anchors (typically for images)
+  const oneCellAnchors = ensureArray(obj["xdr:oneCellAnchor"] ?? obj["oneCellAnchor"]);
+  for (const anchorNode of oneCellAnchors) {
+    if (!anchorNode || typeof anchorNode !== "object") continue;
+    const a = anchorNode as Record<string, unknown>;
+
+    const from = parseAnchorPoint(a, "xdr:from", "from");
+    if (!from) continue;
+
+    // Use extent for width/height
+    const anchor: DrawingAnchor = {
+      from,
+      to: { row: from.row + 5, col: from.col + 3 }, // approximate
+    };
+
+    const pic = a["xdr:pic"] ?? a["pic"];
+    if (pic && typeof pic === "object") {
+      const rId = extractPicRId(pic as Record<string, unknown>);
+      if (rId) {
+        results.push({ type: "image", anchor, rId });
+      }
+    }
+  }
+
+  return results;
+}
+
+// =============================================================================
+// Anchor parsing
+// =============================================================================
+
+function parseTwoCellAnchor(node: Record<string, unknown>): DrawingAnchor | undefined {
+  const from = parseAnchorPoint(node, "xdr:from", "from");
+  const to = parseAnchorPoint(node, "xdr:to", "to");
+  if (!from || !to) return undefined;
+  return { from, to };
+}
+
+function parseAnchorPoint(
+  node: Record<string, unknown>,
+  key1: string,
+  key2: string,
+): DrawingAnchor["from"] | undefined {
+  const pt = node[key1] ?? node[key2];
+  if (!pt || typeof pt !== "object") return undefined;
+  const o = pt as Record<string, unknown>;
+
+  const col = parseIntVal(o["xdr:col"] ?? o["col"]);
+  const row = parseIntVal(o["xdr:row"] ?? o["row"]);
+  const colOffset = parseIntVal(o["xdr:colOff"] ?? o["colOff"]);
+  const rowOffset = parseIntVal(o["xdr:rowOff"] ?? o["rowOff"]);
+
+  if (col === undefined || row === undefined) return undefined;
+  return { row, col, rowOffset, colOffset };
+}
+
+// =============================================================================
+// Shape parsing
+// =============================================================================
+
+function parseShapeNode(sp: Record<string, unknown>, anchor: DrawingAnchor): ParsedDrawing {
+  const spPr = sp["xdr:spPr"] ?? sp["spPr"] ?? {};
+  const txBody = sp["xdr:txBody"] ?? sp["txBody"];
+
+  // Geometry
+  const prstGeom = (spPr as Record<string, unknown>)["a:prstGeom"]
+    ?? (spPr as Record<string, unknown>)["prstGeom"];
+  const geometry = prstGeom && typeof prstGeom === "object"
+    ? ((prstGeom as Record<string, unknown>)["@_prst"] as string | undefined) ?? "rect"
+    : "rect";
+
+  // Fill
+  const fillColor = extractFillColor(spPr as Record<string, unknown>);
+  const outlineColor = extractOutlineColor(spPr as Record<string, unknown>);
+
+  // Text
+  const text = extractTextContent(txBody);
+
+  const isTextBox = text !== undefined && geometry === "rect";
+
+  return {
+    type: isTextBox ? "textbox" : "shape",
+    geometry,
+    text,
+    fillColor,
+    outlineColor,
+    anchor,
+  };
+}
+
+function parseConnectorNode(cxnSp: Record<string, unknown>, anchor: DrawingAnchor): ParsedDrawing {
+  const spPr = cxnSp["xdr:spPr"] ?? cxnSp["spPr"] ?? {};
+  const outlineColor = extractOutlineColor(spPr as Record<string, unknown>);
+
+  return {
+    type: "connector",
+    geometry: "line",
+    outlineColor,
+    anchor,
+  };
+}
+
+// =============================================================================
+// Color extraction
+// =============================================================================
+
+function extractFillColor(spPr: Record<string, unknown>): string | undefined {
+  const solidFill = spPr["a:solidFill"] ?? spPr["solidFill"];
+  if (solidFill && typeof solidFill === "object") {
+    return extractSrgb(solidFill as Record<string, unknown>);
+  }
+  return undefined;
+}
+
+function extractOutlineColor(spPr: Record<string, unknown>): string | undefined {
+  const ln = spPr["a:ln"] ?? spPr["ln"];
+  if (!ln || typeof ln !== "object") return undefined;
+  const solidFill = (ln as Record<string, unknown>)["a:solidFill"]
+    ?? (ln as Record<string, unknown>)["solidFill"];
+  if (solidFill && typeof solidFill === "object") {
+    return extractSrgb(solidFill as Record<string, unknown>);
+  }
+  return undefined;
+}
+
+function extractSrgb(fill: Record<string, unknown>): string | undefined {
+  const srgb = fill["a:srgbClr"] ?? fill["srgbClr"];
+  if (srgb && typeof srgb === "object") {
+    const val = (srgb as Record<string, unknown>)["@_val"];
+    if (typeof val === "string") return `#${val}`;
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Text extraction
+// =============================================================================
+
+function extractTextContent(txBody: unknown): string | undefined {
+  if (!txBody || typeof txBody !== "object") return undefined;
+  const paras = ensureArray((txBody as Record<string, unknown>)["a:p"] ?? (txBody as Record<string, unknown>)["p"]);
+  const texts: string[] = [];
+  for (const para of paras) {
+    if (!para || typeof para !== "object") continue;
+    const runs = ensureArray((para as Record<string, unknown>)["a:r"] ?? (para as Record<string, unknown>)["r"]);
+    for (const run of runs) {
+      if (!run || typeof run !== "object") continue;
+      const t = (run as Record<string, unknown>)["a:t"] ?? (run as Record<string, unknown>)["t"];
+      if (typeof t === "string") texts.push(t);
+    }
+  }
+  return texts.length > 0 ? texts.join("") : undefined;
+}
+
+// =============================================================================
+// Relationship extraction
+// =============================================================================
+
+function extractChartRId(graphicFrame: Record<string, unknown>): string | undefined {
+  const graphic = graphicFrame["a:graphic"] ?? graphicFrame["graphic"];
+  if (!graphic || typeof graphic !== "object") return undefined;
+  const graphicData = (graphic as Record<string, unknown>)["a:graphicData"]
+    ?? (graphic as Record<string, unknown>)["graphicData"];
+  if (!graphicData || typeof graphicData !== "object") return undefined;
+  const chartRef = (graphicData as Record<string, unknown>)["c:chart"]
+    ?? (graphicData as Record<string, unknown>)["chart"];
+  if (!chartRef || typeof chartRef !== "object") return undefined;
+  const rId = (chartRef as Record<string, unknown>)["@_r:id"]
+    ?? (chartRef as Record<string, unknown>)["@_id"];
+  return typeof rId === "string" ? rId : undefined;
+}
+
+function extractPicRId(pic: Record<string, unknown>): string | undefined {
+  const blipFill = pic["xdr:blipFill"] ?? pic["blipFill"];
+  if (!blipFill || typeof blipFill !== "object") return undefined;
+  const blip = (blipFill as Record<string, unknown>)["a:blip"]
+    ?? (blipFill as Record<string, unknown>)["blip"];
+  if (!blip || typeof blip !== "object") return undefined;
+  const rId = (blip as Record<string, unknown>)["@_r:embed"]
+    ?? (blip as Record<string, unknown>)["@_embed"];
+  return typeof rId === "string" ? rId : undefined;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function ensureArray(val: unknown): unknown[] {
+  if (val === undefined || val === null) return [];
+  return Array.isArray(val) ? val : [val];
+}
+
+function parseIntVal(val: unknown): number | undefined {
+  if (typeof val === "number") return val;
+  if (typeof val === "string") {
+    const n = parseInt(val, 10);
+    return isNaN(n) ? undefined : n;
+  }
+  return undefined;
+}

package/src/ooxml_pivot.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from "vitest";
+import { XMLParser } from "fast-xml-parser";
+import {
+  parsePivotTableXml,
+  parsePivotCacheDefinitionXml,
+  extractPivotTableRIds,
+  extractWorkbookPivotCaches,
+} from "./ooxml_pivot";
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  isArray: (tagName) =>
+    tagName === "Relationship" ||
+    tagName === "pivotField" ||
+    tagName === "cacheField" ||
+    tagName === "field" ||
+    tagName === "pageField" ||
+    tagName === "dataField" ||
+    tagName === "pivotCache",
+});
+const parseXml = (xml: string) => parser.parse(xml) as Record<string, unknown>;
+
+// =============================================================================
+// PivotTable
+// =============================================================================
+
+const PIVOT_TABLE_XML = `<?xml version="1.0"?>
+<pivotTableDefinition xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+    name="SalesByRegion" cacheId="1" rowGrandTotals="1" colGrandTotals="1">
+  <location ref="A3:E12" firstHeaderRow="1" firstDataCol="1" firstDataRow="2"/>
+  <pivotFields count="3">
+    <pivotField axis="axisRow" defaultSubtotal="1" sumSubtotal="1"/>
+    <pivotField axis="axisCol" defaultSubtotal="1"/>
+    <pivotField dataField="1" showAll="0"/>
+  </pivotFields>
+  <rowFields count="1">
+    <field x="0"/>
+  </rowFields>
+  <colFields count="1">
+    <field x="1"/>
+  </colFields>
+  <dataFields count="1">
+    <dataField name="Sum of Revenue" fld="2" subtotal="sum"/>
+  </dataFields>
+  <pivotTableStyleInfo name="PivotStyleLight16" showRowStripes="1"/>
+</pivotTableDefinition>`;
+
+describe("parsePivotTableXml", () => {
+  it("extracts the basic shape of a pivot table", () => {
+    const pivot = parsePivotTableXml(PIVOT_TABLE_XML, parseXml);
+    expect(pivot.name).toBe("SalesByRegion");
+    expect(pivot.cacheId).toBe(1);
+    expect(pivot.ref).toBe("A3:E12");
+    expect(pivot.firstHeaderRow).toBe(1);
+    expect(pivot.firstDataCol).toBe(1);
+    expect(pivot.firstDataRow).toBe(2);
+  });
+
+  it("classifies fields onto axes", () => {
+    const pivot = parsePivotTableXml(PIVOT_TABLE_XML, parseXml);
+    expect(pivot.fields).toHaveLength(3);
+    expect(pivot.fields[0].axis).toBe("row");
+    expect(pivot.fields[1].axis).toBe("column");
+    // Field 2 is referenced by the dataField but doesn't carry an axis attr.
+    expect(pivot.fields[2].axis).toBeUndefined();
+    expect(pivot.fields[0].subtotalFunction).toBe("sum");
+  });
+
+  it("captures the row/col field ordering", () => {
+    const pivot = parsePivotTableXml(PIVOT_TABLE_XML, parseXml);
+    expect(pivot.rowFieldIndices).toEqual([0]);
+    expect(pivot.colFieldIndices).toEqual([1]);
+    expect(pivot.pageFieldIndices).toEqual([]);
+  });
+
+  it("parses the values area", () => {
+    const pivot = parsePivotTableXml(PIVOT_TABLE_XML, parseXml);
+    expect(pivot.dataFields).toEqual([
+      { name: "Sum of Revenue", fieldIndex: 2, subtotal: "sum", numFmt: undefined },
+    ]);
+  });
+
+  it("captures display flags and style", () => {
+    const pivot = parsePivotTableXml(PIVOT_TABLE_XML, parseXml);
+    expect(pivot.styleName).toBe("PivotStyleLight16");
+    expect(pivot.display.rowGrandTotals).toBe(true);
+    expect(pivot.display.colGrandTotals).toBe(true);
+    expect(pivot.display.showRowStripes).toBe(true);
+  });
+});
+
+// =============================================================================
+// PivotCache
+// =============================================================================
+
+const PIVOT_CACHE_XML = `<?xml version="1.0"?>
+<pivotCacheDefinition xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+    refreshOnLoad="1" recordCount="4">
+  <cacheSource type="worksheet">
+    <worksheetSource sheet="Data" ref="A1:C5"/>
+  </cacheSource>
+  <cacheFields count="3">
+    <cacheField name="Region">
+      <sharedItems>
+        <s v="North"/>
+        <s v="South"/>
+      </sharedItems>
+    </cacheField>
+    <cacheField name="Quarter">
+      <sharedItems>
+        <s v="Q1"/>
+        <s v="Q2"/>
+      </sharedItems>
+    </cacheField>
+    <cacheField name="Revenue" numFmtId="4">
+      <sharedItems containsNumber="1">
+        <n v="100"/>
+        <n v="200"/>
+        <n v="300"/>
+        <n v="400"/>
+      </sharedItems>
+    </cacheField>
+  </cacheFields>
+</pivotCacheDefinition>`;
+
+describe("parsePivotCacheDefinitionXml", () => {
+  it("captures source range and refresh flag", () => {
+    const cache = parsePivotCacheDefinitionXml(PIVOT_CACHE_XML, 1, parseXml);
+    expect(cache.id).toBe(1);
+    expect(cache.refreshOnLoad).toBe(true);
+    expect(cache.source).toEqual({
+      type: "worksheet",
+      sheetName: "Data",
+      ref: "A1:C5",
+    });
+  });
+
+  it("parses string cache items", () => {
+    const cache = parsePivotCacheDefinitionXml(PIVOT_CACHE_XML, 1, parseXml);
+    expect(cache.fields[0].name).toBe("Region");
+    expect(cache.fields[0].items).toEqual([
+      { kind: "string", value: "North" },
+      { kind: "string", value: "South" },
+    ]);
+  });
+
+  it("parses numeric cache items and keeps numeric flag", () => {
+    const cache = parsePivotCacheDefinitionXml(PIVOT_CACHE_XML, 1, parseXml);
+    const revenue = cache.fields[2];
+    expect(revenue.containsNumber).toBe(true);
+    expect(revenue.items.map((i) => i.kind)).toEqual([
+      "number",
+      "number",
+      "number",
+      "number",
+    ]);
+    expect((revenue.items[0] as { kind: "number"; value: number }).value).toBe(100);
+  });
+});
+
+// =============================================================================
+// Relationship + workbook helpers
+// =============================================================================
+
+const SHEET_RELS_XML = `<?xml version="1.0"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable" Target="../pivotTables/pivotTable1.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing" Target="../drawings/drawing1.xml"/>
+</Relationships>`;
+
+describe("extractPivotTableRIds", () => {
+  it("returns only pivot-table relationships", () => {
+    const map = extractPivotTableRIds(parseXml(SHEET_RELS_XML));
+    expect(map.size).toBe(1);
+    expect(map.get("rId1")).toBe("../pivotTables/pivotTable1.xml");
+  });
+});
+
+const WORKBOOK_XML = `<?xml version="1.0"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+          xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <pivotCaches>
+    <pivotCache cacheId="1" r:id="rId7"/>
+    <pivotCache cacheId="2" r:id="rId8"/>
+  </pivotCaches>
+</workbook>`;
+
+describe("extractWorkbookPivotCaches", () => {
+  it("returns cacheId → rId mapping", () => {
+    const map = extractWorkbookPivotCaches(parseXml(WORKBOOK_XML));
+    expect(map.get(1)).toBe("rId7");
+    expect(map.get(2)).toBe("rId8");
+  });
+});