@heyramzi/ui 1.54.1 → 2.0.0

package/src/charts/area-chart.svelte

@@ -0,0 +1,204 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./area-chart.css";
+	import { Area, Axis, Chart, Highlight, LinearGradient, Spline, Svg, Tooltip } from "layerchart";
+	import { curveMonotoneX } from "d3-shape";
+	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 Reveal from "./reveal.svelte";
+	import ReferenceLine, { type ChartReference } from "./reference-line.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Series = {
+		key: keyof TData & string;
+		label?: string;
+		color?: string;
+	};
+
+	interface Props {
+		data: TData[];
+		xKey: keyof TData & string;
+		yKey?: keyof TData & string;
+		series?: Series[];
+		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.
+		 */
+
+		/*
+		 * `true` fades 8% of the width per side, a number sets the fraction (0-0.45), `false` keeps the hard edges.
+		 */
+		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;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		data,
+		xKey,
+		yKey,
+		series: seriesInput,
+		color = "var(--chart-1)",
+		height = 240,
+		stacked = false,
+		smooth = true,
+		edgeFade = true,
+		formatValue = (v) => v.toLocaleString(),
+		formatX = (v) => String(v),
+		xTicks = 6,
+		reference,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let active = $state<TData | null>(null);
+
+	// ========================= 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.
+
+	// The microtask defers the state write out of template evaluation.
+	function trackActive(d: TData): string {
+		queueMicrotask(() => {
+			active = d;
+		});
+		return formatX(d[xKey]);
+	}
+
+	// =========================
+	// DERIVED
+	// =========================
+	const uid = `hr-area-${Math.random().toString(36).slice(2, 8)}`;
+	const series = $derived(
+		seriesInput && seriesInput.length > 0
+			? seriesInput.map((s, i) => ({
+					key: s.key,
+					label: s.label ?? s.key,
+					color: s.color ?? `var(--chart-${(i % 5) + 1})`,
+				}))
+			: yKey
+				? [{ key: yKey, label: yKey, color }]
+				: [],
+	);
+	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.flatMap((d) => series.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));
+	const curve = $derived(smooth ? curveMonotoneX : undefined);
+	const fade = $derived(resolveEdgeFade(edgeFade));
+	const fadeMask = $derived(fade > 0 ? `url(#${uid}-fade)` : undefined);
+	const fallback = $derived(data.length > 0 ? data[data.length - 1] : null);
+	const display = $derived(active ?? fallback);
+	const figureRows = $derived(
+		display
+			? series.map((s) => ({ value: Number(display[s.key]), label: s.label, color: s.color }))
+			: null,
+	);
+</script>
+
+<!-- =========================== -->
+<!-- AREA CHART -->
+<!-- =========================== -->
+<div
+	class="hr-area-chart {className ?? ''}"
+	role="img"
+	aria-label="Area chart"
+	onpointerleave={() => (active = null)}
+>
+	{#if figureRows && display}
+		<Figure series={figureRows} eyebrow={formatX(display[xKey])} format={formatValue} size="md" />
+	{:else}
+		<Figure value="—" eyebrow="Latest" size="md" />
+	{/if}
+
+	<div class="hr-chart-body" style:height="{height}px">
+		{#if data.length === 0}
+			<div class="empty"><p>No data</p></div>
+		{:else}
+			<Chart
+				{data}
+				x={xKey}
+				y={series[0]?.key}
+				yDomain={[0, yMax || 1]}
+				yNice
+				padding={{ left: 48, bottom: 28, top: 8, right: 12 }}
+				tooltipContext={{ mode: "quadtree-x" }}
+				motion={DOMAIN_MOTION}
+			>
+				<Svg>
+					<Axis placement="left" format={(v) => formatValue(Number(v))} ticks={4} />
+					<Axis placement="bottom" format={(v) => formatX(v)} ticks={xTicks} />
+					<g class="hr-area-grid">
+						<Axis placement="left" grid rule={false} ticks={4} format={() => ""} />
+					</g>
+					{#if fade > 0}
+						<EdgeFade id="{uid}-fade" amount={fade} />
+					{/if}
+					<Crosshair id="{uid}-cross" />
+					{#if reference}
+						<ReferenceLine {reference} />
+					{/if}
+					<HoverFocus>
+						<Reveal>
+							{#each series as s, i (s.key)}
+								<LinearGradient id="{uid}-{i}" vertical>
+									{#snippet stopsContent()}
+										<stop offset="0%" stop-color={s.color} stop-opacity="0.45" />
+										<stop offset="100%" stop-color={s.color} stop-opacity="0.04" />
+									{/snippet}
+								</LinearGradient>
+								<!-- 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" />
+							{/each}
+						</Reveal>
+						{#snippet segment()}
+							{#each series as s (s.key)}
+								<Spline y={s.key} {curve} style="stroke: {s.color}; fill: none" stroke-width="2" />
+							{/each}
+						{/snippet}
+					</HoverFocus>
+					<Highlight points lines={{ style: `stroke: url(#${uid}-cross)` }} />
+				</Svg>
+				<Tooltip.Root x="data" y={TOOLTIP_TOP} xOffset={TOOLTIP_GAP}>
+					{#snippet children({ data: d })}
+						<Tooltip.Header value={trackActive(d as TData)} />
+						<Tooltip.List>
+							{#each series as s (s.key)}
+								<Tooltip.Item
+									label={s.label}
+									value={formatValue(Number(d[s.key]))}
+									color={s.color}
+								/>
+							{/each}
+						</Tooltip.List>
+					{/snippet}
+				</Tooltip.Root>
+			</Chart>
+		{/if}
+	</div>
+</div>

package/src/charts/bar-chart.css

@@ -0,0 +1,119 @@
+/* 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%;
+}
+
+/* WHY: height="fill" grows the chart to its parent's height (e.g. a card that
+   stretches to match a taller sibling) instead of the fixed body height. The
+   parent must be a flex column that gives this 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 .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) ease-in-out;
+}
+.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);
+}
+@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;
+  }
+}

package/src/charts/bar-chart.svelte

@@ -0,0 +1,275 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./bar-chart.css";
+	import { Axis, Bars, Chart, Highlight, Svg, Tooltip } from "layerchart";
+	import { scaleBand } from "d3-scale";
+	import Figure from "./figure.svelte";
+	import { TOOLTIP_GAP, TOOLTIP_TOP } from "./motion.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Series = { key: keyof TData & string; label: string; color: string };
+
+	interface 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?: Series[];
+		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;
+		/** Screen-reader summary; also renders an sr-only data table when set. */
+		label?: string;
+		/** Column header for the x values in the sr-only table. */
+		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;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		data,
+		xKey,
+		yKey,
+		series,
+		color = "var(--chart-1)",
+		colorOf,
+		height = 240,
+		orientation = "vertical",
+		leftPadding = 80,
+		formatValue = (v) => v.toLocaleString(),
+		formatX = (v) => String(v),
+		formatTick,
+		label,
+		xLabel,
+		yLabel,
+		details,
+		showFigure = true,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let active = $state<TData | null>(null);
+
+	// ========================= FUNCTIONS ========================= WHY: called from the tooltip header's value expression so it re-runs on every active-band change; an unread {@const} side effect only evaluates once.
+
+	// The microtask defers the state write out of template evaluation.
+	function trackActive(d: TData): string {
+		queueMicrotask(() => {
+			active = d;
+		});
+		return formatX(d[xKey]);
+	}
+
+	function valueOf(d: TData): number {
+		if (series) return series.reduce((sum, s) => sum + Number(d[s.key] ?? 0), 0);
+		return Number(yKey ? (d[yKey] ?? 0) : 0);
+	}
+
+	/** Where one series' segment starts and ends inside its stacked bar. */
+	function span(d: TData, key: string): [number, number] {
+		let at = 0;
+		for (const s of series ?? []) {
+			const next = at + Number(d[s.key] ?? 0);
+			if (s.key === key) return [at, next];
+			at = next;
+		}
+		return [0, 0];
+	}
+
+	// =========================
+	// DERIVED
+	// =========================
+	const yMax = $derived(Math.max(0, ...data.map(valueOf)));
+	const total = $derived(data.reduce((sum, d) => sum + valueOf(d), 0));
+	const valueLabel = $derived(yLabel ?? String(yKey ?? "value"));
+	const fill = $derived(height === "fill");
+	const horizontal = $derived(orientation === "horizontal");
+	const radius = $derived(horizontal ? "right" : "top");
+	// One Bars layer per fill: a stacked series, a colorOf group, or the single color.
+	const layers = $derived.by(() => {
+		if (series) {
+			return series.map((s) => ({
+				key: s.key,
+				color: s.color,
+				rows: data,
+				at: (d: TData) => span(d, s.key),
+			}));
+		}
+		const groups = new Map<string, TData[]>();
+		for (const d of data) {
+			const c = colorOf?.(d) ?? color;
+			groups.set(c, [...(groups.get(c) ?? []), d]);
+		}
+		return [...groups].map(([c, rows]) => ({ key: c, color: c, rows, at: undefined }));
+	});
+	const activeColor = $derived(active && colorOf ? colorOf(active) : color);
+</script>
+
+<!-- =========================== -->
+<!-- BAR CHART -->
+<!-- =========================== -->
+<div
+	class="hr-bar-chart {className ?? ''}"
+	class:hr-bar-horizontal={horizontal}
+	class:hr-bar-fill={fill}
+	class:hr-bar-has-active={active !== null && !series}
+	role="img"
+	aria-label={label ?? "Bar chart"}
+	onpointerleave={() => (active = null)}
+>
+	{#if showFigure}
+		<Figure
+			value={active ? valueOf(active) : total}
+			color="var(--chart-1)"
+			eyebrow={active ? formatX(active[xKey]) : "Total"}
+			format={formatValue}
+			size="md"
+		/>
+	{/if}
+
+	<div class="hr-chart-body" style:height={fill ? null : `${height}px`}>
+		{#if data.length === 0}
+			<div class="empty"><p>No data</p></div>
+		{:else}
+			<Chart
+				{data}
+				x={horizontal ? valueOf : xKey}
+				y={horizontal ? xKey : valueOf}
+				xScale={horizontal ? undefined : scaleBand().padding(0.3)}
+				yScale={horizontal ? scaleBand().padding(0.3) : undefined}
+				xDomain={horizontal ? [0, yMax || 1] : undefined}
+				yDomain={horizontal ? undefined : [0, yMax || 1]}
+				xNice={horizontal}
+				yNice={!horizontal}
+				padding={{ left: horizontal ? leftPadding : 48, bottom: 28, top: 8, right: 12 }}
+				tooltipContext={{ mode: "band" }}
+			>
+				<Svg>
+					{#if horizontal}
+						<Axis placement="left" format={(v) => (formatTick ?? formatX)(v)} />
+						<Axis placement="bottom" format={(v) => formatValue(Number(v))} ticks={4} />
+						<g class="hr-bar-grid">
+							<Axis placement="bottom" grid rule={false} ticks={4} format={() => ""} />
+						</g>
+					{:else}
+						<Axis placement="left" format={(v) => formatValue(Number(v))} ticks={4} />
+						<Axis placement="bottom" format={(v) => (formatTick ?? formatX)(v)} />
+						<g class="hr-bar-grid">
+							<Axis placement="left" grid rule={false} ticks={4} format={() => ""} />
+						</g>
+					{/if}
+					{#each layers as layer (layer.key)}
+						{#if layer.at && horizontal}
+							<Bars x={layer.at} style="fill: {layer.color}" class="hr-bar-bars" />
+						{:else if layer.at}
+							<Bars y={layer.at} style="fill: {layer.color}" class="hr-bar-bars" />
+						{:else}
+							<Bars
+								data={layer.rows}
+								rounded={radius}
+								radius={4}
+								style="fill: {layer.color}"
+								class="hr-bar-bars"
+							/>
+						{/if}
+					{/each}
+					<!-- WHY: the band tooltip layer eats pointer events, so bar :hover never
+				     fires. The active bar is a Highlight copy; motion "none" keeps it from
+				     sliding between bands. -->
+					{#if !series}
+						<Highlight
+							motion="none"
+							bar={{ rounded: radius, radius: 4, fill: activeColor, class: "hr-bar-active" }}
+						/>
+					{/if}
+				</Svg>
+				<Tooltip.Root
+					x={horizontal ? "pointer" : "data"}
+					y={horizontal ? "data" : TOOLTIP_TOP}
+					xOffset={TOOLTIP_GAP}
+				>
+					{#snippet children({ data: d })}
+						<Tooltip.Header value={trackActive(d as TData)} />
+						<Tooltip.List>
+							{#if series}
+								{#each series as s (s.key)}
+									<Tooltip.Item
+										label={s.label}
+										value={formatValue(Number(d[s.key] ?? 0))}
+										color={s.color}
+									/>
+								{/each}
+							{:else}
+								<Tooltip.Item
+									label={valueLabel}
+									value={formatValue(valueOf(d as TData))}
+									color={colorOf ? colorOf(d as TData) : color}
+								/>
+								{#each details?.(d as TData) ?? [] as row (row.label)}
+									<Tooltip.Item label={row.label} value={row.value} />
+								{/each}
+							{/if}
+						</Tooltip.List>
+					{/snippet}
+				</Tooltip.Root>
+			</Chart>
+		{/if}
+	</div>
+
+	{#if label && data.length > 0}
+		<table class="hr-sr-only">
+			<caption>{label}</caption>
+			<thead>
+				<tr>
+					<th scope="col">{xLabel}</th>
+					{#if series}
+						{#each series as s (s.key)}
+							<th scope="col">{s.label}</th>
+						{/each}
+					{:else}
+						<th scope="col">{yLabel}</th>
+					{/if}
+				</tr>
+			</thead>
+			<tbody>
+				{#each data as d, i (i)}
+					<tr>
+						<th scope="row">{formatX(d[xKey])}</th>
+						{#if series}
+							{#each series as s (s.key)}
+								<td>{formatValue(Number(d[s.key] ?? 0))}</td>
+							{/each}
+						{:else}
+							<td>{formatValue(valueOf(d))}</td>
+						{/if}
+					</tr>
+				{/each}
+			</tbody>
+		</table>
+	{/if}
+</div>