@heyramzi/ui 2.24.0 → 3.1.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,7 +71,7 @@ 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` | A titled panel for a table or chart. The dashed empty state is `EmptyState surface="dashed"` from `@heyramzi/ui/components/list-page` |
+| `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,38 @@
+@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%;
+  }
+
+  /* A value axis owned by one series wears its colour. Mixed toward the foreground like the
+     figure above it, since a line colour clears 3:1 and 11px text needs 4.5:1. */
+  .hr-area-chart .hr-axis-tone[style*="--hr-axis-tone"] .lc-axis-tick-label {
+    fill: color-mix(in oklab, var(--hr-axis-tone) 70%, var(--foreground, oklch(0.2 0.01 286)));
+  }
+
+  .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,13 +4,26 @@
 	// =========================
 	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 { dualAxis } from "./dual-axis.js";
 	import { DOMAIN_MOTION, TOOLTIP_GAP, TOOLTIP_TOP } from "./motion.js";
 	import { valueTick } from "./primitives/chart-utils.js";
 	import Reveal from "./reveal.svelte";
@@ -32,6 +45,11 @@
 		key: keyof TData & string;
 		label?: string;
 		color?: string;
+		/**
+		 * `"right"` plots the series on a second value axis with its own scale, for a measure in a
+		 * different unit or about 10x larger than the rest. It draws as a line, without the fill.
+		 */
+		axis?: "left" | "right";
 	};
 
 	interface Props {
@@ -56,10 +74,19 @@
 		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 };
+		/**
+		 * The headline while no point is hovered, like a period total. Defaults to the last point.
+		 * `values`, keyed by series, shows one figure per series side by side in its colour, so it also reads as the legend.
+		 */
+		resting?: {
+			value?: number;
+			values?: Partial<Record<keyof TData & string, 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;
 	}
 
@@ -82,6 +109,7 @@
 		reference,
 		resting,
 		smoothing,
+		label = "Area chart",
 		class: className,
 	}: Props = $props();
 
@@ -89,6 +117,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.
 
@@ -111,6 +140,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
 	// =========================
@@ -121,11 +159,14 @@
 					key: s.key,
 					label: s.label ?? s.key,
 					color: s.color ?? `var(--chart-series-${(i % 6) + 1})`,
+					axis: s.axis === "right" ? ("right" as const) : ("left" as const),
 				}))
 			: yKey
-				? [{ key: yKey, label: yKey, color }]
+				? [{ key: yKey, label: yKey, color, axis: "left" as const }]
 				: [],
 	);
+	const leftSeries = $derived(series.filter((s) => s.axis === "left"));
+	const rightSeries = $derived(series.filter((s) => s.axis === "right"));
 	const smoothed = $derived(
 		smoothing
 			? smoothSeries(
@@ -142,12 +183,41 @@
 	const averageLabel = $derived(mode === "rolling" ? averageName(smoothed.window) : null);
 	const dataMax = $derived.by(() => {
 		if (stacked) {
-			return Math.max(0, ...data.map((d) => series.reduce((s, k) => s + Number(d[k.key] ?? 0), 0)));
+			return Math.max(
+				0,
+				...data.map((d) => leftSeries.reduce((s, k) => s + Number(d[k.key] ?? 0), 0)),
+			);
 		}
-		return Math.max(0, ...data.flatMap((d) => series.map((s) => Number(d[s.key] ?? 0))));
+		return Math.max(0, ...data.flatMap((d) => leftSeries.map((s) => Number(d[s.key] ?? 0))));
 	});
 	// A target above every point would sit off the plot.
 	const yMax = $derived(Math.max(dataMax, reference?.value ?? 0));
+	// A right-axis series lives on the chart's one y scale, rescaled so its domain fills the same
+	// height; the right axis labels that height in the series' own unit.
+	const axes = $derived.by(() => {
+		if (rightSeries.length === 0) return null;
+		const rightMax = Math.max(
+			0,
+			...data.flatMap((d) => rightSeries.map((s) => Number(d[s.key] ?? 0))),
+		);
+		return dualAxis(yMax, rightMax);
+	});
+	const plotKey = (s: { key: string; axis: "left" | "right" }) =>
+		s.axis === "right" ? `__hr_right_${s.key}` : s.key;
+	const plotData = $derived.by((): TData[] => {
+		if (!axes) return data;
+		const factor = axes.left.max / axes.right.max;
+		return data.map((d) => {
+			const row: Record<string, unknown> = { ...d };
+			// A gap stays a gap: null times a factor would draw a 0.
+			for (const s of rightSeries)
+				row[plotKey(s)] = d[s.key] == null ? null : Number(d[s.key]) * factor;
+			return row as TData;
+		});
+	});
+	// An axis takes its series' colour only when one series owns it; with two on a side the colour would name one of them.
+	const leftTone = $derived(axes && leftSeries.length === 1 ? leftSeries[0].color : undefined);
+	const rightTone = $derived(rightSeries.length === 1 ? rightSeries[0].color : undefined);
 	const curve = $derived(smooth ? curveMonotoneX : undefined);
 	const fade = $derived(resolveEdgeFade(edgeFade));
 	const fadeMask = $derived(fade > 0 ? `url(#${uid}-fade)` : undefined);
@@ -164,18 +234,33 @@
 				}))
 			: 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)}
