@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/charts/stat-card.svelte

@@ -0,0 +1,267 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./stat-card.css";
+	import { Area, Bars, Chart, Highlight, LinearGradient, Spline, Svg, Tooltip } from "layerchart";
+	import { scaleBand } from "d3-scale";
+	import { curveBasis, curveCardinal } from "d3-shape";
+	import type { Snippet } from "svelte";
+	import Crosshair from "./crosshair.svelte";
+	import EdgeFade from "./edge-fade.svelte";
+	import Reveal from "./reveal.svelte";
+	import { resolveEdgeFade } from "./edge-fade.js";
+	import Figure from "./figure.svelte";
+	import GaugeChart from "./gauge-chart.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Variant = "line" | "area" | "bar" | "gauge";
+	type Trend = "up" | "down" | "neutral";
+
+	type Props = {
+		/** Series for the line/area/bar variants. Unused by the gauge variant. */
+		data?: TData[];
+		xKey?: keyof TData & string;
+		yKey?: keyof TData & string;
+		/** Chart kind. "gauge" puts a radial gauge to the right of the figure. */
+		variant?: Variant;
+		/** Arc fill 0-100 for variant="gauge". Falls back to `value` when numeric. */
+		gaugeValue?: number;
+		/** Label under the gauge percentage. */
+		gaugeLabel?: string;
+		/** Metric name shown top-left. Omit (or set `figureOnly`) for a bare chart. */
+		label?: string;
+		/** Headline number; counts up on mount. */
+		value?: number;
+		/** Percentage change. Its sign drives the trend color/arrow unless `trend` is set. */
+		delta?: number;
+		/** Force the trend direction independent of `delta`'s sign. */
+		trend?: Trend;
+		/** Caption under the value, e.g. "Avg" or "vs last month". */
+		caption?: string;
+		/** Render only the edge-to-edge chart, no header/value/caption. */
+		figureOnly?: boolean;
+		color?: string;
+		/** Chart height in px. */
+		height?: number;
+		smooth?: boolean;
+		/**
+		 * Softens the left and right ends of the line and the area fill instead of cutting them off at the card 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;
+		/** Format for the headline value. */
+		formatValue?: (v: number) => string;
+		/** Format for the x value shown as the tooltip header (e.g. a date/period). */
+		formatX?: (v: unknown) => string;
+		/** Leading icon next to the label. */
+		icon?: Snippet;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		data = [],
+		xKey,
+		yKey,
+		variant = "area",
+		gaugeValue,
+		gaugeLabel,
+		label,
+		value,
+		delta,
+		trend,
+		caption,
+		figureOnly = false,
+		color = "var(--chart-1)",
+		height = 150,
+		smooth = true,
+		edgeFade = true,
+		formatValue = (v) => v.toLocaleString(),
+		formatX = (v) => String(v),
+		icon,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	const uid = `hr-stat-${Math.random().toString(36).slice(2, 8)}`;
+	// WHY: match bklit's stat-card curves per variant. The area card uses cardinal
+
+	// at 0.65 tension; the line card uses curveBasis (a smoother, approximating spline) so the line flows instead of kinking through every point.
+	const areaCurve = $derived(smooth ? curveCardinal.tension(0.65) : undefined);
+	const lineCurve = $derived(smooth ? curveBasis : undefined);
+	const yMax = $derived(yKey ? Math.max(0, ...data.map((d) => Number(d[yKey] ?? 0))) : 0);
+	const arcValue = $derived(gaugeValue ?? (typeof value === "number" ? value : 0));
+	// WHY: one prop drives both ends. The stroke ramp is half the fill's so the
+
+	// line still spans nearly the full width (8% fill fade -> the 4% stroke fade this card has always used) instead of reading as side padding.
+	const fade = $derived(resolveEdgeFade(edgeFade));
+	const strokePct = $derived(Math.round(fade * 50 * 1000) / 1000);
+	const strokeStop = $derived(`${strokePct}%`);
+	const strokeEnd = $derived(`${100 - strokePct}%`);
+	const fadeMask = $derived(fade > 0 ? `url(#${uid}-fade)` : undefined);
+</script>
+
+<!-- =========================== -->
+<!-- STAT CARD -->
+<!-- =========================== -->
+<div
+	class="hr-stat-card {className ?? ''}"
+	class:hr-stat-figure-only={figureOnly}
+	class:hr-stat-has-gauge={variant === "gauge"}
+>
+	{#if variant === "gauge"}
+		<div class="hr-stat-gauge-row">
+			{#if label != null || value != null || caption != null}
+				<Figure
+					{icon}
+					title={label}
+					{value}
+					{delta}
+					{trend}
+					{caption}
+					size="lg"
+					format={formatValue}
+					class="hr-stat-gauge-figure"
+				/>
+			{/if}
+			<GaugeChart
+				value={arcValue}
+				{color}
+				size={116}
+				minWidth={0}
+				suffix="%"
+				showValue
+				defaultLabel={gaugeLabel ?? ""}
+				ariaLabel={label}
+			/>
+		</div>
+	{:else}
+		{#if !figureOnly && (label != null || value != null || caption != null)}
+			<Figure
+				{icon}
+				title={label}
+				{value}
+				{delta}
+				{trend}
+				{caption}
+				size="lg"
+				format={formatValue}
+			/>
+		{/if}
+
+		<div
+			class="hr-stat-chart"
+			style:height="{height}px"
+			role="img"
+			aria-label="{label ?? 'Value'} trend"
+		>
+			{#if data.length > 0 && xKey && yKey}
+				{#if variant === "bar"}
+					<Chart
+						{data}
+						x={xKey}
+						xScale={scaleBand().padding(0.28)}
+						y={yKey}
+						yDomain={[0, yMax || 1]}
+						padding={{ top: 6, bottom: 0, left: 0, right: 0 }}
+						tooltipContext={{ mode: "band" }}
+					>
+						<Svg>
+							<Bars rounded="top" radius={2} style="fill: {color}" class="hr-stat-bars" />
+							<Highlight
+								bar={{ rounded: "top", radius: 2, fill: color, class: "hr-stat-bar-active" }}
+							/>
+						</Svg>
+						<Tooltip.Root>
+							{#snippet children({ data: d })}
+								<Tooltip.Header value={xKey ? formatX(d[xKey]) : ""} />
+								<Tooltip.List>
+									<Tooltip.Item label={String(yKey)} value={formatValue(Number(d[yKey]))} />
+								</Tooltip.List>
+							{/snippet}
+						</Tooltip.Root>
+					</Chart>
+				{:else}
+					<Chart
+						{data}
+						x={xKey}
+						y={yKey}
+						padding={{ top: 8, bottom: 0, left: 0, right: 0 }}
+						tooltipContext={{ mode: "quadtree-x" }}
+					>
+						<Svg>
+							<!-- WHY: bklit fades the stroke to transparent at both ends via a
+						     horizontal gradient applied as the stroke paint; shared by the area
+						     and line variants. -->
+							<LinearGradient id="{uid}-stroke">
+								{#snippet stopsContent()}
+									<stop offset="0%" stop-color={color} stop-opacity={fade > 0 ? 0 : 1} />
+									<stop offset={strokeStop} stop-color={color} stop-opacity="1" />
+									<stop offset={strokeEnd} stop-color={color} stop-opacity="1" />
+									<stop offset="100%" stop-color={color} stop-opacity={fade > 0 ? 0 : 1} />
+								{/snippet}
+							</LinearGradient>
+							{#if fade > 0}
+								<EdgeFade id="{uid}-fade" amount={fade} />
+							{/if}
+							<Crosshair id="{uid}-cross" />
+							<Reveal bleed={3}>
+								{#if variant === "area"}
+									<LinearGradient id={uid} vertical>
+										{#snippet stopsContent()}
+											<stop offset="0%" stop-color={color} stop-opacity="0.45" />
+											<stop offset="100%" stop-color={color} stop-opacity="0" />
+										{/snippet}
+									</LinearGradient>
+									<Area
+										y1={yKey}
+										curve={areaCurve}
+										fill="url(#{uid})"
+										mask={fadeMask}
+										line={false}
+									/>
+								{/if}
+								<Spline
+									y={yKey}
+									curve={variant === "line" ? lineCurve : areaCurve}
+									stroke="url(#{uid}-stroke)"
+									fill="none"
+									stroke-width={variant === "line" ? 2.5 : 2}
+									stroke-linecap="round"
+									class="hr-stat-spline"
+								/>
+							</Reveal>
+							<!-- WHY: the crosshair line (not just the point dot) makes hover targeting legible on the edge-to-edge chart; quadtree-x snaps to the nearest -->
+							<!-- point by cursor x (bisect-x mis-tracks a categorical x-axis), but without -->
+							<!-- the line the selected point is easy to miss. Matches AreaChart's highlight. points fill is forced to the series color (else it -->
+							<!-- falls back to layerchart's blue --color-primary); motion="none" drops the spring so the dot tracks the cursor instantly instead of lagging behind. -->
+							<Highlight
+								points={{ fill: color }}
+								lines={{ style: `stroke: url(#${uid}-cross)` }}
+								motion="none"
+							/>
+						</Svg>
+						<Tooltip.Root>
+							{#snippet children({ data: d })}
+								<Tooltip.Header value={xKey ? formatX(d[xKey]) : ""} />
+								<Tooltip.List>
+									<Tooltip.Item label={String(yKey)} value={formatValue(Number(d[yKey]))} />
+								</Tooltip.List>
+							{/snippet}
+						</Tooltip.Root>
+					</Chart>
+				{/if}
+			{/if}
+		</div>
+	{/if}
+</div>

package/src/charts/time-series-chart.css

@@ -0,0 +1,28 @@
+/* Styles for TimeSeriesChart. Shipped as a plain stylesheet (imported by the
+   component) instead of a Svelte `<style>` block: a `<style>` block becomes a
+   `?type=style&lang.css` virtual module that Tailwind v4's Vite plugin mis-parses
+   when this package is consumed as source from node_modules (tailwindlabs/
+   tailwindcss#20000). Selectors are namespaced under `.hr-ts-chart`. */
+
+.hr-ts-chart {
+  width: 100%;
+  overflow: hidden;
+}
+
+.hr-ts-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-ts-chart .empty p {
+  font-size: 0.875rem;
+  color: var(--chart-label, oklch(0.5 0.01 286));
+  margin: 0;
+}
+
+.hr-ts-chart .hr-ts-grid {
+  stroke: var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
+}

package/src/charts/time-series-chart.svelte

@@ -0,0 +1,179 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./time-series-chart.css";
+	import { scaleTime } from "d3-scale";
+	import { curveMonotoneX } from "d3-shape";
+	import {
+		Area,
+		Axis,
+		Chart,
+		Grid,
+		Highlight,
+		LinearGradient,
+		Spline,
+		Svg,
+		Tooltip,
+	} from "layerchart";
+	import Crosshair from "./crosshair.svelte";
+	import EdgeFade from "./edge-fade.svelte";
+	import { resolveEdgeFade } from "./edge-fade.js";
+	import { DOMAIN_MOTION } from "./motion.js";
+	import Reveal from "./reveal.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface DataPoint {
+		date: string;
+		value: number;
+		value2?: number;
+	}
+
+	interface Props {
+		data: DataPoint[];
+		label?: string;
+		label2?: string;
+		color?: string;
+		color2?: string;
+		formatValue?: (v: number) => string;
+		formatValue2?: (v: number) => string;
+		height?: number;
+		/** Clamp Y-axis to 95th percentile so outlier spikes don't flatten normal data */
+		softMax?: boolean;
+		/** Y-axis floor. Raise above 0 to frame variation around a baseline. */
+		yMin?: number;
+		/**
+		 * 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;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		data,
+		label = "Value",
+		label2,
+		color = "var(--chart-1)",
+		color2 = "var(--muted-foreground)",
+		formatValue = (v) => v.toLocaleString(),
+		formatValue2,
+		height = 280,
+		softMax = false,
+		yMin = 0,
+		edgeFade = true,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	const gradientId = $derived(
+		`time-series-gradient-${label.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
+	);
+	const fade = $derived(resolveEdgeFade(edgeFade));
+	const fadeMask = $derived(fade > 0 ? `url(#${gradientId}-fade)` : undefined);
+
+	let chartData = $derived(
+		data.map((d) => ({
+			...d,
+			dateObj: new Date(d.date),
+		})),
+	);
+
+	let yMax = $derived.by(() => {
+		const allValues = [
+			...data.map((d) => d.value),
+			...data.filter((d) => d.value2 != null).map((d) => d.value2!),
+		];
+		const absMax = Math.max(...allValues);
+
+		if (!softMax || allValues.length < 10) return absMax;
+
+		const sorted = allValues.filter((v) => v > 0).toSorted((a, b) => a - b);
+		if (sorted.length === 0) return absMax;
+
+		const p95 = sorted[Math.floor(sorted.length * 0.95)];
+		// Only clamp if the max is significantly larger than p95 (2x+)
+		if (absMax > p95 * 2) return p95 * 1.3;
+		return absMax;
+	});
+</script>
+
+<!-- =========================== -->
+<!-- TIME SERIES CHART -->
+<!-- =========================== -->
+<div class="hr-ts-chart" style="height: {height}px">
+	{#if chartData.length === 0}
+		<div class="empty"><p>No historical data yet</p></div>
+	{:else}
+		<Chart
+			data={chartData}
+			x="dateObj"
+			xScale={scaleTime()}
+			y="value"
+			yDomain={[yMin, yMax]}
+			yNice
+			padding={{ left: 56, bottom: 36, top: 12, right: 16 }}
+			tooltipContext={{ mode: "bisect-x" }}
+			motion={DOMAIN_MOTION}
+		>
+			<Svg>
+				<Axis placement="left" format={(v) => formatValue(v)} ticks={6} />
+				<Axis
+					placement="bottom"
+					format={(d) => {
+						const date = d instanceof Date ? d : new Date(d);
+						return date.toLocaleDateString("en", { month: "short", day: "numeric" });
+					}}
+				/>
+				<Grid y class="hr-ts-grid" />
+				<LinearGradient id={gradientId} vertical>
+					{#snippet stopsContent()}
+						<stop offset="0%" stop-color={color} stop-opacity="0.35" />
+						<stop offset="100%" stop-color={color} stop-opacity="0.02" />
+					{/snippet}
+				</LinearGradient>
+				{#if fade > 0}
+					<EdgeFade id="{gradientId}-fade" amount={fade} />
+				{/if}
+				<Crosshair id="{gradientId}-cross" />
+				<Reveal>
+					<Area curve={curveMonotoneX} fill="url(#{gradientId})" mask={fadeMask} />
+					<Spline curve={curveMonotoneX} style="stroke: {color}; fill: none" stroke-width="1.5" />
+					{#if label2}
+						<Spline
+							y="value2"
+							curve={curveMonotoneX}
+							style="stroke: {color2}; stroke-dasharray: 4 4; stroke-width: 1; fill: none"
+						/>
+					{/if}
+				</Reveal>
+				<Highlight points lines={{ style: `stroke: url(#${gradientId}-cross)` }} />
+			</Svg>
+			<Tooltip.Root>
+				{#snippet children({ data: d })}
+					<Tooltip.Header
+						value={d.dateObj.toLocaleDateString("en", {
+							month: "short",
+							day: "numeric",
+							year: "numeric",
+						})}
+					/>
+					<Tooltip.List>
+						<Tooltip.Item {label} value={formatValue(d.value)} />
+						{#if label2 && d.value2 !== undefined}
+							<Tooltip.Item label={label2} value={(formatValue2 ?? formatValue)(d.value2)} />
+						{/if}
+					</Tooltip.List>
+				{/snippet}
+			</Tooltip.Root>
+		</Chart>
+	{/if}
+</div>

package/src/charts/trend-pill.css

@@ -0,0 +1,38 @@
+/* Styles for TrendPill. Plain stylesheet (see area-chart.css for why). All
+   selectors are already namespaced under `.hr-trend`. */
+
+.hr-trend {
+  display: inline-flex;
+  /* WHY no shrink: the delta is the row's point, and it is only three characters wide. */
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 0.1875rem;
+  padding: 0.1875rem 0.5rem;
+  border-radius: 999px;
+  border: 1px solid color-mix(in srgb, var(--stat-trend, currentColor) 22%, transparent);
+  background: color-mix(in srgb, var(--stat-trend, currentColor) 10%, transparent);
+  /* WHY the mix: a trend colour is picked to read as a mark, and at 12px on its
+	   own 10% wash the raw hue measured 3.5:1. Mixing toward --foreground darkens
+	   it on a light page and lightens it on a dark one, so one rule serves both
+	   themes and the package needs to know nothing about which is on. */
+  color: color-mix(
+    in oklab,
+    var(--stat-trend, var(--muted-foreground, oklch(0.5 0.01 286))) 72%,
+    var(--foreground, oklch(0.2 0.01 286))
+  );
+  font-size: 0.75rem;
+  font-weight: 600;
+  font-feature-settings: "tnum";
+  line-height: 1.2;
+  white-space: nowrap;
+}
+.hr-trend[data-trend="up"] {
+  --stat-trend: var(--stat-up, oklch(0.6 0.13 163));
+}
+.hr-trend[data-trend="down"] {
+  --stat-trend: var(--stat-down, oklch(0.58 0.22 25));
+}
+.hr-trend-arrow {
+  font-size: 0.8125rem;
+  line-height: 1;
+}

package/src/charts/trend-pill.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./trend-pill.css";
+	import { cn } from "@heyramzi/utils";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Trend = "up" | "down" | "neutral";
+
+	type Props = {
+		/** Percentage change. Its sign drives the color/arrow unless `trend` is set. */
+		delta: number;
+		/** Force the direction independent of `delta`'s sign. */
+		trend?: Trend;
+		/** Format the delta text. */
+		format?: (v: number) => string;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		delta,
+		trend,
+		format = (v) =>
+			`${v > 0 ? "+" : ""}${v.toLocaleString(undefined, { maximumFractionDigits: 1 })}%`,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	const resolved = $derived<Trend>(trend ?? (delta === 0 ? "neutral" : delta > 0 ? "up" : "down"));
+</script>
+
+<!-- =========================== -->
+<!-- TREND PILL -->
+<!-- =========================== -->
+<span class={cn("hr-trend", className)} data-trend={resolved}>
+	{#if resolved !== "neutral"}
+		<span class="hr-trend-arrow" aria-hidden="true">{resolved === "up" ? "↑" : "↓"}</span>
+	{/if}
+	{format(delta)}
+</span>