@heyramzi/ui 2.24.0 → 3.0.0

package/src/charts/bar-chart.svelte.d.ts

@@ -0,0 +1,64 @@
+import "./chart-tokens.css";
+import "./bar-chart.css";
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: {
+        data: TData[];
+        xKey: keyof TData & string;
+        /** The bar's value. Required unless `series` is set. */
+        yKey?: keyof TData & string;
+        /** Stacks these keys into one bar per row; the bar's value is their sum. */
+        series?: {
+            key: keyof TData & string;
+            label: string;
+            color: string;
+        }[];
+        color?: string;
+        /** A fill per bar, for bands whose meaning changes along the axis. */
+        colorOf?: (d: TData) => string;
+        /** Body height in px, or "fill" to grow to the parent's height (parent must
+         * be a flex column that gives the chart a determinate height). Default 240. */
+        height?: number | "fill";
+        orientation?: "vertical" | "horizontal";
+        /** Left padding for horizontal charts (label space). Default 80. */
+        leftPadding?: number;
+        formatValue?: (v: number) => string;
+        formatX?: (v: unknown) => string;
+        /** Axis tick label. Return "" to skip a tick. Defaults to formatX. */
+        formatTick?: (v: unknown) => string;
+        /** The chart's accessible name and the hidden data table's caption. */
+        label?: string;
+        /** Column header for the x values in the hidden table. Defaults to xKey. */
+        xLabel?: string;
+        /** Column header for the y values in the sr-only table, and the tooltip's label. */
+        yLabel?: string;
+        /** Extra tooltip rows under the value, for a second measure of the same row. */
+        details?: (d: TData) => {
+            label: string;
+            value: string;
+        }[];
+        /** Show the value/label figure above the chart. */
+        showFigure?: boolean;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData extends Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<TData extends Record<string, unknown>> = InstanceType<typeof $$Component<TData>>;
+export default $$Component;

package/src/charts/chart-a11y.css

@@ -0,0 +1,23 @@
+@layer theme, base, components, utilities;
+
+/* Plain stylesheet (see area-chart.css for why). The charts can't lean on the host's Tailwind
+   for the hidden text a screen reader hears. */
+
+@layer components {
+  .hr-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* The kit's focus ring is a box shadow, so it follows this radius. */
+  .hr-chart-plot:focus-visible {
+    border-radius: 0.375rem;
+  }
+}

package/src/charts/chart-a11y.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vite-plus/test";
+import { chartTable, nextPoint, rowSummary } from "./chart-a11y.js";
+
+type Row = { month: string; revenue: number | null; cost: number };
+const rows: Row[] = [
+  { month: "Jan", revenue: null, cost: 1800 },
+  { month: "Feb", revenue: 4100, cost: 2100 },
+  { month: "Mar", revenue: 3800, cost: 2400 },
+  { month: "Apr", revenue: 5300, cost: 1500 },
+];
+const money = (v: number) => `$${v.toLocaleString("en")}`;
+const table = chartTable(
+  rows,
+  (d) => d.month,
+  [
+    { label: "Revenue", value: (d) => d.revenue },
+    { label: "Cost", value: (d) => d.cost },
+  ],
+  money,
+  { xLabel: "Month" },
+);
+
+describe("chartTable", () => {
+  it("summarises the range and each series' first, last, low and high, skipping gaps", () => {
+    expect(table.summary).toBe(
+      "Jan to Apr. Revenue: first $4,100, last $5,300, low $3,800, high $5,300. " +
+        "Cost: first $1,800, last $1,500, low $1,500, high $2,400.",
+    );
+  });
+
+  it("writes a missing value as No data in the table and the spoken row", () => {
+    expect(table.rows[0]).toEqual({ x: "Jan", cells: ["No data", "$1,800"] });
+    expect(rowSummary(table, 0)).toBe("Jan: Revenue No data, Cost $1,800");
+  });
+
+  it("says No data when there are no rows", () => {
+    expect(chartTable([], String, [], money).summary).toBe("No data.");
+  });
+});
+
+describe("nextPoint", () => {
+  it("starts at the first point on Right and the last on Left", () => {
+    expect(nextPoint("ArrowRight", -1, 4)).toBe(0);
+    expect(nextPoint("ArrowLeft", -1, 4)).toBe(3);
+  });
+
+  it("stops at the ends instead of wrapping", () => {
+    expect(nextPoint("ArrowRight", 3, 4)).toBe(3);
+    expect(nextPoint("ArrowUp", 0, 4)).toBe(0);
+  });
+
+  it("jumps with Home and End, clears with Escape, and leaves other keys alone", () => {
+    expect(nextPoint("Home", 2, 4)).toBe(0);
+    expect(nextPoint("End", 0, 4)).toBe(3);
+    expect(nextPoint("Escape", 2, 4)).toBeNull();
+    expect(nextPoint("Escape", -1, 4)).toBeUndefined();
+    expect(nextPoint("Tab", 1, 4)).toBeUndefined();
+  });
+});

package/src/charts/chart-a11y.ts

@@ -0,0 +1,92 @@
+/** What a screen reader gets from a chart: the hidden table's rows and a one-line summary of them. */
+export type ChartTable = {
+  xLabel: string;
+  columns: string[];
+  rows: { x: string; cells: string[] }[];
+  summary: string;
+};
+
+/** One series. `format` overrides the chart's formatter for this column. */
+type Column<T> = { label: string; value: (d: T) => unknown; format?: (v: number) => string };
+
+/** Builds the table and summary every cartesian chart hands to ChartPlot. A missing value reads `empty`. */
+export function chartTable<T>(
+  data: T[],
+  x: (d: T) => string,
+  series: Column<T>[],
+  format: (v: number) => string,
+  { xLabel = "", empty = "No data" }: { xLabel?: string; empty?: string } = {},
+): ChartTable {
+  const xs = data.map(x);
+  const rows = data.map((d, i) => ({
+    x: xs[i],
+    cells: series.map((s) => {
+      const n = numeric(s.value(d));
+      return n == null ? empty : (s.format ?? format)(n);
+    }),
+  }));
+  const lines = series.map((s) =>
+    seriesLine(
+      s.label,
+      data.map((d) => numeric(s.value(d))),
+      s.format ?? format,
+    ),
+  );
+  const range = xs.length === 0 ? "No data" : xs.length === 1 ? xs[0] : `${xs[0]} to ${xs.at(-1)}`;
+  return {
+    xLabel,
+    columns: series.map((s) => s.label),
+    rows,
+    summary: xs.length === 0 ? "No data." : [`${range}.`, ...lines].join(" "),
+  };
+}
+
+function numeric(v: unknown): number | null {
+  if (v == null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function seriesLine(label: string, values: (number | null)[], format: (v: number) => string) {
+  const nums = values.filter((n): n is number => n != null);
+  if (nums.length === 0) return `${label}: no data.`;
+  let low = nums[0];
+  let high = nums[0];
+  for (const n of nums) {
+    if (n < low) low = n;
+    if (n > high) high = n;
+  }
+  const ends = `first ${format(nums[0])}, last ${format(nums[nums.length - 1])}`;
+  return `${label}: ${ends}, low ${format(low)}, high ${format(high)}.`;
+}
+
+/** What one row reads as when the arrow keys land on it, like "Mar: Revenue $4,100, Cost $2,100". */
+export function rowSummary(table: ChartTable, i: number): string {
+  const row = table.rows[i];
+  if (!row) return "";
+  return `${row.x}: ${table.columns.map((c, j) => `${c} ${row.cells[j]}`).join(", ")}`;
+}
+
+/**
+ * The point a key moves to from `at`, where -1 is none yet. `undefined` means the key isn't the
+ * plot's, and `null` means Escape cleared the point.
+ */
+export function nextPoint(key: string, at: number, count: number): number | null | undefined {
+  if (count === 0) return undefined;
+  switch (key) {
+    case "ArrowRight":
+    case "ArrowDown":
+      return at < 0 ? 0 : Math.min(at + 1, count - 1);
+    case "ArrowLeft":
+    case "ArrowUp":
+      return at < 0 ? count - 1 : Math.max(at - 1, 0);
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    case "Escape":
+      return at < 0 ? undefined : null;
+    default:
+      return undefined;
+  }
+}

package/src/charts/chart-plot.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./chart-a11y.css";
+	import type { Snippet } from "svelte";
+	import { cn } from "../lib/utils.js";
+	import { nextPoint, rowSummary, type ChartTable } from "./chart-a11y.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		/** The plot's accessible name and the hidden table's caption. */
+		label: string;
+		/** From chartTable(): the summary read after the name, and one row per point. */
+		table: ChartTable;
+		/** Shows point `i`'s tooltip, or clears it on `null`. */
+		onStep?: (i: number | null) => void;
+		/** Any CSS length. */
+		height?: string | null;
+		class?: string;
+		children: Snippet;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let { label, table, onStep, height, class: className, children }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const uid = $props.id();
+	let at = $state(-1);
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function onkeydown(e: KeyboardEvent) {
+		const next = nextPoint(e.key, at, count);
+		if (next === undefined) return;
+		e.preventDefault();
+		at = next ?? -1;
+		onStep?.(next);
+	}
+
+	function onfocusout() {
+		if (at < 0) return;
+		at = -1;
+		onStep?.(null);
+	}
+
+	// =========================
+	// DERIVED
+	// =========================
+	const count = $derived(onStep ? table.rows.length : 0);
+	const shown = $derived(table.rows.length > 0);
+	const announce = $derived(at >= 0 ? rowSummary(table, at) : "");
+</script>
+
+<!-- =========================== -->
+<!-- CHART PLOT -->
+<!-- =========================== -->
+<!-- WHY application: a screen reader in browse mode keeps the arrow keys for itself on an img. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+	class={cn("hr-chart-plot", className)}
+	style:height
+	role={shown ? (count > 0 ? "application" : "img") : undefined}
+	aria-roledescription={count > 0 ? "chart" : undefined}
+	aria-label={shown ? label : undefined}
+	aria-describedby={shown ? `${uid}-summary` : undefined}
+	tabindex={count > 0 ? 0 : undefined}
+	{onkeydown}
+	{onfocusout}
+>
+	{@render children()}
+</div>
+{#if shown}
+	<p id="{uid}-summary" class="hr-sr-only">{table.summary}</p>
+	{#if count > 0}
+		<p class="hr-sr-only" aria-live="polite">{announce}</p>
+	{/if}
+	<table class="hr-sr-only">
+		<caption>{label}</caption>
+		<thead>
+			<tr>
+				<th scope="col">{table.xLabel}</th>
+				{#each table.columns as column, j (j)}
+					<th scope="col">{column}</th>
+				{/each}
+			</tr>
+		</thead>
+		<tbody>
+			{#each table.rows as row, i (i)}
+				<tr>
+					<th scope="row">{row.x}</th>
+					{#each row.cells as cell, j (j)}
+						<td>{cell}</td>
+					{/each}
+				</tr>
+			{/each}
+		</tbody>
+	</table>
+{/if}

package/src/charts/chart-plot.svelte.d.ts

@@ -0,0 +1,18 @@
+import "./chart-a11y.css";
+import type { Snippet } from "svelte";
+import { type ChartTable } from "./chart-a11y.js";
+interface Props {
+    /** The plot's accessible name and the hidden table's caption. */
+    label: string;
+    /** From chartTable(): the summary read after the name, and one row per point. */
+    table: ChartTable;
+    /** Shows point `i`'s tooltip, or clears it on `null`. */
+    onStep?: (i: number | null) => void;
+    /** Any CSS length. */
+    height?: string | null;
+    class?: string;
+    children: Snippet;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/chart-tokens.css

@@ -1,55 +1,56 @@
+@layer theme, base, components, utilities;
+
 /* Each chart imports these beside its own stylesheet, so a deep import such as
    `@heyramzi/ui/charts/dashboard` keeps its card edge without the barrel. */
 
-/* Shared chart tokens, held at zero specificity by `:where()`. The reveal pair
-   is the entrance every chart shares; motion.ts mirrors its duration. */
-:where(
-  .hr-area-chart,
-  .hr-bar-chart,
-  .hr-line-chart,
-  .hr-sparkline,
-  .hr-number-chart,
-  .hr-stat-card,
-  .hr-legend,
-  .hr-ts-chart,
-  .hr-donut-chart,
-  .hr-ring,
-  .hr-gauge
-) {
-  /* The categorical series palette. The brand leads, then hues spaced round the
-     wheel so neighbours never share a family (blue and orange first, the pair that
-     survives colour blindness). Each hue is a cat token pulled 15% toward the text
-     colour: darker on a light card, lighter on a dark one, so every series clears
-     3:1 against the card in both themes (lowest: teal, 3.6:1 light, 6.2:1 dark). */
-  --chart-series-1: var(--color-brand, oklch(0.28 0 0));
-  --chart-series-2: color-mix(in oklab, var(--color-cat-blue) 85%, var(--color-foreground));
-  --chart-series-3: color-mix(in oklab, var(--color-cat-orange) 85%, var(--color-foreground));
-  --chart-series-4: color-mix(in oklab, var(--color-cat-green) 85%, var(--color-foreground));
-  --chart-series-5: color-mix(in oklab, var(--color-cat-pink) 85%, var(--color-foreground));
-  --chart-series-6: color-mix(in oklab, var(--color-cat-teal) 85%, var(--color-foreground));
-  /* The palette's `--chart-N` names point here inside a chart, so a series passed as
-     `var(--chart-3)` gets a hue, not the brand's grey highlight. */
-  --chart-1: var(--chart-series-1);
-  --chart-2: var(--chart-series-2);
-  --chart-3: var(--chart-series-3);
-  --chart-4: var(--chart-series-4);
-  --chart-5: var(--chart-series-5);
-  --chart-6: var(--chart-series-6);
-  --chart-label: var(--muted-foreground, oklch(0.5 0.01 286));
-  --chart-grid: color-mix(in srgb, var(--border, oklch(0.5 0.01 286)) 50%, transparent);
-  --chart-ease-out: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
-  --chart-motion-fast: var(--duration-quick, 150ms);
-  --chart-motion: var(--duration-fast, 250ms);
-  --chart-motion-slow: 800ms;
-  --chart-motion-reveal: 1100ms;
-  --chart-ease-reveal: cubic-bezier(0.85, 0, 0.15, 1);
-  --chart-stagger: 30ms;
-  --chart-crosshair: color-mix(
-    in srgb,
-    var(--muted-foreground, oklch(0.5 0.01 286)) 60%,
-    transparent
-  );
-  /* The card step draws its own hairline, so a chart card carries no border of its own. */
-  --chart-card-shadow: var(--elev-card);
-  --chart-card-shadow-hover: var(--elev-card-hover);
+@layer components {
+  /* Shared chart tokens, held at zero specificity by `:where()`. The reveal pair
+     is the entrance every chart shares; motion.ts mirrors its duration. */
+  :where(
+    .hr-area-chart,
+    .hr-bar-chart,
+    .hr-line-chart,
+    .hr-sparkline,
+    .hr-number-chart,
+    .hr-stat-card,
+    .hr-legend,
+    .hr-ts-chart,
+    .hr-donut-chart,
+    .hr-ring,
+    .hr-gauge
+  ) {
+    /* Series palette: brand, then hues round the wheel, blue and orange first for colour
+       blindness. Each is pulled 15% toward the text, clearing 3:1 on the card in both themes. */
+    --chart-series-1: var(--color-brand, oklch(0.28 0 0));
+    --chart-series-2: color-mix(in oklab, var(--color-cat-blue) 85%, var(--color-foreground));
+    --chart-series-3: color-mix(in oklab, var(--color-cat-orange) 85%, var(--color-foreground));
+    --chart-series-4: color-mix(in oklab, var(--color-cat-green) 85%, var(--color-foreground));
+    --chart-series-5: color-mix(in oklab, var(--color-cat-pink) 85%, var(--color-foreground));
+    --chart-series-6: color-mix(in oklab, var(--color-cat-teal) 85%, var(--color-foreground));
+    /* The palette's `--chart-N` names point here inside a chart, so a series passed as
+       `var(--chart-3)` gets a hue, not the brand's grey highlight. */
+    --chart-1: var(--chart-series-1);
+    --chart-2: var(--chart-series-2);
+    --chart-3: var(--chart-series-3);
+    --chart-4: var(--chart-series-4);
+    --chart-5: var(--chart-series-5);
+    --chart-6: var(--chart-series-6);
+    --chart-label: var(--muted-foreground, oklch(0.5 0.01 286));
+    --chart-grid: color-mix(in srgb, var(--border, oklch(0.5 0.01 286)) 50%, transparent);
+    --chart-ease-out: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+    --chart-motion-fast: var(--duration-quick, 150ms);
+    --chart-motion: var(--duration-fast, 250ms);
+    --chart-motion-slow: 800ms;
+    --chart-motion-reveal: 1100ms;
+    --chart-ease-reveal: cubic-bezier(0.85, 0, 0.15, 1);
+    --chart-stagger: 30ms;
+    --chart-crosshair: color-mix(
+      in srgb,
+      var(--muted-foreground, oklch(0.5 0.01 286)) 60%,
+      transparent
+    );
+    /* The card step draws its own hairline, so a chart card carries no border of its own. */
+    --chart-card-shadow: var(--elev-card);
+    --chart-card-shadow-hover: var(--elev-card-hover);
+  }
 }