@heyramzi/ui 0.0.0-stage → 6.0.1

package/src/animations/tooltip.css

@@ -0,0 +1,72 @@
+/* Transitions.dev — Tooltip open / close */
+/* Source: https://github.com/Jakubantalik/transitions.dev */
+
+/*
+  Usage:
+      <span class="t-tt-wrap">
+        <button class="t-tt-trigger" aria-describedby="tt-1">…</button>
+        <span class="t-tt" id="tt-1" role="tooltip">Tooltip text</span>
+      </span>
+
+  Pure CSS — no JS. The wrap (not the trigger) is the hover
+  target so the pointer can drift onto the tooltip without
+  flicker. transition-delay only applies in the hover/focus
+  rule, so leaving snaps it to 0 and the disappear plays
+  immediately.
+*/
+
+:root {
+  --tt-in-dur: var(--duration-quick, 150ms);
+  --tt-out-dur: 50ms;
+  --tt-scale: var(--scale-small, 0.98);
+  --tt-delay: 80ms;
+  --tt-in-ease: var(--ease-out, ease-out);
+  --tt-out-ease: var(--ease-out, ease-out);
+  --tt-bg: #ffffff;
+  --tt-fg: #2f2f2f;
+}
+
+.t-tt-wrap {
+  position: relative;
+  display: inline-block;
+}
+.t-tt {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 50%;
+  transform: translate(-50%, 0) scale(var(--tt-scale));
+  transform-origin: 50% 100%;
+  padding: 8px 12px;
+  border-radius: 8px;
+  background: var(--tt-bg);
+  color: var(--tt-fg);
+  white-space: nowrap;
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.06),
+    0 2px 6px 0 rgba(0, 0, 0, 0.05),
+    0 4px 42px 0 rgba(0, 0, 0, 0.06);
+  opacity: 0;
+  pointer-events: none;
+  /* Default rule controls the LEAVE state. transition-delay
+	   stays unset so leaving plays without delay. */
+  transition:
+    opacity var(--tt-out-dur) var(--tt-out-ease),
+    transform var(--tt-out-dur) var(--tt-out-ease);
+}
+/* The delay belongs ONLY to the hover rule so leaving the
+   trigger snaps the delay back to 0 and the disappear plays
+   immediately. */
+.t-tt-wrap:hover .t-tt,
+.t-tt-trigger:focus-visible + .t-tt {
+  opacity: 1;
+  transform: translate(-50%, 0) scale(1);
+  transition-duration: var(--tt-in-dur);
+  transition-timing-function: var(--tt-in-ease);
+  transition-delay: var(--tt-delay);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-tt {
+    transition: none !important;
+  }
+}

package/src/animations/upstream-coverage.test.ts

