@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Chart/chartModel.ts

@@ -0,0 +1,689 @@
+import { scaleLinear } from 'd3-scale';
+import { stack, stackOffsetDiverging, stackOffsetNone, type Series } from 'd3-shape';
+
+/** Chart form. `area` is always stacked. */
+export type ChartType = 'line' | 'bar' | 'stacked-bar' | 'area';
+
+/** One plotted series. `values[i]` belongs to `categories[i]`; `null` is a gap. */
+export interface ChartSeries {
+  /** Stable identity: legend toggles, `hiddenSeries` and `comparisonOf` refer to it. */
+  key: string;
+  /** Human name shown in the legend, tooltip and data table. */
+  label: string;
+  /** One value per category; `null` is a gap. */
+  values: (number | null)[];
+  /**
+   * Marks this series as a comparison (e.g. previous period) of another: the `key` of its parent
+   * series, or `'total'` for the stacked sum. Supported on `line`, `bar` and `area`.
+   */
+  comparisonOf?: string;
+}
+
+/**
+ * Marker tone.
+ * - `'neutral'` — default; a visible dashed line or grey band for events (launch, campaign).
+ * - `'subtle'` — a faint band or line for recurring context (weekends, off-hours) that must not compete with data.
+ */
+export type ChartMarkerTone = 'neutral' | 'subtle';
+
+interface ChartMarkerBase {
+  /** Stable identity (React key). */
+  key: string;
+  /** Short text drawn on the plot and listed in the tooltip, keyboard announcement and data table. Omit for decorative shading (weekends). */
+  label?: string;
+  /** Visual weight. Default `'neutral'`. */
+  tone?: ChartMarkerTone;
+}
+
+/**
+ * A static annotation pinned to categories: a vertical line at one category (`at`) or a shaded band over a
+ * category range (`from`…`to`, inclusive). Values are category labels from `categories`.
+ */
+export type ChartMarker =
+  | (ChartMarkerBase & {
+      /** Category the vertical line sits on (its centre). */
+      at: string;
+      from?: never;
+      to?: never;
+    })
+  | (ChartMarkerBase & {
+      /** First category of the band (inclusive). */
+      from: string;
+      /** Last category of the band (inclusive); may equal `from` for one bucket. */
+      to: string;
+      at?: never;
+    });
+
+export interface ResolvedMarker {
+  key: string;
+  label?: string;
+  tone: ChartMarkerTone;
+  kind: 'line' | 'band';
+  /** Category index range, inclusive; `from === to` for a line. */
+  from: number;
+  to: number;
+}
+
+/** Maps markers onto category indices; markers naming an unknown category are dropped. */
+export function resolveMarkers(
+  markers: readonly ChartMarker[],
+  categories: readonly string[],
+): { markers: ResolvedMarker[]; dropped: string[] } {
+  const resolved: ResolvedMarker[] = [];
+  const dropped: string[] = [];
+  for (const m of markers) {
+    const range = m.at === undefined ? [m.from, m.to] : [m.at, m.at];
+    const [a, b] = range.map((c) => categories.indexOf(c as string));
+    if (a < 0 || b < 0) {
+      dropped.push(m.key);
+      continue;
+    }
+    resolved.push({
+      key: m.key,
+      label: m.label || undefined,
+      tone: m.tone ?? 'neutral',
+      kind: m.at === undefined ? 'band' : 'line',
+      from: Math.min(a, b),
+      to: Math.max(a, b),
+    });
+  }
+  return { markers: resolved, dropped };
+}
+
+/** Labels of the markers covering category `i`, in marker order. */
+export function markerLabelsAt(markers: readonly ResolvedMarker[], i: number): string[] {
+  return markers.flatMap((m) => (m.label && m.from <= i && i <= m.to ? [m.label] : []));
+}
+
+export interface MarkerGeometry {
+  key: string;
+  kind: 'line' | 'band';
+  tone: ChartMarkerTone;
+  /** Line x, or band left edge. */
+  x: number;
+  /** Band width; 0 for a line. */
+  width: number;
+  /** Label to draw, or undefined when absent or it would collide/clip. */
+  label?: { text: string; x: number; anchor: 'start' | 'end' };
+}
+
+/** Marker geometry in svg coordinates. Labels that would overlap an earlier label or leave the plot are dropped. */
+export function layoutMarkers(
+  markers: readonly ResolvedMarker[],
+  layout: Pick<ChartLayout, 'plot' | 'categoryX' | 'step'>,
+): MarkerGeometry[] {
+  const { plot, categoryX, step } = layout;
+  const right = plot.x + plot.width;
+  const taken: [number, number][] = [];
+  return markers.map((m) => {
+    const x = m.kind === 'line' ? categoryX[m.from] : categoryX[m.from] - step / 2;
+    const width = m.kind === 'line' ? 0 : (m.to - m.from + 1) * step;
+    const g: MarkerGeometry = { key: m.key, kind: m.kind, tone: m.tone, x, width };
+    if (!m.label) return g;
+    const w = textWidth(m.label);
+    // Start just right of the line / inside the band's left edge; flip left of a line near the right edge.
+    let anchor: 'start' | 'end' = 'start';
+    let lx = x + MARKER_LABEL_INSET;
+    if (lx + w > right && m.kind === 'line') {
+      anchor = 'end';
+      lx = x - MARKER_LABEL_INSET;
+    }
+    const span: [number, number] = anchor === 'start' ? [lx, lx + w] : [lx - w, lx];
+    const fits = span[0] >= plot.x && span[1] <= right;
+    const free = taken.every(([a, b]) => span[1] + LABEL_GAP <= a || b + LABEL_GAP <= span[0]);
+    if (fits && free) {
+      taken.push(span);
+      g.label = { text: m.label, x: lx, anchor };
+    }
+    return g;
+  });
+}
+
+/** Distinct categorical colours; series past this reuse the palette with a dashed/outlined overflow style. */
+export const PALETTE_SIZE = 8;
+// ponytail: estimated glyph width at --font-size-sm (12px) instead of measuring text;
+// measure with canvas.measureText if labels clip or overlap in real fonts.
+export const CHAR_WIDTH = 7;
+export const LABEL_GAP = 8;
+/** Distance of the x-label baseline from the svg bottom edge. */
+export const X_LABEL_BASELINE = 4;
+/** Radius of the isolated-point dots. */
+export const DOT_RADIUS = 3;
+/** Radius of the keyboard/hover inspection marker on a line point. */
+export const MARKER_RADIUS = 4;
+/** Baseline of marker labels below the plot top. */
+export const MARKER_LABEL_BASELINE = 12;
+/** Below this root height the legend collapses to one row with a "+N" counter. */
+export const COMPACT_HEIGHT = 120;
+
+const MARK_GAP = 2;
+const MARKER_LABEL_INSET = 4;
+const BAR_RADIUS = 4;
+const BAND_RATIO = 0.65;
+const PAD_TOP = 8;
+const PAD_RIGHT = 8;
+const X_AXIS_HEIGHT = 20;
+const Y_TICK_SPACING = 40;
+const LEGEND_ITEM_EXTRA = 28; // swatch + gaps around one legend item
+const LEGEND_MORE_WIDTH = 4 * CHAR_WIDTH; // "+NN"
+
+export function isStacked(type: ChartType): boolean {
+  return type === 'stacked-bar' || type === 'area';
+}
+
+export interface ResolvedSeries {
+  key: string;
+  label: string;
+  values: (number | null)[];
+  /** Palette slot 1..8; 0 = neutral (a `'total'` comparison). */
+  slot: number;
+  /** True when the slot is reused (primary index ≥ 8). */
+  overflow: boolean;
+  /** Parent key, `'total'`, or undefined for a primary series. */
+  comparisonOf?: string;
+}
+
+export interface ResolveResult {
+  series: ResolvedSeries[];
+  dropped: string[];
+  overflowCount: number;
+}
+
+const fit = (values: readonly (number | null)[], length: number) =>
+  Array.from({ length }, (_, i) => (Number.isFinite(values[i]) ? (values[i] as number) : null));
+
+export function resolveSeries(
+  type: ChartType,
+  input: readonly ChartSeries[],
+  length: number,
+): ResolveResult {
+  const stacked = isStacked(type);
+  const primaries = input.filter((x) => x.comparisonOf === undefined);
+  const primaryKeys = new Set(primaries.map((x) => x.key));
+  const dropped: string[] = [];
+  const byParent = new Map<string, ChartSeries[]>();
+  const totals: ChartSeries[] = [];
+
+  for (const c of input) {
+    if (c.comparisonOf === undefined) continue;
+    if (c.comparisonOf === 'total') {
+      if (stacked) totals.push(c);
+      else dropped.push(c.key);
+    } else if (stacked || !primaryKeys.has(c.comparisonOf)) {
+      dropped.push(c.key);
+    } else {
+      byParent.set(c.comparisonOf, [...(byParent.get(c.comparisonOf) ?? []), c]);
+    }
+  }
+
+  const series: ResolvedSeries[] = [];
+  primaries.forEach((p, i) => {
+    const slot = (i % PALETTE_SIZE) + 1;
+    const overflow = i >= PALETTE_SIZE;
+    series.push({ key: p.key, label: p.label, values: fit(p.values, length), slot, overflow });
+    for (const c of byParent.get(p.key) ?? []) {
+      series.push({
+        key: c.key,
+        label: c.label,
+        values: fit(c.values, length),
+        slot,
+        overflow,
+        comparisonOf: p.key,
+      });
+    }
+  });
+  for (const c of totals) {
+    series.push({
+      key: c.key,
+      label: c.label,
+      values: fit(c.values, length),
+      slot: 0,
+      overflow: false,
+      comparisonOf: 'total',
+    });
+  }
+  return { series, dropped, overflowCount: Math.max(0, primaries.length - PALETTE_SIZE) };
+}
+
+export function visibleSeries(
+  series: readonly ResolvedSeries[],
+  hidden: readonly string[],
+): ResolvedSeries[] {
+  const h = new Set(hidden);
+  return series.filter(
+    (x) =>
+      !h.has(x.key) &&
+      !(x.comparisonOf !== undefined && x.comparisonOf !== 'total' && h.has(x.comparisonOf)),
+  );
+}
+
+export function isEmpty(categories: readonly string[], series: readonly ResolvedSeries[]): boolean {
+  return (
+    categories.length === 0 || series.every((x) => x.values.every((v) => v === null || v === 0))
+  );
+}
+
+const textWidth = (text: string) => text.length * CHAR_WIDTH;
+
+/** Indices of the x labels to draw so none overlap; first always kept, last kept when it fits. */
+export function thinLabels(categories: readonly string[], step: number): number[] {
+  const n = categories.length;
+  if (n === 0) return [];
+  const labelWidth = Math.max(...categories.map(textWidth)) + LABEL_GAP;
+  const every = Math.max(1, Math.ceil(labelWidth / step));
+  const kept: number[] = [];
+  for (let i = 0; i < n; i += every) kept.push(i);
+  const last = n - 1;
+  if (kept[kept.length - 1] !== last) {
+    while (kept.length > 1 && (last - kept[kept.length - 1]) * step < labelWidth) kept.pop();
+    if ((last - kept[kept.length - 1]) * step >= labelWidth) kept.push(last);
+  }
+  return kept;
+}
+
+/** How many legend items fit on one row of `width`, leaving room for a "+N" counter. At least 1. */
+export function fitLegend(labels: readonly string[], width: number): number {
+  let used = 0;
+  for (let i = 0; i < labels.length; i++) {
+    const w = textWidth(labels[i]) + LEGEND_ITEM_EXTRA;
+    const reserve = i === labels.length - 1 ? 0 : LEGEND_MORE_WIDTH;
+    if (used + w + reserve > width) return Math.max(1, i);
+    used += w;
+  }
+  return labels.length;
+}
+
+export type BarEnd = 'top' | 'bottom' | null;
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** SVG path for a bar with a rounded data end (`top` for positive, `bottom` for negative). */
+export function barPath({ x, y, width, height }: Rect, end: BarEnd): string {
+  const r = end ? Math.min(BAR_RADIUS, width / 2, height) : 0;
+  if (r === 0) return `M${x},${y}h${width}v${height}h${-width}Z`;
+  const right = x + width;
+  const bottom = y + height;
+  if (end === 'top') {
+    return `M${x},${bottom}V${y + r}Q${x},${y} ${x + r},${y}H${right - r}Q${right},${y} ${right},${y + r}V${bottom}Z`;
+  }
+  return `M${x},${y}H${right}V${bottom - r}Q${right},${bottom} ${right - r},${bottom}H${x + r}Q${x},${bottom} ${x},${bottom - r}Z`;
+}
+
+export type MarkerShape = 'circle' | 'square' | 'triangle' | 'diamond';
+const SHAPES: MarkerShape[] = ['circle', 'square', 'triangle', 'diamond'];
+
+/** Marker shape per palette slot, so identity never relies on colour alone. */
+export function markerShape(slot: number): MarkerShape {
+  return SHAPES[(Math.max(1, slot) - 1) % SHAPES.length];
+}
+
+export function markerPath(shape: MarkerShape, x: number, y: number, r: number): string {
+  switch (shape) {
+    case 'square':
+      return `M${x - r},${y - r}h${2 * r}v${2 * r}h${-2 * r}Z`;
+    case 'triangle':
+      return `M${x},${y - r}L${x + r},${y + r}L${x - r},${y + r}Z`;
+    case 'diamond':
+      return `M${x},${y - r}L${x + r},${y}L${x},${y + r}L${x - r},${y}Z`;
+    default:
+      return `M${x - r},${y}a${r},${r} 0 1,0 ${2 * r},0a${r},${r} 0 1,0 ${-2 * r},0`;
+  }
+}
+
+export interface SeriesMarks {
+  key: string;
+  slot: number;
+  overflow: boolean;
+  comparison: boolean;
+  kind: 'line' | 'area' | 'bars';
+  line?: string;
+  area?: string;
+  /** One path per category; `null` where the bar is absent (null or zero). */
+  bars?: (string | null)[];
+  /** Active-category anchor per category (top of the mark); `null` at gaps. */
+  points: (Point | null)[];
+  /** Isolated points that a line/area cannot draw. */
+  dots: Point[];
+}
+
+export interface LayoutInput {
+  type: ChartType;
+  categories: readonly string[];
+  /** Visible series only, in `resolveSeries` order. */
+  series: readonly ResolvedSeries[];
+  width: number;
+  height: number;
+  formatValue: (n: number) => string;
+}
+
+export interface ChartLayout {
+  plot: Rect;
+  yTicks: { value: number; y: number; label: string }[];
+  xLabels: { index: number; x: number; label: string }[];
+  /** Centre x of each category, in svg coordinates. */
+  categoryX: number[];
+  step: number;
+  bandWidth: number;
+  marks: SeriesMarks[];
+}
+
+type StackRow = Record<string, number>;
+
+const isolated = (values: readonly (number | null)[], i: number) =>
+  values[i] !== null && (values[i - 1] ?? null) === null && (values[i + 1] ?? null) === null;
+
+export function computeLayout(input: LayoutInput): ChartLayout {
+  const { type, categories, series, width, height, formatValue } = input;
+  const n = categories.length;
+  const stacked = isStacked(type);
+  const primaries = series.filter((x) => x.comparisonOf === undefined);
+  const comparisons = series.filter((x) => x.comparisonOf !== undefined);
+
+  const layers: Series<StackRow, string>[] | null = stacked
+    ? stack<StackRow, string>()
+        .keys(primaries.map((p) => p.key))
+        .value((row, key) => row[key])
+        .offset(type === 'area' ? stackOffsetNone : stackOffsetDiverging)(
+        Array.from({ length: n }, (_, i) =>
+          Object.fromEntries(primaries.map((p) => [p.key, p.values[i] ?? 0])),
+        ),
+      )
+    : null;
+
+  let min = 0;
+  let max = 0;
+  const take = (v: number | null) => {
+    if (v === null || Number.isNaN(v)) return;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  };
+  if (layers)
+    for (const layer of layers)
+      for (const [y0, y1] of layer) {
+        take(y0);
+        take(y1);
+      }
+  else for (const p of primaries) p.values.forEach(take);
+  for (const c of comparisons) c.values.forEach(take);
+
+  const samples = Math.max(2, Math.min(MAX_SAMPLES, Math.ceil(width / Math.max(1, n) / SAMPLE_PX)));
+  const smoothed = new Map(
+    (type === 'line' ? series : stacked ? comparisons : []).map((x) => [
+      x.key,
+      smoothLine(x.values, samples),
+    ]),
+  );
+  const areaStack =
+    type === 'area'
+      ? smoothStack(
+          primaries.map((p) => p.values.map((v) => v ?? 0)),
+          samples,
+        )
+      : null;
+  // Each layer stays within its own values, but layers trading places can lift the stacked top past
+  // the largest real total: keep that inside the plot.
+  for (const layer of areaStack ?? []) for (const seg of layer) seg.forEach(take);
+  if (min === max) max = min + 1;
+
+  const plotTop = PAD_TOP;
+  const plotBottom = Math.max(plotTop + 1, height - X_AXIS_HEIGHT);
+  const tickCount = Math.max(2, Math.floor((plotBottom - plotTop) / Y_TICK_SPACING));
+  const y = scaleLinear().domain([min, max]).range([plotBottom, plotTop]).nice(tickCount);
+  const tickValues = y.ticks(tickCount);
+  const tickLabels = tickValues.map(formatValue);
+  const left = Math.max(0, ...tickLabels.map(textWidth)) + LABEL_GAP;
+  const plot: Rect = {
+    x: left,
+    y: plotTop,
+    width: Math.max(1, width - left - PAD_RIGHT),
+    height: plotBottom - plotTop,
+  };
+  const step = plot.width / Math.max(1, n);
+  const bandWidth = step * BAND_RATIO;
+  const categoryX = categories.map((_, i) => plot.x + step * (i + 0.5));
+  const zeroY = y(0);
+
+  const yTicks = tickValues.map((value, i) => ({ value, y: y(value), label: tickLabels[i] }));
+  // Clamp end labels inside the svg, then drop any label the clamping made collide.
+  const boxes = thinLabels(categories, step).map((index) => {
+    const half = textWidth(categories[index]) / 2;
+    const x = Math.min(Math.max(categoryX[index], half), Math.max(half, width - half));
+    return { index, x, label: categories[index], half };
+  });
+  const hits = (a: (typeof boxes)[number], b: (typeof boxes)[number]) =>
+    b.x - b.half < a.x + a.half + LABEL_GAP;
+  const xLabels: typeof boxes = [];
+  boxes.forEach((b, i) => {
+    if (i === boxes.length - 1 && i > 0) {
+      while (xLabels.length > 1 && hits(xLabels[xLabels.length - 1], b)) xLabels.pop();
+    }
+    if (xLabels.length === 0 || !hits(xLabels[xLabels.length - 1], b)) xLabels.push(b);
+  });
+
+  const linePath = (key: string) =>
+    sampledRuns(smoothed.get(key) ?? [], categoryX, step, y)
+      .map((run) => `M${run.join('L')}`)
+      .join('');
+  const pointsOf = (values: readonly (number | null)[]) =>
+    values.map((v, i) => (v === null ? null : { x: categoryX[i], y: y(v) }));
+  const dotsOf = (values: readonly (number | null)[], points: (Point | null)[]) =>
+    values.flatMap((_, i) => (isolated(values, i) ? [points[i] as Point] : []));
+  const base = (x: ResolvedSeries) => ({
+    key: x.key,
+    slot: x.slot,
+    overflow: x.overflow,
+    comparison: x.comparisonOf !== undefined,
+  });
+
+  const lineMarks = (x: ResolvedSeries): SeriesMarks => {
+    const points = pointsOf(x.values);
+    return {
+      ...base(x),
+      kind: 'line',
+      line: linePath(x.key),
+      points,
+      dots: dotsOf(x.values, points),
+    };
+  };
+
+  const marks: SeriesMarks[] = [];
+
+  if (type === 'line') {
+    for (const x of series) marks.push(lineMarks(x));
+  } else if (type === 'bar') {
+    const groups = series.length;
+    // Shrink the gap with the slot so a group never spills into its neighbours.
+    const gap = Math.min(MARK_GAP, bandWidth / (2 * groups));
+    const barWidth = (bandWidth - gap * (groups - 1)) / groups;
+    series.forEach((x, j) => {
+      const bars = x.values.map((v, i) => {
+        if (v === null || v === 0) return null;
+        const bx = categoryX[i] - bandWidth / 2 + j * (barWidth + gap);
+        const top = Math.min(y(v), zeroY);
+        const h = Math.max(1, Math.abs(zeroY - y(v)));
+        return barPath({ x: bx, y: top, width: barWidth, height: h }, v > 0 ? 'top' : 'bottom');
+      });
+      marks.push({ ...base(x), kind: 'bars', bars, points: pointsOf(x.values), dots: [] });
+    });
+  } else if (layers) {
+    const posTotal = categories.map((_, i) => Math.max(0, ...layers.map((l) => l[i][1])));
+    const negTotal = categories.map((_, i) => Math.min(0, ...layers.map((l) => l[i][0])));
+    primaries.forEach((x, j) => {
+      const layer = layers[j];
+      const points = x.values.map((v, i) =>
+        v === null
+          ? null
+          : { x: categoryX[i], y: y(type === 'area' || v >= 0 ? layer[i][1] : layer[i][0]) },
+      );
+      if (type === 'stacked-bar') {
+        const bars = x.values.map((v, i) => {
+          if (v === null || v === 0) return null;
+          const [y0, y1] = layer[i];
+          let top = y(Math.max(y0, y1));
+          let bottom = y(Math.min(y0, y1));
+          if (v > 0 && y0 !== 0) bottom -= MARK_GAP;
+          if (v < 0 && y1 !== 0) top += MARK_GAP;
+          const end: BarEnd =
+            v > 0 && y1 === posTotal[i] ? 'top' : v < 0 && y0 === negTotal[i] ? 'bottom' : null;
+          return barPath(
+            {
+              x: categoryX[i] - bandWidth / 2,
+              y: top,
+              width: bandWidth,
+              height: Math.max(1, bottom - top),
+            },
+            end,
+          );
+        });
+        marks.push({ ...base(x), kind: 'bars', bars, points, dots: [] });
+      } else {
+        // Mask segments touching this series' gaps; the bottom edge is the layer below's top.
+        const mask = (segs: number[][]) =>
+          segs.map((seg, i) => (x.values[i] === null || x.values[i + 1] === null ? null : seg));
+        const flat = (segs: number[][]) => segs.map((seg) => seg.map(() => 0));
+        const tops = sampledRuns(mask(areaStack![j]), categoryX, step, y);
+        const bottoms = sampledRuns(
+          mask(j === 0 ? flat(areaStack![j]) : areaStack![j - 1]),
+          categoryX,
+          step,
+          y,
+        );
+        const topLine = tops.map((run) => `M${run.join('L')}`).join('');
+        const areaPath = tops
+          .map((run, r) => `M${run.join('L')}L${[...bottoms[r]].reverse().join('L')}Z`)
+          .join('');
+        marks.push({
+          ...base(x),
+          kind: 'area',
+          area: areaPath,
+          line: topLine,
+          points,
+          dots: dotsOf(x.values, points),
+        });
+      }
+    });
+    for (const c of comparisons) marks.push(lineMarks(c));
+  }
+
+  return {
+    plot,
+    yTicks,
+    xLabels: xLabels.map(({ index, x, label }) => ({ index, x, label })),
+    categoryX,
+    step,
+    bandWidth,
+    marks,
+  };
+}
+
+/** Pixels per straight sub-segment of a smoothed curve. */
+const SAMPLE_PX = 4;
+const MAX_SAMPLES = 32;
+const hermite = (y0: number, y1: number, m0: number, m1: number, t: number) => {
+  const t2 = t * t;
+  const t3 = t2 * t;
+  return (
+    (2 * t3 - 3 * t2 + 1) * y0 + (t3 - 2 * t2 + t) * m0 + (-2 * t3 + 3 * t2) * y1 + (t3 - t2) * m1
+  );
+};
+
+/**
+ * Monotone cubic through `v`: `result[i][s]` is the value at sample s (0..samples) of the segment
+ * between points i and i+1. Passes through every point and never leaves the range of its two ends: no
+ * dip before a climb, no bump after it, no negative counts, no inverted stack layers.
+ */
+function smoothRun(v: readonly number[], samples: number): number[][] {
+  const n = v.length;
+  const m = v.map((x, i) => {
+    // Two points: full slope at both ends, so the segment is straight rather than an S.
+    if (n === 2) return v[1] - v[0];
+    // Run ends: half their one real slope, so a climb from the edge starts nearly straight.
+    if (i === 0) return (v[1] - x) / 2;
+    if (i === n - 1) return (x - v[i - 1]) / 2;
+    const d0 = x - v[i - 1];
+    const d1 = v[i + 1] - x;
+    // Peaks, troughs and flat runs ease in flat.
+    if (d0 * d1 <= 0) return 0;
+    // Catmull-Rom, capped at 3x the gentler neighbouring slope (Fritsch-Carlson).
+    const cap = 3 * Math.min(Math.abs(d0), Math.abs(d1));
+    return Math.sign(d0) * Math.min(cap, Math.abs(d0 + d1) / 2);
+  });
+  return Array.from({ length: Math.max(0, n - 1) }, (_, i) => {
+    const lo = Math.min(v[i], v[i + 1]);
+    const hi = Math.max(v[i], v[i + 1]);
+    // The cap leaves a sliver of overshoot possible next to a run end; clamp it away.
+    return Array.from({ length: samples + 1 }, (_, s) =>
+      Math.min(hi, Math.max(lo, hermite(v[i], v[i + 1], m[i], m[i + 1], s / samples))),
+    );
+  });
+}
+
+/** Smoothed segments of a series with gaps: each defined run is its own curve; `null` where a segment touches a gap. */
+function smoothLine(values: readonly (number | null)[], samples: number): (number[] | null)[] {
+  const segs: (number[] | null)[] = Array.from(
+    { length: Math.max(0, values.length - 1) },
+    () => null,
+  );
+  for (let a = 0; a < values.length; a++) {
+    if (values[a] === null) continue;
+    let b = a;
+    while (b + 1 < values.length && values[b + 1] !== null) b++;
+    smoothRun(values.slice(a, b + 1) as number[], samples).forEach((seg, i) => (segs[a + i] = seg));
+    a = b;
+  }
+  return segs;
+}
+
+/**
+ * Cumulative tops of smoothed stacked layers: `result[k][i][s]` is the top of layer k at sample s of the
+ * segment between categories i and i+1. Each series' own values are smoothed (the same curve as lines,
+ * which never crosses 0 between same-signed values) and the curves are stacked. So a steady layer stays
+ * steady whatever its neighbours do, a series that is 0 has no thickness, and with non-negative data no
+ * layer turns inside out or crosses its neighbour.
+ */
+export function smoothStack(layers: readonly (readonly number[])[], samples: number): number[][][] {
+  let below: number[][] | null = null;
+  return layers.map((v) => {
+    const tops = smoothRun(v, samples).map((seg, i) => seg.map((h, s) => (below?.[i][s] ?? 0) + h));
+    below = tops;
+    return tops;
+  });
+}
+
+const r2 = (v: number) => Math.round(v * 100) / 100;
+
+/** Point lists of each drawable run in `segs` (svg coordinates). */
+function sampledRuns(
+  segs: readonly (readonly number[] | null)[],
+  categoryX: readonly number[],
+  step: number,
+  y: (v: number) => number,
+): string[][] {
+  const runs: string[][] = [];
+  let run: string[] | null = null;
+  segs.forEach((seg, i) => {
+    if (!seg) {
+      run = null;
+      return;
+    }
+    if (!run) runs.push((run = []));
+    const samples = seg.length - 1;
+    for (let s = run.length === 0 ? 0 : 1; s <= samples; s++)
+      run.push(`${r2(categoryX[i] + (step * s) / samples)},${r2(y(seg[s]))}`);
+  });
+  return runs;
+}
+
+/** Category index under svg x coordinate `x`, clamped to the data (0 when there are no categories). */
+export function categoryIndexAt(layout: ChartLayout, x: number): number {
+  const n = layout.categoryX.length;
+  return Math.max(0, Math.min(n - 1, Math.max(0, Math.floor((x - layout.plot.x) / layout.step))));
+}

package/src/components/Chart/index.ts

@@ -0,0 +1,2 @@
+export { Chart } from './Chart';
+export type { ChartMarker, ChartMarkerTone, ChartProps, ChartSeries, ChartType } from './Chart';