@multiplatform.one/components 6.1.0 → 6.4.0

package/src/charts/composeChart.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared layout/color plumbing for the composed charts (Bar/Line/Area/Pie).
+ * Pure helpers — unit-testable without a renderer.
+ */
+
+import type { ChartPalette } from "@multiplatform.one/theme";
+import { AXIS_LABEL_GAP, AXIS_TICK_LENGTH } from "./Axis";
+import { approximateTextWidth } from "./math";
+import type { ChartDatum, ChartSize, PlotArea } from "./types";
+
+export interface CartesianPlotInput {
+  showXAxis: boolean;
+  showYAxis: boolean;
+  /** Formatted y tick labels (drives the left margin). */
+  yTickLabels: string[];
+  fontSize: number;
+}
+
+/**
+ * Reserve margins for axes inside the measured surface and return the plot
+ * rectangle. Label widths are approximated cross-platform (no DOM measure);
+ * the approximation over-reserves slightly so labels never clip (LC-10).
+ */
+export function computeCartesianPlot(size: ChartSize, input: CartesianPlotInput): PlotArea {
+  const { showXAxis, showYAxis, yTickLabels, fontSize } = input;
+  const top = Math.ceil(fontSize / 2) + 2;
+  const right = 4;
+  const bottom = showXAxis ? AXIS_TICK_LENGTH + AXIS_LABEL_GAP + Math.ceil(fontSize * 1.15) : 4;
+  const maxYLabelWidth = showYAxis
+    ? Math.max(0, ...yTickLabels.map((label) => approximateTextWidth(label, fontSize)))
+    : 0;
+  const left = showYAxis ? Math.ceil(maxYLabelWidth) + AXIS_TICK_LENGTH + AXIS_LABEL_GAP + 2 : 4;
+  return {
+    x: left,
+    y: top,
+    width: Math.max(0, size.width - left - right),
+    height: Math.max(0, size.height - top - bottom),
+  };
+}
+
+export interface SeriesFillsInput {
+  /** Explicit single-series color (a prop-level data color). */
+  color?: string;
+  /** Explicit per-datum colors (prop-level data colors). */
+  colors?: string[];
+  /** Paint per-datum categorical identity instead of one series color. */
+  categorical?: boolean;
+}
+
+/**
+ * Resolve one fill per datum (LC-27 CHART-PALETTE):
+ * per-datum `color` > explicit `colors`/`color` props (VALUE IS DATA — pass
+ * through untouched) > canonical palette (categorical cycle for categorical
+ * data, otherwise the single theme identity for every mark).
+ */
+export function resolveSeriesFills(
+  data: ChartDatum[],
+  palette: ChartPalette,
+  input?: SeriesFillsInput,
+): string[] {
+  return data.map((datum, index) => {
+    if (datum.color) return datum.color;
+    if (input?.colors && input.colors.length > 0) return input.colors[index % input.colors.length];
+    if (input?.categorical) return palette.categorical[index % palette.categorical.length];
+    return input?.color ?? palette.single;
+  });
+}
+
+/** Widest x label a slot may spend before thinning kicks in (px). */
+const MAX_X_LABEL_SLOT = 72;
+const X_LABEL_SLOT_GAP = 8;
+
+/**
+ * Pick an evenly-strided subset of category labels that fits the plot width
+ * without overlap (LC-10 at phone widths): every label gets a slot sized by
+ * the widest label (capped), and the stride skips the rest.
+ */
+export function thinCategories(labels: string[], plotWidth: number, fontSize: number): string[] {
+  if (labels.length <= 1 || plotWidth <= 0) return labels;
+  const widest = Math.max(...labels.map((label) => approximateTextWidth(label, fontSize)));
+  const slot = Math.min(widest, MAX_X_LABEL_SLOT) + X_LABEL_SLOT_GAP;
+  const capacity = Math.max(1, Math.floor(plotWidth / slot));
+  if (labels.length <= capacity) return labels;
+  const stride = Math.ceil(labels.length / capacity);
+  return labels.filter((_, index) => index % stride === 0);
+}

