@multiplatform.one/components 6.1.0 → 6.3.0

package/src/charts/PieChart.tsx

@@ -0,0 +1,153 @@
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useTranslation } from "react-i18next";
+import { Text, XStack, YStack, type YStackProps } from "tamagui";
+import { componentColors } from "../componentColors";
+import { ChartSurface } from "./ChartSurface";
+import { describeChart, describeDatum } from "./accessibility";
+import { resolveSeriesFills } from "./composeChart";
+import { PieSeries } from "./series";
+import type { ChartDatum, ChartDatumEvents } from "./types";
+import { useChartTheme } from "./useChartTheme";
+
+export interface PieChartProps
+  extends ChartDatumEvents, Omit<YStackProps, "children" | "width" | "height"> {
+  data: ChartDatum[];
+  /** Pie diameter in px (default 200). */
+  height?: number;
+  /**
+   * Donut mode: `true` uses the default hole ratio (0.55); a number sets the
+   * inner-radius ratio (0–1). The hole is genuinely transparent (d3 arc
+   * innerRadius) — the card surface shows through on every platform.
+   */
+  donut?: boolean | number;
+  /** Radians between slices (default 0). */
+  padAngle?: number;
+  /** Explicit slice colors (data values — pass through untouched). */
+  colors?: string[];
+  /** Legend rows beside the pie (default true). */
+  showLegend?: boolean;
+  valueFormatter?: (value: number) => string;
+  /** Chart title used in the generated accessible summary. */
+  title?: string;
+  /** Override the generated accessible summary. */
+  label?: string;
+}
+
+const DEFAULT_DONUT_RATIO = 0.55;
+
+/**
+ * Pie/donut chart. Slices are categorical data, so defaults come from the
+ * identity-led categorical palette (LC-27); per-datum and prop colors pass
+ * through untouched. Legend rows carry the accessible per-slice values and
+ * remain the reliable interaction surface for thin slices.
+ *
+ * Containment (LC-10): the root shrinks with its frame instead of holding
+ * its intrinsic width, so in narrow cards the legend wraps below the pie —
+ * it never paints past the frame. Inside a legend row the label truncates
+ * first (ellipsis); the value is data and never truncates (Axiom 11).
+ */
+export function PieChart({
+  data,
+  height = 200,
+  donut = false,
+  padAngle = 0,
+  colors,
+  showLegend = true,
+  valueFormatter,
+  title,
+  label,
+  onDatumPress,
+  onDatumHoverIn,
+  onDatumHoverOut,
+  ...stackProps
+}: PieChartProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const { palette } = useChartTheme();
+  const fills = resolveSeriesFills(data, palette, { colors, categorical: true });
+  const format = valueFormatter ?? ((value: number) => value.toLocaleString());
+  const total = data.reduce((sum, datum) => sum + datum.value, 0);
+  const ariaLabel =
+    label ??
+    describeChart({
+      typeLabel: donut ? t("Donut chart") : t("Pie chart"),
+      title,
+      data,
+      formatValue: valueFormatter,
+      includeShare: true,
+    });
+  const interactive = Boolean(onDatumPress || onDatumHoverIn || onDatumHoverOut);
+  const innerRatio =
+    donut === false ? 0 : donut === true ? DEFAULT_DONUT_RATIO : Math.min(Math.max(donut, 0), 0.9);
+
+  return (
+    // LC-10: `flexShrink` + `minWidth 0` let a row parent (e.g. Card.Footer)
+    // constrain the chart below its intrinsic width — the wrap then stacks
+    // the legend under the pie instead of painting past the frame.
+    <XStack
+      flexWrap="wrap"
+      alignItems="center"
+      flexShrink={1}
+      minWidth={0}
+      {...knobProps.gap}
+      {...stackProps}
+    >
+      <YStack width={height} height={height}>
+        <ChartSurface label={ariaLabel} height={height} width={height}>
+          {(size) => {
+            const outerRadius = Math.min(size.width, size.height) / 2;
+            return (
+              <PieSeries
+                data={data}
+                cx={size.width / 2}
+                cy={size.height / 2}
+                outerRadius={outerRadius}
+                innerRadius={outerRadius * innerRatio}
+                padAngle={padAngle}
+                fills={fills}
+                onDatumPress={onDatumPress}
+                onDatumHoverIn={onDatumHoverIn}
+                onDatumHoverOut={onDatumHoverOut}
+                datumLabel={
+                  interactive
+                    ? (datum) => describeDatum({ datum, total, formatValue: valueFormatter })
+                    : undefined
+                }
+              />
+            );
+          }}
+        </ChartSurface>
+      </YStack>
+
+      {showLegend ? (
+        <YStack
+          flex={1}
+          minWidth={140}
+          justifyContent="center"
+          gap="$2"
+          {...{ "data-pie-legend": "true" }}
+        >
+          {data.map((datum, index) => (
+            <XStack key={`${datum.label}-${index}`} gap="$2" alignItems="center" minWidth={0}>
+              <YStack
+                width={12}
+                height={12}
+                borderRadius="$2"
+                flexShrink={0}
+                backgroundColor={fills[index] as never}
+              />
+              {/* The label yields (truncates) before the value — values are
+                  data and never truncate (Axiom 11). */}
+              <Text fontSize="$2" color={componentColors.text.muted} flex={1} numberOfLines={1}>
+                {datum.label}
+              </Text>
+              <Text fontSize="$2" fontWeight="500" flexShrink={0}>
+                {format(datum.value)}
+              </Text>
+            </XStack>
+          ))}
+        </YStack>
+      ) : null}
+    </XStack>
+  );
+}

