@lotics/xlsx 0.1.0

package/src/ooxml_chart.ts

@@ -0,0 +1,347 @@
+// =============================================================================
+// OOXML Chart Parser
+// =============================================================================
+//
+// Parses xl/charts/chartN.xml files into ParsedChart objects.
+// Handles: bar, column, line, pie, doughnut, area, scatter, bubble, radar,
+// stock, combo charts. Extracts series data, axes, legend, formatting.
+// =============================================================================
+
+import type { ParsedChart, ChartType, ChartSeries, ChartAxis } from "./ooxml_chart_types";
+
+// =============================================================================
+// Parser
+// =============================================================================
+
+/**
+ * Parse a chart XML string into a ParsedChart (without anchor — caller sets it).
+ */
+export function parseChartXml(
+  xml: string,
+  parseXml: (xml: string) => Record<string, unknown>,
+): Omit<ParsedChart, "anchor"> {
+  const doc = parseXml(xml);
+  const chartSpace = (getObj(doc, "c:chartSpace") ?? getObj(doc, "chartSpace") ?? doc) as Record<string, unknown>;
+  const chart = (getObj(chartSpace, "c:chart") ?? getObj(chartSpace, "chart") ?? chartSpace) as Record<string, unknown>;
+  const plotArea = (getObj(chart, "c:plotArea") ?? getObj(chart, "plotArea") ?? chart) as Record<string, unknown>;
+
+  // Detect chart type from plot area child elements
+  const { chartType, series, categories } = parseChartData(plotArea as Record<string, unknown>);
+
+  // Title
+  const titleObj = getObj(chart as Record<string, unknown>, "c:title")
+    ?? getObj(chart as Record<string, unknown>, "title");
+  const title = extractTitle(titleObj);
+
+  // Legend
+  const legendObj = getObj(chart as Record<string, unknown>, "c:legend")
+    ?? getObj(chart as Record<string, unknown>, "legend");
+  const legendPosition = extractLegendPosition(legendObj);
+
+  // Axes
+  const axes = parseAxes(plotArea as Record<string, unknown>);
+
+  return { chartType, series, title, legendPosition, axes, categories };
+}
+
+// =============================================================================
+// Chart data extraction
+// =============================================================================
+
+const CHART_TYPE_MAP: Record<string, ChartType> = {
+  "c:barChart": "col",
+  "c:bar3DChart": "col",
+  "c:lineChart": "line",
+  "c:line3DChart": "line",
+  "c:pieChart": "pie",
+  "c:pie3DChart": "pie",
+  "c:doughnutChart": "doughnut",
+  "c:areaChart": "area",
+  "c:area3DChart": "area",
+  "c:scatterChart": "scatter",
+  "c:bubbleChart": "bubble",
+  "c:radarChart": "radar",
+  "c:stockChart": "stock",
+  "c:surfaceChart": "surface",
+  "c:surface3DChart": "surface",
+  "barChart": "col",
+  "bar3DChart": "col",
+  "lineChart": "line",
+  "line3DChart": "line",
+  "pieChart": "pie",
+  "pie3DChart": "pie",
+  "doughnutChart": "doughnut",
+  "areaChart": "area",
+  "area3DChart": "area",
+  "scatterChart": "scatter",
+  "bubbleChart": "bubble",
+  "radarChart": "radar",
+  "stockChart": "stock",
+  "surfaceChart": "surface",
+  "surface3DChart": "surface",
+};
+
+function parseChartData(plotArea: Record<string, unknown>): { chartType: ChartType; series: ChartSeries[]; categories?: string[] } {
+  // Detect combo charts — multiple chart type children in plot area
+  const foundTypes: { key: string; type: ChartType; node: Record<string, unknown> }[] = [];
+  for (const [key, type] of Object.entries(CHART_TYPE_MAP)) {
+    const chartNode = plotArea[key];
+    if (!chartNode) continue;
+    let chartType = type;
+    const obj = chartNode as Record<string, unknown>;
+    if ((key === "c:barChart" || key === "barChart") &&
+        (getAttr(obj, "c:barDir", "val") === "bar" || getAttr(obj, "barDir", "val") === "bar")) {
+      chartType = "bar";
+    }
+    foundTypes.push({ key, type: chartType, node: obj });
+  }
+
+  if (foundTypes.length === 0) {
+    return { chartType: "unknown", series: [] };
+  }
+
+  // Single chart type
+  if (foundTypes.length === 1) {
+    const { type, node } = foundTypes[0];
+    const series = extractSeries(node);
+    const categories = extractCategories(node);
+    return { chartType: type, series, categories };
+  }
+
+  // Combo chart — merge series from all types, tag each with its chart type
+  const allSeries: ChartSeries[] = [];
+  let categories: string[] | undefined;
+  for (const { type, node } of foundTypes) {
+    const series = extractSeries(node);
+    for (const s of series) {
+      s.seriesChartType = type;
+    }
+    allSeries.push(...series);
+    if (!categories) categories = extractCategories(node);
+  }
+
+  return { chartType: "combo", series: allSeries, categories };
+}
+
+function extractSeries(chartNode: Record<string, unknown>): ChartSeries[] {
+  const serNodes = ensureArray(chartNode["c:ser"] ?? chartNode["ser"]);
+  const series: ChartSeries[] = [];
+
+  for (const ser of serNodes) {
+    if (!ser || typeof ser !== "object") continue;
+    const s = ser as Record<string, unknown>;
+
+    // Series name
+    const txNode = getObj(s, "c:tx") ?? getObj(s, "tx");
+    const name = extractSeriesName(txNode);
+
+    // Values
+    const valNode = getObj(s, "c:val") ?? getObj(s, "val")
+      ?? getObj(s, "c:yVal") ?? getObj(s, "yVal");
+    const values = extractNumericValues(valNode);
+
+    // Bubble sizes
+    const bubbleSizeNode = getObj(s, "c:bubbleSize") ?? getObj(s, "bubbleSize");
+    const bubbleSizes = extractNumericValues(bubbleSizeNode);
+
+    // Color from shape properties
+    const spPr = getObj(s, "c:spPr") ?? getObj(s, "spPr");
+    const color = extractColor(spPr);
+
+    const entry: ChartSeries = { name, values, color };
+    if (bubbleSizes.length > 0) entry.bubbleSizes = bubbleSizes;
+    series.push(entry);
+  }
+
+  return series;
+}
+
+function extractSeriesName(txNode: unknown): string | undefined {
+  if (!txNode || typeof txNode !== "object") return undefined;
+  const tx = txNode as Record<string, unknown>;
+  const strRef = getObj(tx, "c:strRef") ?? getObj(tx, "strRef");
+  if (strRef) {
+    const cache = getObj(strRef as Record<string, unknown>, "c:strCache") ?? getObj(strRef as Record<string, unknown>, "strCache");
+    if (cache) {
+      const pt = ensureArray((cache as Record<string, unknown>)["c:pt"] ?? (cache as Record<string, unknown>)["pt"]);
+      if (pt[0] && typeof pt[0] === "object") {
+        const v = (pt[0] as Record<string, unknown>)["c:v"] ?? (pt[0] as Record<string, unknown>)["v"];
+        if (typeof v === "string") return v;
+      }
+    }
+  }
+  const v = getObj(tx, "c:v") ?? getObj(tx, "v");
+  if (typeof v === "string") return v;
+  return undefined;
+}
+
+function extractNumericValues(valNode: unknown): number[] {
+  if (!valNode || typeof valNode !== "object") return [];
+  const val = valNode as Record<string, unknown>;
+  const numRef = getObj(val, "c:numRef") ?? getObj(val, "numRef");
+  const cache = numRef
+    ? getObj(numRef as Record<string, unknown>, "c:numCache") ?? getObj(numRef as Record<string, unknown>, "numCache")
+    : getObj(val, "c:numLit") ?? getObj(val, "numLit");
+
+  if (!cache || typeof cache !== "object") return [];
+  const pts = ensureArray((cache as Record<string, unknown>)["c:pt"] ?? (cache as Record<string, unknown>)["pt"]);
+  const values: number[] = [];
+  for (const pt of pts) {
+    if (!pt || typeof pt !== "object") continue;
+    const v = (pt as Record<string, unknown>)["c:v"] ?? (pt as Record<string, unknown>)["v"];
+    const num = typeof v === "string" ? parseFloat(v) : typeof v === "number" ? v : NaN;
+    values.push(isNaN(num) ? 0 : num);
+  }
+  return values;
+}
+
+function extractCategories(chartNode: Record<string, unknown>): string[] | undefined {
+  const serNodes = ensureArray(chartNode["c:ser"] ?? chartNode["ser"]);
+  for (const ser of serNodes) {
+    if (!ser || typeof ser !== "object") continue;
+    const s = ser as Record<string, unknown>;
+    const catNode = getObj(s, "c:cat") ?? getObj(s, "cat");
+    if (!catNode || typeof catNode !== "object") continue;
+    const cat = catNode as Record<string, unknown>;
+    const strRef = getObj(cat, "c:strRef") ?? getObj(cat, "strRef");
+    if (strRef && typeof strRef === "object") {
+      const cache = getObj(strRef as Record<string, unknown>, "c:strCache")
+        ?? getObj(strRef as Record<string, unknown>, "strCache");
+      if (cache && typeof cache === "object") {
+        const pts = ensureArray((cache as Record<string, unknown>)["c:pt"] ?? (cache as Record<string, unknown>)["pt"]);
+        const cats: string[] = [];
+        for (const pt of pts) {
+          if (!pt || typeof pt !== "object") continue;
+          const v = (pt as Record<string, unknown>)["c:v"] ?? (pt as Record<string, unknown>)["v"];
+          cats.push(typeof v === "string" ? v : String(v ?? ""));
+        }
+        if (cats.length > 0) return cats;
+      }
+    }
+  }
+  return undefined;
+}
+
+function extractColor(spPr: unknown): string | undefined {
+  if (!spPr || typeof spPr !== "object") return undefined;
+  const obj = spPr as Record<string, unknown>;
+  const solidFill = getObj(obj, "a:solidFill") ?? getObj(obj, "solidFill");
+  if (!solidFill || typeof solidFill !== "object") return undefined;
+  const srgb = getObj(solidFill as Record<string, unknown>, "a:srgbClr") ?? getObj(solidFill as Record<string, unknown>, "srgbClr");
+  if (srgb && typeof srgb === "object") {
+    const val = (srgb as Record<string, unknown>)["@_val"];
+    if (typeof val === "string") return `#${val}`;
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Title
+// =============================================================================
+
+function extractTitle(titleNode: unknown): string | undefined {
+  if (!titleNode || typeof titleNode !== "object") return undefined;
+  const tx = getObj(titleNode as Record<string, unknown>, "c:tx") ?? getObj(titleNode as Record<string, unknown>, "tx");
+  if (!tx || typeof tx !== "object") return undefined;
+  const rich = getObj(tx as Record<string, unknown>, "c:rich") ?? getObj(tx as Record<string, unknown>, "rich");
+  if (!rich || typeof rich !== "object") return undefined;
+  const paras = ensureArray((rich as Record<string, unknown>)["a:p"] ?? (rich 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;
+}
+
+// =============================================================================
+// Legend
+// =============================================================================
+
+function extractLegendPosition(legendNode: unknown): ParsedChart["legendPosition"] {
+  if (!legendNode || typeof legendNode !== "object") return undefined;
+  const pos = getObj(legendNode as Record<string, unknown>, "c:legendPos") ?? getObj(legendNode as Record<string, unknown>, "legendPos");
+  if (!pos || typeof pos !== "object") return undefined;
+  const val = (pos as Record<string, unknown>)["@_val"];
+  const map: Record<string, ParsedChart["legendPosition"]> = { t: "top", b: "bottom", l: "left", r: "right" };
+  return typeof val === "string" ? map[val] ?? "right" : "right";
+}
+
+// =============================================================================
+// Axes
+// =============================================================================
+
+function parseAxes(plotArea: Record<string, unknown>): ChartAxis[] {
+  const axes: ChartAxis[] = [];
+
+  const catAx = ensureArray(plotArea["c:catAx"] ?? plotArea["catAx"]);
+  for (const ax of catAx) {
+    if (!ax || typeof ax !== "object") continue;
+    axes.push(parseAxis(ax as Record<string, unknown>, "category"));
+  }
+
+  const valAx = ensureArray(plotArea["c:valAx"] ?? plotArea["valAx"]);
+  for (const ax of valAx) {
+    if (!ax || typeof ax !== "object") continue;
+    axes.push(parseAxis(ax as Record<string, unknown>, "value"));
+  }
+
+  const dateAx = ensureArray(plotArea["c:dateAx"] ?? plotArea["dateAx"]);
+  for (const ax of dateAx) {
+    if (!ax || typeof ax !== "object") continue;
+    axes.push(parseAxis(ax as Record<string, unknown>, "date"));
+  }
+
+  return axes;
+}
+
+function parseAxis(ax: Record<string, unknown>, type: ChartAxis["type"]): ChartAxis {
+  const titleNode = getObj(ax, "c:title") ?? getObj(ax, "title");
+  const title = extractTitle(titleNode);
+
+  const numFmtNode = getObj(ax, "c:numFmt") ?? getObj(ax, "numFmt");
+  const numFmt = numFmtNode ? getAttr(numFmtNode as Record<string, unknown>, "", "formatCode") ?? (numFmtNode as Record<string, unknown>)["@_formatCode"] as string | undefined : undefined;
+
+  const scalingNode = getObj(ax, "c:scaling") ?? getObj(ax, "scaling");
+  let min: number | undefined;
+  let max: number | undefined;
+  if (scalingNode && typeof scalingNode === "object") {
+    const minNode = getObj(scalingNode as Record<string, unknown>, "c:min") ?? getObj(scalingNode as Record<string, unknown>, "min");
+    if (minNode && typeof minNode === "object") {
+      const v = (minNode as Record<string, unknown>)["@_val"];
+      if (typeof v === "string") min = parseFloat(v);
+    }
+    const maxNode = getObj(scalingNode as Record<string, unknown>, "c:max") ?? getObj(scalingNode as Record<string, unknown>, "max");
+    if (maxNode && typeof maxNode === "object") {
+      const v = (maxNode as Record<string, unknown>)["@_val"];
+      if (typeof v === "string") max = parseFloat(v);
+    }
+  }
+
+  return { type, title, numFmt, min, max };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function getObj(parent: Record<string, unknown>, key: string): unknown {
+  return parent[key];
+}
+
+function getAttr(obj: Record<string, unknown>, childKey: string, attr: string): string | undefined {
+  const child = childKey ? obj[childKey] : obj;
+  if (!child || typeof child !== "object") return undefined;
+  const val = (child as Record<string, unknown>)[`@_${attr}`];
+  return typeof val === "string" ? val : undefined;
+}
+
+function ensureArray(val: unknown): unknown[] {
+  if (val === undefined || val === null) return [];
+  return Array.isArray(val) ? val : [val];
+}

package/src/ooxml_chart_types.ts

@@ -0,0 +1,207 @@
+// =============================================================================
+// Chart & Drawing Types
+// =============================================================================
+//
+// Types for parsed chart, sparkline, table, and drawing objects from OOXML.
+// These are read from xl/charts/*.xml, xl/tables/*.xml, and
+// xl/drawings/*.xml during workbook loading.
+// =============================================================================
+
+// =============================================================================
+// Charts
+// =============================================================================
+
+export interface ParsedChart {
+  /** Chart title text. */
+  title?: string;
+  /** Chart type (bar, line, pie, scatter, area, etc.). */
+  chartType: ChartType;
+  /** Data series. */
+  series: ChartSeries[];
+  /** Category labels (X-axis or pie labels). */
+  categories?: string[];
+  /** Axis configuration. */
+  axes?: ChartAxis[];
+  /** Legend position. */
+  legendPosition?: "top" | "bottom" | "left" | "right" | "none";
+  /** Anchor position in the sheet (row/col for top-left and bottom-right). */
+  anchor: DrawingAnchor;
+}
+
+export type ChartType =
+  | "bar"
+  | "col"
+  | "line"
+  | "pie"
+  | "doughnut"
+  | "area"
+  | "scatter"
+  | "bubble"
+  | "radar"
+  | "stock"
+  | "surface"
+  | "combo"
+  | "unknown";
+
+export interface ChartSeries {
+  /** Series name/label. */
+  name?: string;
+  /** Data values. */
+  values: number[];
+  /** Series color (resolved from theme/style). */
+  color?: string;
+  /** Bubble sizes (for bubble charts). */
+  bubbleSizes?: number[];
+  /** Per-series chart type (for combo charts). */
+  seriesChartType?: ChartType;
+}
+
+export interface ChartAxis {
+  /** Axis type. */
+  type: "category" | "value" | "date" | "series";
+  /** Axis title. */
+  title?: string;
+  /** Number format for axis labels. */
+  numFmt?: string;
+  /** Min/max bounds. */
+  min?: number;
+  max?: number;
+}
+
+// =============================================================================
+// Sparklines
+// =============================================================================
+
+export interface ParsedSparklineGroup {
+  /** Sparkline type. */
+  type: "line" | "column" | "stacked";
+  /** Individual sparklines in the group. */
+  sparklines: ParsedSparkline[];
+  /** Series color. */
+  color?: string;
+  /** Min/max axis settings. */
+  minAxis?: "individual" | "group" | "custom";
+  maxAxis?: "individual" | "group" | "custom";
+}
+
+export interface ParsedSparkline {
+  /** Data range (e.g., "Sheet1!A1:A10"). */
+  dataRange: string;
+  /** Cell where the sparkline is rendered. */
+  locationRef: string;
+}
+
+// =============================================================================
+// Structured Tables
+// =============================================================================
+
+export interface ParsedTable {
+  /** Table name (used in structured references like TableName[Column]). */
+  name: string;
+  /** Display name. */
+  displayName: string;
+  /** Cell range (e.g., "A1:D10"). */
+  ref: string;
+  /** Column definitions. */
+  columns: TableColumn[];
+  /** Whether the table has a header row. */
+  headerRow: boolean;
+  /** Whether the table has a totals row. */
+  totalsRow: boolean;
+  /** Table style name (e.g., "TableStyleMedium2"). */
+  styleName?: string;
+  /** Auto-filter enabled. */
+  autoFilter: boolean;
+}
+
+export interface TableColumn {
+  /** Column ID (1-based within the table). */
+  id: number;
+  /** Column header text. */
+  name: string;
+  /** Totals row function (sum, count, average, etc.). */
+  totalsFunction?: string;
+  /** Totals row formula. */
+  totalsFormula?: string;
+}
+
+// =============================================================================
+// Drawings (shapes, text boxes, etc.)
+// =============================================================================
+
+export interface ParsedDrawing {
+  /** Drawing type. */
+  type: "shape" | "textbox" | "connector" | "group" | "unknown";
+  /** Shape geometry preset (rect, roundRect, ellipse, etc.). */
+  geometry?: string;
+  /** Shape text content. */
+  text?: string;
+  /** Fill color. */
+  fillColor?: string;
+  /** Outline color. */
+  outlineColor?: string;
+  /** Outline width in points. */
+  outlineWidth?: number;
+  /** Anchor position. */
+  anchor: DrawingAnchor;
+}
+
+// =============================================================================
+// Drawing anchors — position relative to cells
+// =============================================================================
+
+export interface DrawingAnchor {
+  /** Top-left cell. */
+  from: { row: number; col: number; rowOffset?: number; colOffset?: number };
+  /** Bottom-right cell. */
+  to: { row: number; col: number; rowOffset?: number; colOffset?: number };
+}
+
+// =============================================================================
+// Auto-filters
+// =============================================================================
+
+export interface AutoFilterRange {
+  /** Range reference (e.g., "A1:D10"). */
+  ref: string;
+  /** Per-column filter criteria. */
+  columns: AutoFilterColumn[];
+}
+
+export interface AutoFilterColumn {
+  /** Column index within the filter range (0-based). */
+  colIndex: number;
+  /** Filter values (for value-based filters). */
+  filterValues?: string[];
+  /** Custom filter condition. */
+  customFilter?: { operator: string; value: string };
+}
+
+// =============================================================================
+// Data Validation
+// =============================================================================
+
+export interface ParsedDataValidation {
+  /** Cell range this validation applies to. */
+  ref: string;
+  /** Validation type. */
+  type: "list" | "whole" | "decimal" | "date" | "time" | "textLength" | "custom" | "none";
+  /** Comparison operator. */
+  operator?: "between" | "notBetween" | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual";
+  /** Formula for value 1. */
+  formula1?: string;
+  /** Formula for value 2 (for between/notBetween). */
+  formula2?: string;
+  /** Whether to show dropdown for list validation. */
+  showDropdown: boolean;
+  /** Error alert style. */
+  errorStyle?: "stop" | "warning" | "information";
+  /** Error alert title. */
+  errorTitle?: string;
+  /** Error alert message. */
+  errorMessage?: string;
+  /** Input prompt title. */
+  promptTitle?: string;
+  /** Input prompt message. */
+  promptMessage?: string;
+}