@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/io/ooxml/chart/parse-series.ts

@@ -0,0 +1,570 @@
+/**
+ * Parse `<c:ser>` elements and their numCache/strCache bodies.
+ *
+ * The sparse-point semantics are important: `<c:numCache>` carries a
+ * `c:ptCount` attribute and zero or more `<c:pt idx="N">` children; any
+ * index between 0 and ptCount that does not appear represents a blank
+ * (null) value. Consumers rely on that layout to render gaps / stacked
+ * zeros / "span" lines per the chart family's c:dispBlanksAs setting.
+ *
+ * Callers that already have the series element in hand should use
+ * `parseBarSeriesNode` to avoid re-parsing the XML.
+ */
+
+import {
+  findChildOptional,
+  findFirstDescendant,
+  localName,
+  readFloatVal,
+  readIntVal,
+  readOnOff,
+  textContent,
+} from "../xml-attr-helpers.ts";
+import type { XmlElementNode } from "../xml-element.ts";
+import { parseXml } from "../xml-parser.ts";
+
+import type {
+  BubbleSeries,
+  ColorMod,
+  ColorRef,
+  DataPointOverride,
+  FillSpec,
+  LineSeries,
+  MarkerSpec,
+  PieSeries,
+  ScatterSeries,
+  Series,
+  ShapeProperties,
+  StrokeSpec,
+} from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Series
+// ---------------------------------------------------------------------------
+
+/** Parse a `<c:ser>` XML fragment into a `Series`. */
+export function parseBarSeries(serXml: string): Series {
+  const root = parseXml(serXml);
+  const node = findFirstDescendant(root, "ser");
+  if (!node) {
+    return emptySeries();
+  }
+  return parseBarSeriesNode(node);
+}
+
+/**
+ * Parse the `Series` fields that every chart family shares: idx, order,
+ * name (c:tx), categories (c:cat), values (c:val), and the explicit
+ * fill/stroke overrides from c:spPr.
+ *
+ * Family-specific parsers (line markers, pie explosion, scatter xValues,
+ * etc.) wrap this and attach additional fields to the base shape.
+ */
+export function parseSeriesBase(node: XmlElementNode): Series {
+  const idx = readIntVal(findChildOptional(node, "idx")) ?? 0;
+  const order = readIntVal(findChildOptional(node, "order")) ?? 0;
+  const name = readSeriesName(findChildOptional(node, "tx"));
+  const categories = extractStrCache(findChildOptional(node, "cat"));
+  const values = extractNumCache(findChildOptional(node, "val"));
+  const spPr = parseShapeProperties(findChildOptional(node, "spPr"));
+
+  const series: Series = {
+    idx,
+    order,
+    categories,
+    values,
+  };
+  if (name !== undefined) series.name = name;
+  if (spPr) series.spPr = spPr;
+  return series;
+}
+
+/**
+ * Parse a pre-parsed `<c:ser>` element into a `Series`. Thin wrapper over
+ * `parseSeriesBase`, kept for call-site readability in bar/column parsing
+ * where "bar" makes the intent clear.
+ */
+export function parseBarSeriesNode(node: XmlElementNode): Series {
+  return parseSeriesBase(node);
+}
+
+function emptySeries(): Series {
+  return { idx: 0, order: 0, categories: [], values: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Line series
+// ---------------------------------------------------------------------------
+
+/** Parse a `<c:ser>` XML fragment from a lineChart into a `LineSeries`. */
+export function parseLineSeries(serXml: string): LineSeries {
+  const root = parseXml(serXml);
+  const node = findFirstDescendant(root, "ser");
+  if (!node) {
+    return emptySeries();
+  }
+  return parseLineSeriesNode(node);
+}
+
+/**
+ * Parse a pre-parsed `<c:ser>` element from a lineChart. Returns the common
+ * `Series` fields plus optional per-series smooth + marker overrides. Omits
+ * the optional keys entirely when absent so strict-type consumers can
+ * distinguish "not specified" from "explicitly false / none".
+ */
+export function parseLineSeriesNode(node: XmlElementNode): LineSeries {
+  const base = parseSeriesBase(node);
+  const smoothNode = findChildOptional(node, "smooth");
+  const smooth = readOnOff(smoothNode);
+  const marker = parseMarkerSpec(findChildOptional(node, "marker"));
+
+  const series: LineSeries = { ...base };
+  if (smooth !== undefined) series.smooth = smooth;
+  if (marker) series.marker = marker;
+  return series;
+}
+
+// ---------------------------------------------------------------------------
+// Marker
+// ---------------------------------------------------------------------------
+
+const MARKER_SYMBOLS: ReadonlySet<MarkerSpec["symbol"]> = new Set<
+  MarkerSpec["symbol"]
+>([
+  "circle",
+  "square",
+  "diamond",
+  "triangle",
+  "x",
+  "star",
+  "dot",
+  "dash",
+  "plus",
+  "picture",
+  "none",
+  "auto",
+]);
+
+/**
+ * Parse a `<c:marker>` element. Returns undefined when the node is absent.
+ * Returns a `MarkerSpec` with `symbol: "auto"` when the element is present
+ * but declares no symbol — OOXML's default for a marker with no subclass.
+ * Unknown symbol values also collapse to `"auto"` so renderers never see
+ * an unrecognised enum.
+ */
+export function parseMarkerSpec(
+  markerNode: XmlElementNode | undefined,
+): MarkerSpec | undefined {
+  if (!markerNode) return undefined;
+  const symbolRaw = findChildOptional(markerNode, "symbol")?.attributes["val"];
+  const symbol: MarkerSpec["symbol"] =
+    symbolRaw && isMarkerSymbol(symbolRaw) ? symbolRaw : "auto";
+  const size = readIntVal(findChildOptional(markerNode, "size"));
+  const spPr = parseShapeProperties(findChildOptional(markerNode, "spPr"));
+
+  const marker: MarkerSpec = { symbol };
+  if (size !== undefined) marker.size = size;
+  if (spPr) marker.spPr = spPr;
+  return marker;
+}
+
+function isMarkerSymbol(value: string): value is MarkerSpec["symbol"] {
+  return MARKER_SYMBOLS.has(value as MarkerSpec["symbol"]);
+}
+
+// ---------------------------------------------------------------------------
+// Pie series
+// ---------------------------------------------------------------------------
+
+/** Parse a `<c:ser>` XML fragment from a pieChart/doughnutChart into `PieSeries`. */
+export function parsePieSeries(serXml: string): PieSeries {
+  const root = parseXml(serXml);
+  const node = findFirstDescendant(root, "ser");
+  if (!node) {
+    return { idx: 0, order: 0, values: [] };
+  }
+  return parsePieSeriesNode(node);
+}
+
+/**
+ * Parse a pre-parsed `<c:ser>` element from a pieChart/doughnutChart.
+ *
+ * PieSeries extends SeriesBase (idx/order/name/spPr) with:
+ * - values: the numeric cache from c:val/c:numRef/c:numCache (sparse, nulls preserved).
+ * - explosion: series-level default offset percent from c:explosion val.
+ * - dataPoints: optional per-slice overrides (c:dPt[idx]/{spPr,explosion,bubble3D}).
+ *
+ * Categories for pie live on `PieChartModel.categoryLabels`, not on the
+ * series — the group parser reads them from the first series' c:cat.
+ */
+export function parsePieSeriesNode(node: XmlElementNode): PieSeries {
+  const idx = readIntVal(findChildOptional(node, "idx")) ?? 0;
+  const order = readIntVal(findChildOptional(node, "order")) ?? 0;
+  const name = readSeriesName(findChildOptional(node, "tx"));
+  const values = extractNumCache(findChildOptional(node, "val"));
+  const spPr = parseShapeProperties(findChildOptional(node, "spPr"));
+  const explosion = readIntVal(findChildOptional(node, "explosion"));
+  const dataPoints = parseDataPointOverrides(node);
+
+  const series: PieSeries = { idx, order, values };
+  if (name !== undefined) series.name = name;
+  if (spPr) series.spPr = spPr;
+  if (explosion !== undefined) series.explosion = explosion;
+  if (dataPoints.length > 0) series.dataPoints = dataPoints;
+  return series;
+}
+
+// ---------------------------------------------------------------------------
+// Data-point overrides (c:dPt)
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk `<c:dPt>` children of a `<c:ser>` element and return typed overrides.
+ *
+ * Each override must have a `<c:idx val="N">` child; malformed entries (no
+ * idx) are skipped silently — the well-formed entries still apply. Optional
+ * children captured: spPr (fill/stroke override), explosion (pie slice
+ * offset percent), bubble3D (tolerated on non-bubble charts), marker (line
+ * variants), invertIfNegative (bar variants).
+ */
+// ---------------------------------------------------------------------------
+// Scatter series
+// ---------------------------------------------------------------------------
+
+/** Parse a `<c:ser>` XML fragment from a scatterChart into `ScatterSeries`. */
+export function parseScatterSeries(serXml: string): ScatterSeries {
+  const root = parseXml(serXml);
+  const node = findFirstDescendant(root, "ser");
+  if (!node) {
+    return { idx: 0, order: 0, xValues: [], yValues: [] };
+  }
+  return parseScatterSeriesNode(node);
+}
+
+/**
+ * Parse a pre-parsed `<c:ser>` element from a scatterChart.
+ *
+ * ScatterSeries extends SeriesBase (idx/order/name/spPr) with:
+ * - xValues, yValues: parallel numeric caches from c:xVal and c:yVal.
+ * - smooth: per-series override (c:smooth).
+ * - marker: optional MarkerSpec (c:marker).
+ *
+ * Categories don't apply to scatter — both axes are numeric.
+ */
+export function parseScatterSeriesNode(node: XmlElementNode): ScatterSeries {
+  const idx = readIntVal(findChildOptional(node, "idx")) ?? 0;
+  const order = readIntVal(findChildOptional(node, "order")) ?? 0;
+  const name = readSeriesName(findChildOptional(node, "tx"));
+  const spPr = parseShapeProperties(findChildOptional(node, "spPr"));
+  const xValues = extractNumCache(findChildOptional(node, "xVal"));
+  const yValues = extractNumCache(findChildOptional(node, "yVal"));
+  const smooth = readOnOff(findChildOptional(node, "smooth"));
+  const marker = parseMarkerSpec(findChildOptional(node, "marker"));
+
+  const series: ScatterSeries = { idx, order, xValues, yValues };
+  if (name !== undefined) series.name = name;
+  if (spPr) series.spPr = spPr;
+  if (smooth !== undefined) series.smooth = smooth;
+  if (marker) series.marker = marker;
+  return series;
+}
+
+// ---------------------------------------------------------------------------
+// Bubble series
+// ---------------------------------------------------------------------------
+
+/** Parse a `<c:ser>` XML fragment from a bubbleChart into `BubbleSeries`. */
+export function parseBubbleSeries(serXml: string): BubbleSeries {
+  const root = parseXml(serXml);
+  const node = findFirstDescendant(root, "ser");
+  if (!node) {
+    return { idx: 0, order: 0, xValues: [], yValues: [], sizes: [] };
+  }
+  return parseBubbleSeriesNode(node);
+}
+
+/**
+ * Parse a pre-parsed `<c:ser>` element from a bubbleChart.
+ *
+ * BubbleSeries extends SeriesBase with x/y caches plus a third
+ * `sizes` channel from c:bubbleSize. Each triple (x, y, size) is one
+ * bubble; all three arrays are parallel-indexed, nulls preserved.
+ */
+export function parseBubbleSeriesNode(node: XmlElementNode): BubbleSeries {
+  const idx = readIntVal(findChildOptional(node, "idx")) ?? 0;
+  const order = readIntVal(findChildOptional(node, "order")) ?? 0;
+  const name = readSeriesName(findChildOptional(node, "tx"));
+  const spPr = parseShapeProperties(findChildOptional(node, "spPr"));
+  const xValues = extractNumCache(findChildOptional(node, "xVal"));
+  const yValues = extractNumCache(findChildOptional(node, "yVal"));
+  const sizes = extractNumCache(findChildOptional(node, "bubbleSize"));
+
+  const series: BubbleSeries = { idx, order, xValues, yValues, sizes };
+  if (name !== undefined) series.name = name;
+  if (spPr) series.spPr = spPr;
+  return series;
+}
+
+export function parseDataPointOverrides(
+  serNode: XmlElementNode,
+): DataPointOverride[] {
+  const overrides: DataPointOverride[] = [];
+  for (const child of serNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "dPt") continue;
+    const idxNode = findChildOptional(child, "idx");
+    const idx = readIntVal(idxNode);
+    if (idx === undefined) continue;
+
+    const override: DataPointOverride = { idx };
+    const spPr = parseShapeProperties(findChildOptional(child, "spPr"));
+    if (spPr) override.spPr = spPr;
+    const marker = parseMarkerSpec(findChildOptional(child, "marker"));
+    if (marker) override.marker = marker;
+    const explosion = readIntVal(findChildOptional(child, "explosion"));
+    if (explosion !== undefined) override.explosion = explosion;
+    const invert = readOnOff(findChildOptional(child, "invertIfNegative"));
+    if (invert !== undefined) override.invertIfNegative = invert;
+    const bubble3D = readOnOff(findChildOptional(child, "bubble3D"));
+    if (bubble3D !== undefined) override.bubble3D = bubble3D;
+
+    overrides.push(override);
+  }
+  return overrides;
+}
+
+function readSeriesName(txNode: XmlElementNode | undefined): string | undefined {
+  if (!txNode) return undefined;
+
+  // Case 1: <c:tx><c:strRef><c:strCache>…<c:v>Name</c:v>…
+  const strRef = findChildOptional(txNode, "strRef");
+  if (strRef) {
+    const cache = findFirstDescendant(strRef, "strCache");
+    if (cache) {
+      for (const child of cache.children) {
+        if (child.type !== "element" || localName(child.name) !== "pt") continue;
+        const v = findChildOptional(child, "v");
+        if (v) return textContent(v);
+      }
+    }
+    // strCache missing — fall back to any c:v descendant under the strRef.
+    const directV = findFirstDescendant(strRef, "v");
+    if (directV) return textContent(directV);
+  }
+
+  // Case 2: <c:tx><c:v>Name</c:v> (inline literal).
+  const direct = findChildOptional(txNode, "v");
+  if (direct) return textContent(direct);
+
+  // Case 3: <c:tx><c:rich><a:p><a:r><a:t>Name</a:t>… — plain-text collapse.
+  const rich = findChildOptional(txNode, "rich");
+  if (rich) {
+    const firstT = findFirstDescendant(rich, "t");
+    if (firstT) return textContent(firstT);
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Cache extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a sparse numeric cache. Returns an array of `ptCount` length
+ * filled with `null`, with each `<c:pt idx="N"><c:v>value</c:v></c:pt>`
+ * populating index N. Values that fail to parse as finite numbers become
+ * `null` as well.
+ *
+ * The `expected` parameter lets callers bump the array length when
+ * `c:ptCount` is absent (e.g. when the cache is a companion to another
+ * series whose length is known).
+ */
+export function extractNumCache(
+  container: XmlElementNode | undefined,
+  expected?: number,
+): Array<number | null> {
+  if (!container) return [];
+  const cache =
+    findFirstDescendant(container, "numCache") ??
+    findFirstDescendant(container, "strCache");
+  if (!cache) return [];
+  const ptCount = readIntVal(findChildOptional(cache, "ptCount")) ?? 0;
+  const length = Math.max(ptCount, expected ?? 0);
+  const out: Array<number | null> = new Array(length).fill(null);
+  for (const child of cache.children) {
+    if (child.type !== "element" || localName(child.name) !== "pt") continue;
+    const idxRaw = child.attributes["idx"];
+    const idx = idxRaw ? Number.parseInt(idxRaw, 10) : Number.NaN;
+    if (!Number.isFinite(idx) || idx < 0 || idx >= out.length) continue;
+    const vNode = findChildOptional(child, "v");
+    if (!vNode) continue;
+    const n = Number.parseFloat(textContent(vNode));
+    if (Number.isFinite(n)) out[idx] = n;
+  }
+  return out;
+}
+
+/**
+ * Extract a sparse string cache. Mirrors `extractNumCache` but fills
+ * missing indices with empty strings. Falls back to `numCache` if the
+ * container only has numeric data (so a numRef-backed category axis still
+ * yields stringified labels).
+ */
+export function extractStrCache(
+  container: XmlElementNode | undefined,
+): string[] {
+  if (!container) return [];
+  const cache =
+    findFirstDescendant(container, "strCache") ??
+    findFirstDescendant(container, "numCache");
+  if (!cache) return [];
+  const ptCount = readIntVal(findChildOptional(cache, "ptCount")) ?? 0;
+  const out: string[] = new Array(ptCount).fill("");
+  for (const child of cache.children) {
+    if (child.type !== "element" || localName(child.name) !== "pt") continue;
+    const idxRaw = child.attributes["idx"];
+    const idx = idxRaw ? Number.parseInt(idxRaw, 10) : Number.NaN;
+    if (!Number.isFinite(idx) || idx < 0 || idx >= out.length) continue;
+    const vNode = findChildOptional(child, "v");
+    if (!vNode) continue;
+    out[idx] = textContent(vNode);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Shape properties (spPr) — fills and strokes
+// ---------------------------------------------------------------------------
+
+export function parseShapeProperties(
+  spPrNode: XmlElementNode | undefined,
+): ShapeProperties | undefined {
+  if (!spPrNode) return undefined;
+  const fill = parseFill(spPrNode);
+  const stroke = parseStroke(findChildOptional(spPrNode, "ln"));
+  if (!fill && !stroke) return undefined;
+  const result: ShapeProperties = {};
+  if (fill) result.fill = fill;
+  if (stroke) result.stroke = stroke;
+  return result;
+}
+
+function parseFill(spPrNode: XmlElementNode): FillSpec | undefined {
+  // Explicit fill-none sentinel.
+  if (findChildOptional(spPrNode, "noFill")) {
+    return { kind: "none" };
+  }
+  const solid = findChildOptional(spPrNode, "solidFill");
+  if (solid) {
+    const color = parseColorRef(solid);
+    if (color) return { kind: "solid", color };
+  }
+  // Gradient and pattern fills are not resolved in Stage 1 — they stay
+  // as `{ kind: "none" }` placeholders so the downstream renderer at least
+  // produces a consistent, non-crashing surface. Stage 2 replaces this.
+  if (findChildOptional(spPrNode, "gradFill")) {
+    return { kind: "none" };
+  }
+  if (findChildOptional(spPrNode, "pattFill")) {
+    return { kind: "none" };
+  }
+  return undefined;
+}
+
+function parseStroke(lnNode: XmlElementNode | undefined): StrokeSpec | undefined {
+  if (!lnNode) return undefined;
+  const stroke: StrokeSpec = {};
+  const widthAttr = lnNode.attributes["w"];
+  if (widthAttr) {
+    const w = Number.parseInt(widthAttr, 10);
+    if (Number.isFinite(w)) stroke.widthEmu = w;
+  }
+  if (findChildOptional(lnNode, "noFill")) {
+    stroke.noFill = true;
+  }
+  const solid = findChildOptional(lnNode, "solidFill");
+  if (solid) {
+    const color = parseColorRef(solid);
+    if (color) stroke.color = color;
+  }
+  const prstDash = findChildOptional(lnNode, "prstDash");
+  if (prstDash) {
+    const dashVal = prstDash.attributes["val"];
+    switch (dashVal) {
+      case "solid":
+      case "dash":
+      case "dashDot":
+      case "lgDash":
+      case "lgDashDot":
+      case "sysDash":
+      case "sysDashDot":
+        stroke.dash = dashVal;
+        break;
+      default:
+        break;
+    }
+  }
+  if (
+    stroke.widthEmu === undefined &&
+    stroke.noFill === undefined &&
+    stroke.color === undefined &&
+    stroke.dash === undefined
+  ) {
+    return undefined;
+  }
+  return stroke;
+}
+
+/**
+ * Parse a color reference child out of a fill wrapper (solidFill, stroke
+ * solidFill, etc.). Supports srgbClr and schemeClr with the full OOXML
+ * modifier set (lumMod, lumOff, shade, tint, satMod, hueMod, alpha).
+ */
+function parseColorRef(wrapper: XmlElementNode): ColorRef | undefined {
+  for (const child of wrapper.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+    if (local === "srgbClr") {
+      const val = child.attributes["val"];
+      if (!val) continue;
+      return { kind: "srgb", value: `#${val.toUpperCase()}` };
+    }
+    if (local === "schemeClr") {
+      const val = child.attributes["val"];
+      if (!val) continue;
+      const mods = parseColorMods(child);
+      const ref: ColorRef = { kind: "scheme", value: val };
+      if (mods.length > 0) ref.mods = mods;
+      return ref;
+    }
+    if (local === "sysClr") {
+      // Take the resolved lastClr value; treat as sRGB to stay in-band.
+      const lastClr = child.attributes["lastClr"];
+      if (lastClr) return { kind: "srgb", value: `#${lastClr.toUpperCase()}` };
+    }
+  }
+  return undefined;
+}
+
+function parseColorMods(colorNode: XmlElementNode): ColorMod[] {
+  const mods: ColorMod[] = [];
+  for (const child of colorNode.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+    if (
+      local !== "lumMod" &&
+      local !== "lumOff" &&
+      local !== "shade" &&
+      local !== "tint" &&
+      local !== "satMod" &&
+      local !== "hueMod" &&
+      local !== "alpha"
+    ) {
+      continue;
+    }
+    const value = readFloatVal(child);
+    if (value === undefined) continue;
+    mods.push({ kind: local, value });
+  }
+  return mods;
+}