@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/ui-tailwind/chart/render/data-labels.tsx

@@ -0,0 +1,513 @@
+/**
+ * Data-label renderer (Stage 4 Slice 4G).
+ *
+ * Produces `<text>` elements for each data point's label according to
+ * the series-level `DataLabelsSpec`. Supports:
+ *   - `showVal`: raw numeric value (passed through `formatNumber(value,
+ *     spec.numberFormat?)` — the Stage 3A number-format engine).
+ *   - `showPercent`: percent of category total (pie) or series total.
+ *   - `showCatName`: category name.
+ *   - `showSerName`: series name.
+ *   - `separator`: default `", "`.
+ *
+ * Position rules:
+ *   - Bar/column clustered/stacked: `outEnd` (outside the bar end),
+ *     `inEnd` (inside the bar end), `inBase` (inside the bar base),
+ *     `ctr` (center), or `bestFit` (heuristic: outEnd if value fits,
+ *     else inEnd). Default bar: `outEnd`.
+ *   - Line/area: `t` (above), `b` (below), `l`, `r`, `ctr`. Default: `t`.
+ *   - Pie: `ctr` (inside slice), `outEnd` (outside, with leader line
+ *     NOT rendered here — leader-line geometry is deferred to Stage 7).
+ *     Default pie: `ctr`.
+ *   - Scatter/bubble: same as line (`t` default).
+ *
+ * This module is called by `ChartSurface` after the per-family
+ * renderer has committed its SVG, filling the `<g data-role="data-
+ * labels"/>` placeholder each renderer emitted.
+ */
+
+import React from "react";
+import { formatNumber } from "./number-format.ts";
+import type {
+  AreaChartModel,
+  BarChartModel,
+  BubbleChartModel,
+  ChartModel,
+  DataLabelsSpec,
+  LineChartModel,
+  PieChartModel,
+  ScatterChartModel,
+  Series,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface DataLabelsProps {
+  model: ChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+}
+
+/**
+ * Render data labels for every series in the model whose spec opts in.
+ * Callers are responsible for placing the returned elements inside the
+ * appropriate `<g data-role="data-labels"/>` container in their SVG.
+ */
+export function DataLabels({
+  model,
+  layout,
+  theme,
+}: DataLabelsProps): React.ReactElement | null {
+  switch (model.kind) {
+    case "bar":
+      return <>{renderBarLabels(model, layout, theme)}</>;
+    case "line":
+      return <>{renderLineLabels(model, layout, theme)}</>;
+    case "pie":
+      return <>{renderPieLabels(model, layout, theme)}</>;
+    case "area":
+      return <>{renderAreaLabels(model, layout, theme)}</>;
+    case "scatter":
+      return <>{renderScatterLabels(model, layout, theme)}</>;
+    case "bubble":
+      return <>{renderBubbleLabels(model, layout, theme)}</>;
+    case "combo":
+      return (
+        <>
+          {model.groups.flatMap((g, i) => {
+            const groupProps = { model: g, layout, theme };
+            const inner = DataLabels(groupProps);
+            return inner ? [React.cloneElement(inner, { key: `combo-labels-${i}` })] : [];
+          })}
+        </>
+      );
+    case "unsupported":
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Label composition
+// ---------------------------------------------------------------------------
+
+interface LabelComposition {
+  parts: string[];
+}
+
+/**
+ * Compose a single data-label string from `spec` + value context.
+ *
+ * The order matches Word's observed behavior: series name → category
+ * name → value/percent → bubble size.
+ */
+function composeLabel(
+  spec: DataLabelsSpec | undefined,
+  ctx: {
+    value?: number;
+    percent?: number;
+    categoryName?: string;
+    seriesName?: string;
+    bubbleSize?: number;
+  },
+): string {
+  if (!spec) return "";
+  const sep = spec.separator ?? ", ";
+  const parts: string[] = [];
+  if (spec.showSerName && ctx.seriesName) parts.push(ctx.seriesName);
+  if (spec.showCatName && ctx.categoryName) parts.push(ctx.categoryName);
+  if (spec.showVal && ctx.value !== undefined) {
+    parts.push(formatNumber(ctx.value, spec.numberFormat));
+  }
+  if (spec.showPercent && ctx.percent !== undefined) {
+    // Honor numberFormat when it's a percent code; else append a "%".
+    if (spec.numberFormat && /%/.test(spec.numberFormat)) {
+      parts.push(formatNumber(ctx.percent / 100, spec.numberFormat));
+    } else {
+      parts.push(`${Math.round(ctx.percent * 10) / 10}%`);
+    }
+  }
+  if (spec.showBubbleSize && ctx.bubbleSize !== undefined) {
+    parts.push(formatNumber(ctx.bubbleSize, spec.numberFormat));
+  }
+  return parts.join(sep);
+}
+
+function hasLabel(spec: DataLabelsSpec | undefined): boolean {
+  if (!spec) return false;
+  return (
+    spec.showVal ||
+    spec.showCatName ||
+    spec.showSerName ||
+    spec.showPercent ||
+    spec.showBubbleSize ||
+    spec.showLegendKey
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Per-family renderers
+// ---------------------------------------------------------------------------
+
+function renderBarLabels(
+  model: BarChartModel,
+  layout: PlotAreaLayout,
+  _theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  const plot = layout.plotRect;
+  const horizontal = model.direction === "bar";
+  const categoryCount = Math.max(
+    1,
+    model.categoryAxis.kind === "category"
+      ? model.categoryAxis.categoryLabels.length
+      : model.series[0]?.values.length ?? 1,
+  );
+  const slotSize = (horizontal ? plot.h : plot.w) / categoryCount;
+  const valueAxisMin = model.valueAxis.min ?? 0;
+  const valueAxisMax = model.valueAxis.max ?? 100;
+  const span = Math.max(1e-9, valueAxisMax - valueAxisMin);
+  const valueToPlot = (v: number): number => {
+    const frac = (v - valueAxisMin) / span;
+    return horizontal ? plot.x + frac * plot.w : plot.y + plot.h - frac * plot.h;
+  };
+
+  const out: React.ReactElement[] = [];
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const spec = series.dataLabels;
+    if (!hasLabel(spec)) continue;
+    const pos = spec!.position ?? "outEnd";
+    for (let c = 0; c < categoryCount; c++) {
+      const v = series.values[c];
+      if (v === null || v === undefined || !Number.isFinite(v)) continue;
+      const category = model.categoryAxis.kind === "category"
+        ? model.categoryAxis.categoryLabels[c]
+        : undefined;
+      const label = composeLabel(spec, {
+        value: v,
+        categoryName: category,
+        seriesName: series.name,
+      });
+      if (!label) continue;
+      const slotStart = (horizontal ? plot.y : plot.x) + c * slotSize;
+      const slotCenter = slotStart + slotSize / 2;
+      const valuePos = valueToPlot(v);
+      const { x, y, anchor } = positionBarLabel(pos, horizontal, slotCenter, valuePos, v);
+      out.push(
+        <text
+          key={`lbl-${s}-${c}`}
+          x={x}
+          y={y}
+          textAnchor={anchor}
+          fontSize={9 * (96 / 72)}
+          fill="#595959"
+          data-role="data-label"
+          data-series-index={s}
+          data-category-index={c}
+        >
+          {label}
+        </text>,
+      );
+    }
+  }
+  return out;
+}
+
+function positionBarLabel(
+  pos: NonNullable<DataLabelsSpec["position"]>,
+  horizontal: boolean,
+  slotCenter: number,
+  valuePos: number,
+  value: number,
+): { x: number; y: number; anchor: "start" | "middle" | "end" } {
+  const offset = 6; // pt
+  if (horizontal) {
+    // Bars extend horizontally; label position lives on the x axis.
+    const outEndX = valuePos + (value >= 0 ? offset : -offset);
+    const inEndX = valuePos - (value >= 0 ? offset : -offset);
+    switch (pos) {
+      case "outEnd":
+      case "bestFit":
+        return { x: outEndX, y: slotCenter + 3, anchor: value >= 0 ? "start" : "end" };
+      case "inEnd":
+        return { x: inEndX, y: slotCenter + 3, anchor: value >= 0 ? "end" : "start" };
+      case "ctr":
+        return { x: (valuePos + outEndX) / 2, y: slotCenter + 3, anchor: "middle" };
+      case "inBase":
+      default:
+        return { x: outEndX, y: slotCenter + 3, anchor: value >= 0 ? "start" : "end" };
+    }
+  }
+  // Column (vertical bars).
+  const outEndY = valuePos + (value >= 0 ? -offset : offset);
+  const inEndY = valuePos + (value >= 0 ? offset : -offset);
+  switch (pos) {
+    case "outEnd":
+    case "bestFit":
+      return { x: slotCenter, y: outEndY, anchor: "middle" };
+    case "inEnd":
+      return { x: slotCenter, y: inEndY, anchor: "middle" };
+    case "ctr":
+      return { x: slotCenter, y: (valuePos + outEndY) / 2, anchor: "middle" };
+    case "inBase":
+    default:
+      return { x: slotCenter, y: outEndY, anchor: "middle" };
+  }
+}
+
+function renderLineLabels(
+  model: LineChartModel,
+  layout: PlotAreaLayout,
+  _theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  const plot = layout.plotRect;
+  const categoryCount = Math.max(
+    1,
+    model.categoryAxis.kind === "category"
+      ? model.categoryAxis.categoryLabels.length
+      : model.series[0]?.values.length ?? 1,
+  );
+  const slotWidth = plot.w / categoryCount;
+  const valueAxisMin = model.valueAxis.min ?? 0;
+  const valueAxisMax = model.valueAxis.max ?? 100;
+  const span = Math.max(1e-9, valueAxisMax - valueAxisMin);
+
+  const out: React.ReactElement[] = [];
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const spec = series.dataLabels;
+    if (!hasLabel(spec)) continue;
+    for (let c = 0; c < categoryCount; c++) {
+      const v = series.values[c];
+      if (v === null || v === undefined || !Number.isFinite(v)) continue;
+      const category = model.categoryAxis.kind === "category"
+        ? model.categoryAxis.categoryLabels[c]
+        : undefined;
+      const label = composeLabel(spec, {
+        value: v,
+        categoryName: category,
+        seriesName: series.name,
+      });
+      if (!label) continue;
+      const x = plot.x + (c + 0.5) * slotWidth;
+      const frac = (v - valueAxisMin) / span;
+      const yPoint = plot.y + plot.h - frac * plot.h;
+      const y = yPoint - 8; // above the point by default
+      out.push(
+        <text
+          key={`lbl-${s}-${c}`}
+          x={x}
+          y={y}
+          textAnchor="middle"
+          fontSize={9 * (96 / 72)}
+          fill="#595959"
+          data-role="data-label"
+          data-series-index={s}
+          data-category-index={c}
+        >
+          {label}
+        </text>,
+      );
+    }
+  }
+  return out;
+}
+
+function renderAreaLabels(
+  model: AreaChartModel,
+  layout: PlotAreaLayout,
+  theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  // Area labels use the same logic as line labels — anchor on top of
+  // each series' upper boundary. Casting the model to LineChartModel's
+  // shape is safe because Series → values lookup is identical.
+  return renderLineLabels(
+    {
+      ...model,
+      kind: "line" as const,
+      smooth: false,
+      marker: false,
+      series: model.series.map((s): LineChartModel["series"][number] => ({
+        ...s,
+      })),
+    },
+    layout,
+    theme,
+  );
+}
+
+function renderPieLabels(
+  model: PieChartModel,
+  layout: PlotAreaLayout,
+  _theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  const plot = layout.plotRect;
+  const cx = plot.x + plot.w / 2;
+  const cy = plot.y + plot.h / 2;
+  const rOuter = Math.max(0, Math.min(plot.w, plot.h) / 2);
+  const rInner = model.doughnut
+    ? (rOuter * Math.max(10, Math.min(90, model.holeSizePercent ?? 50))) / 100
+    : 0;
+  const labelRadius = (rInner + rOuter) / 2;
+
+  const series = model.series[0];
+  if (!series) return [];
+  // PieSeries has no per-series dataLabels field — pie data labels are
+  // declared at the chart level in OOXML (c:dLbls child of c:pieChart).
+  // Stage 1 parser doesn't yet surface the chart-level dLbls into
+  // PieChartModel, so we treat pie labels as opt-out for now. Renderers
+  // can still supply labels via a future chart-level spec.
+  const spec: DataLabelsSpec | undefined = undefined;
+  if (!hasLabel(spec)) return [];
+  const values = series.values;
+  const total = values.reduce<number>(
+    (sum, v) => (v === null || v === undefined || !Number.isFinite(v) || v <= 0 ? sum : sum + v),
+    0,
+  );
+  if (total === 0) return [];
+
+  const startDeg = model.firstSliceAngle ?? 0;
+  let cursor = startDeg;
+  const out: React.ReactElement[] = [];
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (v === null || v === undefined || !Number.isFinite(v) || v <= 0) continue;
+    const sweep = (v / total) * 360;
+    const midDeg = cursor + sweep / 2;
+    cursor += sweep;
+    const svgDeg = midDeg - 90;
+    const rad = (svgDeg * Math.PI) / 180;
+    const x = cx + labelRadius * Math.cos(rad);
+    const y = cy + labelRadius * Math.sin(rad);
+    const label = composeLabel(spec, {
+      value: v,
+      percent: (v / total) * 100,
+      categoryName: model.categoryLabels[i],
+      seriesName: series.name,
+    });
+    if (!label) continue;
+    out.push(
+      <text
+        key={`lbl-${i}`}
+        x={x}
+        y={y}
+        textAnchor="middle"
+        fontSize={9 * (96 / 72)}
+        fill="#595959"
+        data-role="data-label"
+        data-slice-index={i}
+      >
+        {label}
+      </text>,
+    );
+  }
+  return out;
+}
+
+function renderScatterLabels(
+  model: ScatterChartModel,
+  layout: PlotAreaLayout,
+  _theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  const plot = layout.plotRect;
+  const xMin = model.xAxis.min ?? 0;
+  const xMax = model.xAxis.max ?? 1;
+  const yMin = model.yAxis.min ?? 0;
+  const yMax = model.yAxis.max ?? 1;
+  const xSpan = Math.max(1e-9, xMax - xMin);
+  const ySpan = Math.max(1e-9, yMax - yMin);
+
+  const out: React.ReactElement[] = [];
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const spec: DataLabelsSpec | undefined = undefined;
+    if (!hasLabel(spec)) continue;
+    const n = Math.min(series.xValues.length, series.yValues.length);
+    for (let i = 0; i < n; i++) {
+      const x = series.xValues[i];
+      const y = series.yValues[i];
+      if (x === null || y === null || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+      const px = plot.x + ((x - xMin) / xSpan) * plot.w;
+      const py = plot.y + plot.h - ((y - yMin) / ySpan) * plot.h;
+      const label = composeLabel(spec, {
+        value: y,
+        seriesName: series.name,
+      });
+      if (!label) continue;
+      out.push(
+        <text
+          key={`lbl-${s}-${i}`}
+          x={px}
+          y={py - 8}
+          textAnchor="middle"
+          fontSize={9 * (96 / 72)}
+          fill="#595959"
+          data-role="data-label"
+          data-series-index={s}
+          data-point-index={i}
+        >
+          {label}
+        </text>,
+      );
+    }
+  }
+  return out;
+}
+
+function renderBubbleLabels(
+  model: BubbleChartModel,
+  layout: PlotAreaLayout,
+  _theme: ResolvedTheme | undefined,
+): React.ReactElement[] {
+  const plot = layout.plotRect;
+  const xMin = model.xAxis.min ?? 0;
+  const xMax = model.xAxis.max ?? 1;
+  const yMin = model.yAxis.min ?? 0;
+  const yMax = model.yAxis.max ?? 1;
+  const xSpan = Math.max(1e-9, xMax - xMin);
+  const ySpan = Math.max(1e-9, yMax - yMin);
+
+  const out: React.ReactElement[] = [];
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const spec: DataLabelsSpec | undefined = undefined;
+    if (!hasLabel(spec)) continue;
+    const n = Math.min(series.xValues.length, series.yValues.length, series.sizes.length);
+    for (let i = 0; i < n; i++) {
+      const x = series.xValues[i];
+      const y = series.yValues[i];
+      const size = series.sizes[i];
+      if (x === null || y === null || size === null) continue;
+      const px = plot.x + ((x - xMin) / xSpan) * plot.w;
+      const py = plot.y + plot.h - ((y - yMin) / ySpan) * plot.h;
+      const label = composeLabel(spec, {
+        value: y,
+        bubbleSize: size,
+        seriesName: series.name,
+      });
+      if (!label) continue;
+      out.push(
+        <text
+          key={`lbl-${s}-${i}`}
+          x={px}
+          y={py - 8}
+          textAnchor="middle"
+          fontSize={9 * (96 / 72)}
+          fill="#595959"
+          data-role="data-label"
+          data-series-index={s}
+          data-point-index={i}
+        >
+          {label}
+        </text>,
+      );
+    }
+  }
+  return out;
+}
+
+// Reference the unused parameter to avoid lint warnings.
+void ({} as Series);