@heyramzi/ui 0.0.0-stage → 6.0.1

package/src/charts/gauge-chart.svelte

@@ -0,0 +1,303 @@
+<script module lang="ts">
+	// WHY: each gradient needs a document-unique <defs> id; a module counter keeps
+	// SSR and hydration in lockstep (def and ref share the same value per render).
+	let gradientSeq = 0;
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./gauge-chart.css";
+	import { cn } from "@heyramzi/utils";
+	import AnimatedValue from "./animated-value.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		/** Arc fill, 0-100 (how many notches light up). */
+		value: number;
+		/** "gauge" = notched arc, "ring" = continuous swept arc. */
+		variant?: "gauge" | "ring";
+		/** Show the center value/label. Off when the number sits beside the gauge. */
+		showValue?: boolean;
+		/** Active arc color (CSS color or var). Alias for `activeFill`. */
+		color?: string;
+		/** Single-hue gradient along the active arc. Alias for `useGradient`. */
+		gradient?: boolean;
+		/** Center label under the value. Alias for `defaultLabel`. */
+		label?: string;
+		/** Center statistic. Defaults to `value`. Formatted via `formatOptions`. */
+		centerValue?: number;
+		/** Notch count around the arc. */
+		totalNotches?: number;
+		/** Gap between notches as a percentage of the arc. */
+		spacing?: number;
+		/** Radial depth of the notch band as a percentage of the default. */
+		notchLengthPercent?: number;
+		/** Corner fillet in viewBox units (0 = sharp). Defaults to a soft pill. */
+		notchCornerRadius?: number;
+		/** Rectangular notches instead of angular/tapered. */
+		uniformWidth?: boolean;
+		/** Arc start in degrees (default 135, sweeping to 405 = 270deg with a bottom gap). */
+		startAngle?: number;
+		endAngle?: number;
+		/** Single-hue gradient along the active arc instead of a flat fill. */
+		useGradient?: boolean;
+		/** Hex stops for the active gradient. Defaults to a tonal ramp of `activeFill`. */
+		activeGradient?: [string, string];
+		/** Active notch color (CSS color or var). */
+		activeFill?: string;
+		/** Track notch color. Defaults to `activeFill`. */
+		inactiveFill?: string;
+		activeFillOpacity?: number;
+		inactiveFillOpacity?: number;
+		/** Center label under the value. */
+		defaultLabel?: string;
+		/** Intl formatting for the center value. */
+		formatOptions?: Intl.NumberFormatOptions;
+		locale?: string;
+		prefix?: string;
+		suffix?: string;
+		/** Fixed square size in px. Omit to fill the parent (responsive). */
+		size?: number;
+		/** Minimum width when responsive. */
+		minWidth?: number;
+		/** Accessible description, e.g. "ARR run rate". */
+		ariaLabel?: string;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		value,
+		variant = "gauge",
+		showValue = true,
+		color,
+		gradient,
+		label,
+		centerValue,
+		totalNotches = 40,
+		spacing = 25,
+		notchLengthPercent = 100,
+		notchCornerRadius,
+		uniformWidth = false,
+		startAngle = 135,
+		endAngle = 405,
+		useGradient = false,
+		activeGradient,
+		activeFill = "var(--chart-1)",
+		inactiveFill,
+		activeFillOpacity = 1,
+		inactiveFillOpacity = 0.12,
+		defaultLabel = "Total",
+		formatOptions,
+		locale,
+		prefix,
+		suffix,
+		size,
+		minWidth = 160,
+		ariaLabel,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// CONST
+	// =========================
+	// Normalized 100x100 coordinate space so the SVG scales to any container.
+	const CX = 50;
+	const CY = 50;
+	const OUTER_R = 42;
+	const gradientId = `hr-gauge-grad-${(gradientSeq += 1)}`;
+
+	// =========================
+	// DERIVED
+	// =========================
+	const clamped = $derived(Math.max(0, Math.min(100, value)));
+	const center = $derived(centerValue ?? value);
+	const effFill = $derived(color ?? activeFill);
+	const effGradient = $derived(gradient ?? useGradient);
+	const effLabel = $derived(label ?? defaultLabel);
+	const band = $derived(14 * (Math.max(5, Math.min(100, notchLengthPercent)) / 100));
+	const innerR = $derived(OUTER_R - band);
+	const midR = $derived((OUTER_R + innerR) / 2);
+	const corner = $derived(notchCornerRadius ?? band * 0.22);
+	const totalAngle = $derived(endAngle - startAngle);
+	const activeCount = $derived(Math.round((clamped / 100) * totalNotches));
+	const trackFill = $derived(inactiveFill ?? effFill);
+	const activePaint = $derived(effGradient ? `url(#${gradientId})` : effFill);
+	const gradStops = $derived(
+		activeGradient ?? [`color-mix(in oklab, ${effFill}, white 45%)`, effFill],
+	);
+	// WHY: ring variant draws a single rounded arc that sweeps from empty; the
+	// stroke-dashoffset (with pathLength 100) maps 1:1 to the percent value.
+	const ringTrack = $derived(arcPath(startAngle, endAngle));
+	const ringOffset = $derived(100 - clamped);
+
+	const notches = $derived.by(() => {
+		const notchAngle = (totalAngle * (1 - spacing / 100)) / totalNotches;
+		const gapAngle = (totalAngle * (spacing / 100)) / Math.max(1, totalNotches - 1);
+		const half = (notchAngle * 0.8 * Math.PI) / 180 / 2;
+		const items: { d: string; active: boolean; index: number }[] = [];
+		for (let i = 0; i < totalNotches; i++) {
+			const angle = startAngle + i * (notchAngle + gapAngle) + notchAngle / 2;
+			items.push({
+				index: i,
+				active: i < activeCount,
+				d: notchPath(buildQuad(angle, half), corner),
+			});
+		}
+		return items;
+	});
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function buildQuad(
+		angleDeg: number,
+		half: number,
+	): [number, number, number, number, number, number, number, number] {
+		const rad = (angleDeg * Math.PI) / 180;
+		if (uniformWidth) {
+			// WHY: constant perpendicular half-width gives rectangular notches; the
+			// chord at the mid radius keeps them visually consistent with tapered ones.
+			const w = midR * Math.sin(half);
+			const ux = Math.cos(rad);
+			const uy = Math.sin(rad);
+			const px = -uy;
+			const py = ux;
+			const ox = CX + ux * OUTER_R;
+			const oy = CY + uy * OUTER_R;
+			const ix = CX + ux * innerR;
+			const iy = CY + uy * innerR;
+			return [
+				ox + px * w,
+				oy + py * w,
+				ox - px * w,
+				oy - py * w,
+				ix - px * w,
+				iy - py * w,
+				ix + px * w,
+				iy + py * w,
+			];
+		}
+		return [
+			CX + Math.cos(rad - half) * OUTER_R,
+			CY + Math.sin(rad - half) * OUTER_R,
+			CX + Math.cos(rad + half) * OUTER_R,
+			CY + Math.sin(rad + half) * OUTER_R,
+			CX + Math.cos(rad + half) * innerR,
+			CY + Math.sin(rad + half) * innerR,
+			CX + Math.cos(rad - half) * innerR,
+			CY + Math.sin(rad - half) * innerR,
+		];
+	}
+
+	function arcPath(startDeg: number, endDeg: number): string {
+		const a0 = (startDeg * Math.PI) / 180;
+		const a1 = (endDeg * Math.PI) / 180;
+		const sx = CX + Math.cos(a0) * midR;
+		const sy = CY + Math.sin(a0) * midR;
+		const ex = CX + Math.cos(a1) * midR;
+		const ey = CY + Math.sin(a1) * midR;
+		const large = endDeg - startDeg > 180 ? 1 : 0;
+		return `M ${sx} ${sy} A ${midR} ${midR} 0 ${large} 1 ${ex} ${ey}`;
+	}
+
+	// WHY: rounded corners (lerp toward each vertex, then a quadratic through it)
+	// read as soft pills, matching the bklit gauge look.
+	function notchPath([x1, y1, x2, y2, x3, y3, x4, y4]: number[], cornerR: number): string {
+		if (cornerR <= 0) {
+			return `M ${x1} ${y1} L ${x2} ${y2} L ${x3} ${y3} L ${x4} ${y4} Z`;
+		}
+		const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+		const dist = (ax: number, ay: number, bx: number, by: number) => Math.hypot(bx - ax, by - ay);
+		const d12 = dist(x1, y1, x2, y2);
+		const d23 = dist(x2, y2, x3, y3);
+		const d34 = dist(x3, y3, x4, y4);
+		const d41 = dist(x4, y4, x1, y1);
+		const r1 = Math.min(cornerR / d12, 0.49);
+		const r2 = Math.min(cornerR / d23, 0.49);
+		const r3 = Math.min(cornerR / d34, 0.49);
+		const r4 = Math.min(cornerR / d41, 0.49);
+		const p = (ax: number, ay: number, bx: number, by: number, t: number) =>
+			`${lerp(ax, bx, t)} ${lerp(ay, by, t)}`;
+		return (
+			`M ${p(x1, y1, x4, y4, r4)} Q ${x1} ${y1} ${p(x1, y1, x2, y2, r1)} ` +
+			`L ${p(x2, y2, x1, y1, r1)} Q ${x2} ${y2} ${p(x2, y2, x3, y3, r2)} ` +
+			`L ${p(x3, y3, x2, y2, r2)} Q ${x3} ${y3} ${p(x3, y3, x4, y4, r3)} ` +
+			`L ${p(x4, y4, x3, y3, r3)} Q ${x4} ${y4} ${p(x4, y4, x1, y1, r4)} Z`
+		);
+	}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div
+	class={cn("hr-gauge", className)}
+	style:width={size ? `${size}px` : "100%"}
+	style:min-width="{minWidth}px"
+	role="img"
+	aria-label={ariaLabel
+		? `${ariaLabel}: ${Math.round(clamped)}%`
+		: `Gauge at ${Math.round(clamped)}%`}
+>
+	<!-- no-inline-svg-ignore -->
+	<svg viewBox="0 0 100 100" aria-hidden="true">
+		{#if effGradient}
+			<defs>
+				<linearGradient id={gradientId} gradientUnits="userSpaceOnUse" x1="8" y1="0" x2="92" y2="0">
+					<stop offset="0%" stop-color={gradStops[0]} />
+					<stop offset="100%" stop-color={gradStops[1]} />
+				</linearGradient>
+			</defs>
+		{/if}
+		{#if variant === "ring"}
+			<path
+				class="ring-track"
+				d={ringTrack}
+				stroke={trackFill}
+				stroke-opacity={inactiveFillOpacity}
+				style:stroke-width="{band}px"
+			/>
+			<path
+				class="ring-fill"
+				d={ringTrack}
+				pathLength="100"
+				stroke={activePaint}
+				style:stroke-width="{band}px"
+				style:stroke-dashoffset={ringOffset}
+			/>
+		{:else}
+			{#each notches as notch (notch.index)}
+				<path class="track" d={notch.d} fill={trackFill} fill-opacity={inactiveFillOpacity} />
+			{/each}
+			{#each notches as notch (notch.index)}
+				{#if notch.active}
+					<path
+						class="fill"
+						d={notch.d}
+						fill={activePaint}
+						fill-opacity={activeFillOpacity}
+						style:animation-delay="{100 + notch.index * 18}ms"
+					/>
+				{/if}
+			{/each}
+		{/if}
+	</svg>
+
+	{#if showValue}
+		<div class="center">
+			<span class="value">
+				<AnimatedValue value={center} {formatOptions} {locale} {prefix} {suffix} />
+			</span>
+			{#if effLabel}
+				<span class="label">{effLabel}</span>
+			{/if}
+		</div>
+	{/if}
+</div>

package/src/charts/hover-band.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { hoverBand } from "./hover-band.js";
+
+const center = (b: { x: number; width: number } | null) => (b ? b.x + b.width / 2 : NaN);
+
+describe("hoverBand", () => {
+  it("centers on the point when the gaps are even", () => {
+    expect(hoverBand([0, 100, 200], 1, 300)).toEqual({ x: 20, width: 160 });
+  });
+
+  it("stays centered when the gaps differ", () => {
+    const b = hoverBand([0, 40, 200], 1, 300);
+    expect(center(b)).toBe(40);
+    expect(b?.width).toBe(64);
+  });
+
+  it("stays centered at either end of the line", () => {
+    expect(center(hoverBand([0, 100, 200], 0, 300))).toBe(0);
+    expect(center(hoverBand([0, 100, 200], 2, 300))).toBe(200);
+  });
+
+  it("falls back to the plot width for a single point", () => {
+    expect(hoverBand([50], 0, 100)).toEqual({ x: -30, width: 160 });
+  });
+
+  it("returns null for an index off the data", () => {
+    expect(hoverBand([0, 100], -1, 300)).toBeNull();
+    expect(hoverBand([0, 100], 2, 300)).toBeNull();
+  });
+});

package/src/charts/hover-band.ts

@@ -0,0 +1,21 @@
+/** How far the hover band reaches each side of the point, as a share of the gap to its neighbour. */
+export const HOVER_BAND_REACH = 0.8;
+
+/**
+ * The hovered segment's clip, centered on the point at `xs[i]`.
+ * Both sides take the shorter neighbour gap, so the dot always sits in the middle.
+ */
+export function hoverBand(
+  xs: number[],
+  i: number,
+  width: number,
+  reach = HOVER_BAND_REACH,
+): { x: number; width: number } | null {
+  if (i < 0 || i >= xs.length) return null;
+  const at = xs[i];
+  const before = i > 0 ? at - xs[i - 1] : Infinity;
+  const after = i < xs.length - 1 ? xs[i + 1] - at : Infinity;
+  const gap = Math.min(before, after);
+  const half = (Number.isFinite(gap) ? gap : width) * reach;
+  return { x: at - half, width: half * 2 };
+}

package/src/charts/hover-focus.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { getChartContext } from "layerchart";
+	import type { Snippet } from "svelte";
+	import { prefersReducedMotion, Spring } from "svelte/motion";
+	import { fade } from "svelte/transition";
+	import { HOVER_BAND_REACH, hoverBand } from "./hover-band.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		/** The series: dims while a point is hovered. */
+		children: Snippet;
+		/** The strokes alone, redrawn at full strength around the hovered point. */
+		segment: Snippet;
+		/** Headroom above and below the plot so a thick stroke is not cut. */
+		bleed?: number;
+		/** How far the band reaches each side of the point, as a share of the gap to its neighbour. */
+		reach?: number;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let { children, segment, bleed = 6, reach = HOVER_BAND_REACH }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const ctx = getChartContext();
+	const id = `hr-focus-${Math.random().toString(36).slice(2, 8)}`;
+	const left = new Spring(0, { stiffness: 0.2, damping: 0.85 });
+	const width = new Spring(0, { stiffness: 0.2, damping: 0.85 });
+
+	// =========================
+	// DERIVED
+	// =========================
+	const band = $derived.by(() => {
+		const d = ctx.tooltip.data;
+		const xs = (ctx.data as unknown[]).map((r) => Number(ctx.xGet(r)));
+		// WHY by x and not indexOf: ctx.data hands back proxies, so identity never matches.
+		const at = d ? Number(ctx.xGet(d)) : NaN;
+		return hoverBand(xs, xs.indexOf(at), ctx.width, reach);
+	});
+	const duration = $derived(prefersReducedMotion.current ? 0 : 400);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	// WHY instant on first hover: the clip should open where the pointer is, not
+	// slide in from wherever it last closed.
+	let wasOn = false;
+	$effect(() => {
+		if (!band) {
+			wasOn = false;
+			return;
+		}
+		const instant = !wasOn || prefersReducedMotion.current;
+		left.set(band.x, { instant });
+		width.set(band.width, { instant });
+		wasOn = true;
+	});
+</script>
+
+<!-- =========================== -->
+<!-- HOVER FOCUS -->
+<!-- =========================== -->
+<g class="hr-hover-dim" class:hr-hover-dimmed={band !== null}>
+	{@render children()}
+</g>
+<!-- WHY outside the if: the segment fades out after hover ends, and without its
+     clip it would flash as the whole line. -->
+<defs>
+	<clipPath {id}>
+		<rect x={left.current} y={-bleed} width={width.current} height={ctx.height + bleed * 2} />
+	</clipPath>
+</defs>
+{#if band}
+	<g clip-path="url(#{id})" transition:fade={{ duration }}>
+		{@render segment()}
+	</g>
+{/if}

package/src/charts/index.ts

@@ -0,0 +1,30 @@
+import "./charts.css";
+
+export { default as BarChart } from "./bar-chart.svelte";
+export { default as AreaChart } from "./area-chart.svelte";
+export { default as LineChart } from "./line-chart.svelte";
+export { default as DonutChart } from "./donut-chart.svelte";
+export { default as Sparkline } from "./sparkline.svelte";
+export { default as TimeSeriesChart } from "./time-series-chart.svelte";
+export { default as GaugeChart } from "./gauge-chart.svelte";
+export { default as RingChart } from "./ring-chart.svelte";
+export { default as Legend } from "./legend.svelte";
+export { default as StatCard } from "./stat-card.svelte";
+export { default as NumberChart, type NumberDirection } from "./number-chart.svelte";
+export { default as Figure } from "./figure.svelte";
+export { default as TrendPill } from "./trend-pill.svelte";
+export { default as AnimatedValue } from "./animated-value.svelte";
+export { default as EdgeFade } from "./edge-fade.svelte";
+export { resolveEdgeFade, EDGE_FADE_DEFAULT } from "./edge-fade.js";
+
+export {
+  ChartContainer,
+  ChartTooltip,
+  ChartStyle,
+  type ChartConfig,
+  type TooltipSeriesItem,
+  getPayloadConfigFromPayload,
+  useChart,
+  setChartContext,
+  THEMES,
+} from "./primitives/index.js";

package/src/charts/legend.css

@@ -0,0 +1,131 @@
+/* Styles for Legend. Plain stylesheet (see area-chart.css for why). Selectors
+   are namespaced under `.hr-legend`; the `.horizontal` layout modifier sits on
+   the same root element. */
+
+.hr-legend {
+  width: 100%;
+  font-size: 0.8125rem;
+}
+
+.hr-legend-title {
+  margin: 0 0 0.625rem;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--foreground);
+}
+
+.hr-legend-items {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.hr-legend.horizontal .hr-legend-items {
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: 0.5rem 1rem;
+}
+
+.hr-legend-item {
+  width: 100%;
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 0.5rem 0.625rem;
+  padding: 0.375rem 0.5rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  font: inherit;
+  color: var(--foreground);
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background 160ms ease,
+    opacity 160ms ease;
+}
+
+.hr-legend.horizontal .hr-legend-item {
+  width: auto;
+  grid-template-columns: auto auto;
+  padding: 0.25rem 0.375rem;
+}
+
+.hr-legend-item:hover,
+.hr-legend-item:focus-visible {
+  background: var(--muted);
+  outline: none;
+}
+
+.hr-legend-item.dimmed {
+  opacity: 0.4;
+}
+
+.hr-legend-marker {
+  width: 0.625rem;
+  height: 0.625rem;
+  border-radius: 3px;
+  flex-shrink: 0;
+}
+
+.hr-legend-label {
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hr-legend-value {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.3125rem;
+  font-variant-numeric: tabular-nums;
+  color: var(--foreground);
+  white-space: nowrap;
+}
+
+.hr-legend-pct {
+  font-size: 0.6875rem;
+  color: var(--muted-foreground);
+}
+
+.hr-legend-track {
+  grid-column: 1 / -1;
+  height: 0.375rem;
+  border-radius: 999px;
+  background: var(--muted);
+  overflow: hidden;
+}
+
+.hr-legend-bar {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: 999px;
+  /* WHY: scaleX from the left avoids the layout thrash of animating width;
+	   the bar's fill fraction is set inline as --hr-bar-scale. The entrance
+	   sweeps from 0 once (delays match the ring sweep); the transition takes
+	   over for later data changes. */
+  transform-origin: left center;
+  transform: scaleX(var(--hr-bar-scale, 0));
+  animation: hr-legend-fill var(--chart-motion-reveal, 1100ms)
+    var(--chart-ease-reveal, cubic-bezier(0.85, 0, 0.15, 1)) both;
+  transition: transform var(--chart-motion-slow, 1.1s)
+    var(--chart-ease-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+@keyframes hr-legend-fill {
+  from {
+    transform: scaleX(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hr-legend-bar {
+    animation: none;
+    transition: none;
+  }
+}