@xemahq/ui-kernel 0.5.0 → 0.6.1

package/src/ui/charts/charts.test.tsx

@@ -0,0 +1,204 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Chart primitives — render proofs (Wave 9.2)
+//
+// Repo convention: `renderToStaticMarkup` (no @testing-library, effects DON'T
+// run — so `useIsMobile` stays false and the desktop layout renders). We assert
+// on the produced SVG markup: element counts, the fluid `viewBox` + width,
+// the aria summary, the legend, and — critically — that no coordinate ever
+// serializes as `NaN`.
+// ═══════════════════════════════════════════════════════════════════════════
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { BarChart } from './bar-chart';
+import { DonutChart } from './donut-chart';
+import { LineChart } from './line-chart';
+import { Sparkline } from './sparkline';
+
+const count = (markup: string, tag: string): number =>
+  markup.match(new RegExp(`<${tag}[\\s>]`, 'g'))?.length ?? 0;
+
+describe('BarChart', () => {
+  const data = [
+    { label: 'Q1', value: 120 },
+    { label: 'Q2', value: 340 },
+    { label: 'Q3', value: 210 },
+  ];
+
+  it('renders one bar per datum, fluid SVG, legend and aria summary', () => {
+    const markup = renderToStaticMarkup(<BarChart title="Revenue" data={data} />);
+    expect(count(markup, 'rect')).toBe(3);
+    expect(markup).toContain('viewBox="0 0 640 360"');
+    expect(markup).toContain('width="100%"');
+    expect(markup).toContain('role="img"');
+    // aria summary carries the title + the values (data is never color-only).
+    expect(markup).toContain('aria-label="Revenue:');
+    expect(markup).toContain('Q2 340');
+    // legend beside the plot (desktop: effects don't run so useIsMobile=false).
+    expect(count(markup, 'li')).toBe(3);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('renders an explicit empty state (no NaN) for an empty series', () => {
+    const markup = renderToStaticMarkup(<BarChart title="Revenue" data={[]} />);
+    expect(markup).toContain('role="img"');
+    expect(markup).toContain('aria-label="Revenue: No data"');
+    expect(count(markup, 'rect')).toBe(0);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('skips a non-finite value instead of emitting NaN coordinates', () => {
+    const markup = renderToStaticMarkup(
+      <BarChart
+        title="Revenue"
+        data={[
+          { label: 'Q1', value: 120 },
+          { label: 'Q2', value: Number.NaN },
+          { label: 'Q3', value: Number.POSITIVE_INFINITY },
+        ]}
+      />,
+    );
+    // only the one finite bar survives
+    expect(count(markup, 'rect')).toBe(1);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('honours a custom value formatter', () => {
+    const markup = renderToStaticMarkup(
+      <BarChart title="Revenue" data={data} formatValue={(v) => `$${v}`} />,
+    );
+    expect(markup).toContain('$340');
+  });
+});
+
+describe('LineChart', () => {
+  const series = [
+    {
+      name: 'Sessions',
+      points: [
+        { label: 'Mon', value: 10 },
+        { label: 'Tue', value: 30 },
+        { label: 'Wed', value: 20 },
+      ],
+    },
+    {
+      name: 'Errors',
+      points: [
+        { label: 'Mon', value: 2 },
+        { label: 'Tue', value: 5 },
+        { label: 'Wed', value: 1 },
+      ],
+    },
+  ];
+
+  it('renders a polyline per series with point markers, fluid + accessible', () => {
+    const markup = renderToStaticMarkup(<LineChart title="Traffic" series={series} />);
+    expect(count(markup, 'polyline')).toBe(2);
+    expect(count(markup, 'circle')).toBe(6);
+    expect(markup).toContain('viewBox="0 0 640 360"');
+    expect(markup).toContain('width="100%"');
+    expect(markup).toContain('role="img"');
+    expect(markup).toContain('aria-label="Traffic:');
+    // two named series => two legend rows
+    expect(count(markup, 'li')).toBe(2);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('breaks the line at a non-finite gap (no NaN, one fewer marker)', () => {
+    const markup = renderToStaticMarkup(
+      <LineChart
+        title="Traffic"
+        series={[
+          {
+            name: 'Sessions',
+            points: [
+              { label: 'Mon', value: 10 },
+              { label: 'Tue', value: Number.NaN },
+              { label: 'Wed', value: 20 },
+            ],
+          },
+        ]}
+      />,
+    );
+    // gap splits the single line into two 1-point segments; markers only for finite points
+    expect(count(markup, 'circle')).toBe(2);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('renders the empty state when no series has a finite point', () => {
+    const markup = renderToStaticMarkup(
+      <LineChart title="Traffic" series={[{ name: 'X', points: [] }]} />,
+    );
+    expect(markup).toContain('aria-label="Traffic: No data"');
+    expect(count(markup, 'polyline')).toBe(0);
+    expect(markup).not.toContain('NaN');
+  });
+});
+
+describe('Sparkline', () => {
+  it('renders a fluid trend polyline with an aria summary', () => {
+    const markup = renderToStaticMarkup(
+      <Sparkline title="Latency" values={[5, 8, 6, 9, 7]} />,
+    );
+    expect(count(markup, 'polyline')).toBe(1);
+    expect(markup).toContain('width="100%"');
+    expect(markup).toContain('viewBox="0 0 100 28"');
+    expect(markup).toContain('role="img"');
+    expect(markup).toContain('aria-label="Latency:');
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('renders an empty state for no finite values', () => {
+    const markup = renderToStaticMarkup(
+      <Sparkline title="Latency" values={[Number.NaN, Number.POSITIVE_INFINITY]} />,
+    );
+    expect(markup).toContain('aria-label="Latency: No data"');
+    expect(count(markup, 'polyline')).toBe(0);
+    expect(markup).not.toContain('NaN');
+  });
+});
+
+describe('DonutChart', () => {
+  const data = [
+    { label: 'Passed', value: 70 },
+    { label: 'Failed', value: 20 },
+    { label: 'Skipped', value: 10 },
+  ];
+
+  it('renders one arc path per positive slice, with legend percentages', () => {
+    const markup = renderToStaticMarkup(<DonutChart title="Results" data={data} />);
+    expect(count(markup, 'path')).toBe(3);
+    expect(markup).toContain('viewBox="0 0 200 200"');
+    expect(markup).toContain('width="100%"');
+    expect(markup).toContain('role="img"');
+    expect(markup).toContain('aria-label="Results:');
+    // legend shows label + value + percent (never color-only)
+    expect(markup).toContain('70%');
+    expect(count(markup, 'li')).toBe(3);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('skips negative / non-finite slices', () => {
+    const markup = renderToStaticMarkup(
+      <DonutChart
+        title="Results"
+        data={[
+          { label: 'Passed', value: 70 },
+          { label: 'Bad', value: -5 },
+          { label: 'Worse', value: Number.NaN },
+        ]}
+      />,
+    );
+    expect(count(markup, 'path')).toBe(1);
+    expect(markup).not.toContain('NaN');
+  });
+
+  it('renders the empty state when every value is zero', () => {
+    const markup = renderToStaticMarkup(
+      <DonutChart title="Results" data={[{ label: 'None', value: 0 }]} />,
+    );
+    expect(markup).toContain('aria-label="Results: No data"');
+    expect(count(markup, 'path')).toBe(0);
+    expect(markup).not.toContain('NaN');
+  });
+});

package/src/ui/charts/donut-chart.tsx

@@ -0,0 +1,111 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// DonutChart — proportional ring, pure SVG (Wave 9.2)
+//
+// Slices are built from finite, non-negative values (a slice needs a magnitude).
+// If no finite positive value remains, an explicit empty state renders instead
+// of a broken ring.
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
+import type { ChartBaseProps, ChartDatum } from './chart-types';
+import { buildAriaSummary, chartColorAt, defaultFormatValue } from './chart-utils';
+
+const SIZE = 200;
+const CX = SIZE / 2;
+const CY = SIZE / 2;
+const R_OUTER = 90;
+const R_INNER = 56;
+const FULL = Math.PI * 2;
+
+export interface DonutChartProps extends ChartBaseProps {
+  /** The slices — one per labelled datum. Negative/non-finite values are skipped. */
+  readonly data: readonly ChartDatum[];
+}
+
+/** Point on a circle at `angle` (radians, 0 = 12 o'clock, clockwise). */
+function polar(radius: number, angle: number): [number, number] {
+  return [CX + radius * Math.sin(angle), CY - radius * Math.cos(angle)];
+}
+
+/** Annulus-segment path from `start` to `end` (radians). */
+function slicePath(start: number, end: number): string {
+  const [ox1, oy1] = polar(R_OUTER, start);
+  const [ox2, oy2] = polar(R_OUTER, end);
+  const [ix2, iy2] = polar(R_INNER, end);
+  const [ix1, iy1] = polar(R_INNER, start);
+  const largeArc = end - start > Math.PI ? 1 : 0;
+  return [
+    `M ${ox1} ${oy1}`,
+    `A ${R_OUTER} ${R_OUTER} 0 ${largeArc} 1 ${ox2} ${oy2}`,
+    `L ${ix2} ${iy2}`,
+    `A ${R_INNER} ${R_INNER} 0 ${largeArc} 0 ${ix1} ${iy1}`,
+    'Z',
+  ].join(' ');
+}
+
+export function DonutChart({
+  data,
+  title,
+  ariaLabel,
+  formatValue,
+  className,
+  emptyLabel = 'No data',
+}: DonutChartProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+  const slices = data.filter((d) => Number.isFinite(d.value) && d.value > 0);
+  const total = slices.reduce((sum, d) => sum + d.value, 0);
+
+  if (slices.length === 0 || total <= 0) {
+    return <ChartEmpty title={title} label={emptyLabel} className={className} />;
+  }
+
+  const legend: ChartLegendItem[] = slices.map((d, i) => ({
+    label: d.label,
+    value: `${format(d.value)} (${Math.round((d.value / total) * 100)}%)`,
+    color: chartColorAt(i, d.color),
+  }));
+
+  const summaryPoints = slices.map((d) => ({ label: d.label, value: d.value }));
+  const summary = ariaLabel ?? buildAriaSummary(title, summaryPoints, format, 'slice');
+
+  let cursor = 0;
+  const arcs = slices.map((d, i) => {
+    const start = cursor;
+    // A lone full-circle slice can't be drawn as a single arc (start===end):
+    // nudge the end just shy of a full turn so the ring still closes visually.
+    const sweep = slices.length === 1 ? FULL - 1e-3 : (d.value / total) * FULL;
+    const end = start + sweep;
+    cursor = end;
+    return { path: slicePath(start, end), color: chartColorAt(i, d.color), key: `${d.label}-${i}` };
+  });
+
+  const plot = (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${SIZE} ${SIZE}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="mx-auto block h-auto w-full max-w-[240px] text-ink-4"
+    >
+      {arcs.map((a) => (
+        <path key={a.key} d={a.path} fill={a.color} stroke="var(--card, transparent)" strokeWidth={1} />
+      ))}
+      <text
+        x={CX}
+        y={CY}
+        textAnchor="middle"
+        dominantBaseline="middle"
+        fontSize={20}
+        fontWeight={600}
+        fill="currentColor"
+        className="text-ink"
+      >
+        {format(total)}
+      </text>
+    </svg>
+  );
+
+  return <ChartFrame plot={plot} legend={legend} className={className} />;
+}

package/src/ui/charts/index.ts

@@ -0,0 +1,27 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Chart primitives (Wave 9.2) — pure-SVG, responsive-by-construction dashboard
+// charts. The kernel ships NO chart library: a strict CSP blocks external
+// scripts/fonts/images, so every chart is inline SVG built from React.
+// ═══════════════════════════════════════════════════════════════════════════
+export type {
+  ChartDatum,
+  ChartLineSeries,
+  ChartValueFormatter,
+  ChartBaseProps,
+} from './chart-types';
+export {
+  CHART_PALETTE,
+  chartColorAt,
+  defaultFormatValue,
+  finitePoints,
+  niceScale,
+  buildAriaSummary,
+  type NiceScale,
+  type NiceScaleOptions,
+  type FiniteDatum,
+} from './chart-utils';
+export { ChartLegend, type ChartLegendItem } from './chart-frame';
+export { BarChart, type BarChartProps } from './bar-chart';
+export { LineChart, type LineChartProps } from './line-chart';
+export { Sparkline, type SparklineProps } from './sparkline';
+export { DonutChart, type DonutChartProps } from './donut-chart';

package/src/ui/charts/line-chart.tsx

@@ -0,0 +1,180 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// LineChart — one or more line series over shared x-labels, pure SVG (Wave 9.2)
+//
+// Non-finite points break the line (a new segment starts after the gap) rather
+// than emitting a NaN coordinate.
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
+import type { ChartBaseProps, ChartLineSeries } from './chart-types';
+import {
+  buildAriaSummary,
+  chartColorAt,
+  defaultFormatValue,
+  niceScale,
+} from './chart-utils';
+
+const VIEW_W = 640;
+const VIEW_H = 360;
+const PAD = { top: 12, right: 12, bottom: 44, left: 48 } as const;
+const PLOT_L = PAD.left;
+const PLOT_R = VIEW_W - PAD.right;
+const PLOT_T = PAD.top;
+const PLOT_B = VIEW_H - PAD.bottom;
+const PLOT_W = PLOT_R - PLOT_L;
+const PLOT_H = PLOT_B - PLOT_T;
+
+export interface LineChartProps extends ChartBaseProps {
+  /** One or more named line series. */
+  readonly series: readonly ChartLineSeries[];
+}
+
+/** Break a series' points into finite segments (a gap ends the current run). */
+function toSegments(
+  points: readonly { value: number }[],
+  xToPx: (i: number) => number,
+  yToPx: (v: number) => number,
+): string[] {
+  const segments: string[] = [];
+  let current: string[] = [];
+  points.forEach((p, i) => {
+    if (Number.isFinite(p.value)) {
+      current.push(`${xToPx(i)},${yToPx(p.value)}`);
+    } else if (current.length > 0) {
+      segments.push(current.join(' '));
+      current = [];
+    }
+  });
+  if (current.length > 0) segments.push(current.join(' '));
+  return segments;
+}
+
+export function LineChart({
+  series,
+  title,
+  ariaLabel,
+  formatValue,
+  className,
+  emptyLabel = 'No data',
+}: LineChartProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+
+  // Every finite value across all series drives the y-domain and the summary.
+  const finiteValues: number[] = [];
+  let maxLen = 0;
+  for (const s of series) {
+    maxLen = Math.max(maxLen, s.points.length);
+    for (const p of s.points) if (Number.isFinite(p.value)) finiteValues.push(p.value);
+  }
+
+  if (finiteValues.length === 0) {
+    return <ChartEmpty title={title} label={emptyLabel} className={className} />;
+  }
+
+  const scale = niceScale(Math.min(...finiteValues), Math.max(...finiteValues), {
+    pinZero: false,
+  });
+  const span = scale.max - scale.min;
+  const yToPx = (v: number): number => PLOT_B - ((v - scale.min) / span) * PLOT_H;
+  const xToPx = (i: number): number =>
+    maxLen <= 1 ? PLOT_L + PLOT_W / 2 : PLOT_L + (i / (maxLen - 1)) * PLOT_W;
+
+  // x labels from the longest series (deterministic pick: first of that length).
+  const xLabelSource = series.find((s) => s.points.length === maxLen)?.points ?? [];
+
+  const legend: ChartLegendItem[] = series.map((s, i) => ({
+    label: s.name,
+    color: chartColorAt(i, s.color),
+  }));
+
+  // Summarize the first series' points (or the union count) for the aria label.
+  const summaryPoints = series.flatMap((s) =>
+    s.points
+      .filter((p) => Number.isFinite(p.value))
+      .map((p) => ({ label: `${s.name} ${p.label}`, value: p.value })),
+  );
+  const summary = ariaLabel ?? buildAriaSummary(title, summaryPoints, format, 'point');
+
+  const plot = (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="block h-auto w-full overflow-visible text-ink-4"
+    >
+      {/* y gridlines + tick labels */}
+      {scale.ticks.map((t) => {
+        const y = yToPx(t);
+        return (
+          <g key={`y-${t}`}>
+            <line
+              x1={PLOT_L}
+              x2={PLOT_R}
+              y1={y}
+              y2={y}
+              stroke="currentColor"
+              strokeOpacity={0.12}
+            />
+            <text
+              x={PLOT_L - 8}
+              y={y}
+              textAnchor="end"
+              dominantBaseline="middle"
+              fontSize={12}
+              fill="currentColor"
+            >
+              {format(t)}
+            </text>
+          </g>
+        );
+      })}
+
+      {/* x labels */}
+      {xLabelSource.map((p, i) => (
+        <text
+          key={`x-${p.label}-${i}`}
+          x={xToPx(i)}
+          y={PLOT_B + 16}
+          textAnchor="middle"
+          fontSize={12}
+          fill="currentColor"
+        >
+          {p.label}
+        </text>
+      ))}
+
+      {/* lines */}
+      {series.map((s, si) => {
+        const color = chartColorAt(si, s.color);
+        const segments = toSegments(s.points, xToPx, yToPx);
+        return (
+          <g key={`line-${s.name}-${si}`}>
+            {segments.map((pts, gi) => (
+              <polyline
+                key={`seg-${gi}`}
+                points={pts}
+                fill="none"
+                stroke={color}
+                strokeWidth={2}
+                strokeLinejoin="round"
+                strokeLinecap="round"
+              />
+            ))}
+            {s.points.map((p, i) =>
+              Number.isFinite(p.value) ? (
+                <circle key={`pt-${i}`} cx={xToPx(i)} cy={yToPx(p.value)} r={2.5} fill={color}>
+                  <title>{`${s.name} — ${p.label}: ${format(p.value)}`}</title>
+                </circle>
+              ) : null,
+            )}
+          </g>
+        );
+      })}
+    </svg>
+  );
+
+  return <ChartFrame plot={plot} legend={legend} className={className} />;
+}

package/src/ui/charts/sparkline.tsx

@@ -0,0 +1,101 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Sparkline — tiny inline trend line, pure SVG, no axes/legend (Wave 9.2)
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { cn } from '../cn';
+
+import type { ChartValueFormatter } from './chart-types';
+import { chartColorAt, defaultFormatValue, niceScale } from './chart-utils';
+
+const VIEW_W = 100;
+const VIEW_H = 28;
+const PAD_Y = 3;
+
+export interface SparklineProps {
+  /** The ordered values. Non-finite entries break the line rather than plotting NaN. */
+  readonly values: readonly number[];
+  /** Title — the spine of the `aria-label` summary. */
+  readonly title: string;
+  readonly ariaLabel?: string;
+  readonly formatValue?: ChartValueFormatter;
+  /** Line color (CSS color / `currentColor` / `var(--…)`). Defaults to the brand palette slot 0. */
+  readonly color?: string;
+  readonly className?: string;
+  readonly emptyLabel?: string;
+}
+
+export function Sparkline({
+  values,
+  title,
+  ariaLabel,
+  formatValue,
+  color,
+  className,
+  emptyLabel = 'No data',
+}: SparklineProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+  const finite = values.filter((v) => Number.isFinite(v));
+
+  if (finite.length === 0) {
+    return (
+      <span
+        role="img"
+        aria-label={`${title}: ${emptyLabel}`}
+        className={cn('inline-block text-body-2 text-ink-4', className)}
+      >
+        {emptyLabel}
+      </span>
+    );
+  }
+
+  const scale = niceScale(Math.min(...finite), Math.max(...finite), { pinZero: false });
+  const span = scale.max - scale.min;
+  const yToPx = (v: number): number =>
+    VIEW_H - PAD_Y - ((v - scale.min) / span) * (VIEW_H - 2 * PAD_Y);
+  const xToPx = (i: number): number =>
+    values.length <= 1 ? VIEW_W / 2 : (i / (values.length - 1)) * VIEW_W;
+
+  // Break into finite segments so a gap never yields a NaN coordinate.
+  const segments: string[] = [];
+  let current: string[] = [];
+  values.forEach((v, i) => {
+    if (Number.isFinite(v)) current.push(`${xToPx(i)},${yToPx(v)}`);
+    else if (current.length > 0) {
+      segments.push(current.join(' '));
+      current = [];
+    }
+  });
+  if (current.length > 0) segments.push(current.join(' '));
+
+  const stroke = chartColorAt(0, color);
+  const first = finite[0];
+  const last = finite[finite.length - 1];
+  const summary =
+    ariaLabel ??
+    `${title}: trend of ${finite.length} points, from ${format(first)} to ${format(last)}.`;
+
+  return (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="none"
+      className={cn('block h-auto w-full overflow-visible', className)}
+    >
+      {segments.map((pts, i) => (
+        <polyline
+          key={`seg-${i}`}
+          points={pts}
+          fill="none"
+          stroke={stroke}
+          strokeWidth={1.5}
+          strokeLinejoin="round"
+          strokeLinecap="round"
+          vectorEffect="non-scaling-stroke"
+        />
+      ))}
+    </svg>
+  );
+}

package/src/ui/hooks/use-is-mobile.ts

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+
+import { MOBILE_BREAKPOINT } from '../breakpoints';
+
+/**
+ * `true` when the viewport is narrower than the shared {@link MOBILE_BREAKPOINT}
+ * (Tailwind's `md`). Server-driven renderers use this to collapse tables to
+ * cards, reflow grids and go single-column WITHOUT the author declaring a
+ * breakpoint — responsiveness is a property of the primitive, not a checklist.
+ *
+ * Reads `window.innerWidth`, so it returns `false` until mounted on the client
+ * (SSR-safe: no layout thrash, no hydration mismatch beyond the first paint).
+ */
+export function useIsMobile(): boolean {
+  const [isMobile, setIsMobile] = useState<boolean | undefined>(undefined);
+
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = (): void => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener('change', onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return !!isMobile;
+}