package/src/charts/index.ts

@@ -0,0 +1,69 @@
+// Headless math core (pure, renderer-agnostic)
+export {
+  approximateTextWidth,
+  arcCentroid,
+  arcPath,
+  areaPath,
+  createBandScale,
+  createLinearScale,
+  createPointScale,
+  createTimeScale,
+  formatChartValue,
+  getLinearTicks,
+  getTimeTicks,
+  linePath,
+  pieSlices,
+  truncateLabel,
+  valueDomain,
+  type ArcPathInput,
+  type AreaPathOptions,
+  type BandScaleInput,
+  type LinearScaleInput,
+  type LinePathOptions,
+  type PieSlice,
+  type PieSliceOptions,
+  type PointScaleInput,
+  type TimeScaleInput,
+  type ValueDomainOptions,
+} from "./math";
+
+// Accessible summaries (Axiom 12)
+export {
+  describeChart,
+  describeDatum,
+  type DescribeChartInput,
+  type DescribeDatumInput,
+} from "./accessibility";
+
+// Data contracts
+export type {
+  ChartCurve,
+  ChartDatum,
+  ChartDatumEvents,
+  ChartSize,
+  PixelPoint,
+  PlotArea,
+} from "./types";
+
+// Theming (chrome from knobs + ramps; series from useChartPalette)
+export { useChartTheme, type ChartTheme } from "./useChartTheme";
+
+// Primitives
+export { ChartSurface, type ChartSurfaceProps } from "./ChartSurface";
+export { XAxis, YAxis, type XAxisProps, type YAxisProps } from "./Axis";
+export {
+  AreaSeries,
+  BarSeries,
+  LineSeries,
+  PieSeries,
+  type AreaSeriesProps,
+  type BarSeriesProps,
+  type LineSeriesProps,
+  type PieSeriesProps,
+} from "./series";
+
+// Composed charts
+export { BarChart, type BarChartProps } from "./BarChart";
+export { AreaChart, LineChart, type AreaChartProps, type LineChartProps } from "./LineChart";
+export { PieChart, type PieChartProps } from "./PieChart";
+export { Sparkline, type SparklineProps } from "./Sparkline";

