@beyondwork/docx-react-component 1.0.48 → 1.0.49

package/src/io/ooxml/chart/chart-style-table.ts

@@ -0,0 +1,543 @@
+/**
+ * OOXML chart-style table (styles 1-48).
+ *
+ * Chart styles are Word's legacy mechanism for setting per-chart visual
+ * properties by a single integer id. They pre-date the 2013+ per-chart
+ * `style1.xml` + `colors1.xml` sidecar parts, but Word still emits
+ * `c:chart/c:style val="N"` (or `c14:style val="10N"` as the MC choice
+ * wrapper) for every chart, and the legacy interpretation is the
+ * rendering fallback when no sidecar is present.
+ *
+ * Microsoft does not publish a machine-readable table for styles 1-48.
+ * The semantics below were reconstructed from:
+ *   - ECMA-376 Part 1 Annex K (chart-style IDs)
+ *   - Microsoft's visual references in the XlsxWriter project
+ *   - LibreOffice's `chart2/source/tools/ChartTypeTemplate.cxx`
+ *   - Observed behavior of Word 2016 / M365 when a chart carries only
+ *     a c:style element with no sidecar parts.
+ *
+ * Scope: styles 1-12. The remaining 13-48 are listed as "default" here
+ * and filled in by follow-up slices. A chart that references a style
+ * not yet in the table falls back to style 2 (the Office default) so
+ * the renderer always has a usable value.
+ *
+ * This file is pure data. No DOM, no React, no rendering code — any
+ * stage (Stage 3 SVG primitives, Stage 4 per-type renderers) can import
+ * from here without creating a layering cycle.
+ */
+
+import type { FillSpec, StrokeSpec, TextProperties } from "./types.ts";
+
+/**
+ * How each series gets a color.
+ *
+ * - `accent1To6`: round-robin through accent1..accent6, wrapping back
+ *   to accent1 on series 7+. Default for styles 1-4 + most charts.
+ * - `monochromaticAccentN`: single accent hue with per-series tint/shade
+ *   variations (first series at full strength, subsequent series
+ *   lightened or darkened by fixed steps). Styles 5-10.
+ */
+export type SeriesColorMode =
+  | "accent1To6"
+  | "monochromaticAccent1"
+  | "monochromaticAccent2"
+  | "monochromaticAccent3"
+  | "monochromaticAccent4"
+  | "monochromaticAccent5"
+  | "monochromaticAccent6";
+
+export interface ChartStyle {
+  /** How to assign a color to each series index. */
+  seriesColorMode: SeriesColorMode;
+  /** Background fill of the entire chart card (outside the plot area). */
+  backgroundFill?: FillSpec;
+  /** Plot area fill (behind the bars / lines / slices). */
+  plotAreaFill?: FillSpec;
+  /** Default title text properties. */
+  titleTxPr: TextProperties;
+  /** Default axis-label text properties. */
+  axisTxPr: TextProperties;
+  /** Default data-label text properties. */
+  dataLabelTxPr: TextProperties;
+  /** Default stroke around each series shape (bar/column/slice outline). */
+  seriesOutline?: StrokeSpec;
+  /** Default major gridline stroke. */
+  gridlineStroke?: StrokeSpec;
+}
+
+/**
+ * Style 2 is the Office default — it's what you get if you insert a
+ * chart in Word without touching the style picker. We use it as the
+ * fallback for unknown ids and as the anchor for derived styles.
+ */
+export const DEFAULT_CHART_STYLE_ID = 2;
+
+// ---------------------------------------------------------------------------
+// Common building blocks
+// ---------------------------------------------------------------------------
+
+const TEXT_BODY: TextProperties = {
+  fontFamily: "+mn-lt", // minor latin font from theme
+  fontSizePt: 9,
+  color: { kind: "scheme", value: "tx1", mods: [
+    { kind: "lumMod", value: 65000 },
+    { kind: "lumOff", value: 35000 },
+  ] },
+};
+
+const TEXT_TITLE: TextProperties = {
+  fontFamily: "+mn-lt",
+  fontSizePt: 14,
+  bold: false,
+  color: { kind: "scheme", value: "tx1", mods: [
+    { kind: "lumMod", value: 65000 },
+    { kind: "lumOff", value: 35000 },
+  ] },
+};
+
+const GRIDLINE_STROKE_SUBTLE: StrokeSpec = {
+  color: { kind: "scheme", value: "tx1", mods: [
+    { kind: "lumMod", value: 15000 },
+    { kind: "lumOff", value: 85000 },
+  ] },
+  widthEmu: 9525, // 0.75 pt
+  dash: "solid",
+};
+
+const SERIES_OUTLINE_NONE: StrokeSpec = {
+  noFill: true,
+};
+
+const SERIES_OUTLINE_LIGHT: StrokeSpec = {
+  color: { kind: "scheme", value: "lt1" },
+  widthEmu: 9525,
+  dash: "solid",
+};
+
+// ---------------------------------------------------------------------------
+// Styles 1-12
+// ---------------------------------------------------------------------------
+
+/**
+ * Style 1 — "Plain". Flat accent colors, no background, no outline,
+ * no gridlines. Used for minimal presentation.
+ */
+const STYLE_1: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: { kind: "none" },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_NONE,
+};
+
+/**
+ * Style 2 — Office default. Flat accent colors, subtle gridlines,
+ * minor outline. This is what `c:style val="2"` means.
+ */
+const STYLE_2: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: { kind: "none" },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_NONE,
+  gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+};
+
+/**
+ * Style 3 — Outlined variant of style 2. Subtle white outline on each
+ * series shape for card-style separation.
+ */
+const STYLE_3: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: { kind: "none" },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+  gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+};
+
+/**
+ * Style 4 — Colorful with a light plot-area background.
+ */
+const STYLE_4: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: {
+    kind: "solid",
+    color: { kind: "scheme", value: "lt1", mods: [
+      { kind: "lumMod", value: 95000 },
+    ] },
+  },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_NONE,
+  gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+};
+
+/**
+ * Styles 5-10 — Monochromatic. Each uses a single accent hue with
+ * per-series luminance variations. Style 5 = accent1, 6 = accent2, etc.
+ * ECMA-376 Annex K documents this six-way split.
+ */
+function monochromaticStyle(mode: SeriesColorMode): ChartStyle {
+  return {
+    seriesColorMode: mode,
+    backgroundFill: { kind: "none" },
+    plotAreaFill: { kind: "none" },
+    titleTxPr: TEXT_TITLE,
+    axisTxPr: TEXT_BODY,
+    dataLabelTxPr: TEXT_BODY,
+    seriesOutline: SERIES_OUTLINE_LIGHT,
+    gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+  };
+}
+
+const STYLE_5 = monochromaticStyle("monochromaticAccent1");
+const STYLE_6 = monochromaticStyle("monochromaticAccent2");
+const STYLE_7 = monochromaticStyle("monochromaticAccent3");
+const STYLE_8 = monochromaticStyle("monochromaticAccent4");
+const STYLE_9 = monochromaticStyle("monochromaticAccent5");
+const STYLE_10 = monochromaticStyle("monochromaticAccent6");
+
+/**
+ * Styles 11-12 — Colorful with darker plot-area background variations.
+ * These are less common in practice; rendered as decorated accent1To6.
+ */
+const STYLE_11: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: {
+    kind: "solid",
+    color: { kind: "scheme", value: "tx1", mods: [
+      { kind: "lumMod", value: 5000 },
+      { kind: "lumOff", value: 95000 },
+    ] },
+  },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_NONE,
+  gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+};
+
+const STYLE_12: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: {
+    kind: "solid",
+    color: { kind: "scheme", value: "tx1", mods: [
+      { kind: "lumMod", value: 15000 },
+      { kind: "lumOff", value: 85000 },
+    ] },
+  },
+  titleTxPr: TEXT_TITLE,
+  axisTxPr: TEXT_BODY,
+  dataLabelTxPr: TEXT_BODY,
+  seriesOutline: SERIES_OUTLINE_NONE,
+  gridlineStroke: GRIDLINE_STROKE_SUBTLE,
+};
+
+// ---------------------------------------------------------------------------
+// Styles 13-48
+//
+// Semantics below follow ECMA-376 Annex K groupings. The table mirrors the
+// visual grid from Microsoft's XlsxWriter reference:
+//   13-16: accent1To6 with decorated plot-area or darker gridlines
+//   17-22: accent1To6 with various plot-area backgrounds
+//   23-28: accent1To6 with dark (tx1-tinted) plot-area backgrounds
+//   29-34: monochromatic on accent1..accent6 (second pass with decoration)
+//   35-40: monochromatic on accent1..accent6 (third pass, darker)
+//   41-48: accent1To6 with mixed backgrounds/decorations
+//
+// Undocumented decoration details (gradient stops, precise luminance
+// ratios) are approximated. Fidelity refinement happens per-fixture once
+// the renderer lands in Stage 3-4.
+// ---------------------------------------------------------------------------
+
+function accentDecoratedStyle(options: {
+  plotAreaFill?: FillSpec;
+  seriesOutline?: StrokeSpec;
+  gridlineStroke?: StrokeSpec;
+} = {}): ChartStyle {
+  return {
+    seriesColorMode: "accent1To6",
+    backgroundFill: { kind: "none" },
+    plotAreaFill: options.plotAreaFill ?? { kind: "none" },
+    titleTxPr: TEXT_TITLE,
+    axisTxPr: TEXT_BODY,
+    dataLabelTxPr: TEXT_BODY,
+    seriesOutline: options.seriesOutline ?? SERIES_OUTLINE_NONE,
+    gridlineStroke: options.gridlineStroke ?? GRIDLINE_STROKE_SUBTLE,
+  };
+}
+
+const PLOT_AREA_FILL_LIGHT: FillSpec = {
+  kind: "solid",
+  color: { kind: "scheme", value: "lt1", mods: [
+    { kind: "lumMod", value: 95000 },
+  ] },
+};
+
+const PLOT_AREA_FILL_MEDIUM: FillSpec = {
+  kind: "solid",
+  color: { kind: "scheme", value: "tx1", mods: [
+    { kind: "lumMod", value: 25000 },
+    { kind: "lumOff", value: 75000 },
+  ] },
+};
+
+const PLOT_AREA_FILL_DARK: FillSpec = {
+  kind: "solid",
+  color: { kind: "scheme", value: "tx1", mods: [
+    { kind: "lumMod", value: 50000 },
+    { kind: "lumOff", value: 50000 },
+  ] },
+};
+
+const GRIDLINE_STROKE_LIGHT: StrokeSpec = {
+  color: { kind: "scheme", value: "lt1", mods: [
+    { kind: "lumMod", value: 80000 },
+  ] },
+  widthEmu: 9525,
+  dash: "solid",
+};
+
+// Styles 13-16: decorated accent1To6 with outline variants.
+const STYLE_13 = accentDecoratedStyle({ seriesOutline: SERIES_OUTLINE_LIGHT });
+const STYLE_14 = accentDecoratedStyle({
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+});
+const STYLE_15 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_LIGHT });
+const STYLE_16 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+  seriesOutline: SERIES_OUTLINE_NONE,
+});
+
+// Styles 17-22: accent1To6 with progressively darker plot-area fills.
+const STYLE_17 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_MEDIUM });
+const STYLE_18 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+});
+const STYLE_19 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+  gridlineStroke: GRIDLINE_STROKE_LIGHT,
+});
+const STYLE_20 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+  gridlineStroke: GRIDLINE_STROKE_LIGHT,
+});
+const STYLE_21 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_DARK,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+  gridlineStroke: GRIDLINE_STROKE_LIGHT,
+});
+const STYLE_22 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_DARK });
+
+// Styles 23-28: dark theme — dark plot-area background with light text.
+const TEXT_BODY_LIGHT: TextProperties = {
+  fontFamily: "+mn-lt",
+  fontSizePt: 9,
+  color: { kind: "scheme", value: "lt1" },
+};
+
+const TEXT_TITLE_LIGHT: TextProperties = {
+  fontFamily: "+mn-lt",
+  fontSizePt: 14,
+  color: { kind: "scheme", value: "lt1" },
+};
+
+function darkThemeStyle(mode: SeriesColorMode): ChartStyle {
+  return {
+    seriesColorMode: mode,
+    backgroundFill: { kind: "none" },
+    plotAreaFill: PLOT_AREA_FILL_DARK,
+    titleTxPr: TEXT_TITLE_LIGHT,
+    axisTxPr: TEXT_BODY_LIGHT,
+    dataLabelTxPr: TEXT_BODY_LIGHT,
+    seriesOutline: SERIES_OUTLINE_NONE,
+    gridlineStroke: GRIDLINE_STROKE_LIGHT,
+  };
+}
+
+const STYLE_23 = darkThemeStyle("accent1To6");
+const STYLE_24 = darkThemeStyle("accent1To6");
+const STYLE_25 = darkThemeStyle("accent1To6");
+const STYLE_26 = darkThemeStyle("accent1To6");
+const STYLE_27 = darkThemeStyle("accent1To6");
+const STYLE_28 = darkThemeStyle("accent1To6");
+
+// Styles 29-34: monochromatic second pass (accent1..accent6 with decoration).
+const STYLE_29: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent1"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+const STYLE_30: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent2"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+const STYLE_31: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent3"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+const STYLE_32: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent4"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+const STYLE_33: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent5"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+const STYLE_34: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent6"),
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+};
+
+// Styles 35-40: monochromatic third pass (darker, with medium background).
+const STYLE_35: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent1"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+const STYLE_36: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent2"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+const STYLE_37: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent3"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+const STYLE_38: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent4"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+const STYLE_39: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent5"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+const STYLE_40: ChartStyle = {
+  ...monochromaticStyle("monochromaticAccent6"),
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+};
+
+// Styles 41-48: accent1To6 mixed decoration.
+const STYLE_41 = accentDecoratedStyle();
+const STYLE_42 = accentDecoratedStyle({ seriesOutline: SERIES_OUTLINE_LIGHT });
+const STYLE_43 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_LIGHT });
+const STYLE_44 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_LIGHT,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+});
+const STYLE_45 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_MEDIUM });
+const STYLE_46 = accentDecoratedStyle({
+  plotAreaFill: PLOT_AREA_FILL_MEDIUM,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+});
+const STYLE_47 = accentDecoratedStyle({ plotAreaFill: PLOT_AREA_FILL_DARK });
+const STYLE_48: ChartStyle = {
+  seriesColorMode: "accent1To6",
+  backgroundFill: { kind: "none" },
+  plotAreaFill: PLOT_AREA_FILL_DARK,
+  titleTxPr: TEXT_TITLE_LIGHT,
+  axisTxPr: TEXT_BODY_LIGHT,
+  dataLabelTxPr: TEXT_BODY_LIGHT,
+  seriesOutline: SERIES_OUTLINE_LIGHT,
+  gridlineStroke: GRIDLINE_STROKE_LIGHT,
+};
+
+// ---------------------------------------------------------------------------
+// Exported lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Chart-style lookup keyed by the numeric style id. Styles not yet in
+ * the table are absent; use `getChartStyle()` for safe default fallback.
+ *
+ * Styles 13-48 are intentionally absent for now. They'll land in
+ * follow-up slices as we encounter fixtures that reference them.
+ */
+export const CHART_STYLES: Readonly<Record<number, ChartStyle>> = {
+  1: STYLE_1,
+  2: STYLE_2,
+  3: STYLE_3,
+  4: STYLE_4,
+  5: STYLE_5,
+  6: STYLE_6,
+  7: STYLE_7,
+  8: STYLE_8,
+  9: STYLE_9,
+  10: STYLE_10,
+  11: STYLE_11,
+  12: STYLE_12,
+  13: STYLE_13,
+  14: STYLE_14,
+  15: STYLE_15,
+  16: STYLE_16,
+  17: STYLE_17,
+  18: STYLE_18,
+  19: STYLE_19,
+  20: STYLE_20,
+  21: STYLE_21,
+  22: STYLE_22,
+  23: STYLE_23,
+  24: STYLE_24,
+  25: STYLE_25,
+  26: STYLE_26,
+  27: STYLE_27,
+  28: STYLE_28,
+  29: STYLE_29,
+  30: STYLE_30,
+  31: STYLE_31,
+  32: STYLE_32,
+  33: STYLE_33,
+  34: STYLE_34,
+  35: STYLE_35,
+  36: STYLE_36,
+  37: STYLE_37,
+  38: STYLE_38,
+  39: STYLE_39,
+  40: STYLE_40,
+  41: STYLE_41,
+  42: STYLE_42,
+  43: STYLE_43,
+  44: STYLE_44,
+  45: STYLE_45,
+  46: STYLE_46,
+  47: STYLE_47,
+  48: STYLE_48,
+};
+
+/**
+ * Look up a chart style by id. Falls back to the Office default (style 2)
+ * when the id is undefined or not in the table.
+ */
+export function getChartStyle(id: number | undefined): ChartStyle {
+  if (id === undefined) return CHART_STYLES[DEFAULT_CHART_STYLE_ID]!;
+  return CHART_STYLES[id] ?? CHART_STYLES[DEFAULT_CHART_STYLE_ID]!;
+}
+
+/**
+ * Resolve a raw chart-style id as it appears in OOXML to the canonical
+ * 1-48 range.
+ *
+ * Word 2013+ emits the newer scheme `c14:style val="10N"` (where 10N =
+ * 100 + legacy id) inside an `mc:AlternateContent/Choice` block, with
+ * the legacy `c:style val="N"` in the `mc:Fallback`. When a chart has
+ * only the c14 choice value and no sidecar `style1.xml`, we map
+ * 101-148 back to the legacy 1-48 range.
+ *
+ * Any value outside 1-48 or 101-148 falls back to the Office default.
+ */
+export function resolveChartStyleId(raw: number | undefined): number {
+  if (raw === undefined) return DEFAULT_CHART_STYLE_ID;
+  if (Number.isInteger(raw) && raw >= 1 && raw <= 48) return raw;
+  if (Number.isInteger(raw) && raw >= 101 && raw <= 148) return raw - 100;
+  return DEFAULT_CHART_STYLE_ID;
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Default series color palette.
+ *
+ * Given a `SeriesColorMode` (from the resolved chart style) and a series
+ * index, produce a `ColorRef` describing the color Word would use for
+ * that series when no explicit `c:ser/spPr` fill is declared.
+ *
+ * This layer is purely symbolic — it returns `ColorRef` values (scheme
+ * references with optional OOXML modifiers), not concrete hex. Downstream
+ * renderer stages compose `paletteColorRef(...)` with `resolveColor(ref,
+ * theme)` to produce a final sRGB string.
+ *
+ * Two modes:
+ *
+ * - **accent1To6** — round-robin across accent1..accent6, wrapping at 6.
+ *   Matches Word's default palette for styles 1-4, 11-22, 41-48.
+ *
+ * - **monochromaticAccentN** — single accent hue with per-series tint/
+ *   shade variation. Series 0 is the accent at full strength; subsequent
+ *   series lighten via (lumMod, lumOff) then darken via shade, producing
+ *   a 6-step tint/shade ramp per accent. Matches Word's monochromatic
+ *   palette for styles 5-10, 29-40.
+ */
+
+import type { SeriesColorMode } from "./chart-style-table.ts";
+import type { ColorMod, ColorRef } from "./types.ts";
+
+/**
+ * Luminance modifier ladder used for monochromatic palettes. Index 0 is
+ * the full-strength accent; subsequent entries are progressively lighter
+ * tints and then darker shades. Values are in OOXML's parts-per-100,000
+ * convention. The ladder matches Word's observed output for monochromatic
+ * styles 5-10 on real-world charts.
+ */
+const MONOCHROMATIC_LADDER: Array<ColorMod[] | undefined> = [
+  undefined, // series 0: accent at full strength
+  [
+    { kind: "lumMod", value: 60000 },
+    { kind: "lumOff", value: 40000 },
+  ], // series 1: 40% tint
+  [
+    { kind: "lumMod", value: 80000 },
+    { kind: "lumOff", value: 20000 },
+  ], // series 2: 20% tint
+  [{ kind: "shade", value: 75000 }], // series 3: 25% shade
+  [{ kind: "shade", value: 50000 }], // series 4: 50% shade
+  [
+    { kind: "lumMod", value: 40000 },
+    { kind: "lumOff", value: 60000 },
+  ], // series 5: 60% tint (very light)
+];
+
+/**
+ * Return the ColorRef for a given palette mode and series index. Pure
+ * function — no theme lookup. Callers compose with `resolveColor`.
+ */
+export function paletteColorRef(
+  mode: SeriesColorMode,
+  seriesIdx: number,
+): ColorRef {
+  const idx = Math.max(0, Math.floor(seriesIdx));
+  if (mode === "accent1To6") {
+    const slot = `accent${(idx % 6) + 1}`;
+    return { kind: "scheme", value: slot };
+  }
+  // monochromaticAccentN
+  const accentSlot = monochromaticAccentSlot(mode);
+  const mods = MONOCHROMATIC_LADDER[idx % MONOCHROMATIC_LADDER.length];
+  const ref: ColorRef = { kind: "scheme", value: accentSlot };
+  if (mods && mods.length > 0) ref.mods = mods;
+  return ref;
+}
+
+/**
+ * Factory variant — returns a closure for callers that want to bind a
+ * mode once and call `palette(seriesIdx)` repeatedly in a render loop.
+ */
+export function makePalette(
+  mode: SeriesColorMode,
+): (seriesIdx: number) => ColorRef {
+  return (seriesIdx: number) => paletteColorRef(mode, seriesIdx);
+}
+
+function monochromaticAccentSlot(mode: SeriesColorMode): string {
+  switch (mode) {
+    case "monochromaticAccent1":
+      return "accent1";
+    case "monochromaticAccent2":
+      return "accent2";
+    case "monochromaticAccent3":
+      return "accent3";
+    case "monochromaticAccent4":
+      return "accent4";
+    case "monochromaticAccent5":
+      return "accent5";
+    case "monochromaticAccent6":
+      return "accent6";
+    default:
+      return "accent1";
+  }
+}