->
-	{#if resting && !active && series[0]}
+<!-- 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?.values && !active}
+		<Figure
+			series={series
+				.filter((s) => resting.values?.[s.key] != null)
+				.map((s) => ({ value: Number(resting.values?.[s.key]), label: s.label, color: s.color }))}
+			eyebrow={resting.label}
+			format={formatValue}
+			size="md"
+		/>
+	{:else if resting && resting.value != null && !active && series[0]}
 		<Figure
 			series={[{ value: resting.value, label: series[0].label, color: series[0].color }]}
 			eyebrow={resting.label}
@@ -190,25 +275,48 @@
 		<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}
 			<Chart
-				{data}
+				data={plotData}
 				x={xKey}
-				y={series[0]?.key}
-				yDomain={[0, yMax || 1]}
-				yNice
-				padding={{ left: 48, bottom: 28, top: 8, right: 12 }}
+				y={series[0] ? plotKey(series[0]) : undefined}
+				yDomain={[0, axes ? axes.left.max : yMax || 1]}
+				yNice={!axes}
+				padding={{ left: 48, bottom: 28, top: 8, right: axes ? 48 : 12 }}
 				tooltipContext={{ mode: "quadtree-x" }}
 				motion={DOMAIN_MOTION}
+				bind:context
 			>
-				<Svg>
-					<Axis placement="left" format={(v) => tick(Number(v))} ticks={4} />
+				<Svg aria-hidden="true">
+					<g class="hr-axis-tone" style:--hr-axis-tone={leftTone}>
+						<Axis
+							placement="left"
+							format={(v) => tick(Number(v))}
+							ticks={axes ? axes.left.ticks : 4}
+						/>
+					</g>
+					{#if axes}
+						<g class="hr-axis-tone" style:--hr-axis-tone={rightTone}>
+							<Axis
+								placement="right"
+								domain={[0, axes.right.max]}
+								format={(v) => tick(Number(v))}
+								ticks={axes.right.ticks}
+							/>
+						</g>
+					{/if}
 					<Axis placement="bottom" format={(v) => formatX(v)} ticks={ticksForWidth(xTicks)} />
 					<g class="hr-area-grid">
-						<Axis placement="left" grid rule={false} ticks={4} format={() => ""} />
+						<Axis
+							placement="left"
+							grid
+							rule={false}
+							ticks={axes ? axes.left.ticks : 4}
+							format={() => ""}
+						/>
 					</g>
 					{#if fade > 0}
 						<EdgeFade id="{uid}-fade" amount={fade} />
@@ -229,17 +337,39 @@
 								<!-- WHY `y1` and not `y`: layerchart's Area has no `y` prop, so every
 							     series drew the first series' shape and the gradients stacked on
 							     one path. See `Area.shared.svelte.js`. -->
-								<Area y1={s.key} {curve} fill="url(#{uid}-{i})" mask={fadeMask} />
-								<Spline y={s.key} {curve} style="stroke: {s.color}; fill: none" stroke-width="2" />
+								{#if s.axis === "left"}
+									<Area y1={s.key} {curve} fill="url(#{uid}-{i})" mask={fadeMask} />
+								{/if}
+								<Spline
+									y={plotKey(s)}
+									{curve}
+									style="stroke: {s.color}; fill: none"
+									stroke-width="2"
+								/>
 							{/each}
 						</Reveal>
 						{#snippet segment()}
 							{#each series as s (s.key)}
-								<Spline y={s.key} {curve} style="stroke: {s.color}; fill: none" stroke-width="2" />
+								<Spline
+									y={plotKey(s)}
+									{curve}
+									style="stroke: {s.color}; fill: none"
+									stroke-width="2"
+								/>
 							{/each}
 						{/snippet}
 					</HoverFocus>
-					<Highlight points lines={{ style: `stroke: url(#${uid}-cross)` }} />
+					{#if axes}
+						<!-- WHY `data`: without it Highlight places dots from the tooltip's raw values, off the rescaled right series. -->
+						<Highlight lines={{ style: `stroke: url(#${uid}-cross)` }} />
+						{#if context?.tooltip.data}
+							{#each series as s (s.key)}
+								<Highlight data={context.tooltip.data} y={plotKey(s)} points={{ fill: s.color }} />
+							{/each}
+						{/if}
+					{:else}
+						<Highlight points lines={{ style: `stroke: url(#${uid}-cross)` }} />
+					{/if}
 				</Svg>
 				<Tooltip.Root x="data" y={TOOLTIP_TOP} xOffset={TOOLTIP_GAP}>
 					{#snippet children({ data: d })}
@@ -257,5 +387,5 @@
 				</Tooltip.Root>
 			</Chart>
 		{/if}
-	</div>
+	</ChartPlot>
 </div>

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

@@ -0,0 +1,69 @@
+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;
+            /**
+             * `"right"` plots the series on a second value axis with its own scale, for a measure in a
+             * different unit or about 10x larger than the rest. It draws as a line, without the fill.
+             */
+            axis?: "left" | "right";
+        }[];
+        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.
+         * `values`, keyed by series, shows one figure per series side by side in its colour, so it also reads as the legend.
+         */
+        resting?: {
+            value?: number;
+            values?: Partial<Record<keyof TData & string, 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;