@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/charts/donut-chart.svelte

@@ -0,0 +1,158 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./donut-chart.css";
+	import { Arc, Chart, Group, Pie, Svg, Text } from "layerchart";
+	import { scaleOrdinal } from "d3-scale";
+	import { expoInOut } from "svelte/easing";
+	import { prefersReducedMotion, Tween } from "svelte/motion";
+	import { REVEAL_MS } from "./motion.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		data: TData[];
+		valueKey: keyof TData & string;
+		labelKey: keyof TData & string;
+		colorKey?: keyof TData & string;
+		height?: number;
+		innerRadius?: number;
+		outerRadius?: number;
+		/** Center label shown when nothing is hovered */
+		centerLabel?: string;
+		/** Format the center value */
+		formatValue?: (v: number) => string;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		data,
+		valueKey,
+		labelKey,
+		colorKey,
+		height = 240,
+		innerRadius = 60,
+		outerRadius = 100,
+		centerLabel,
+		formatValue = (v) => v.toLocaleString(),
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let hovered = $state<string | null>(null);
+	// Milliseconds into the entrance; each slice sweeps on its own offset.
+	const clock = new Tween(0);
+	let swept = $state(false);
+	let started = false;
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	const SLICE_DELAY = 100;
+	const SLICE_STEP = 80;
+	const HOVER_OFFSET = 6;
+
+	function sweep(i: number): number {
+		if (swept) return 1;
+		const t = (clock.current - SLICE_DELAY - i * SLICE_STEP) / REVEAL_MS;
+		return expoInOut(Math.min(1, Math.max(0, t)));
+	}
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		if (started || filtered.length === 0) return;
+		started = true;
+		const end = SLICE_DELAY + (filtered.length - 1) * SLICE_STEP + REVEAL_MS;
+		const duration = prefersReducedMotion.current ? 0 : end;
+		clock.set(end, { duration }).then(() => (swept = true));
+	});
+
+	// =========================
+	// DERIVED
+	// =========================
+	const filtered = $derived(data.filter((d) => Number(d[valueKey] ?? 0) > 0));
+	const total = $derived(filtered.reduce((sum, d) => sum + Number(d[valueKey] ?? 0), 0));
+	const idAccessor = $derived((d: TData) => String(d[labelKey] ?? ""));
+	const colorRange = $derived(colorKey ? filtered.map((d) => String(d[colorKey] ?? "")) : []);
+	const colorDomain = $derived(filtered.map(idAccessor));
+	const hoveredItem = $derived(filtered.find((d) => idAccessor(d) === hovered) ?? null);
+</script>
+
+<!-- =========================== -->
+<!-- DONUT CHART -->
+<!-- =========================== -->
+<div
+	class="hr-donut-chart {className ?? ''}"
+	style:height="{height}px"
+	role="img"
+	aria-label="{centerLabel ?? 'Donut chart'}: {formatValue(total)} total"
+>
+	{#if filtered.length === 0}
+		<div class="empty">
+			<p>No data</p>
+		</div>
+	{:else}
+		<Chart
+			data={filtered}
+			x={valueKey}
+			c={colorKey ? idAccessor : undefined}
+			cScale={scaleOrdinal()}
+			cDomain={colorDomain}
+			cRange={colorRange}
+		>
+			<Svg>
+				<Group center>
+					<Pie {innerRadius} {outerRadius} cornerRadius={3} padAngle={0.02} sort={null}>
+						{#snippet children({ arcs })}
+							{#each arcs as arc, i (i)}
+								{@const id = idAccessor(arc.data as TData)}
+								{@const isHovered = hovered === id}
+								{@const dimmed = hovered !== null && !isHovered}
+								{@const mid = (arc.startAngle + arc.endAngle) / 2}
+								{@const dx = isHovered ? Math.sin(mid) * HOVER_OFFSET : 0}
+								{@const dy = isHovered ? -Math.cos(mid) * HOVER_OFFSET : 0}
+								<Arc
+									startAngle={arc.startAngle}
+									endAngle={arc.startAngle + (arc.endAngle - arc.startAngle) * sweep(i)}
+									padAngle={arc.padAngle}
+									{innerRadius}
+									{outerRadius}
+									cornerRadius={3}
+									fill={colorKey
+										? String((arc.data as TData)[colorKey])
+										: `var(--chart-${(i % 5) + 1})`}
+									class="hr-donut-arc"
+									data-hovered={isHovered ? "" : undefined}
+									style="opacity: {dimmed ? 0.4 : 1}; translate: {dx}px {dy}px"
+									onmouseenter={() => (hovered = id)}
+									onmouseleave={() => (hovered = null)}
+								/>
+							{/each}
+						{/snippet}
+					</Pie>
+					<Text
+						value={hoveredItem ? formatValue(Number(hoveredItem[valueKey])) : formatValue(total)}
+						textAnchor="middle"
+						dy={-4}
+						class="hr-donut-center-value"
+					/>
+					<Text
+						value={hoveredItem ? String(hoveredItem[labelKey]) : (centerLabel ?? "Total")}
+						textAnchor="middle"
+						dy={14}
+						class="hr-donut-center-label"
+					/>
+				</Group>
+			</Svg>
+		</Chart>
+	{/if}
+</div>

package/src/charts/edge-fade.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { EDGE_FADE_DEFAULT } from "./edge-fade.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		/** Mask id. Apply it to the shape with `mask="url(#id)"`. */
+		id: string;
+		/** Fraction of the shape's width faded at each side, 0-0.45. */
+		amount?: number;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let { id, amount = EDGE_FADE_DEFAULT }: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	const stop = $derived(Math.min(0.45, Math.max(0, amount)));
+</script>
+
+<!-- =========================== -->
+<!-- EDGE FADE -->
+<!-- =========================== -->
+<!-- WHY: the fill gradient of an area is vertical, so the horizontal fade cannot ride on it. A luminance mask in objectBoundingBox units needs no pixel -->
+<!-- dimensions: the ramp is expressed as a fraction of the masked path's own box, so it follows the plot width through every resize. -->
+<defs>
+	<linearGradient id="{id}-ramp" x1="0" y1="0" x2="1" y2="0">
+		<stop offset="0" stop-color="#fff" stop-opacity="0" />
+		<stop offset={stop} stop-color="#fff" stop-opacity="1" />
+		<stop offset={1 - stop} stop-color="#fff" stop-opacity="1" />
+		<stop offset="1" stop-color="#fff" stop-opacity="0" />
+	</linearGradient>
+	<mask {id} maskContentUnits="objectBoundingBox">
+		<rect x="0" y="0" width="1" height="1" fill="url(#{id}-ramp)" />
+	</mask>
+</defs>

package/src/charts/edge-fade.ts

@@ -0,0 +1,16 @@
+/** `true` fades this much of the width at each side. */
+export const EDGE_FADE_DEFAULT = 0.08;
+
+/**
+ * Turns an `edgeFade` prop into the fraction of the width to fade at each side.
+ * `false` (or 0) means no mask is rendered at all.
+ */
+export function resolveEdgeFade(
+  value: boolean | number | undefined,
+  fallback = EDGE_FADE_DEFAULT,
+): number {
+  if (value === false) return 0;
+  if (value === true || value == null) return fallback;
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(0.45, Math.max(0, value));
+}

package/src/charts/figure.css

@@ -0,0 +1,100 @@
+/* Styles for Figure. Plain stylesheet (see area-chart.css for why). All
+   selectors are already namespaced under `.hr-figure`. */
+
+.hr-figure {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1875rem;
+  min-width: 0;
+}
+.hr-figure[data-align="center"] {
+  align-items: center;
+  text-align: center;
+}
+
+/* WHY the title truncates: title and pill share one narrow row (the gauge card
+   leaves it ~160px), and a shrunken title box let the word paint over the pill. */
+.hr-figure-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+.hr-figure-title {
+  display: flex;
+  align-items: center;
+  gap: 0.4375rem;
+  min-width: 0;
+  font-size: 0.9375rem;
+  font-weight: 600;
+  color: var(--foreground, oklch(0.2 0.01 286));
+  letter-spacing: -0.005em;
+}
+.hr-figure-title-text {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.hr-figure-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.hr-figure-values {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  align-items: baseline;
+}
+.hr-figure-value-row {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.375rem;
+}
+
+.hr-figure-value {
+  font-feature-settings: "tnum";
+  line-height: 1.1;
+  transition: color 180ms ease;
+}
+/* md: chart header (monospace, compact). */
+.hr-figure[data-size="md"] .hr-figure-value {
+  font-size: 1.25rem;
+  font-weight: 600;
+  font-family: ui-monospace, SFMono-Regular, monospace;
+}
+/* lg: KPI card headline. */
+.hr-figure[data-size="lg"] .hr-figure-value {
+  font-size: 1.875rem;
+  font-weight: 700;
+  line-height: 1;
+  letter-spacing: -0.025em;
+  color: var(--foreground, oklch(0.2 0.01 286));
+}
+
+.hr-figure-series-label {
+  font-size: 0.6875rem;
+}
+
+/* The readable form of a series colour: see the note in figure.svelte. The wash
+   and the line keep the raw hue; only text is pulled toward the foreground. */
+.hr-figure-value.is-series,
+.hr-figure-series-label.is-series {
+  color: color-mix(
+    in oklab,
+    var(--hr-series, currentColor) 70%,
+    var(--foreground, oklch(0.2 0.01 286))
+  );
+}
+.hr-figure-caption {
+  font-size: 0.75rem;
+  color: var(--muted-foreground, oklch(0.5 0.01 286));
+}
+.hr-figure-eyebrow {
+  font-size: 0.6875rem;
+  color: var(--chart-label, var(--muted-foreground, oklch(0.5 0.01 286)));
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}

package/src/charts/figure.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./figure.css";
+	import { cn } from "@heyramzi/utils";
+	import type { Snippet } from "svelte";
+	import AnimatedValue from "./animated-value.svelte";
+	import TrendPill from "./trend-pill.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Trend = "up" | "down" | "neutral";
+	type SeriesValue = { value: number; label?: string; color?: string };
+
+	type Props = {
+		/** Single metric value. Numbers count up via AnimatedValue. Ignored when `series` is set. */
+		value?: number | string;
+		/** Multiple value rows (chart headers with more than one series). */
+		series?: SeriesValue[];
+		/** Single-value color. */
+		color?: string;
+		/** Title above the value (KPI card). Pairs with `delta` for a trend pill. */
+		title?: string;
+		/** Percentage change; renders a TrendPill beside the title. */
+		delta?: number;
+		trend?: Trend;
+		/** Sub-caption under the value. */
+		caption?: string;
+		/** Uppercase context label under the value (chart headers, e.g. "JUN"). */
+		eyebrow?: string;
+		/** Left header (md, monospace) vs centered overlay reuse later. */
+		align?: "start" | "center";
+		/** Value scale: md = chart header, lg = KPI card. */
+		size?: "md" | "lg";
+		format?: (v: number) => string;
+		formatOptions?: Intl.NumberFormatOptions;
+		locale?: string;
+		animate?: boolean;
+		/** Leading icon before the title. */
+		icon?: Snippet;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		value,
+		series,
+		color,
+		title,
+		delta,
+		trend,
+		caption,
+		eyebrow,
+		align = "start",
+		size = "md",
+		format,
+		formatOptions,
+		locale,
+		animate = true,
+		icon,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	const rows = $derived(series && series.length > 0 ? series : null);
+</script>
+
+<!-- =========================== -->
+<!-- FIGURE -->
+<!-- =========================== -->
+<div class={cn("hr-figure", className)} data-align={align} data-size={size}>
+	{#if title}
+		<div class="hr-figure-head">
+			<span class="hr-figure-title">
+				{#if icon}<span class="hr-figure-icon" style:color>{@render icon()}</span>{/if}
+				<span class="hr-figure-title-text">{title}</span>
+			</span>
+			{#if delta != null}
+				<TrendPill {delta} {trend} />
+			{/if}
+		</div>
+	{/if}
+
+	{#if rows}
+		<div class="hr-figure-values">
+			{#each rows as row, i (i)}
+				<!-- WHY the series colour goes in as a custom property rather than as `color`: a palette entry is picked to read as a line on a chart, which -->
+				<!-- is a 3:1 job, and the same value as 11px text measured 2.7:1. The stylesheet mixes it toward the page foreground, so the number still -->
+				<!-- names its series and the text still clears AA in either theme. -->
+				<span class="hr-figure-value-row" style:--hr-series={row.color}>
+					<span class="hr-figure-value is-series">
+						<AnimatedValue value={row.value} {format} {formatOptions} {locale} duration={450} />
+					</span>
+					{#if rows.length > 1 && row.label}
+						<span class="hr-figure-series-label is-series">{row.label}</span>
+					{/if}
+				</span>
+			{/each}
+		</div>
+	{:else if value != null}
+		<span class="hr-figure-value" style:color>
+			{#if typeof value === "number" && animate}
+				<AnimatedValue {value} {format} {formatOptions} {locale} duration={600} />
+			{:else}
+				{value}
+			{/if}
+		</span>
+	{/if}
+
+	{#if caption}
+		<span class="hr-figure-caption">{caption}</span>
+	{/if}
+	{#if eyebrow}
+		<span class="hr-figure-eyebrow">{eyebrow}</span>
+	{/if}
+</div>

package/src/charts/gauge-chart.css

@@ -0,0 +1,94 @@
+/* Styles for GaugeChart. Plain stylesheet (see area-chart.css for why).
+   Selectors are namespaced under `.hr-gauge` (the generic ones below would
+   otherwise collide with RingChart's identical `.value`/`.label`/`.center`/
+   `.fill`/`svg` names once they are no longer Svelte-scoped). */
+
+.hr-gauge {
+  position: relative;
+  display: inline-grid;
+  place-items: center;
+  aspect-ratio: 1;
+  container-type: size;
+}
+
+.hr-gauge svg {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+.hr-gauge .center {
+  grid-area: 1 / 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.15cqmin;
+  /* WHY: keep the readout inside the inner ring so long values never collide
+	   with the notches. */
+  max-width: 62cqmin;
+  pointer-events: none;
+}
+
+.hr-gauge .value {
+  font-size: max(0.78rem, 11cqmin);
+  font-weight: 650;
+  line-height: 1;
+  letter-spacing: -0.02em;
+  font-variant-numeric: tabular-nums;
+  color: var(--foreground);
+}
+
+.hr-gauge .label {
+  margin-top: 1.5cqmin;
+  font-size: max(0.5rem, 5cqmin);
+  font-weight: 500;
+  white-space: nowrap;
+  color: var(--muted-foreground);
+}
+
+/* WHY: active paint comes from the fill attribute (flat or gradient url), so
+   no CSS fill here, which would override it. */
+.hr-gauge .fill {
+  /* WHY: each active notch fades up in arc order; the per-notch stagger
+	   sweeps the colour around the arc so the gauge reads as filling, instead
+	   of every notch popping in from the centre at once. */
+  animation: hr-gauge-notch-in 0.3s var(--chart-ease-out, cubic-bezier(0.22, 1, 0.36, 1)) both;
+}
+
+@keyframes hr-gauge-notch-in {
+  from {
+    opacity: 0;
+  }
+}
+
+.hr-gauge .ring-track,
+.hr-gauge .ring-fill {
+  fill: none;
+  stroke-linecap: round;
+}
+
+.hr-gauge .ring-fill {
+  stroke-dasharray: 100;
+  transition: stroke-dashoffset var(--chart-motion-slow, 1.1s)
+    var(--chart-ease-out, cubic-bezier(0.22, 1, 0.36, 1));
+  animation: hr-gauge-ring-sweep var(--chart-motion-reveal, 1100ms)
+    var(--chart-ease-reveal, cubic-bezier(0.85, 0, 0.15, 1)) both;
+}
+
+@keyframes hr-gauge-ring-sweep {
+  from {
+    stroke-dashoffset: 100;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hr-gauge .fill {
+    animation: none;
+  }
+  .hr-gauge .ring-fill {
+    transition: none;
+    animation: none;
+  }
+}