@heyramzi/ui 2.23.0 → 3.0.0

package/src/charts/README.md

@@ -1,6 +1,6 @@
 # @heyramzi/ui/charts
 
-Svelte 5 charts on [LayerChart](https://layerchart.com): area, line, bar, donut, ring, gauge, sparkline, time series and stat cards. One set of tokens, a crosshair tooltip, a screen reader data table on the bar chart, and an entrance sweep that respects `prefers-reduced-motion`.
+Svelte 5 charts on [LayerChart](https://layerchart.com): area, line, bar, donut, ring, gauge, sparkline, time series and stat cards. One set of tokens, a crosshair tooltip the arrow keys can step through, a named plot with a spoken summary and a hidden data table on every cartesian chart, and an entrance sweep that respects `prefers-reduced-motion`.
 
 Live demos: [ui.heyramzi.com/charts](https://ui.heyramzi.com/charts).
 
@@ -71,8 +71,8 @@ The `@source` line matters: the chart markup carries Tailwind classes, and Tailw
 | --- | --- |
 | `DashboardSection`, `PanelGrid`, `StatBand` | A named area, a row of panels side by side, a row of number cards |
 | `StatTile` | A number card on `NumberChart`: a delta, a share track, a trend shape behind the figure, an optional link |
-| `DataPanel`, `DashboardEmpty` | A titled panel for a table or chart, and the dashed empty state |
-| `DataTable`, `DataSortHead`, `RatingChip` | The one data table: sortable heads, a row that opens, columns that hide on a phone, share bars, loading and empty states. An A to E grade chip |
+| `DetailPanel` (from `@heyramzi/ui/components/list-page`) | A titled panel for a table or chart. The dashed empty state is `EmptyState surface="dashed"` from the same path |
+| `DataTable`, `RatingChip` | The one data table: sortable heads (bind `sort`, the `SortState` TableView takes; a new column starts descending), a row that opens, columns that hide on a phone, share bars, loading and empty states. An A to E grade chip |
 | `PeriodFilter`, `DAY_WINDOWS` | The 7, 30 and 90 day window, as a filter or as links |
 | `CHART_HEIGHT`, `dataTableClass` and friends | The one chart height and the table skin |
 

package/src/charts/animated-value.css

@@ -1,7 +1,11 @@
+@layer theme, base, components, utilities;
+
 /* Styles for AnimatedValue. Plain stylesheet (see area-chart.css for why).
    `.hr-animated-value` is the component's own namespaced fallback for tabular
    figures (it also carries the `tabular-nums` utility class). */
 
-.hr-animated-value {
-  font-variant-numeric: tabular-nums;
+@layer components {
+  .hr-animated-value {
+    font-variant-numeric: tabular-nums;
+  }
 }

package/src/charts/animated-value.svelte.d.ts

@@ -0,0 +1,24 @@
+import "./animated-value.css";
+interface Props {
+    /** Target number. The display counts up to it on mount and tweens on change. */
+    value: number;
+    /** Fixed decimal places when no `formatOptions` is given. */
+    decimals?: number;
+    /** Count-up duration in ms. */
+    duration?: number;
+    /** Custom formatter for the live number. Wins over `formatOptions`/`decimals`. */
+    format?: (value: number) => string;
+    /** Intl number formatting (currency, compact, percent, ...). Wins over `decimals`. */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** BCP-47 locale for `formatOptions`. */
+    locale?: string;
+    /** Rendered before the number. */
+    prefix?: string;
+    /** Rendered after the number. */
+    suffix?: string;
+    class?: string;
+    style?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/area-chart.css

@@ -1,26 +1,32 @@
+@layer theme, base, components, utilities;
+
 /* A plain stylesheet, not a `<style>` block, because Tailwind v4's Vite plugin mis-parses that
    virtual module when this package is consumed from node_modules (tailwindcss#20000). */
 
-.hr-area-chart {
-  width: 100%;
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-.hr-area-chart .hr-chart-body {
-  width: 100%;
-}
+@layer components {
+  .hr-area-chart {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
 
-.hr-area-chart .empty {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100%;
-  border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
-  border-radius: 0.5rem;
-}
-.hr-area-chart .empty p {
-  font-size: 0.8125rem;
-  color: var(--chart-label, oklch(0.5 0.01 286));
-  margin: 0;
+  .hr-area-chart .hr-chart-body {
+    width: 100%;
+  }
+
+  .hr-area-chart .empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
+    border-radius: 0.5rem;
+  }
+
+  .hr-area-chart .empty p {
+    font-size: 0.8125rem;
+    color: var(--chart-label, oklch(0.5 0.01 286));
+    margin: 0;
+  }
 }

package/src/charts/area-chart.svelte

@@ -4,14 +4,27 @@
 	// =========================
 	import "./chart-tokens.css";
 	import "./area-chart.css";
-	import { Area, Axis, Chart, Highlight, LinearGradient, Spline, Svg, Tooltip } from "layerchart";
+	import {
+		Area,
+		Axis,
+		Chart,
+		Highlight,
+		LinearGradient,
+		Spline,
+		Svg,
+		Tooltip,
+		type ChartState,
+	} from "layerchart";
 	import { curveMonotoneX } from "d3-shape";
+	import { chartTable } from "./chart-a11y.js";
+	import ChartPlot from "./chart-plot.svelte";
 	import Crosshair from "./crosshair.svelte";
 	import EdgeFade from "./edge-fade.svelte";
 	import { resolveEdgeFade } from "./edge-fade.js";
 	import Figure from "./figure.svelte";
 	import HoverFocus from "./hover-focus.svelte";
 	import { DOMAIN_MOTION, TOOLTIP_GAP, TOOLTIP_TOP } from "./motion.js";
+	import { valueTick } from "./primitives/chart-utils.js";
 	import Reveal from "./reveal.svelte";
 	import ReferenceLine, { type ChartReference } from "./reference-line.svelte";
 	import {
@@ -59,6 +72,8 @@
 		resting?: { value: number; label: string };
 		/** Smooths the drawn line by the window shown; the resting figure stays the caller's total. */
 		smoothing?: Smoothing;
+		/** The chart's accessible name. Its data range and values are read after it. */
+		label?: string;
 		class?: string;
 	}
 
@@ -81,6 +96,7 @@
 		reference,
 		resting,
 		smoothing,
+		label = "Area chart",
 		class: className,
 	}: Props = $props();
 
@@ -88,6 +104,7 @@
 	// STATE
 	// =========================
 	let active = $state<TData | null>(null);
+	let context = $state<ChartState<TData>>();
 
 	// ========================= FUNCTIONS ========================= WHY: called from the tooltip header's value expression so it re-runs on every active-point change; an unread {@const} side effect only evaluates once.
 
@@ -110,6 +127,15 @@
 		return value == null ? NO_DATA : formatValue(Number(value));
 	}
 
+	function step(i: number | null) {
+		if (i === null) {
+			context?.tooltip.hide();
+			active = null;
+			return;
+		}
+		context?.tooltip.show({ data: data[i] });
+	}
+
 	// =========================
 	// DERIVED
 	// =========================
@@ -153,15 +179,7 @@
 	const fallback = $derived(data.length > 0 ? data[data.length - 1] : null);
 	const display = $derived(active ?? fallback);
 
-	// A long tick label ("1,000,000") falls back to "1M" so the left gutter holds it.
-	const compact = new Intl.NumberFormat(undefined, {
-		notation: "compact",
-		maximumFractionDigits: 1,
-	});
-	function valueTick(v: number): string {
-		const full = formatValue(v);
-		return full.length > 6 && Number.isFinite(v) ? compact.format(v) : full;
-	}
+	const tick = $derived(valueTick(formatValue));
 	const figureRows = $derived(
 		display
 			? series.map((s) => ({
@@ -171,17 +189,23 @@
 				}))
 			: null,
 	);
+	const table = $derived(
+		chartTable(
+			data,
+			pointLabel,
+			series.map((s) => ({ label: averageLabel ?? s.label, value: (d: TData) => d[s.key] })),
+			formatValue,
+			{ xLabel: xKey, empty: NO_DATA },
+		),
+	);
 </script>
 
 <!-- =========================== -->
 <!-- AREA CHART -->
 <!-- =========================== -->
-<div
-	class="hr-area-chart {className ?? ''}"
-	role="img"
-	aria-label="Area chart"
-	onpointerleave={() => (active = null)}
->
+<!-- WHY: leaving only resets the hover readout; the keyboard path is ChartPlot's. -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="hr-area-chart {className ?? ''}" onpointerleave={() => (active = null)}>
 	{#if resting && !active && series[0]}
 		<Figure
 			series={[{ value: resting.value, label: series[0].label, color: series[0].color }]}
@@ -197,7 +221,7 @@
 		<Figure value="—" eyebrow="Latest" size="md" />
 	{/if}
 
-	<div class="hr-chart-body" style:height="{height}px">
+	<ChartPlot class="hr-chart-body" height="{height}px" {label} {table} onStep={step}>
 		{#if data.length === 0}
 			<div class="empty"><p>No data</p></div>
 		{:else}
@@ -210,9 +234,10 @@
 				padding={{ left: 48, bottom: 28, top: 8, right: 12 }}
 				tooltipContext={{ mode: "quadtree-x" }}
 				motion={DOMAIN_MOTION}
+				bind:context
 			>
-				<Svg>
-					<Axis placement="left" format={(v) => valueTick(Number(v))} ticks={4} />
+				<Svg aria-hidden="true">
+					<Axis placement="left" format={(v) => tick(Number(v))} ticks={4} />
 					<Axis placement="bottom" format={(v) => formatX(v)} ticks={ticksForWidth(xTicks)} />
 					<g class="hr-area-grid">
 						<Axis placement="left" grid rule={false} ticks={4} format={() => ""} />
@@ -264,5 +289,5 @@
 				</Tooltip.Root>
 			</Chart>
 		{/if}
-	</div>
+	</ChartPlot>
 </div>

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

@@ -0,0 +1,60 @@
+import "./chart-tokens.css";
+import "./area-chart.css";
+import { type ChartReference } from "./reference-line.svelte";
+import { type Smoothing } from "./smoothing.js";
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: {
+        data: TData[];
+        xKey: keyof TData & string;
+        yKey?: keyof TData & string;
+        series?: {
+            key: keyof TData & string;
+            label?: string;
+            color?: string;
+        }[];
+        color?: string;
+        height?: number;
+        stacked?: boolean;
+        smooth?: boolean;
+        /**
+         * Softens the left and right ends of the filled area instead of cutting them off at the plot edge.
+         */
+        edgeFade?: boolean | number;
+        formatValue?: (v: number) => string;
+        formatX?: (v: unknown) => string;
+        xTicks?: number;
+        /** A target drawn across the plot, like the deal a cost runs up to. */
+        reference?: ChartReference;
+        /** The headline while no point is hovered, like a period total. Defaults to the last point. */
+        resting?: {
+            value: number;
+            label: string;
+        };
+        /** Smooths the drawn line by the window shown; the resting figure stays the caller's total. */
+        smoothing?: Smoothing;
+        /** The chart's accessible name. Its data range and values are read after it. */
+        label?: string;
+        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/bar-chart.css

@@ -1,119 +1,129 @@
+@layer theme, base, components, utilities;
+
 /* Styles for BarChart. Plain stylesheet (see area-chart.css for why). Selectors
    are namespaced under `.hr-bar-chart`. */
 
-/* WHY: self-contained visually-hidden styling so the data table reaches
-   screen readers without depending on the consumer's CSS framework. */
-.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;
-}
-.hr-bar-chart {
-  width: 100%;
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-.hr-bar-chart .hr-chart-body {
-  width: 100%;
-}
+@layer components {
+  .hr-bar-chart {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
 
-/* height="fill" grows the chart to its parent's height, so the parent must be a
-   flex column with a determinate height. */
-.hr-bar-chart.hr-bar-fill {
-  flex: 1 1 auto;
-  min-height: 0;
-}
-.hr-bar-chart.hr-bar-fill .hr-chart-body {
-  flex: 1 1 auto;
-  min-height: 0;
-}
+  .hr-bar-chart .hr-chart-body {
+    width: 100%;
+  }
 
-.hr-bar-chart .empty {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100%;
-  border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
-  border-radius: 0.5rem;
-}
-.hr-bar-chart .empty p {
-  font-size: 0.8125rem;
-  color: var(--chart-label, oklch(0.5 0.01 286));
-  margin: 0;
-}
+  /* height="fill" grows the chart to its parent's height, so the parent must be a
+     flex column with a determinate height. */
+  .hr-bar-chart.hr-bar-fill {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
 
-/* WHY: Bars render as <path> elements, not <rect>. Selectors target the path's class directly. */
-.hr-bar-chart .hr-bar-bars {
-  transform-box: fill-box;
-  transform-origin: bottom;
-  animation: hr-bar-grow var(--chart-motion-reveal, 1100ms)
-    var(--chart-ease-reveal, cubic-bezier(0.85, 0, 0.15, 1)) both;
-  transition: opacity var(--chart-motion-fast, 150ms)
-    var(--ease-in-out, cubic-bezier(0.77, 0, 0.175, 1));
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(2) {
-  animation-delay: var(--chart-stagger, 30ms);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(3) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 2);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(4) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 3);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(5) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 4);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(6) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 5);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(7) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 6);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(8) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 7);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(9) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 8);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(10) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 9);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(11) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 10);
-}
-.hr-bar-chart .hr-bar-bars:nth-of-type(n + 12) {
-  animation-delay: calc(var(--chart-stagger, 30ms) * 11);
+  .hr-bar-chart.hr-bar-fill .hr-chart-body {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  .hr-bar-chart .empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
+    border-radius: 0.5rem;
+  }
+
+  .hr-bar-chart .empty p {
+    font-size: 0.8125rem;
+    color: var(--chart-label, oklch(0.5 0.01 286));
+    margin: 0;
+  }
+
+  /* WHY: Bars render as <path> elements, not <rect>. Selectors target the path's class directly. */
+  .hr-bar-chart .hr-bar-bars {
+    transform-box: fill-box;
+    transform-origin: bottom;
+    animation: hr-bar-grow var(--chart-motion-reveal, 1100ms)
+      var(--chart-ease-reveal, cubic-bezier(0.85, 0, 0.15, 1)) both;
+    transition: opacity var(--chart-motion-fast, 150ms)
+      var(--ease-in-out, cubic-bezier(0.77, 0, 0.175, 1));
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(2) {
+    animation-delay: var(--chart-stagger, 30ms);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(3) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 2);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(4) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 3);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(5) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 4);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(6) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 5);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(7) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 6);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(8) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 7);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(9) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 8);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(10) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 9);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(11) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 10);
+  }
+
+  .hr-bar-chart .hr-bar-bars:nth-of-type(n + 12) {
+    animation-delay: calc(var(--chart-stagger, 30ms) * 11);
+  }
+
+  .hr-bar-horizontal .hr-bar-bars {
+    transform-origin: left;
+    animation-name: hr-bar-grow-x;
+  }
+
+  .hr-bar-chart.hr-bar-has-active .hr-bar-bars {
+    opacity: 0.3;
+  }
+
+  .hr-bar-chart .hr-bar-active {
+    pointer-events: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hr-bar-chart .hr-bar-bars {
+      animation: none;
+    }
+  }
 }
+
 @keyframes hr-bar-grow {
   from {
     transform: scaleY(0);
   }
 }
-.hr-bar-horizontal .hr-bar-bars {
-  transform-origin: left;
-  animation-name: hr-bar-grow-x;
-}
+
 @keyframes hr-bar-grow-x {
   from {
     transform: scaleX(0);
   }
 }
-.hr-bar-chart.hr-bar-has-active .hr-bar-bars {
-  opacity: 0.3;
-}
-.hr-bar-chart .hr-bar-active {
-  pointer-events: none;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .hr-bar-chart .hr-bar-bars {
-    animation: none;
-  }
-}