package/src/charts/math.spec.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { describeChart, describeDatum } from "./accessibility";
+import {
+  approximateTextWidth,
+  arcCentroid,
+  arcPath,
+  areaPath,
+  createBandScale,
+  createLinearScale,
+  createPointScale,
+  createTimeScale,
+  getLinearTicks,
+  getTimeTicks,
+  linePath,
+  pieSlices,
+  truncateLabel,
+  valueDomain,
+} from "./math";
+
+describe("charts/math scales", () => {
+  it("band scale maps categories into the pixel range with padding", () => {
+    const scale = createBandScale({ domain: ["a", "b", "c"], range: [0, 300] });
+    expect(scale("a")).toBeDefined();
+    expect(scale.bandwidth()).toBeGreaterThan(0);
+    // Bands stay inside the range.
+    for (const label of ["a", "b", "c"]) {
+      const x = scale(label) as number;
+      expect(x).toBeGreaterThanOrEqual(0);
+      expect(x + scale.bandwidth()).toBeLessThanOrEqual(300);
+    }
+    // Order preserved.
+    expect(scale("a") as number).toBeLessThan(scale("b") as number);
+    expect(scale("b") as number).toBeLessThan(scale("c") as number);
+  });
+
+  it("point scale spreads categories across the range", () => {
+    const scale = createPointScale({ domain: ["a", "b", "c"], range: [0, 100] });
+    expect(scale("a")).toBe(0);
+    expect(scale("b")).toBe(50);
+    expect(scale("c")).toBe(100);
+    expect(scale.bandwidth()).toBe(0);
+  });
+
+  it("linear scale maps values and inverts for the y axis", () => {
+    const scale = createLinearScale({ domain: [0, 100], range: [200, 0], nice: false });
+    expect(scale(0)).toBe(200);
+    expect(scale(100)).toBe(0);
+    expect(scale(50)).toBe(100);
+  });
+
+  it("time scale maps dates monotonically", () => {
+    const start = new Date("2026-01-01");
+    const end = new Date("2026-12-31");
+    const scale = createTimeScale({ domain: [start, end], range: [0, 365], nice: false });
+    expect(scale(start)).toBe(0);
+    expect(scale(new Date("2026-06-01"))).toBeGreaterThan(100);
+    expect(scale(end)).toBe(365);
+    expect(getTimeTicks(scale, 4).length).toBeGreaterThan(0);
+  });
+
+  it("nice ticks come from the scale domain", () => {
+    const scale = createLinearScale({ domain: [0, 870], range: [0, 1] });
+    const ticks = getLinearTicks(scale, 4);
+    expect(ticks[0]).toBe(0);
+    expect(ticks[ticks.length - 1]).toBeGreaterThanOrEqual(800);
+  });
+});
+
+describe("charts/math valueDomain", () => {
+  it("anchors at zero by default (honest bars)", () => {
+    expect(valueDomain([400, 870])).toEqual([0, 870]);
+  });
+
+  it("keeps negative minimums", () => {
+    expect(valueDomain([-20, 50])[0]).toBe(-20);
+  });
+
+  it("respects zeroBased=false (sparkline trend window)", () => {
+    const [min, max] = valueDomain([400, 870], { zeroBased: false });
+    expect(min).toBe(400);
+    expect(max).toBe(870);
+  });
+
+  it("opens a degenerate single-value domain", () => {
+    const [min, max] = valueDomain([5, 5]);
+    expect(max).toBeGreaterThan(min);
+  });
+
+  it("handles empty input", () => {
+    expect(valueDomain([])).toEqual([0, 1]);
+  });
+});
+
+describe("charts/math shape generators", () => {
+  const points = [
+    { x: 0, y: 100 },
+    { x: 50, y: 20 },
+    { x: 100, y: 60 },
+  ];
+
+  it("linePath emits an SVG path through every point", () => {
+    const d = linePath(points);
+    expect(d.startsWith("M")).toBe(true);
+    expect(d).toContain("100");
+  });
+
+  it("areaPath closes down to the baseline", () => {
+    const d = areaPath(points, { baseline: 120 });
+    expect(d.startsWith("M")).toBe(true);
+    expect(d).toContain("Z");
+    expect(d).toContain("120");
+  });
+
+  it("monotone curve produces cubic segments", () => {
+    const d = linePath(points, { curve: "monotone" });
+    expect(d).toContain("C");
+  });
+
+  it("pieSlices preserves input order and covers the full circle", () => {
+    const slices = pieSlices([{ value: 1 }, { value: 3 }, { value: 2 }]);
+    expect(slices.map((s) => s.index)).toEqual([0, 1, 2]);
+    expect(slices[0].startAngle).toBe(0);
+    expect(slices[2].endAngle).toBeCloseTo(Math.PI * 2, 6);
+    // Angular size follows value share.
+    const size = (s: { startAngle: number; endAngle: number }) => s.endAngle - s.startAngle;
+    expect(size(slices[1])).toBeGreaterThan(size(slices[0]));
+  });
+
+  it("arcPath renders a slice; innerRadius produces a donut hole", () => {
+    const pieD = arcPath({ startAngle: 0, endAngle: Math.PI, outerRadius: 50 });
+    const donutD = arcPath({ startAngle: 0, endAngle: Math.PI, outerRadius: 50, innerRadius: 25 });
+    expect(pieD.length).toBeGreaterThan(0);
+    expect(donutD).not.toBe(pieD);
+    // Donut path carries the inner-radius arc.
+    expect(donutD).toContain("25");
+  });
+
+  it("arcCentroid sits between inner and outer radii", () => {
+    const { x, y } = arcCentroid({ startAngle: 0, endAngle: Math.PI / 2, outerRadius: 100 });
+    const distance = Math.hypot(x, y);
+    expect(distance).toBeGreaterThan(0);
+    expect(distance).toBeLessThan(100);
+  });
+});
+
+describe("charts/math label fitting (LC-10)", () => {
+  it("keeps short labels and truncates long ones with an ellipsis", () => {
+    expect(truncateLabel("May", 12, 100)).toBe("May");
+    const truncated = truncateLabel("Extremely long category label", 12, 60);
+    expect(truncated.endsWith("\u2026")).toBe(true);
+    expect(approximateTextWidth(truncated, 12)).toBeLessThanOrEqual(60);
+  });
+});
+
+describe("charts/accessibility", () => {
+  const data = [
+    { label: "Jan", value: 400 },
+    { label: "May", value: 1200 },
+    { label: "Jun", value: 900 },
+  ];
+
+  it("summarizes count, highest, and lowest", () => {
+    const summary = describeChart({ typeLabel: "Bar chart", title: "Revenue", data });
+    expect(summary).toContain("Bar chart, Revenue");
+    expect(summary).toContain("3 data points");
+    expect(summary).toContain("highest May (1,200)");
+    expect(summary).toContain("lowest Jan (400)");
+  });
+
+  it("includes the total for share-based charts", () => {
+    const summary = describeChart({ typeLabel: "Pie chart", data, includeShare: true });
+    expect(summary).toContain("total 2,500");
+  });
+
+  it("handles empty and single-point data", () => {
+    expect(describeChart({ typeLabel: "Line chart", data: [] })).toBe("Line chart: no data");
+    expect(describeChart({ typeLabel: "Line chart", data: [data[0]] })).toContain("1 data point");
+  });
+
+  it("names a datum, optionally with its share", () => {
+    expect(describeDatum({ datum: data[1] })).toBe("May: 1,200");
+    expect(describeDatum({ datum: data[1], total: 2400 })).toBe("May: 1,200 (50%)");
+  });
+});

