@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/io/ooxml/chart/compose-series-color.ts

@@ -0,0 +1,147 @@
+/**
+ * Compose the final sRGB color for a series in a parsed `ChartModel`.
+ *
+ * This is the Stage-2 call site that stitches together the three pieces
+ * the Stage-2 slices shipped:
+ *
+ *   explicit `c:ser/spPr/fill.color` override   (`parse-series.ts`)
+ *         ↓ (fallback when no override)
+ *   `paletteColorRef(style.seriesColorMode, seriesIdx)`   (`color-palette.ts`)
+ *         ↓
+ *   `resolveColor(ref, theme)`   (`resolve-color.ts`)
+ *         ↓
+ *   `#RRGGBB`
+ *
+ * Stage 3 + 4 renderers consume `composeSeriesColor` rather than reaching
+ * into the three helpers individually. Keeping the composition in one
+ * place guarantees the cascade order stays correct and gives us a stable
+ * unit-test surface.
+ *
+ * `deriveResolvedColors(model, theme)` pre-computes the full series list
+ * so renderers can render without touching the chart-style table in hot
+ * paths.
+ */
+
+import { getChartStyle, resolveChartStyleId } from "./chart-style-table.ts";
+import { paletteColorRef } from "./color-palette.ts";
+import { resolveColor } from "./resolve-color.ts";
+import type { ChartModel, ColorRef } from "./types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+
+/**
+ * Compose a single series's final sRGB color.
+ *
+ * - `model` may be any ChartModel variant. For the `unsupported` /
+ *   `combo` variants the seriesIdx refers to the top-level series list
+ *   (bar/line/area/pie/scatter/bubble) flattened in declaration order.
+ *   Combo callers should pass the sub-group's model directly for the
+ *   cleanest result.
+ * - `seriesIdx` is the index into the model's `series` array (or
+ *   `categoryLabels` for pie when `varyColors=true`).
+ * - `theme` is the resolved workbook theme; pass `{ colors: {} }` for
+ *   tests that want fallback-only behavior.
+ *
+ * Returns an always-valid `#RRGGBB` string. Malformed inputs fall through
+ * to the resolver's fallback color (#808080).
+ */
+export function composeSeriesColor(
+  model: ChartModel,
+  theme: ResolvedTheme,
+  seriesIdx: number,
+): string {
+  // 1. Explicit per-series override takes priority.
+  const override = readSeriesOverrideColor(model, seriesIdx);
+  if (override) return resolveColor(override, theme);
+
+  // 2. Fall through to the chart-style's palette.
+  const style = getChartStyle(resolveChartStyleId(model.styleId));
+  const ref = paletteColorRef(style.seriesColorMode, seriesIdx);
+  return resolveColor(ref, theme);
+}
+
+/**
+ * Pre-compute the resolved sRGB color for every series in `model`.
+ * Returns an empty array for `unsupported` charts. For pie/doughnut the
+ * array length matches the number of slices (categoryLabels), not the
+ * number of series (pie has exactly one series).
+ */
+export function deriveResolvedColors(
+  model: ChartModel,
+  theme: ResolvedTheme,
+): string[] {
+  const out: string[] = [];
+  const n = countPaletteSlots(model);
+  for (let i = 0; i < n; i++) {
+    out.push(composeSeriesColor(model, theme, i));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/**
+ * How many distinct colors the renderer needs. For pie charts with
+ * varyColors (the default), we need one color per slice; for all other
+ * families, one per series.
+ */
+function countPaletteSlots(model: ChartModel): number {
+  switch (model.kind) {
+    case "pie":
+      return model.varyColors && model.series.length > 0
+        ? model.series[0]!.values.length
+        : model.series.length;
+    case "bar":
+    case "line":
+    case "area":
+    case "scatter":
+    case "bubble":
+      return model.series.length;
+    case "combo": {
+      let total = 0;
+      for (const group of model.groups) total += group.series.length;
+      return total;
+    }
+    case "unsupported":
+      return 0;
+  }
+}
+
+/**
+ * Read an explicit per-series fill color override. Pie-only: also checks
+ * per-slice dataPoint overrides when `seriesIdx` is a slice index.
+ */
+function readSeriesOverrideColor(
+  model: ChartModel,
+  seriesIdx: number,
+): ColorRef | undefined {
+  if (model.kind === "unsupported" || model.kind === "combo") return undefined;
+
+  // Pie: per-slice dPt.spPr.fill takes priority.
+  if (model.kind === "pie") {
+    const pieSeries = model.series[0];
+    if (!pieSeries) return undefined;
+    const dp = pieSeries.dataPoints?.find((d) => d.idx === seriesIdx);
+    const dpFill = dp?.spPr?.fill;
+    if (dpFill && dpFill.kind === "solid") return dpFill.color;
+    // Pie with varyColors=false falls through to the series spPr color.
+    if (!model.varyColors) {
+      const seriesFill = pieSeries.spPr?.fill;
+      if (seriesFill && seriesFill.kind === "solid") return seriesFill.color;
+    }
+    return undefined;
+  }
+
+  // Bar / line / area / scatter / bubble: read series[idx].spPr.fill.
+  const series = model.series[seriesIdx];
+  if (!series) return undefined;
+  const fill = series.spPr?.fill;
+  if (fill && fill.kind === "solid") return fill.color;
+  // Gradient and pattern: pick the first stop as a solid approximation
+  // until Stage 4 renderers handle them natively.
+  if (fill && fill.kind === "gradient" && fill.stops.length > 0) {
+    return fill.stops[0]!.color;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,277 @@
+/**
+ * Parse chart axis elements.
+ *
+ * OOXML defines four axis element names:
+ *   c:catAx (category)  c:valAx (value)  c:dateAx (date)  c:serAx (series)
+ *
+ * They share a common set of child elements (c:axId, c:delete, c:axPos,
+ * c:title, c:majorGridlines, c:minorGridlines, c:numFmt, c:crossAx, etc.)
+ * plus axis-specific extensions. This parser produces a discriminated
+ * `Axis` union that records which root element was seen.
+ *
+ * Note: c:delete has inverted semantics — `val="1"` means *invisible* and
+ * a missing element means *visible*. We store the normal-sense boolean
+ * on `AxisBase.visible`.
+ */
+
+import {
+  findChildOptional,
+  localName,
+  readFloatVal,
+  readIntVal,
+  readStringAttr,
+  textContent,
+} from "../xml-attr-helpers.ts";
+import type { XmlElementNode } from "../xml-element.ts";
+import { parseXml } from "../xml-parser.ts";
+
+import type {
+  Axis,
+  AxisBase,
+  CategoryAxis,
+  DateAxis,
+  SeriesAxis,
+  Title,
+  ValueAxis,
+} from "./types.ts";
+
+const AXIS_LOCAL_NAMES = new Set(["catAx", "valAx", "dateAx", "serAx"]);
+
+/** Parse an axis element from raw XML. Throws if the root is not a known axis. */
+export function parseAxis(xml: string): Axis {
+  const root = parseXml(xml);
+  let axisNode: XmlElementNode | undefined;
+  for (const child of root.children) {
+    if (child.type !== "element") continue;
+    if (AXIS_LOCAL_NAMES.has(localName(child.name))) {
+      axisNode = child;
+      break;
+    }
+  }
+  if (!axisNode) {
+    throw new Error(
+      `parseAxis: expected one of catAx/valAx/dateAx/serAx at root`,
+    );
+  }
+  return parseAxisNode(axisNode);
+}
+
+/** Dispatch to the axis-kind-specific parser based on the element name. */
+export function parseAxisNode(node: XmlElementNode): Axis {
+  const base = parseAxisBase(node);
+  switch (localName(node.name)) {
+    case "catAx":
+      return parseCategoryAxisFields(node, base);
+    case "valAx":
+      return parseValueAxisFields(node, base);
+    case "dateAx":
+      return parseDateAxisFields(node, base);
+    case "serAx":
+      return { ...base, kind: "series" } satisfies SeriesAxis;
+    default:
+      throw new Error(`parseAxisNode: unsupported axis element ${node.name}`);
+  }
+}
+
+function parseAxisBase(node: XmlElementNode): AxisBase {
+  const axIdNode = findChildOptional(node, "axId");
+  const id = axIdNode ? (readStringAttr(axIdNode, "val") ?? "") : "";
+  const deleteNode = findChildOptional(node, "delete");
+  // c:delete has inverted semantics.
+  const deleteVal = deleteNode?.attributes["val"] ?? "0";
+  const visible = deleteVal !== "1" && deleteVal.toLowerCase() !== "true";
+
+  const positionRaw = findChildOptional(node, "axPos")?.attributes["val"] ?? "b";
+  const position: AxisBase["position"] =
+    positionRaw === "b" || positionRaw === "t" || positionRaw === "l" || positionRaw === "r"
+      ? positionRaw
+      : "b";
+
+  const crossAxisId = findChildOptional(node, "crossAx")?.attributes["val"];
+  const crossesAt = parseCrossesAt(findChildOptional(node, "crosses"));
+
+  const base: AxisBase = {
+    id,
+    position,
+    visible,
+  };
+  if (crossAxisId !== undefined) base.crossAxisId = crossAxisId;
+  if (crossesAt !== undefined) base.crossesAt = crossesAt;
+
+  const title = parseAxisTitle(findChildOptional(node, "title"));
+  if (title) base.title = title;
+
+  if (findChildOptional(node, "majorGridlines")) base.majorGridlines = true;
+  if (findChildOptional(node, "minorGridlines")) base.minorGridlines = true;
+
+  const majorUnit = readFloatVal(findChildOptional(node, "majorUnit"));
+  if (majorUnit !== undefined) base.majorUnit = majorUnit;
+  const minorUnit = readFloatVal(findChildOptional(node, "minorUnit"));
+  if (minorUnit !== undefined) base.minorUnit = minorUnit;
+
+  const numFmtNode = findChildOptional(node, "numFmt");
+  if (numFmtNode) {
+    const formatCode = numFmtNode.attributes["formatCode"];
+    if (formatCode !== undefined) base.numberFormat = formatCode;
+  }
+
+  return base;
+}
+
+function parseCrossesAt(
+  crossesNode: XmlElementNode | undefined,
+): number | "autoZero" | "max" | "min" | undefined {
+  if (!crossesNode) return undefined;
+  const val = crossesNode.attributes["val"];
+  if (val === undefined) return undefined;
+  if (val === "autoZero" || val === "max" || val === "min") return val;
+  const n = Number.parseFloat(val);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parseAxisTitle(titleNode: XmlElementNode | undefined): Title | undefined {
+  if (!titleNode) return undefined;
+  let text: string | undefined;
+  const tx = findChildOptional(titleNode, "tx");
+  if (tx) {
+    const rich = findChildOptional(tx, "rich");
+    if (rich) {
+      const texts: string[] = [];
+      const collectT = (children: XmlElementNode["children"]): void => {
+        for (const c of children) {
+          if (c.type !== "element") continue;
+          if (localName(c.name) === "t") {
+            texts.push(textContent(c));
+          } else {
+            collectT(c.children);
+          }
+        }
+      };
+      collectT(rich.children);
+      text = texts.join("");
+    } else {
+      const v = findChildOptional(tx, "v");
+      if (v) text = textContent(v);
+    }
+  }
+  const overlay = findChildOptional(titleNode, "overlay")?.attributes["val"] === "1";
+  const title: Title = { overlay };
+  if (text) title.text = text;
+  return title;
+}
+
+// ---------------------------------------------------------------------------
+// Category axis
+// ---------------------------------------------------------------------------
+
+function parseCategoryAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): CategoryAxis {
+  const auto = findChildOptional(node, "auto")?.attributes["val"] === "1";
+  const labelAlignRaw = findChildOptional(node, "lblAlgn")?.attributes["val"];
+  const labelAlign =
+    labelAlignRaw === "ctr" || labelAlignRaw === "l" || labelAlignRaw === "r"
+      ? labelAlignRaw
+      : undefined;
+  const labelOffset = readIntVal(findChildOptional(node, "lblOffset"));
+  const tickMarkRaw = findChildOptional(node, "majorTickMark")?.attributes["val"];
+  const tickMark =
+    tickMarkRaw === "none" ||
+    tickMarkRaw === "in" ||
+    tickMarkRaw === "out" ||
+    tickMarkRaw === "cross"
+      ? tickMarkRaw
+      : undefined;
+  const tickLabelSkip = readIntVal(findChildOptional(node, "tickLblSkip"));
+  const tickMarkSkip = readIntVal(findChildOptional(node, "tickMarkSkip"));
+
+  const axis: CategoryAxis = {
+    ...base,
+    kind: "category",
+    auto,
+    categoryLabels: [],
+  };
+  if (labelAlign) axis.labelAlign = labelAlign;
+  if (labelOffset !== undefined) axis.labelOffset = labelOffset;
+  if (tickMark) axis.tickMark = tickMark;
+  if (tickLabelSkip !== undefined) axis.tickLabelSkip = tickLabelSkip;
+  if (tickMarkSkip !== undefined) axis.tickMarkSkip = tickMarkSkip;
+  return axis;
+}
+
+// ---------------------------------------------------------------------------
+// Value axis
+// ---------------------------------------------------------------------------
+
+function parseValueAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): ValueAxis {
+  const scaling = findChildOptional(node, "scaling");
+  const min = readFloatVal(scaling ? findChildOptional(scaling, "min") : undefined);
+  const max = readFloatVal(scaling ? findChildOptional(scaling, "max") : undefined);
+  const logBase = readFloatVal(
+    scaling ? findChildOptional(scaling, "logBase") : undefined,
+  );
+  const orientation = scaling
+    ? findChildOptional(scaling, "orientation")?.attributes["val"]
+    : undefined;
+  const reverse = orientation === "maxMin";
+
+  const crossBetweenRaw = findChildOptional(node, "crossBetween")?.attributes["val"];
+  const crossBetween =
+    crossBetweenRaw === "between" || crossBetweenRaw === "midCat"
+      ? crossBetweenRaw
+      : undefined;
+
+  const axis: ValueAxis = {
+    ...base,
+    kind: "value",
+    reverse,
+  };
+  if (min !== undefined) axis.min = min;
+  if (max !== undefined) axis.max = max;
+  if (logBase !== undefined) axis.logBase = logBase;
+  if (crossBetween) axis.crossBetween = crossBetween;
+  return axis;
+}
+
+// ---------------------------------------------------------------------------
+// Date axis
+// ---------------------------------------------------------------------------
+
+function parseDateAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): DateAxis {
+  const scaling = findChildOptional(node, "scaling");
+  const min = readFloatVal(scaling ? findChildOptional(scaling, "min") : undefined);
+  const max = readFloatVal(scaling ? findChildOptional(scaling, "max") : undefined);
+  const baseTimeUnit = asTimeUnit(
+    findChildOptional(node, "baseTimeUnit")?.attributes["val"],
+  );
+  const majorTimeUnit = asTimeUnit(
+    findChildOptional(node, "majorTimeUnit")?.attributes["val"],
+  );
+  const minorTimeUnit = asTimeUnit(
+    findChildOptional(node, "minorTimeUnit")?.attributes["val"],
+  );
+  const axis: DateAxis = {
+    ...base,
+    kind: "date",
+  };
+  if (min !== undefined) axis.min = min;
+  if (max !== undefined) axis.max = max;
+  if (baseTimeUnit) axis.baseTimeUnit = baseTimeUnit;
+  if (majorTimeUnit) axis.majorTimeUnit = majorTimeUnit;
+  if (minorTimeUnit) axis.minorTimeUnit = minorTimeUnit;
+  return axis;
+}
+
+function asTimeUnit(
+  raw: string | undefined,
+): "days" | "months" | "years" | undefined {
+  if (raw === "days" || raw === "months" || raw === "years") return raw;
+  return undefined;
+}