package/src/charts/Sparkline.tsx

@@ -0,0 +1,98 @@
+import { useTranslation } from "react-i18next";
+import type { YStackProps } from "tamagui";
+import { ChartSurface } from "./ChartSurface";
+import { describeChart } from "./accessibility";
+import { createLinearScale, createPointScale, valueDomain } from "./math";
+import { AreaSeries, LineSeries } from "./series";
+import type { ChartCurve, ChartDatum } from "./types";
+import { useChartTheme } from "./useChartTheme";
+
+export interface SparklineProps extends Omit<YStackProps, "children" | "width" | "height"> {
+  /** Series values — bare numbers or full data points. */
+  data: Array<number | ChartDatum>;
+  /** Drawing height in px (default 36 — inline metric scale). */
+  height?: number;
+  /** Fixed width; omit to track the parent responsively. */
+  width?: number;
+  /** Explicit color (data value — passes through untouched). */
+  color?: string;
+  /** Soft area fill under the line (default true). */
+  showArea?: boolean;
+  curve?: ChartCurve;
+  strokeWidth?: number;
+  /** Title used in the generated accessible summary. */
+  title?: string;
+  /** Override the generated accessible summary. */
+  label?: string;
+}
+
+/**
+ * Inline trend miniature (KPI-card scale): no axes, no grid, no targets —
+ * one identity-colored line with an optional soft area. The generated
+ * accessible summary carries the data shape a glance conveys visually.
+ */
+export function Sparkline({
+  data,
+  height = 36,
+  width,
+  color,
+  showArea = true,
+  curve = "monotone",
+  strokeWidth = 1.5,
+  title,
+  label,
+  ...stackProps
+}: SparklineProps) {
+  const { t } = useTranslation();
+  const { palette } = useChartTheme();
+  const stroke = color ?? palette.single;
+  const normalized: ChartDatum[] = data.map((entry, index) =>
+    typeof entry === "number" ? { label: String(index + 1), value: entry } : entry,
+  );
+  const ariaLabel = label ?? describeChart({ typeLabel: t("Sparkline"), title, data: normalized });
+
+  return (
+    <ChartSurface label={ariaLabel} height={height} width={width} {...stackProps}>
+      {(size) => {
+        if (normalized.length === 0) return null;
+        const inset = strokeWidth + 1;
+        const xScale = createPointScale({
+          domain: normalized.map((datum) => datum.label),
+          range: [inset, size.width - inset],
+        });
+        const yScale = createLinearScale({
+          domain: valueDomain(
+            normalized.map((datum) => datum.value),
+            { zeroBased: false },
+          ),
+          range: [size.height - inset, inset],
+          nice: false,
+        });
+        const points = normalized.map((datum) => ({
+          x: xScale(datum.label) ?? inset,
+          y: yScale(datum.value),
+        }));
+        return (
+          <>
+            {showArea ? (
+              <AreaSeries
+                points={points}
+                baseline={size.height - inset}
+                color={stroke}
+                curve={curve}
+              />
+            ) : null}
+            <LineSeries
+              data={normalized}
+              points={points}
+              color={stroke}
+              strokeWidth={strokeWidth}
+              curve={curve}
+              showPoints={false}
+            />
+          </>
+        );
+      }}
+    </ChartSurface>
+  );
+}

