@beyondwork/docx-react-component 1.0.48 → 1.0.50

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-chart-space.ts

@@ -49,9 +49,11 @@ import type {
   BubbleChartModel,
   BubbleSeries,
   CategoryAxis,
+  CategoryLikeAxis,
   ChartCommon,
   ChartModel,
   ComboChartModel,
+  DateAxis,
   Legend,
   LineChartModel,
   LineSeries,
@@ -283,16 +285,28 @@ function parsePlotAreaAxes(plotArea: XmlElementNode): Map<string, Axis> {
 }
 
 /**
- * Find the primary category and value axes that a type group binds to. The
- * group declares its binding via two or more `<c:axId val="…"/>` children
- * (typically exactly two: category axis id + value axis id). Shared by
- * bar/line/area since they all have the same category-axis + value-axis
- * topology.
+ * Find the category/date axis and the primary + secondary value axes that
+ * a type group binds to. The group declares its binding via two or more
+ * `<c:axId val="…"/>` children (typically exactly two: category-axis id +
+ * value-axis id; combos with a secondary scale add a third pair).
+ *
+ * Axis objects are **cloned** before return. Multiple groups in a combo
+ * can reference the same shared `Axis` instance from the plot-area map;
+ * downstream code mutates `categoryLabels` on a per-group basis, so a
+ * shared reference would bleed labels from one group into another.
+ *
+ * Date axes are preserved with `kind: "date"` (not narrowed to category)
+ * so the renderer can format tick labels as dates. Bar/line/area models'
+ * `categoryAxis` field is typed `CategoryLikeAxis = CategoryAxis | DateAxis`.
  */
 function resolveCategoryValueAxes(
   groupNode: XmlElementNode,
   axes: Map<string, Axis>,
-): { categoryAxis: CategoryAxis; valueAxis: ValueAxis } {
+): {
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
+} {
   const ids: string[] = [];
   for (const child of groupNode.children) {
     if (child.type !== "element") continue;
@@ -301,40 +315,64 @@ function resolveCategoryValueAxes(
     if (id) ids.push(id);
   }
 
-  let categoryAxis: CategoryAxis | undefined;
-  let valueAxis: ValueAxis | undefined;
+  let categoryAxis: CategoryLikeAxis | undefined;
+  const valueAxesRaw: ValueAxis[] = [];
   for (const id of ids) {
     const ax = axes.get(id);
     if (!ax) continue;
-    if (ax.kind === "category") categoryAxis = ax;
-    // Date axes can bind where a category axis would go; treat as category.
-    else if (ax.kind === "date" && !categoryAxis) {
-      categoryAxis = dateAxisToCategory(ax);
-    } else if (ax.kind === "value" && !valueAxis) valueAxis = ax;
+    if (ax.kind === "category") {
+      if (!categoryAxis) categoryAxis = cloneCategoryAxis(ax);
+    } else if (ax.kind === "date") {
+      if (!categoryAxis) categoryAxis = cloneDateAxis(ax);
+    } else if (ax.kind === "value") {
+      valueAxesRaw.push(ax);
+    }
   }
 
   if (!categoryAxis) categoryAxis = placeholderCategoryAxis();
-  if (!valueAxis) valueAxis = placeholderValueAxis();
-  return { categoryAxis, valueAxis };
+
+  // Primary / secondary resolution:
+  //   - 0 value axes → placeholder primary.
+  //   - 1 value axis  → it's the primary regardless of position (typical
+  //     for a group that only targets the secondary scale in a combo —
+  //     the group itself sees its bound axis as "its" primary).
+  //   - ≥2 value axes → leading side (l/b) is primary, trailing (r/t)
+  //     is secondary. Ambiguous positions fall back to declaration order.
+  let primary: ValueAxis | undefined;
+  let secondary: ValueAxis | undefined;
+  if (valueAxesRaw.length === 1) {
+    primary = cloneValueAxis(valueAxesRaw[0]!);
+  } else if (valueAxesRaw.length >= 2) {
+    for (const ax of valueAxesRaw) {
+      const isLeading = ax.position === "l" || ax.position === "b";
+      if (isLeading && !primary) primary = cloneValueAxis(ax);
+      else if (!secondary) secondary = cloneValueAxis(ax);
+      else if (!primary) primary = cloneValueAxis(ax);
+    }
+  }
+  if (!primary) primary = placeholderValueAxis();
+
+  const out: {
+    categoryAxis: CategoryLikeAxis;
+    valueAxis: ValueAxis;
+    secondaryValueAxis?: ValueAxis;
+  } = { categoryAxis, valueAxis: primary };
+  if (secondary) out.secondaryValueAxis = secondary;
+  return out;
 }
 
-/** Narrow a date axis into a CategoryAxis shape so bar/line/area models
- *  can expose a uniform `categoryAxis` field. Date-specific fields are
- *  dropped here; Stage 2/3 can preserve them via a dedicated route. */
-function dateAxisToCategory(ax: Axis & { kind: "date" }): CategoryAxis {
-  return {
-    kind: "category",
-    id: ax.id,
-    position: ax.position,
-    visible: ax.visible,
-    auto: true,
-    categoryLabels: [],
-    ...(ax.crossAxisId !== undefined ? { crossAxisId: ax.crossAxisId } : {}),
-    ...(ax.crossesAt !== undefined ? { crossesAt: ax.crossesAt } : {}),
-    ...(ax.majorGridlines !== undefined ? { majorGridlines: ax.majorGridlines } : {}),
-    ...(ax.minorGridlines !== undefined ? { minorGridlines: ax.minorGridlines } : {}),
-    ...(ax.numberFormat !== undefined ? { numberFormat: ax.numberFormat } : {}),
-  };
+function cloneCategoryAxis(ax: CategoryAxis): CategoryAxis {
+  // categoryLabels is copied so per-group promotion does not leak across
+  // combo groups sharing the underlying Axis object.
+  return { ...ax, categoryLabels: [...ax.categoryLabels] };
+}
+
+function cloneValueAxis(ax: ValueAxis): ValueAxis {
+  return { ...ax };
+}
+
+function cloneDateAxis(ax: DateAxis): DateAxis {
+  return { ...ax };
 }
 
 function placeholderCategoryAxis(): CategoryAxis {
@@ -390,11 +428,18 @@ function parseBarGroup(
     series.push(parseBarSeriesNode(child));
   }
 
-  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
-
-  // Promote category labels from the first series onto the axis if they
-  // aren't already populated (typical for Word-authored charts).
-  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+  const { categoryAxis, valueAxis, secondaryValueAxis } =
+    resolveCategoryValueAxes(groupNode, axes);
+
+  // Promote category labels from the first series onto a category axis
+  // if they aren't already populated (typical for Word-authored charts).
+  // Date axes derive tick labels from serial dates and must not be
+  // overwritten.
+  if (
+    categoryAxis.kind === "category" &&
+    categoryAxis.categoryLabels.length === 0 &&
+    series.length > 0
+  ) {
     categoryAxis.categoryLabels = series[0]!.categories;
   }
 
@@ -413,6 +458,7 @@ function parseBarGroup(
     categoryAxis,
     valueAxis,
   };
+  if (secondaryValueAxis) model.secondaryValueAxis = secondaryValueAxis;
   return model;
 }
 
@@ -443,12 +489,17 @@ function parseLineGroup(
     series.push(parseLineSeriesNode(child));
   }
 
-  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
-  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+  const { categoryAxis, valueAxis, secondaryValueAxis } =
+    resolveCategoryValueAxes(groupNode, axes);
+  if (
+    categoryAxis.kind === "category" &&
+    categoryAxis.categoryLabels.length === 0 &&
+    series.length > 0
+  ) {
     categoryAxis.categoryLabels = series[0]!.categories;
   }
 
-  return {
+  const model: LineChartModel = {
     ...common,
     kind: "line",
     grouping,
@@ -458,6 +509,8 @@ function parseLineGroup(
     categoryAxis,
     valueAxis,
   };
+  if (secondaryValueAxis) model.secondaryValueAxis = secondaryValueAxis;
+  return model;
 }
 
 /**
@@ -494,11 +547,14 @@ function parsePieGroup(
       : varyColorsRaw !== "0" && varyColorsRaw.toLowerCase() !== "false";
 
   // c:firstSliceAngle is in 1/60000 of a degree, clockwise from 12 o'clock.
-  // ECMA-376 defines 0–360 range; we perform the unit conversion and leave
-  // clamping to the renderer so out-of-range values stay recoverable.
+  // ECMA-376 §21.2.2.68 constrains the value to 0–360; we clamp with
+  // modulo-360 so out-of-range authored XML (rare but legal for transitional
+  // documents) still produces a renderable slice start angle.
   const firstSliceAngleRaw = readIntVal(findChildOptional(groupNode, "firstSliceAngle"));
   const firstSliceAngle =
-    firstSliceAngleRaw !== undefined ? firstSliceAngleRaw / OOXML_ANGLE_UNIT : 0;
+    firstSliceAngleRaw !== undefined
+      ? (((firstSliceAngleRaw / OOXML_ANGLE_UNIT) % 360) + 360) % 360
+      : 0;
 
   // Doughnut hole size is a percent (0–99 typical). Missing on pieChart.
   const holeSizePercent = doughnut
@@ -568,12 +624,17 @@ function parseAreaGroup(
     series.push(parseSeriesBase(child));
   }
 
-  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
-  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+  const { categoryAxis, valueAxis, secondaryValueAxis } =
+    resolveCategoryValueAxes(groupNode, axes);
+  if (
+    categoryAxis.kind === "category" &&
+    categoryAxis.categoryLabels.length === 0 &&
+    series.length > 0
+  ) {
     categoryAxis.categoryLabels = series[0]!.categories;
   }
 
-  return {
+  const model: AreaChartModel = {
     ...common,
     kind: "area",
     grouping,
@@ -581,6 +642,8 @@ function parseAreaGroup(
     categoryAxis,
     valueAxis,
   };
+  if (secondaryValueAxis) model.secondaryValueAxis = secondaryValueAxis;
+  return model;
 }
 
 // ---------------------------------------------------------------------------
@@ -655,6 +718,15 @@ function parseComboPlotArea(
     }
     groups.push(model);
 
+    // hasSecondaryAxis fires in either of two ways:
+    // (1) a single group declared a secondaryValueAxis (two value axes bound
+    //     to the same group — e.g. bar on left + line on right sharing one
+    //     c:barChart + c:lineChart — technically illegal per ECMA but seen
+    //     in the wild).
+    // (2) two groups bind to different value axes (the typical combo shape).
+    if (model.secondaryValueAxis) {
+      hasSecondaryAxis = true;
+    }
     const thisGroupValueAxisId = model.valueAxis.id;
     if (!primaryValueAxisId) {
       primaryValueAxisId = thisGroupValueAxisId;

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

@@ -67,6 +67,7 @@ export function parseSeriesBase(node: XmlElementNode): Series {
   const categories = extractStrCache(findChildOptional(node, "cat"));
   const values = extractNumCache(findChildOptional(node, "val"));
   const spPr = parseShapeProperties(findChildOptional(node, "spPr"));
+  const dataPoints = parseDataPointOverrides(node);
 
   const series: Series = {
     idx,
@@ -76,13 +77,16 @@ export function parseSeriesBase(node: XmlElementNode): Series {
   };
   if (name !== undefined) series.name = name;
   if (spPr) series.spPr = spPr;
+  if (dataPoints.length > 0) series.dataPoints = dataPoints;
   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.
+ * where "bar" makes the intent clear. Per-data-point overrides (c:dPt) —
+ * highlights, invertIfNegative, color overrides — are attached by the
+ * base parser so all category-oriented families (bar, area) surface them.
  */
 export function parseBarSeriesNode(node: XmlElementNode): Series {
   return parseSeriesBase(node);
@@ -384,14 +388,19 @@ export function extractNumCache(
   expected?: number,
 ): Array<number | null> {
   if (!container) return [];
-  const cache =
+  // Prefer numCache. The strCache fallback is intentional for numRef-
+  // backed category axes where Word emits the numeric series through the
+  // string-cache path (e.g. a Year axis authored as numbers but displayed
+  // as labels). Each stringified value is then parseFloat'd; non-finite
+  // strings collapse to null, preserving the sparse-index contract.
+  const cacheNode =
     findFirstDescendant(container, "numCache") ??
     findFirstDescendant(container, "strCache");
-  if (!cache) return [];
-  const ptCount = readIntVal(findChildOptional(cache, "ptCount")) ?? 0;
+  if (!cacheNode) return [];
+  const ptCount = readIntVal(findChildOptional(cacheNode, "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) {
+  for (const child of cacheNode.children) {
     if (child.type !== "element" || localName(child.name) !== "pt") continue;
     const idxRaw = child.attributes["idx"];
     const idx = idxRaw ? Number.parseInt(idxRaw, 10) : Number.NaN;
@@ -459,18 +468,74 @@ function parseFill(spPrNode: XmlElementNode): FillSpec | undefined {
     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" };
+  // Gradient fill: extract c:gsLst stops so renderers can honor the
+  // authored gradient or, as a minimum, fall back to the first stop as a
+  // solid color. Stage 4 renderers consume the full stop list.
+  const gradNode = findChildOptional(spPrNode, "gradFill");
+  if (gradNode) {
+    const gradient = parseGradientFill(gradNode);
+    if (gradient) return gradient;
   }
-  if (findChildOptional(spPrNode, "pattFill")) {
+  // Pattern fill: Stage 1 degrades to the foreground color as a solid
+  // fallback so bars stay visible. A richer pattern renderer is deferred.
+  const pattNode = findChildOptional(spPrNode, "pattFill");
+  if (pattNode) {
+    const fg = findChildOptional(pattNode, "fgClr");
+    if (fg) {
+      const color = parseColorRef(fg);
+      if (color) return { kind: "solid", color };
+    }
     return { kind: "none" };
   }
   return undefined;
 }
 
+/**
+ * Parse a DrawingML `a:gradFill` element per ECMA-376 §20.1.8.33.
+ *
+ * Shape: `<a:gradFill><a:gsLst><a:gs pos="N"><a:srgbClr|a:schemeClr…/></a:gs>…</a:gsLst><a:lin ang="…"/></a:gradFill>`.
+ * Stops' `pos` attribute is in parts-per-100,000 (0..100000); we normalize
+ * to 0..1 so renderers can project onto their own coordinate system.
+ *
+ * Returns undefined when the gradient has no usable stops so the caller
+ * can fall through to the fill chain's subsequent branches. Mal-authored
+ * gradients (no gsLst, no color children) degrade gracefully to `none`
+ * rather than producing an invalid FillSpec.
+ */
+function parseGradientFill(gradNode: XmlElementNode): FillSpec | undefined {
+  const gsLst = findChildOptional(gradNode, "gsLst");
+  if (!gsLst) return { kind: "none" };
+  const stops: Array<{ pos: number; color: ColorRef }> = [];
+  for (const child of gsLst.children) {
+    if (child.type !== "element" || localName(child.name) !== "gs") continue;
+    const posRaw = child.attributes["pos"];
+    const posPpm = posRaw ? Number.parseInt(posRaw, 10) : Number.NaN;
+    const color = parseColorRef(child);
+    if (!color) continue;
+    const pos = Number.isFinite(posPpm)
+      ? Math.max(0, Math.min(1, posPpm / 100_000))
+      : stops.length / 2;
+    stops.push({ pos, color });
+  }
+  if (stops.length === 0) return { kind: "none" };
+
+  // a:lin carries angle in 1/60,000 of a degree; a:path carries a path
+  // type (linear/radial/rect) but no angle. Stage 1 only reads linear.
+  let angle: number | undefined;
+  const lin = findChildOptional(gradNode, "lin");
+  if (lin) {
+    const angRaw = lin.attributes["ang"];
+    if (angRaw) {
+      const n = Number.parseInt(angRaw, 10);
+      if (Number.isFinite(n)) angle = n / 60_000;
+    }
+  }
+
+  const gradient: FillSpec = { kind: "gradient", stops };
+  if (angle !== undefined) gradient.angle = angle;
+  return gradient;
+}
+
 function parseStroke(lnNode: XmlElementNode | undefined): StrokeSpec | undefined {
   if (!lnNode) return undefined;
   const stroke: StrokeSpec = {};

package/src/io/ooxml/chart/resolve-color.ts

@@ -27,13 +27,20 @@ const OOXML_UNIT = 100_000; // modifier val is in parts per 100,000
  * Scheme-alias map. Word often emits aliases that refer to the primary
  * color slots: `tx1` → `dk1`, `bg1` → `lt1`, `tx2` → `dk2`, `bg2` → `lt2`.
  * The mapping is standardized by DrawingML.
+ *
+ * `phClr` is deliberately NOT aliased — it's a DrawingML "placeholder"
+ * color (ECMA-376 §20.1.4.1.22) that the caller is expected to substitute
+ * from its own context (e.g. the surrounding shape's accent). When the
+ * caller has no substitution, resolving phClr should fall through to the
+ * fallback color rather than silently pretend it meant accent1. Prior
+ * behavior aliased `phClr` → `accent1`, which silently miscolored every
+ * chart that used a placeholder color in its sidecar colors.xml.
  */
 const SCHEME_ALIASES: Record<string, string> = {
   tx1: "dk1",
   bg1: "lt1",
   tx2: "dk2",
   bg2: "lt2",
-  phClr: "accent1", // placeholder color — callers usually supply their own
 };
 
 export function resolveColor(ref: ColorRef, theme: ResolvedTheme): string {
@@ -114,12 +121,15 @@ function applyMod(rgb: Rgb, mod: ColorMod): Rgb {
       return hslToRgb(hsl);
     }
     case "hueMod": {
-      // Rotate hue. val is in OOXML's angle-like units (1/100,000 turn →
-      // degrees = frac * 360). The spec is slightly ambiguous here; our
-      // interpretation is that hueMod=1.0 is a full rotation.
+      // Multiplicative scaling of the hue angle — NOT an additive
+      // rotation. ECMA-376 §20.1.2.3.14 and LibreOffice
+      // (oox/source/drawingml/color.cxx `lclModValue`) apply `hueMod` as
+      // `hue' = hue * (val/100000)`, stored in the hue dimension of HSL
+      // and clamped into the valid angle range. We wrap via mod-360 for
+      // numeric resilience when the source value exceeds 100% (a legal
+      // "expand hue" case).
       const hsl = rgbToHsl(rgb);
-      hsl.h = (hsl.h + frac * 360) % 360;
-      if (hsl.h < 0) hsl.h += 360;
+      hsl.h = ((hsl.h * frac) % 360 + 360) % 360;
       return hslToRgb(hsl);
     }
     case "shade": {

package/src/io/ooxml/chart/types.ts

@@ -51,6 +51,14 @@ export interface ChartCommon {
   rawXml: string;
 }
 
+/**
+ * Category-like axis binding for bar/line/area charts. Date axes are a
+ * legal substitute for a category axis at the XML level (c:dateAx replaces
+ * c:catAx) and we preserve the kind here so the renderer can format
+ * category labels as dates when the source authored them that way.
+ */
+export type CategoryLikeAxis = CategoryAxis | DateAxis;
+
 export interface BarChartModel extends ChartCommon {
   kind: "bar";
   /** "bar" = horizontal; "column" = vertical. */
@@ -61,7 +69,7 @@ export interface BarChartModel extends ChartCommon {
   /** Overlap within a category in percent, -100..100 (c:overlap). */
   overlap: number;
   series: Series[];
-  categoryAxis: CategoryAxis;
+  categoryAxis: CategoryLikeAxis;
   valueAxis: ValueAxis;
   /** Present when any series/group targeted the secondary axis. */
   secondaryValueAxis?: ValueAxis;
@@ -75,7 +83,7 @@ export interface LineChartModel extends ChartCommon {
   /** Global marker flag; per-series values can override. */
   marker: boolean;
   series: LineSeries[];
-  categoryAxis: CategoryAxis;
+  categoryAxis: CategoryLikeAxis;
   valueAxis: ValueAxis;
   secondaryValueAxis?: ValueAxis;
 }
@@ -98,8 +106,9 @@ export interface AreaChartModel extends ChartCommon {
   kind: "area";
   grouping: "standard" | "stacked" | "percentStacked";
   series: Series[];
-  categoryAxis: CategoryAxis;
+  categoryAxis: CategoryLikeAxis;
   valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
 }
 
 export interface ScatterChartModel extends ChartCommon {
@@ -400,10 +409,21 @@ export interface TextProperties {
 // ---------------------------------------------------------------------------
 
 /**
- * Compile-time list of every ChartModel kind. If a new family is added to
- * the union without a matching `kind` literal added here, tsgo fails.
+ * Compile-time assertion that `ChartModel["kind"]` equals the expected
+ * literal-union below. If a new variant is added to `ChartModel` without
+ * being listed in `_ExpectedKinds`, `_Equals` resolves to `false` and the
+ * subsequent `true` assignment fails at compile time. The previous
+ * dual-assign-cast pattern did not actually enforce union equality — any
+ * new kind silently passed through.
+ *
+ * Reference: the standard "exact type equality" trick using contravariance
+ * of conditional-type generic functions.
  */
-type _ChartModelKindExhaustive = ChartModel["kind"];
+type _Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2)
+    ? true
+    : false;
+
 type _ExpectedKinds =
   | "bar"
   | "line"
@@ -413,8 +433,7 @@ type _ExpectedKinds =
   | "bubble"
   | "combo"
   | "unsupported";
-// Bi-directional assignability asserts union equality.
-const _kindA: _ChartModelKindExhaustive = "bar" as _ExpectedKinds;
-const _kindB: _ExpectedKinds = "bar" as _ChartModelKindExhaustive;
-void _kindA;
-void _kindB;
+
+type _ChartKindCheck = _Equals<ChartModel["kind"], _ExpectedKinds>;
+const _kindExhaustive: _ChartKindCheck = true;
+void _kindExhaustive;