@@ -0,0 +1,65 @@
+/*
+ * The free transitions.dev catalogue has to stay fully owned.
+ */
+
+/*
+ * `pnpm sync:transitions` reports an unowned slug, but only when someone runs it.
+ */
+
+/*
+ * This asserts the same contract offline, off the lockfile, so a sync that lands a new upstream transition cannot be committed without a home for it.
+ */
+
+/*
+ * The homes are not all in this folder: five live on the component that already did the job. See README.md.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { describe, expect, it } from "vite-plus/test";
+
+/** The runner's cwd is the workspace root or the package; find the package. */
+function packageRoot(): string {
+  let dir = process.cwd();
+  for (;;) {
+    if (existsSync(join(dir, ".upstream", "transitions.lock.json"))) return dir;
+    const candidate = join(dir, "packages", "ui");
+    if (existsSync(join(candidate, ".upstream", "transitions.lock.json"))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error("transitions.lock.json not found");
+    dir = parent;
+  }
+}
+
+type Lock = {
+  free: number;
+  entries: Record<string, { name: string; sha256: string; local: string | null }>;
+};
+
+const PKG = packageRoot();
+const SRC = resolve(PKG, "src");
+const lock: Lock = JSON.parse(
+  readFileSync(join(PKG, ".upstream", "transitions.lock.json"), "utf8"),
+);
+
+describe("transitions.dev coverage", () => {
+  it("vendors every free transition", () => {
+    expect(Object.keys(lock.entries)).toHaveLength(lock.free);
+  });
+
+  it("gives every free transition an owner that exists", () => {
+    const orphans = Object.entries(lock.entries)
+      .filter(([, entry]) => !entry.local || !existsSync(resolve(SRC, entry.local)))
+      .map(([slug, entry]) => `${slug} -> ${entry.local ?? "(nothing)"}`);
+    expect(orphans).toEqual([]);
+  });
+
+  it("keeps the barrel importing every file in this folder", () => {
+    const dir = join(SRC, "animations");
+    const barrel = readFileSync(join(dir, "index.css"), "utf8");
+    const missing = readdirSync(dir)
+      .filter((file) => file.endsWith(".css") && file !== "index.css")
+      .filter((file) => !barrel.includes(`"./${file}"`));
+    expect(missing).toEqual([]);
+  });
+});

package/src/animations/view-transition-reveal.ts

@@ -0,0 +1,74 @@
+export type ViewTransitionRevealOrigin = MouseEvent | { x: number; y: number } | HTMLElement;
+
+export type ViewTransitionRevealOptions = {
+  duration?: number;
+  easing?: string;
+};
+
+const STYLE_ID = "heyramzi-view-transition-reveal";
+
+export function viewTransitionReveal(
+  origin: ViewTransitionRevealOrigin,
+  apply: () => void,
+  options?: ViewTransitionRevealOptions,
+): void {
+  const prefersReduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  // WHY: feature-detect both API presence and reduced-motion to keep callers
+  // from having to branch.
+  if (typeof document === "undefined" || !document.startViewTransition || prefersReduced) {
+    apply();
+    return;
+  }
+
+  const { x, y } = resolveOrigin(origin);
+  const duration = options?.duration ?? 400;
+  const easing = options?.easing ?? "ease-in-out";
+  const endRadius = Math.hypot(
+    Math.max(x, window.innerWidth - x),
+    Math.max(y, window.innerHeight - y),
+  );
+
+  ensureStyles();
+
+  const transition = document.startViewTransition(() => {
+    apply();
+  });
+
+  transition.ready.then(() => {
+    document.documentElement.animate(
+      {
+        clipPath: [`circle(0px at ${x}px ${y}px)`, `circle(${endRadius}px at ${x}px ${y}px)`],
+      },
+      {
+        duration,
+        easing,
+        pseudoElement: "::view-transition-new(root)",
+      },
+    );
+  });
+}
+
+function resolveOrigin(origin: ViewTransitionRevealOrigin): { x: number; y: number } {
+  if (origin instanceof HTMLElement) {
+    const rect = origin.getBoundingClientRect();
+    return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+  }
+  if (typeof MouseEvent !== "undefined" && origin instanceof MouseEvent) {
+    const target = origin.currentTarget instanceof HTMLElement ? origin.currentTarget : null;
+    if (target) {
+      const rect = target.getBoundingClientRect();
+      return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+    }
+    return { x: origin.clientX, y: origin.clientY };
+  }
+  return { x: origin.x, y: origin.y };
+}
+
+function ensureStyles(): void {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `::view-transition-old(root),::view-transition-new(root){animation:none;mix-blend-mode:normal;}`;
+  document.head.appendChild(style);
+}

package/src/charts/animated-value.css

@@ -0,0 +1,7 @@
+/* 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;
+}

package/src/charts/animated-value.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./animated-value.css";
+	import { untrack } from "svelte";
+	import { cn } from "@heyramzi/utils";
+
+	// =========================
+	// TYPES
+	// =========================
+	type 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;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		value,
+		decimals = 0,
+		duration = 800,
+		format,
+		formatOptions,
+		locale,
+		prefix,
+		suffix,
+		class: className,
+		style,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let displayed = $state(0);
+	let started = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	const formatter = $derived(formatOptions ? new Intl.NumberFormat(locale, formatOptions) : null);
+	const currentValue = $derived(started ? displayed : value);
+	const text = $derived(
+		format
+			? format(currentValue)
+			: formatter
+				? formatter.format(currentValue)
+				: currentValue.toFixed(decimals),
+	);
+
+	// ========================= EFFECTS ========================= WHY: $effect only runs in the browser, so SSR renders the final value (no flash).
+
+	// `value` is the sole tracked dependency; `displayed` is read and written inside untrack() so the per-frame writes don't retrigger the effect (that self-dependency loops and Svelte bails, freezing the number).
+
+	// The first run sweeps from 0; later value changes tween from the current display.
+	$effect(() => {
+		const target = value;
+		let raf = 0;
+		untrack(() => {
+			const reduced =
+				typeof window !== "undefined" &&
+				window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+			const from = started ? displayed : 0;
+			started = true;
+
+			// WHY: snap (no tween) when motion is off, the delta is tiny, or the tab
+
+			// is hidden. rAF is paused in background tabs, so animating there would leave the number stale until the tab is shown; snapping keeps it correct.
+			if (reduced || document.hidden || Math.abs(target - from) < 0.005) {
+				displayed = target;
+				return;
+			}
+
+			const start = performance.now();
+			const tick = (now: number) => {
+				const t = Math.min((now - start) / duration, 1);
+				const eased = 1 - (1 - t) ** 3;
+				displayed = from + (target - from) * eased;
+				if (t < 1) raf = requestAnimationFrame(tick);
+			};
+			raf = requestAnimationFrame(tick);
+		});
+		return () => cancelAnimationFrame(raf);
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<span class={cn("hr-animated-value tabular-nums", className)} {style}
+	>{prefix ?? ""}{text}{suffix ?? ""}</span
+>

package/src/charts/area-chart.css

@@ -0,0 +1,29 @@
+/* Styles for AreaChart. 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-area-chart`. */
+
+.hr-area-chart {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.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

@@ -0,0 +1,195 @@
+<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";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Series = {
+		key: keyof TData & string;
+		label?: string;
+		color?: string;
+	};
+
+	type 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;
+		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,
+		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 yMax = $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))));
+	});
+	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" />
+					<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;
+  }
+}