package/src/charts/accessibility.ts

@@ -0,0 +1,75 @@
+/**
+ * Generated accessible chart summaries (Axiom 12 LEGIBLE FLOOR).
+ *
+ * Every chart surface exposes `role="img"` with a generated text summary so
+ * screen-reader users get the shape of the data, not silence. The functions
+ * are pure; components pass already-translated type/title labels in, and the
+ * numbers format through `toLocaleString` like every other catalog value.
+ */
+
+import { formatChartValue } from "./math";
+import type { ChartDatum } from "./types";
+
+export interface DescribeChartInput {
+  /** Already-translated chart-kind label, e.g. `t("Bar chart")`. */
+  typeLabel: string;
+  /** Optional already-translated chart title. */
+  title?: string;
+  data: ChartDatum[];
+  /** Value formatter (defaults to `toLocaleString`). */
+  formatValue?: (value: number) => string;
+  /**
+   * Include each datum's share of the total (pie/donut summaries).
+   */
+  includeShare?: boolean;
+}
+
+/**
+ * One-sentence data summary for a whole chart:
+ * "Bar chart, Revenue: 5 data points. Highest May (1,200); lowest Jan (400)."
+ */
+export function describeChart(input: DescribeChartInput): string {
+  const { typeLabel, title, data } = input;
+  const formatValue = input.formatValue ?? formatChartValue;
+  const head = title ? `${typeLabel}, ${title}` : typeLabel;
+  if (data.length === 0) return `${head}: no data`;
+  if (data.length === 1) {
+    return `${head}: 1 data point. ${data[0].label} ${formatValue(data[0].value)}`;
+  }
+  let highest = data[0];
+  let lowest = data[0];
+  let total = 0;
+  for (const datum of data) {
+    if (datum.value > highest.value) highest = datum;
+    if (datum.value < lowest.value) lowest = datum;
+    total += datum.value;
+  }
+  const parts = [
+    `${head}: ${data.length} data points`,
+    `highest ${highest.label} (${formatValue(highest.value)})`,
+    `lowest ${lowest.label} (${formatValue(lowest.value)})`,
+  ];
+  if (input.includeShare) parts.push(`total ${formatValue(total)}`);
+  return `${parts[0]}. ${parts.slice(1).join("; ")}`;
+}
+
+export interface DescribeDatumInput {
+  datum: ChartDatum;
+  /** Sum of all values — adds a percentage share when provided. */
+  total?: number;
+  formatValue?: (value: number) => string;
+}
+
+/**
+ * Per-datum accessible name for interactive targets:
+ * "May: 1,200" or "May: 1,200 (31%)".
+ */
+export function describeDatum(input: DescribeDatumInput): string {
+  const formatValue = input.formatValue ?? formatChartValue;
+  const base = `${input.datum.label}: ${formatValue(input.datum.value)}`;
+  if (input.total && input.total > 0) {
+    const share = Math.round((input.datum.value / input.total) * 100);
+    return `${base} (${share}%)`;
+  }
+  return base;
+}

package/src/charts/charts.spec.tsx