package/src/charts/math.ts

@@ -0,0 +1,275 @@
+/**
+ * Headless chart math — thin, pure wrappers over d3-scale / d3-shape.
+ *
+ * Everything here is renderer-agnostic (no React, no SVG): scales map data
+ * to pixel space, generators emit SVG path strings, and helpers compute
+ * domains/ticks. The SVG primitives and composed charts consume these; unit
+ * tests exercise them directly.
+ */
+
+import { scaleBand, scaleLinear, scalePoint, scaleTime } from "d3-scale";
+import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from "d3-scale";
+import {
+  arc as d3arc,
+  area as d3area,
+  curveLinear,
+  curveMonotoneX,
+  curveNatural,
+  curveStepAfter,
+  line as d3line,
+  pie as d3pie,
+} from "d3-shape";
+import type { CurveFactory } from "d3-shape";
+import type { ChartCurve, PixelPoint } from "./types";
+
+// ── Scales ────────────────────────────────────────────────────
+
+export interface BandScaleInput {
+  /** Category labels in draw order. */
+  domain: string[];
+  /** Pixel range, usually `[plot.x, plot.x + plot.width]`. */
+  range: [number, number];
+  /** Gap between bands as a fraction of the step (default 0.3). */
+  paddingInner?: number;
+  /** Outer gutter as a fraction of the step (default half the inner). */
+  paddingOuter?: number;
+}
+
+/** Categorical x scale for bar charts: label → band start px. */
+export function createBandScale(input: BandScaleInput): ScaleBand<string> {
+  const paddingInner = input.paddingInner ?? 0.3;
+  return scaleBand<string>()
+    .domain(input.domain)
+    .range(input.range)
+    .paddingInner(paddingInner)
+    .paddingOuter(input.paddingOuter ?? paddingInner / 2);
+}
+
+export interface PointScaleInput {
+  domain: string[];
+  range: [number, number];
+  /** Outer gutter as a fraction of the step (default 0 — full-bleed line). */
+  padding?: number;
+}
+
+/** Categorical x scale for line/area charts: label → point px. */
+export function createPointScale(input: PointScaleInput): ScalePoint<string> {
+  return scalePoint<string>()
+    .domain(input.domain)
+    .range(input.range)
+    .padding(input.padding ?? 0);
+}
+
+export interface LinearScaleInput {
+  domain: [number, number];
+  range: [number, number];
+  /** Round the domain to nice tick values (default true). */
+  nice?: boolean;
+  /** Clamp output to the range (default false). */
+  clamp?: boolean;
+}
+
+/** Continuous value scale: value → px. */
+export function createLinearScale(input: LinearScaleInput): ScaleLinear<number, number> {
+  const scale = scaleLinear().domain(input.domain).range(input.range);
+  if (input.nice !== false) scale.nice();
+  if (input.clamp) scale.clamp(true);
+  return scale;
+}
+
+export interface TimeScaleInput {
+  domain: [Date, Date];
+  range: [number, number];
+  nice?: boolean;
+}
+
+/** Time x scale: Date → px. */
+export function createTimeScale(input: TimeScaleInput): ScaleTime<number, number> {
+  const scale = scaleTime().domain(input.domain).range(input.range);
+  if (input.nice !== false) scale.nice();
+  return scale;
+}
+
+export interface ValueDomainOptions {
+  /**
+   * Anchor the domain at zero (default true — bars/areas that do not start
+   * at zero fabricate differences the data does not carry).
+   */
+  zeroBased?: boolean;
+  /** Head-room fraction above the max (default 0). */
+  paddingRatio?: number;
+}
+
+/** Compute a [min, max] value domain from raw values. */
+export function valueDomain(values: number[], options?: ValueDomainOptions): [number, number] {
+  const zeroBased = options?.zeroBased ?? true;
+  const paddingRatio = options?.paddingRatio ?? 0;
+  if (values.length === 0) return [0, 1];
+  let min = Math.min(...values);
+  let max = Math.max(...values);
+  if (zeroBased) {
+    min = Math.min(0, min);
+    max = Math.max(0, max);
+  }
+  if (min === max) {
+    // Degenerate domain (single value / all equal): open one unit so marks
+    // stay visible instead of collapsing onto the baseline.
+    if (max <= 0) min = max - 1;
+    else max = max + (max === min ? Math.abs(max) * paddingRatio || 1 : 0);
+    if (min === max) max = min + 1;
+  }
+  const pad = (max - min) * paddingRatio;
+  return [min, max + pad];
+}
+
+/** Nice tick values for a continuous scale. */
+export function getLinearTicks(scale: ScaleLinear<number, number>, count = 4): number[] {
+  return scale.ticks(count);
+}
+
+/** Nice tick dates for a time scale. */
+export function getTimeTicks(scale: ScaleTime<number, number>, count = 4): Date[] {
+  return scale.ticks(count);
+}
+
+/** Locale-aware default value format (matches catalog `toLocaleString` use). */
+export function formatChartValue(value: number): string {
+  return value.toLocaleString();
+}
+
+// ── Shape generators ──────────────────────────────────────────
+
+const curveFactories: Record<ChartCurve, CurveFactory> = {
+  linear: curveLinear,
+  monotone: curveMonotoneX,
+  natural: curveNatural,
+  step: curveStepAfter,
+};
+
+export interface LinePathOptions {
+  curve?: ChartCurve;
+}
+
+/** SVG path for a polyline through pixel-space points. */
+export function linePath(points: PixelPoint[], options?: LinePathOptions): string {
+  const generator = d3line<PixelPoint>()
+    .x((p) => p.x)
+    .y((p) => p.y)
+    .curve(curveFactories[options?.curve ?? "linear"]);
+  return generator(points) ?? "";
+}
+
+export interface AreaPathOptions {
+  curve?: ChartCurve;
+  /** Pixel y of the area baseline (usually the plot bottom). */
+  baseline: number;
+}
+
+/** SVG path for the filled area under pixel-space points. */
+export function areaPath(points: PixelPoint[], options: AreaPathOptions): string {
+  const generator = d3area<PixelPoint>()
+    .x((p) => p.x)
+    .y0(options.baseline)
+    .y1((p) => p.y)
+    .curve(curveFactories[options?.curve ?? "linear"]);
+  return generator(points) ?? "";
+}
+
+export interface PieSliceOptions {
+  /** Radians between slices (default 0). */
+  padAngle?: number;
+  /** Start angle in radians (default 0 = 12 o'clock). */
+  startAngle?: number;
+  /** End angle in radians (default 2π). */
+  endAngle?: number;
+}
+
+export interface PieSlice<T> {
+  datum: T;
+  /** Input order index — slice order is data order, never re-sorted. */
+  index: number;
+  value: number;
+  startAngle: number;
+  endAngle: number;
+  padAngle: number;
+}
+
+/** Angular layout for pie/donut slices. Preserves input order (Axiom 11). */
+export function pieSlices<T extends { value: number }>(
+  data: T[],
+  options?: PieSliceOptions,
+): PieSlice<T>[] {
+  const generator = d3pie<T>()
+    .value((d) => d.value)
+    .sort(null)
+    .padAngle(options?.padAngle ?? 0)
+    .startAngle(options?.startAngle ?? 0)
+    .endAngle(options?.endAngle ?? Math.PI * 2);
+  return generator(data).map((slice) => ({
+    datum: slice.data,
+    index: slice.index,
+    value: slice.value,
+    startAngle: slice.startAngle,
+    endAngle: slice.endAngle,
+    padAngle: slice.padAngle,
+  }));
+}
+
+export interface ArcPathInput {
+  startAngle: number;
+  endAngle: number;
+  outerRadius: number;
+  /** 0 for a pie; > 0 for a donut (true hole — background shows through). */
+  innerRadius?: number;
+  padAngle?: number;
+  cornerRadius?: number;
+}
+
+/** SVG path for one pie/donut slice, centered on (0,0). */
+export function arcPath(input: ArcPathInput): string {
+  const generator = d3arc()
+    .innerRadius(input.innerRadius ?? 0)
+    .outerRadius(input.outerRadius)
+    .cornerRadius(input.cornerRadius ?? 0);
+  return (
+    generator({
+      startAngle: input.startAngle,
+      endAngle: input.endAngle,
+      padAngle: input.padAngle ?? 0,
+      innerRadius: input.innerRadius ?? 0,
+      outerRadius: input.outerRadius,
+    }) ?? ""
+  );
+}
+
+/** Centroid of a slice (label/tooltip anchor), centered on (0,0). */
+export function arcCentroid(input: ArcPathInput): PixelPoint {
+  const generator = d3arc()
+    .innerRadius(input.innerRadius ?? 0)
+    .outerRadius(input.outerRadius);
+  const [x, y] = generator.centroid({
+    startAngle: input.startAngle,
+    endAngle: input.endAngle,
+    padAngle: input.padAngle ?? 0,
+    innerRadius: input.innerRadius ?? 0,
+    outerRadius: input.outerRadius,
+  });
+  return { x, y };
+}
+
+// ── Label fitting (LC-10 — no overflow/clipping) ──────────────
+
+/** Approximate glyph advance as a fraction of font size (avg UI sans). */
+const APPROX_CHAR_WIDTH_RATIO = 0.6;
+
+/** Approximate rendered width of a label — cross-platform, no DOM measure. */
+export function approximateTextWidth(text: string, fontSize: number): number {
+  return text.length * fontSize * APPROX_CHAR_WIDTH_RATIO;
+}
+
+/** Truncate a label with an ellipsis so it fits `maxWidth` px. */
+export function truncateLabel(text: string, fontSize: number, maxWidth: number): string {
+  if (approximateTextWidth(text, fontSize) <= maxWidth) return text;
+  const budget = Math.max(1, Math.floor(maxWidth / (fontSize * APPROX_CHAR_WIDTH_RATIO)) - 1);
+  return `${text.slice(0, budget)}\u2026`;
+}