@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/ui/charts/chart-utils.ts

@@ -1,190 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Chart primitives — deterministic, pure helpers (Wave 9.2)
-//
-// Scale/tick maths, the themeable color palette, value formatting, finite-value
-// filtering and aria-summary construction. Everything here is a pure function:
-// given the same input it returns the same output (no Math.random, no Date.now)
-// so the same data always yields the same SVG.
-// ═══════════════════════════════════════════════════════════════════════════
-import type { ChartDatum, ChartValueFormatter } from './chart-types';
-
-/**
- * Themeable categorical palette. Each slot is a CSS custom property with a
- * graceful fallback: a host that defines `--chart-N` (per theme) wins; slot 0
- * additionally follows the app brand via `--app-primary-color`. The fallbacks
- * are the platform's bold, dark-mode-safe primaries — used only when no token
- * is defined, so a chart is never invisible. Data is NEVER conveyed by color
- * alone: every primitive also renders the label + value.
- */
-export const CHART_PALETTE: readonly string[] = [
-  'var(--app-primary-color, var(--chart-1, #00A4EF))',
-  'var(--chart-2, #7FBA00)',
-  'var(--chart-3, #FFB900)',
-  'var(--chart-4, #F25022)',
-  'var(--chart-5, #8B5CF6)',
-  'var(--chart-6, #EC4899)',
-  'var(--chart-7, #06B6D4)',
-  'var(--chart-8, #F59E0B)',
-];
-
-/** Resolve the color for the datum at `index`: explicit override wins, else palette (wraps). */
-export function chartColorAt(index: number, override?: string): string {
-  if (override !== undefined && override.length > 0) {
-    return override;
-  }
-  const size = CHART_PALETTE.length;
-  // `index % size` alone is NOT a wrap: JS `%` keeps the sign, so a negative
-  // index lands on a negative slot and reads back `undefined` — which used to
-  // be returned as a `string` and rendered as a missing `fill`/`stroke`. Wrap
-  // forward instead. A non-finite index yields a NaN slot and falls through to
-  // the throw rather than silently painting the wrong series color.
-  const slot = ((Math.trunc(index) % size) + size) % size;
-  const color = CHART_PALETTE[slot];
-  if (color === undefined) {
-    throw new Error(
-      `chartColorAt: no palette color for index ${index} (resolved slot ${slot} of ${size}).`,
-    );
-  }
-  return color;
-}
-
-/**
- * Deterministic default value formatter. Integers render bare; fractions get a
- * fixed 2 decimals (with trailing zeros trimmed). Locale-free on purpose so the
- * SVG is byte-identical across machines/locales.
- */
-export function defaultFormatValue(value: number): string {
-  if (!Number.isFinite(value)) {
-    return '—';
-  }
-  if (Number.isInteger(value)) {
-    return String(value);
-  }
-  return String(Number(value.toFixed(2)));
-}
-
-/** A datum whose value is a finite number (post-filter). */
-export interface FiniteDatum {
-  readonly label: string;
-  readonly value: number;
-  readonly color?: string;
-}
-
-/** Keep only points with a finite numeric value — NaN/±Infinity are dropped, never plotted. */
-export function finitePoints(points: readonly ChartDatum[]): FiniteDatum[] {
-  const out: FiniteDatum[] = [];
-  for (const p of points) {
-    if (Number.isFinite(p.value)) {
-      out.push({ label: p.label, value: p.value, color: p.color });
-    }
-  }
-  return out;
-}
-
-// ── nice-number axis scale (deterministic) ──────────────────────────────────
-
-function niceNum(range: number, round: boolean): number {
-  const exponent = Math.floor(Math.log10(range));
-  const pow = Math.pow(10, exponent);
-  const fraction = range / pow;
-  let niceFraction: number;
-  if (round) {
-    if (fraction < 1.5) {
-      niceFraction = 1;
-    } else if (fraction < 3) {
-      niceFraction = 2;
-    } else if (fraction < 7) {
-      niceFraction = 5;
-    } else {
-      niceFraction = 10;
-    }
-  } else {
-    if (fraction <= 1) {
-      niceFraction = 1;
-    } else if (fraction <= 2) {
-      niceFraction = 2;
-    } else if (fraction <= 5) {
-      niceFraction = 5;
-    } else {
-      niceFraction = 10;
-    }
-  }
-  return niceFraction * pow;
-}
-
-/** Trim binary-float dust so ticks like 0.30000000000000004 read as 0.3. */
-function tidy(value: number): number {
-  return Number(value.toPrecision(12));
-}
-
-export interface NiceScale {
-  readonly min: number;
-  readonly max: number;
-  readonly ticks: readonly number[];
-}
-
-export interface NiceScaleOptions {
-  /**
-   * Pin the baseline at 0 so heights are proportional (bars, donuts). When
-   * `false` the domain hugs the data — better for line charts over a narrow
-   * band. Defaults to `true`.
-   */
-  readonly pinZero?: boolean;
-  readonly maxTicks?: number;
-}
-
-/**
- * Compute a "nice" axis domain + evenly-spaced ticks for `[dataMin, dataMax]`.
- * With `pinZero` (default) the baseline is pinned at 0 so bar heights are
- * proportional and negatives read below the axis. Fully deterministic; guards
- * the degenerate all-equal / all-zero case instead of producing NaN.
- */
-export function niceScale(
-  dataMin: number,
-  dataMax: number,
-  options: NiceScaleOptions = {},
-): NiceScale {
-  const pinZero = options.pinZero ?? true;
-  const maxTicks = options.maxTicks ?? 5;
-  const lo = pinZero ? Math.min(0, dataMin) : dataMin;
-  let hi = pinZero ? Math.max(0, dataMax) : dataMax;
-  if (lo === hi) {
-    // Flat series (e.g. all equal): open a unit window so we never divide by 0.
-    hi = lo + 1;
-  }
-  const ticks: number[] = [];
-  const range = niceNum(hi - lo, false);
-  const step = niceNum(range / Math.max(1, maxTicks - 1), true);
-  const niceMin = Math.floor(lo / step) * step;
-  const niceMax = Math.ceil(hi / step) * step;
-  for (let v = niceMin; v <= niceMax + step * 0.5; v += step) {
-    ticks.push(tidy(v));
-  }
-  return { min: tidy(niceMin), max: tidy(niceMax), ticks };
-}
-
-// ── aria summary ────────────────────────────────────────────────────────────
-
-/**
- * Build a concise, deterministic aria-label summary from a title and the
- * finite points. Keeps it readable: title, count, then up to `maxItems`
- * "label value" pairs (with an ellipsis when truncated). Color is never the
- * carrier of meaning — this text is.
- */
-export function buildAriaSummary(
-  title: string,
-  points: readonly FiniteDatum[],
-  format: ChartValueFormatter,
-  noun: string,
-  maxItems = 8,
-): string {
-  if (points.length === 0) {
-    return `${title}: no data.`;
-  }
-  const shown = points.slice(0, maxItems);
-  const pairs = shown.map((p) => `${p.label} ${format(p.value)}`).join(', ');
-  const suffix =
-    points.length > maxItems ? `, and ${points.length - maxItems} more` : '';
-  const count = points.length === 1 ? `1 ${noun}` : `${points.length} ${noun}s`;
-  return `${title}: ${count}. ${pairs}${suffix}.`;
-}

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

@@ -1,204 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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

@@ -1,129 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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 { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
-import {
-  buildAriaSummary,
-  chartColorAt,
-  defaultFormatValue,
-} from './chart-utils';
-
-import type { ChartBaseProps, ChartDatum } from './chart-types';
-import type { ReactNode } from 'react';
-
-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

@@ -1,27 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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';