@@ -0,0 +1,321 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset, useChartPalette, type ChartPalette } from "@multiplatform.one/theme";
+import { cleanup, fireEvent, screen } from "@testing-library/react";
+import * as React from "react";
+import { Theme } from "tamagui";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AreaChart, LineChart } from "./LineChart";
+import { BarChart } from "./BarChart";
+import { PieChart } from "./PieChart";
+import { Sparkline } from "./Sparkline";
+import * as ChartExports from "./index";
+import type { ChartDatum } from "./types";
+
+afterEach(cleanup);
+
+const data: ChartDatum[] = [
+  { label: "Jan", value: 400 },
+  { label: "Feb", value: 380 },
+  { label: "May", value: 1200 },
+  { label: "Jun", value: 900 },
+];
+
+function PaletteProbe({ into }: { into: { current?: ChartPalette } }) {
+  into.current = useChartPalette();
+  return null;
+}
+
+function markRects(): Element[] {
+  // Mark rects carry a resolved fill; interaction targets are transparent.
+  return Array.from(document.querySelectorAll("svg rect")).filter(
+    (rect) => rect.getAttribute("fill") !== "transparent",
+  );
+}
+
+function targetRects(): Element[] {
+  return Array.from(document.querySelectorAll('svg rect[fill="transparent"]'));
+}
+
+// In happy-dom onLayout never fires, so every chart passes an explicit width.
+const WIDTH = 400;
+
+describe("BarChart", () => {
+  it("renders one identity-colored bar per datum (single series, LC-27)", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <BarChart data={data} width={WIDTH} />
+      </>,
+    );
+    const bars = markRects();
+    expect(bars.length).toBe(data.length);
+    for (const bar of bars) expect(bar.getAttribute("fill")).toBe(palette.current?.single);
+  });
+
+  it("categorical mode takes the identity-led categorical palette", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <BarChart data={data} width={WIDTH} categorical />
+      </>,
+    );
+    const fills = markRects().map((bar) => bar.getAttribute("fill"));
+    expect(fills).toEqual(palette.current?.categorical.slice(0, data.length));
+  });
+
+  it("re-anchors the identity under a tint sub-theme", () => {
+    const base: { current?: ChartPalette } = {};
+    const tinted: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={base} />
+        <Theme name={"red" as never}>
+          <PaletteProbe into={tinted} />
+          <BarChart data={data} width={WIDTH} />
+        </Theme>
+      </>,
+    );
+    expect(tinted.current?.single).not.toBe(base.current?.single);
+    for (const bar of markRects()) {
+      expect(bar.getAttribute("fill")).toBe(tinted.current?.single);
+    }
+  });
+
+  it("passes explicit data colors through untouched (VALUE IS DATA)", () => {
+    renderWithProviders(
+      <BarChart
+        data={[
+          { label: "custom", value: 5, color: "#123456" },
+          { label: "default", value: 5 },
+        ]}
+        width={WIDTH}
+      />,
+    );
+    const fills = markRects().map((bar) => bar.getAttribute("fill"));
+    expect(fills[0]).toBe("#123456");
+    expect(fills[1]).not.toBe("#123456");
+  });
+
+  it("exposes role=img with a generated data summary (Axiom 12)", () => {
+    renderWithProviders(<BarChart data={data} width={WIDTH} title="Revenue" />);
+    const img = screen.getByRole("img");
+    const label = img.getAttribute("aria-label") ?? "";
+    expect(label).toContain("Bar chart, Revenue");
+    expect(label).toContain("highest May (1,200)");
+    expect(label).toContain("lowest Feb (380)");
+  });
+
+  it("renders 44px-floor hit targets with per-datum names when interactive", () => {
+    const onDatumPress = vi.fn();
+    renderWithProviders(<BarChart data={data} width={WIDTH} onDatumPress={onDatumPress} />);
+    const targets = targetRects();
+    expect(targets.length).toBe(data.length);
+    for (const target of targets) {
+      expect(Number(target.getAttribute("width"))).toBeGreaterThanOrEqual(44);
+    }
+    expect(targets[2].getAttribute("aria-label")).toBe("May: 1,200");
+    fireEvent.click(targets[2]);
+    expect(onDatumPress).toHaveBeenCalledWith(data[2], 2);
+  });
+
+  it("renders y grid lines and axis labels from d3 ticks", () => {
+    renderWithProviders(<BarChart data={data} width={WIDTH} />);
+    expect(document.querySelectorAll("svg line").length).toBeGreaterThan(0);
+    const texts = Array.from(document.querySelectorAll("svg text")).map((t) => t.textContent);
+    expect(texts).toContain("Jan");
+    expect(texts).toContain("0");
+  });
+
+  it("renders nothing but the accessible summary for empty data", () => {
+    renderWithProviders(<BarChart data={[]} width={WIDTH} />);
+    expect(markRects().length).toBe(0);
+    const img = screen.getByRole("img");
+    expect(img.getAttribute("aria-label")).toContain("no data");
+  });
+});
+
+describe("LineChart / AreaChart", () => {
+  it("strokes the line and dots with the palette identity", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <LineChart data={data} width={WIDTH} />
+      </>,
+    );
+    const path = document.querySelector('svg path[fill="none"]');
+    expect(path?.getAttribute("stroke")).toBe(palette.current?.single);
+    const dots = document.querySelectorAll("svg circle:not([fill='transparent'])");
+    expect(dots.length).toBe(data.length);
+  });
+
+  it("renders 44px point targets when interactive", () => {
+    const onDatumPress = vi.fn();
+    renderWithProviders(<LineChart data={data} width={WIDTH} onDatumPress={onDatumPress} />);
+    const targets = Array.from(document.querySelectorAll('svg circle[fill="transparent"]'));
+    expect(targets.length).toBe(data.length);
+    for (const target of targets) {
+      expect(Number(target.getAttribute("r"))).toBeGreaterThanOrEqual(22);
+    }
+    fireEvent.click(targets[0]);
+    expect(onDatumPress).toHaveBeenCalledWith(data[0], 0);
+  });
+
+  it("AreaChart adds the soft area fill under the identity line", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <AreaChart data={data} width={WIDTH} />
+      </>,
+    );
+    const area = Array.from(document.querySelectorAll("svg path")).find(
+      (p) => p.getAttribute("fill") !== "none" && p.getAttribute("opacity"),
+    );
+    expect(area).toBeDefined();
+    expect(area?.getAttribute("fill")).toBe(palette.current?.single);
+  });
+});
+
+describe("PieChart", () => {
+  const pieData: ChartDatum[] = [
+    { label: "A", value: 4 },
+    { label: "B", value: 3 },
+    { label: "C", value: 2 },
+  ];
+
+  it("slices take the categorical palette in data order", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <PieChart data={pieData} showLegend={false} />
+      </>,
+    );
+    const fills = Array.from(document.querySelectorAll("svg path")).map((p) =>
+      p.getAttribute("fill"),
+    );
+    expect(fills).toEqual(palette.current?.categorical.slice(0, pieData.length));
+  });
+
+  it("legend rows carry label and formatted value", () => {
+    renderWithProviders(<PieChart data={pieData} />);
+    expect(screen.getByText("A")).toBeInTheDocument();
+    expect(screen.getByText("4")).toBeInTheDocument();
+  });
+
+  it("per-slice press targets carry share-aware names", () => {
+    const onDatumPress = vi.fn();
+    renderWithProviders(<PieChart data={pieData} showLegend={false} onDatumPress={onDatumPress} />);
+    const slices = Array.from(document.querySelectorAll("svg path"));
+    expect(slices[0].getAttribute("aria-label")).toBe("A: 4 (44%)");
+    fireEvent.click(slices[1]);
+    expect(onDatumPress).toHaveBeenCalledWith(pieData[1], 1);
+  });
+
+  it("donut hole is genuine geometry — no background cover circle", () => {
+    renderWithProviders(<PieChart data={pieData} donut showLegend={false} />);
+    expect(document.querySelectorAll("svg circle").length).toBe(0);
+  });
+
+  describe("legend containment (LC-10)", () => {
+    it("root shrinks with its frame and wraps — never holds intrinsic width", () => {
+      const { container } = renderWithProviders(<PieChart data={pieData} />);
+      const legend = container.querySelector('[data-pie-legend="true"]') as HTMLElement;
+      expect(legend).toBeTruthy();
+      const root = legend.parentElement as HTMLElement;
+      const rootStyle = getComputedStyle(root);
+      // A row parent (e.g. Card.Footer) may constrain the chart below its
+      // intrinsic width; the wrap then stacks the legend under the pie.
+      expect(rootStyle.flexWrap).toBe("wrap");
+      expect(rootStyle.flexShrink).toBe("1");
+      expect(rootStyle.minWidth).toBe("0px");
+      // The legend keeps its wrap floor so it breaks to a full-width line
+      // instead of squeezing beside the pie.
+      expect(getComputedStyle(legend).minWidth).toBe("140px");
+    });
+
+    it("legend rows truncate the label, never the value (Axiom 11)", () => {
+      const { container } = renderWithProviders(
+        <PieChart
+          data={[{ label: "A very long category label that truncates", value: 1234567 }]}
+        />,
+      );
+      const legend = container.querySelector('[data-pie-legend="true"]') as HTMLElement;
+      const label = screen.getByText("A very long category label that truncates");
+      const value = screen.getByText((1234567).toLocaleString());
+      expect(legend.contains(label)).toBe(true);
+      expect(legend.contains(value)).toBe(true);
+      // Label yields: single-line ellipsis + shrinkable flex basis.
+      const labelStyle = getComputedStyle(label);
+      expect(labelStyle.textOverflow).toBe("ellipsis");
+      // Value is data: it never shrinks below its content.
+      expect(getComputedStyle(value).flexShrink).toBe("0");
+    });
+
+    it("no legend frame renders when showLegend is false", () => {
+      const { container } = renderWithProviders(<PieChart data={pieData} showLegend={false} />);
+      expect(container.querySelector('[data-pie-legend="true"]')).toBeNull();
+    });
+  });
+});
+
+describe("Sparkline", () => {
+  it("accepts bare numbers and renders an identity line", () => {
+    const palette: { current?: ChartPalette } = {};
+    renderWithProviders(
+      <>
+        <PaletteProbe into={palette} />
+        <Sparkline data={[1, 3, 2, 5]} width={120} />
+      </>,
+    );
+    const line = document.querySelector('svg path[fill="none"]');
+    expect(line?.getAttribute("stroke")).toBe(palette.current?.single);
+    expect(screen.getByRole("img").getAttribute("aria-label")).toContain("Sparkline");
+  });
+});
+
+describe("animation knob (A-CONTINUOUS)", () => {
+  it("renders identically at animation=none — no driver, no enter styles", () => {
+    renderWithProviders(
+      <Preset overrides={{ animation: "none" }}>
+        <BarChart data={data} width={WIDTH} />
+      </Preset>,
+    );
+    expect(markRects().length).toBe(data.length);
+  });
+});
+
+describe("charts barrel", () => {
+  it("exports the headless core, primitives, and composed charts", () => {
+    for (const name of [
+      "createBandScale",
+      "createLinearScale",
+      "createPointScale",
+      "createTimeScale",
+      "linePath",
+      "areaPath",
+      "pieSlices",
+      "arcPath",
+      "describeChart",
+      "describeDatum",
+      "useChartTheme",
+      "ChartSurface",
+      "XAxis",
+      "YAxis",
+      "BarSeries",
+      "LineSeries",
+      "AreaSeries",
+      "PieSeries",
+      "BarChart",
+      "LineChart",
+      "AreaChart",
+      "PieChart",
+      "Sparkline",
+    ]) {
+      expect(ChartExports).toHaveProperty(name);
+    }
+  });
+});