@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/ui-tailwind/chart/layout/legend-layout.ts

@@ -0,0 +1,231 @@
+/**
+ * Legend layout — entry placement with multi-row wrapping (Stage 3C).
+ *
+ * The layout is pure geometry: given a rectangle the plot-area reserved
+ * for the legend, a list of entries (label + swatch color), and the
+ * declared position (`b`/`t`/`l`/`r`/`tr`), compute the position of each
+ * swatch + label and the bounding box actually consumed.
+ *
+ * Rules (matching Word's observed behavior at 100% zoom):
+ *
+ *   - Horizontal legends (position `b` / `t`) flow entries left-to-right
+ *     and wrap to a new row when the next entry would overflow the
+ *     available width. Entries within a row are gap-separated.
+ *
+ *   - Vertical legends (position `l` / `r` / `tr`) stack entries top-to-
+ *     bottom, one per row. Excess entries are not clipped — the bbox
+ *     grows downward and the caller is responsible for deciding how to
+ *     handle overflow.
+ *
+ *   - Every entry gets a swatch of a fixed pixel width, followed by a
+ *     gap, followed by the label. The label width is computed from the
+ *     real `measureText` helper (Slice 3B).
+ *
+ * The returned `entries` array preserves input order so renderers can
+ * walk entries alongside their swatch color without a second lookup.
+ */
+
+import type { Rect } from "./plot-area.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import { measureText } from "../render/font-metrics.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type LegendPosition = "b" | "t" | "l" | "r" | "tr";
+
+export interface LegendEntryInput {
+  label: string;
+  /** Resolved sRGB color for the swatch (e.g. "#4472C4"). */
+  color: string;
+}
+
+export interface LegendEntryRect {
+  label: string;
+  color: string;
+  swatchRect: Rect;
+  labelRect: Rect;
+}
+
+export interface LegendLayout {
+  /** Bounding box actually consumed inside the input `rect`. */
+  bbox: Rect;
+  /** Per-entry placement, in input order. */
+  entries: LegendEntryRect[];
+}
+
+export interface LegendLayoutOptions {
+  /** Font size in points for the legend label. Word default: 10pt. */
+  labelFontSizePt?: number;
+  /** Swatch width in pixels. Word default: ~10px for chart legends. */
+  swatchWidthPx?: number;
+  /** Swatch height in pixels. Defaults to `swatchWidthPx`. */
+  swatchHeightPx?: number;
+  /** Gap between swatch and label in pixels. Word default: 4px. */
+  swatchToLabelGapPx?: number;
+  /** Horizontal gap between entries in a row. Word default: 12px. */
+  entryGapPx?: number;
+  /** Vertical gap between rows. Default 2px. */
+  rowGapPx?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_LABEL_FONT_PT = 10;
+const DEFAULT_SWATCH_WIDTH = 10;
+const DEFAULT_SWATCH_TO_LABEL_GAP = 4;
+const DEFAULT_ENTRY_GAP = 12;
+const DEFAULT_ROW_GAP = 2;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the layout of legend entries inside `rect`, honoring
+ * `position`. Returns the consumed `bbox` (so callers can re-tighten
+ * the plot-area rectangle) and per-entry swatch + label sub-rects.
+ */
+export function layoutLegend(
+  entries: ReadonlyArray<LegendEntryInput>,
+  rect: Rect,
+  position: LegendPosition,
+  theme: ResolvedTheme | undefined,
+  options: LegendLayoutOptions = {},
+): LegendLayout {
+  if (entries.length === 0) {
+    return {
+      bbox: { x: rect.x, y: rect.y, w: 0, h: 0 },
+      entries: [],
+    };
+  }
+
+  const labelFontPt = options.labelFontSizePt ?? DEFAULT_LABEL_FONT_PT;
+  const swatchW = options.swatchWidthPx ?? DEFAULT_SWATCH_WIDTH;
+  const swatchH = options.swatchHeightPx ?? swatchW;
+  const swatchGap = options.swatchToLabelGapPx ?? DEFAULT_SWATCH_TO_LABEL_GAP;
+  const entryGap = options.entryGapPx ?? DEFAULT_ENTRY_GAP;
+  const rowGap = options.rowGapPx ?? DEFAULT_ROW_GAP;
+  const txPr = { fontSizePt: labelFontPt };
+
+  // Pre-measure every label so wrap decisions can be made without
+  // re-measuring (the LRU cache in font-metrics makes this O(unique)).
+  const measured = entries.map((e) => {
+    const m = measureText(e.label, txPr, theme);
+    return {
+      entry: e,
+      labelWidth: m.width,
+      lineHeight: m.lineHeight,
+    };
+  });
+  const rowHeight = Math.max(swatchH, measured[0]!.lineHeight);
+  const entryWidth = (m: typeof measured[0]): number =>
+    swatchW + swatchGap + m.labelWidth;
+
+  // Vertical legends (l / r / tr) — one entry per row, no wrapping.
+  if (position === "l" || position === "r" || position === "tr") {
+    const maxWidth = Math.max(...measured.map(entryWidth));
+    const outEntries: LegendEntryRect[] = [];
+    let cursorY = rect.y;
+    for (const m of measured) {
+      const entryRect = placeVertical(m, rect.x, cursorY, swatchW, swatchH, swatchGap, rowHeight);
+      outEntries.push(entryRect);
+      cursorY += rowHeight + rowGap;
+    }
+    const consumedH = measured.length * rowHeight + (measured.length - 1) * rowGap;
+    return {
+      bbox: { x: rect.x, y: rect.y, w: maxWidth, h: consumedH },
+      entries: outEntries,
+    };
+  }
+
+  // Horizontal legends (b / t) — row-flow with wrapping.
+  const outEntries: LegendEntryRect[] = [];
+  let cursorX = rect.x;
+  let cursorY = rect.y;
+  let rowStart = 0; // index of first entry in current row
+  let maxConsumedW = 0;
+
+  for (let i = 0; i < measured.length; i++) {
+    const m = measured[i]!;
+    const w = entryWidth(m);
+    const isRowStart = i === rowStart;
+    const nextX = isRowStart ? cursorX + w : cursorX + entryGap + w;
+    const overflows = !isRowStart && nextX > rect.x + rect.w;
+    if (overflows) {
+      // Wrap: center-align current row inside rect.w, move cursor.
+      const consumed = cursorX - rect.x;
+      if (consumed > maxConsumedW) maxConsumedW = consumed;
+      cursorX = rect.x;
+      cursorY += rowHeight + rowGap;
+      rowStart = i;
+    }
+    const xStart = cursorX + (i === rowStart ? 0 : entryGap);
+    outEntries.push(placeHorizontal(m, xStart, cursorY, swatchW, swatchH, swatchGap, rowHeight));
+    cursorX = xStart + w;
+  }
+  const finalRowConsumed = cursorX - rect.x;
+  if (finalRowConsumed > maxConsumedW) maxConsumedW = finalRowConsumed;
+  const totalHeight = cursorY + rowHeight - rect.y;
+
+  return {
+    bbox: { x: rect.x, y: rect.y, w: maxConsumedW, h: totalHeight },
+    entries: outEntries,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Placement helpers
+// ---------------------------------------------------------------------------
+
+function placeHorizontal(
+  m: { entry: LegendEntryInput; labelWidth: number; lineHeight: number },
+  x: number,
+  y: number,
+  swatchW: number,
+  swatchH: number,
+  swatchGap: number,
+  rowH: number,
+): LegendEntryRect {
+  // Vertically center swatch + label inside the row.
+  const swatchY = y + (rowH - swatchH) / 2;
+  const labelY = y + (rowH - m.lineHeight) / 2;
+  return {
+    label: m.entry.label,
+    color: m.entry.color,
+    swatchRect: { x, y: swatchY, w: swatchW, h: swatchH },
+    labelRect: {
+      x: x + swatchW + swatchGap,
+      y: labelY,
+      w: m.labelWidth,
+      h: m.lineHeight,
+    },
+  };
+}
+
+function placeVertical(
+  m: { entry: LegendEntryInput; labelWidth: number; lineHeight: number },
+  x: number,
+  y: number,
+  swatchW: number,
+  swatchH: number,
+  swatchGap: number,
+  rowH: number,
+): LegendEntryRect {
+  const swatchY = y + (rowH - swatchH) / 2;
+  const labelY = y + (rowH - m.lineHeight) / 2;
+  return {
+    label: m.entry.label,
+    color: m.entry.color,
+    swatchRect: { x, y: swatchY, w: swatchW, h: swatchH },
+    labelRect: {
+      x: x + swatchW + swatchGap,
+      y: labelY,
+      w: m.labelWidth,
+      h: m.lineHeight,
+    },
+  };
+}

package/src/ui-tailwind/chart/layout/plot-area.ts

@@ -1,6 +1,6 @@
 /**
  * Plot-area layout: partition the canvas into title / legend / axis /
- * plot rectangles (Stage 3A, pure math).
+ * plot rectangles (Stage 3A + 3B update).
  *
  * Call shape:
  *
@@ -13,21 +13,23 @@
  *   4. Reserve X-axis band on the bottom.
  *   5. Remaining rectangle is the plot area.
  *
- * **Text measurement is a fixed-stub at Slice 3A.** `measureTextWidth`
- * and `measureTextHeight` use a deterministic avg-glyph / line-height
- * approximation so the layout math is unit-testable without a browser.
- * Slice 3B swaps in the real `measureText(text, txPr, theme)` helper
- * that calls `ctx.measureText` (browser) or an empirical LRU (SSR) —
- * the stub keeps the public API stable so Slice 3B is a pure
- * implementation swap.
+ * Slice 3B: text measurement now uses the real `measureText` helper
+ * (`src/ui-tailwind/chart/render/font-metrics.ts`) which calls
+ * `ctx.measureText` in a browser and falls back to an empirical glyph-width
+ * table in SSR / Node test environments. The public `layoutPlotArea`
+ * signature is unchanged.
  */
 
 import type { ChartModel } from "../../../io/ooxml/chart/types.ts";
 import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import { measureText } from "../render/font-metrics.ts";
+import { formatNumber } from "../render/number-format.ts";
 import {
   generateCategoryTicks,
+  generateDateTicks,
   generateValueTicks,
   type TickResult,
+  type TimeUnit,
 } from "./axis-layout.ts";
 
 // ---------------------------------------------------------------------------
@@ -69,7 +71,6 @@ export function layoutPlotArea(
   model: ChartModel,
   theme: ResolvedTheme | undefined,
 ): PlotAreaLayout {
-  void theme; // consumed by Slice 3B's real font-metrics wrapper.
 
   let top = 0;
   let bottom = canvas.h;
@@ -82,7 +83,7 @@ export function layoutPlotArea(
 
   // 1. Title band (top).
   if (model.kind !== "unsupported" && model.title && !model.title.overlay) {
-    const titleHeight = measureTitleHeight(model.title.text ?? "");
+    const titleHeight = measureTitleHeight(model.title.text ?? "", theme);
     out.titleRect = { x: 0, y: 0, w: canvas.w, h: titleHeight };
     top += titleHeight + BAND_GAP_PX;
   }
@@ -90,7 +91,8 @@ export function layoutPlotArea(
   // 2. Legend band — on the side indicated by `legend.position`.
   if (model.kind !== "unsupported" && model.legend && !model.legend.overlay) {
     const entryCount = countLegendEntries(model);
-    const { w: legendW, h: legendH } = measureLegendBox(entryCount);
+    const legendLabels = collectLegendLabels(model);
+    const { w: legendW, h: legendH } = measureLegendBox(entryCount, legendLabels, theme);
     switch (model.legend.position) {
       case "t":
         out.legendRect = { x: 0, y: top, w: canvas.w, h: legendH };
@@ -128,18 +130,19 @@ export function layoutPlotArea(
   const axes = pickAxes(model);
   if (axes) {
     // Y-axis on the left: width = max(tick label width) + axis-title
-    // rotated height.
-    const yTickLabels = axisTickLabels(axes.y);
+    // rotated height. Numeric tick values are passed through
+    // `formatNumber(value, formatCode)` so layout reserves real label width.
+    const yTickLabels = axisTickLabels(axes.y, axes.yFormatCode);
     const yWidth =
-      maxLabelWidth(yTickLabels) + (axes.yTitle ? AXIS_TITLE_BAND_PX : 0);
+      maxLabelWidth(yTickLabels, theme) + (axes.yTitle ? AXIS_TITLE_BAND_PX : 0);
     out.yAxisRect = { x: left, y: top, w: yWidth, h: bottom - top };
     left += yWidth + BAND_GAP_PX;
 
     // Secondary Y-axis on the right.
     if (axes.secondaryY) {
-      const y2TickLabels = axisTickLabels(axes.secondaryY);
+      const y2TickLabels = axisTickLabels(axes.secondaryY, axes.secondaryYFormatCode);
       const y2Width =
-        maxLabelWidth(y2TickLabels) + (axes.secondaryYTitle ? AXIS_TITLE_BAND_PX : 0);
+        maxLabelWidth(y2TickLabels, theme) + (axes.secondaryYTitle ? AXIS_TITLE_BAND_PX : 0);
       out.secondaryYAxisRect = {
         x: right - y2Width,
         y: top,
@@ -150,7 +153,16 @@ export function layoutPlotArea(
     }
 
     // X-axis on the bottom: height = label height + axis-title band.
-    const xLabelHeight = X_AXIS_LABEL_HEIGHT_PX;
+    // For category axes, sample the widest category label so tall rotated
+    // labels reserve enough vertical space; for value/date axes use a
+    // numeric sample run through formatNumber.
+    const xTickLabels = axes.x
+      ? axisTickLabels(axes.x, axes.xFormatCode)
+      : axes.categoryLabels
+        ? Array.from(axes.categoryLabels)
+        : yTickLabels;
+    const xSampleLabel = xTickLabels.length > 0 ? xTickLabels[0]! : "0";
+    const xLabelHeight = measureText(xSampleLabel, AXIS_TXP, theme).lineHeight;
     const xHeight = xLabelHeight + (axes.xTitle ? AXIS_TITLE_BAND_PX : 0);
     out.xAxisRect = {
       x: left,
@@ -171,57 +183,57 @@ export function layoutPlotArea(
 }
 
 // ---------------------------------------------------------------------------
-// Text measurement — fixed stub (Slice 3B replaces with real metrics)
+// Text measurement — real metrics via font-metrics.ts (Slice 3B)
 // ---------------------------------------------------------------------------
 
-/**
- * Approximate glyph width in pixels at font size 1. The real value
- * depends on font + character; Calibri averages ~0.44 em for narrow
- * body text, but chart labels tend to be digits which are monospace-
- * like. 0.55 em is a conservative average that matches Word's default
- * axis-label font (Calibri 10pt ≈ 13.3px) well enough for layout
- * reservation. Replaced in Slice 3B.
- */
-const GLYPH_WIDTH_EM = 0.55;
-
-const LINE_HEIGHT_RATIO = 1.2;
 const BAND_GAP_PX = 4;
 const AXIS_TITLE_BAND_PX = 14;
-const X_AXIS_LABEL_HEIGHT_PX = 14;
-const DEFAULT_AXIS_FONT_PX = 10;
-const DEFAULT_TITLE_FONT_PX = 14;
-const DEFAULT_LEGEND_FONT_PX = 10;
 const LEGEND_SWATCH_WIDTH_PX = 16;
 const LEGEND_SWATCH_GAP_PX = 6;
 const LEGEND_ENTRY_GAP_PX = 12;
 const LEGEND_MIN_WIDTH_PX = 80;
 
-function measureTitleHeight(text: string): number {
+const TITLE_TXP = { fontSizePt: 14 };
+const AXIS_TXP = { fontSizePt: 10 };
+const LEGEND_TXP = { fontSizePt: 10 };
+
+function measureTitleHeight(text: string, theme: ResolvedTheme | undefined): number {
   if (!text) return 0;
-  return DEFAULT_TITLE_FONT_PX * LINE_HEIGHT_RATIO;
+  return measureText(text, TITLE_TXP, theme).lineHeight;
 }
 
-function measureLegendBox(entryCount: number): { w: number; h: number } {
+function measureLegendBox(
+  entryCount: number,
+  labels: ReadonlyArray<string>,
+  theme: ResolvedTheme | undefined,
+): { w: number; h: number } {
   if (entryCount <= 0) return { w: 0, h: 0 };
-  const avgLabelChars = 8;
-  const entryWidth =
-    LEGEND_SWATCH_WIDTH_PX +
-    LEGEND_SWATCH_GAP_PX +
-    GLYPH_WIDTH_EM * DEFAULT_LEGEND_FONT_PX * avgLabelChars;
-  // Reserve a one-column stack: width = entryWidth, height = N lines.
+  // Measure the widest label; fall back to an 8-char estimate when no labels.
+  const sampleLabels = labels.length > 0 ? labels : ["MMMMMMMM"];
+  let maxW = 0;
+  for (const label of sampleLabels) {
+    const w = measureText(label, LEGEND_TXP, theme).width;
+    if (w > maxW) maxW = w;
+  }
+  const entryWidth = LEGEND_SWATCH_WIDTH_PX + LEGEND_SWATCH_GAP_PX + maxW;
+  const lineH = measureText(sampleLabels[0]!, LEGEND_TXP, theme).lineHeight;
   return {
     w: Math.max(LEGEND_MIN_WIDTH_PX, entryWidth + LEGEND_ENTRY_GAP_PX),
-    h: entryCount * DEFAULT_LEGEND_FONT_PX * LINE_HEIGHT_RATIO,
+    h: entryCount * lineH,
   };
 }
 
-function maxLabelWidth(labels: ReadonlyArray<string>): number {
+function maxLabelWidth(
+  labels: ReadonlyArray<string>,
+  theme: ResolvedTheme | undefined,
+): number {
   if (labels.length === 0) return 0;
-  let maxChars = 0;
+  let maxW = 0;
   for (const label of labels) {
-    if (label.length > maxChars) maxChars = label.length;
+    const w = measureText(label, AXIS_TXP, theme).width;
+    if (w > maxW) maxW = w;
   }
-  return maxChars * GLYPH_WIDTH_EM * DEFAULT_AXIS_FONT_PX;
+  return maxW;
 }
 
 // ---------------------------------------------------------------------------
@@ -230,11 +242,20 @@ function maxLabelWidth(labels: ReadonlyArray<string>): number {
 
 interface AxisBundle {
   y: TickResult;
+  yFormatCode?: string;
   yTitle: boolean;
   x?: TickResult;
+  xFormatCode?: string;
   xTitle: boolean;
   secondaryY?: TickResult;
+  secondaryYFormatCode?: string;
   secondaryYTitle: boolean;
+  /**
+   * Category axis labels (for bar/line/area/combo) — pre-resolved
+   * category-axis label strings. When present, the x-axis tick band
+   * measurement uses these strings rather than numeric tick indices.
+   */
+  categoryLabels?: ReadonlyArray<string>;
 }
 
 /**
@@ -254,23 +275,33 @@ function pickAxes(model: ChartModel): AxisBundle | null {
       const bundle: AxisBundle = {
         y: yTicks,
         yTitle: !!model.valueAxis.title,
-        xTitle: model.categoryAxis.kind === "category"
-          ? !!model.categoryAxis.title
-          : !!model.categoryAxis.title,
+        x: axisTicks(model.categoryAxis),
+        xTitle: !!model.categoryAxis.title,
         secondaryYTitle: !!model.secondaryValueAxis?.title,
       };
+      if (model.valueAxis.numberFormat) bundle.yFormatCode = model.valueAxis.numberFormat;
+      if (model.categoryAxis.numberFormat) bundle.xFormatCode = model.categoryAxis.numberFormat;
       if (y2Ticks) bundle.secondaryY = y2Ticks;
+      if (model.secondaryValueAxis?.numberFormat) {
+        bundle.secondaryYFormatCode = model.secondaryValueAxis.numberFormat;
+      }
+      if (model.categoryAxis.kind === "category") {
+        bundle.categoryLabels = model.categoryAxis.categoryLabels;
+      }
       return bundle;
     }
     case "scatter":
     case "bubble": {
-      return {
+      const bundle: AxisBundle = {
         y: axisTicks(model.yAxis),
         yTitle: !!model.yAxis.title,
         x: axisTicks(model.xAxis),
         xTitle: !!model.xAxis.title,
         secondaryYTitle: false,
       };
+      if (model.yAxis.numberFormat) bundle.yFormatCode = model.yAxis.numberFormat;
+      if (model.xAxis.numberFormat) bundle.xFormatCode = model.xAxis.numberFormat;
+      return bundle;
     }
     case "combo": {
       // Use the first group's axes as representative.
@@ -289,6 +320,10 @@ function axisTicks(axis: {
   min?: number;
   max?: number;
   majorUnit?: number;
+  majorTimeUnit?: TimeUnit;
+  minorUnit?: number;
+  minorTimeUnit?: TimeUnit;
+  baseTimeUnit?: TimeUnit;
   categoryLabels?: ReadonlyArray<string>;
 }): TickResult {
   if (axis.kind === "category") {
@@ -300,6 +335,20 @@ function axisTicks(axis: {
       minor: [],
     };
   }
+  // C8: DateAxis (kind === "date") must route to generateDateTicks so Excel
+  // serial dates produce properly-stepped tick positions rather than treating
+  // serials as raw numbers and calling generateValueTicks on them.
+  if (axis.kind === "date") {
+    return generateDateTicks({
+      min: axis.min ?? 0,
+      max: axis.max ?? 1,
+      ...(axis.majorUnit !== undefined ? { majorUnit: axis.majorUnit } : {}),
+      ...(axis.majorTimeUnit !== undefined ? { majorTimeUnit: axis.majorTimeUnit } : {}),
+      ...(axis.minorUnit !== undefined ? { minorUnit: axis.minorUnit } : {}),
+      ...(axis.minorTimeUnit !== undefined ? { minorTimeUnit: axis.minorTimeUnit } : {}),
+      ...(axis.baseTimeUnit !== undefined ? { baseTimeUnit: axis.baseTimeUnit } : {}),
+    });
+  }
   const min = axis.min ?? 0;
   const max = axis.max ?? 1;
   return generateValueTicks({
@@ -310,14 +359,25 @@ function axisTicks(axis: {
 }
 
 /**
- * Produce string labels for an axis's major ticks. Category axis uses
- * the source labels directly; value axis stringifies numeric positions.
- * Real number-format handling lands in Slice 4G via `number-format.ts`;
- * the fixed-width stub here is sufficient for plot-area reservation
- * (within ~1 glyph-width of the real rendered size).
+ * Produce string labels for an axis's major ticks.
+ *
+ * - Value / date axes: each tick numeric value is passed through
+ *   `formatNumber(value, formatCode)` so layout reserves width for the
+ *   real rendered string (e.g. `"$1,234"`, `"45%"`, `"Jan-24"`) not the
+ *   raw `String(1234)` approximation.
+ * - Category axes: when categoryLabels are provided, return them verbatim
+ *   (tick indices 0..N-1 map 1:1 to labels). This avoids reserving space
+ *   for "0", "1", "2" when the real rendered label is "Q1", "Q2", "Q3".
  */
-function axisTickLabels(ticks: TickResult): string[] {
-  return ticks.major.map((t) => String(t));
+function axisTickLabels(
+  ticks: TickResult,
+  formatCode: string | undefined,
+  categoryLabels?: ReadonlyArray<string>,
+): string[] {
+  if (categoryLabels && categoryLabels.length > 0) {
+    return ticks.major.map((i) => categoryLabels[i] ?? "");
+  }
+  return ticks.major.map((t) => formatNumber(t, formatCode));
 }
 
 function countLegendEntries(model: ChartModel): number {
@@ -329,7 +389,9 @@ function countLegendEntries(model: ChartModel): number {
     case "bubble":
       return model.series.length;
     case "pie": {
-      // Pie legends show one entry per slice.
+      // Pie legends show one entry per slice. Prefer categoryLabels when
+      // resolved; fall back to series value count for degenerate inputs.
+      if (model.categoryLabels.length > 0) return model.categoryLabels.length;
       const first = model.series[0];
       return first ? first.values.length : 0;
     }
@@ -342,3 +404,34 @@ function countLegendEntries(model: ChartModel): number {
       return 0;
   }
 }
+
+function collectLegendLabels(model: ChartModel): ReadonlyArray<string> {
+  switch (model.kind) {
+    case "bar":
+    case "line":
+    case "area":
+    case "scatter":
+    case "bubble":
+      return model.series.map((s) => s.name ?? `Series ${s.idx + 1}`);
+    case "pie": {
+      // PieChartModel exposes categoryLabels at the model level (resolved
+      // from the first series' c:cat cache during parsing). Each slice
+      // in the legend corresponds 1:1 to a category label. Fall back to
+      // synthetic "Slice N" only when the parser saw no category cache
+      // (degenerate data-only DOCX).
+      if (model.categoryLabels.length > 0) return model.categoryLabels;
+      const first = model.series[0];
+      if (!first) return [];
+      return first.values.map((_, i) => `Slice ${i + 1}`);
+    }
+    case "combo": {
+      const labels: string[] = [];
+      for (const g of model.groups) {
+        for (const s of g.series) labels.push(s.name ?? `Series ${s.idx + 1}`);
+      }
+      return labels;
+    }
+    case "unsupported":
+      return [];
+  }
+}