@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/charts/number-chart.svelte

@@ -0,0 +1,177 @@
+<script lang="ts" module>
+	/**
+	 * Which way a metric has to move to be good news.
+	 */
+
+	/*
+	 * `neutral` is the honest answer for a figure that is neither on its own: spend is not a win or a loss until the return is beside it.
+	 */
+	export type NumberDirection = "up-good" | "down-good" | "neutral";
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./number-chart.css";
+	import { Minus, TrendDown, TrendUp } from "phosphor-svelte";
+	import { cn } from "@heyramzi/utils";
+	import type { Snippet } from "svelte";
+	import AnimatedValue from "./animated-value.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		/** Metric name, above the figure. */
+		label: string;
+		/**
+		 * The figure.
+		 */
+
+		/*
+		 * A number counts up and is formatted here; a string is taken as already formatted and is printed as it stands, which is the only way to draw a total
+		 */
+
+		/*
+		 * that mixes two currencies.
+		 */
+		value: number | string;
+		/** Formatter for a numeric `value`. Wins over `formatOptions`. */
+		format?: (v: number) => string;
+		/** Intl options for a numeric `value` (currency, compact, percent). */
+		formatOptions?: Intl.NumberFormatOptions;
+		/** BCP-47 locale for `formatOptions`. */
+		locale?: string;
+		/**
+		 * Change against the period before this one, as a percentage. `null` is
+		 * "nothing to compare against", which is not zero and is drawn as a dash.
+		 */
+		delta?: number | null;
+		/** Which way `delta` has to point to be good news. */
+		direction?: NumberDirection;
+		/** Movement below this many points is noise and draws as a dash. */
+		deltaThreshold?: number;
+		/**
+		 * The chart. A fraction from 0 to 1 that gives the figure its scale: a share of a total, a run against a target, a rate against its ceiling.
+		 */
+
+		/*
+		 * Omitted, the number stands on its own and no track is drawn.
+		 */
+		share?: number;
+		/** What the track measures, e.g. "of revenue". Only with `share`. */
+		shareLabel?: string;
+		/** Track colour. Defaults to the first series token. */
+		color?: string;
+		/** md is a figure in a row; lg is the one figure the screen exists to answer. */
+		size?: "md" | "lg";
+		/** A quiet line under the figure: the window it covers, or why it is a dash. */
+		caption?: string;
+		/**
+		 * Drop the card chrome. For a figure that sits in a band or a panel of its
+		 * own, where a second border would draw a box inside a box.
+		 */
+		bare?: boolean;
+		/** Leading icon before the label. */
+		icon?: Snippet;
+		/** Rendered at the right of the label row. */
+		trailing?: Snippet;
+		class?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		label,
+		value,
+		format,
+		formatOptions,
+		locale,
+		delta = null,
+		direction = "neutral",
+		deltaThreshold = 0.5,
+		share,
+		shareLabel,
+		color = "var(--chart-1)",
+		size = "md",
+		caption,
+		bare = false,
+		icon,
+		trailing,
+		class: className,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	// Under half a point either way is noise, not a movement, and eight figures
+	// each reporting a 0% move is eight pieces of chrome saying nothing.
+	const move = $derived(delta != null && Math.abs(delta) >= deltaThreshold ? delta : null);
+	// The arrow follows the sign and the colour follows the news, because a cost
+	// that fell is a green figure with a down arrow. One glyph cannot say both.
+	const tone = $derived.by(() => {
+		if (move == null || direction === "neutral") return "flat";
+		const good = direction === "up-good" ? move > 0 : move < 0;
+		return good ? "up" : "down";
+	});
+	const pct = $derived(share == null ? null : Math.max(0, Math.min(1, share)));
+</script>
+
+<!-- =========================== -->
+<!-- NUMBER CHART -->
+<!-- =========================== -->
+<div class={cn("hr-number-chart", className)} data-size={size} data-bare={bare ? "" : undefined}>
+	<p class="hr-number-label">
+		{#if icon}<span class="hr-number-icon" style:color>{@render icon()}</span>{/if}
+		<span class="hr-number-label-text">{label}</span>
+		{#if trailing}<span class="hr-number-trailing">{@render trailing()}</span>{/if}
+	</p>
+
+	<div class="hr-number-row">
+		<span class="hr-number-value">
+			{#if typeof value === "number"}
+				<AnimatedValue {value} {format} {formatOptions} {locale} duration={600} />
+			{:else}
+				{value}
+			{/if}
+		</span>
+		{#if move != null}
+			<span class="hr-number-delta" data-tone={tone}>
+				{#if move > 0}
+					<TrendUp class="hr-number-arrow" weight="bold" />
+				{:else}
+					<TrendDown class="hr-number-arrow" weight="bold" />
+				{/if}
+				<span class="hr-number-delta-text">{Math.abs(move).toFixed(0)}%</span>
+			</span>
+		{:else}
+			<span class="hr-number-delta" data-tone="none" aria-hidden="true">
+				<Minus class="hr-number-arrow" />
+			</span>
+		{/if}
+	</div>
+
+	{#if pct != null}
+		<!-- WHY the number gets a rail and not a sparkline: one figure has no series to plot, and the question a lone number cannot answer is "out of -->
+		<!-- what". The rail answers exactly that and nothing else. -->
+		<div
+			class="hr-number-track"
+			role="img"
+			aria-label="{label}: {Math.round(pct * 100)}% {shareLabel ?? 'of the total'}"
+		>
+			<span class="hr-number-fill" style:width="{pct * 100}%" style:background={color}></span>
+		</div>
+	{/if}
+
+	{#if shareLabel && pct != null}
+		<p class="hr-number-caption">
+			<span class="hr-number-share">{Math.round(pct * 100)}%</span>
+			{shareLabel}
+		</p>
+	{/if}
+	{#if caption}
+		<p class="hr-number-caption">{caption}</p>
+	{/if}
+</div>

package/src/charts/primitives/chart-container.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import type { HTMLAttributes } from "svelte/elements";
+	import { cn, type WithElementRef } from "@heyramzi/utils";
+	import ChartStyle from "./chart-style.svelte";
+	import { type ChartConfig, setChartContext } from "./chart-utils.js";
+
+	const uid = $props.id();
+
+	let {
+		ref = $bindable(null),
+		id = uid,
+		class: className,
+		children,
+		config,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLElement>> & {
+		config: ChartConfig;
+	} = $props();
+
+	const chartId = $derived(`chart-${id || uid.replace(/:/g, "")}`);
+
+	setChartContext({
+		get config() {
+			return config;
+		},
+	});
+</script>
+
+<div
+	bind:this={ref}
+	data-chart={chartId}
+	data-slot="chart"
+	class={cn(
+		"flex aspect-video justify-center overflow-visible text-xs",
+		"[&_.stroke-white]:stroke-transparent",
+		"[&_.lc-line]:stroke-border/50",
+		"[&_.lc-highlight-line]:stroke-0",
+		"[&_.lc-area-path]:opacity-100 [&_.lc-highlight-line]:opacity-100 [&_.lc-highlight-point]:opacity-100 [&_.lc-spline-path]:opacity-100 [&_.lc-text-svg]:overflow-visible [&_.lc-text]:text-xs",
+		"[&_.lc-axis-tick]:stroke-0",
+		"[&_.lc-rule-x-line:not(.lc-grid-x-rule)]:stroke-0 [&_.lc-rule-y-line:not(.lc-grid-y-rule)]:stroke-0",
+		"[&_.lc-grid-x-radial-line]:stroke-border [&_.lc-grid-x-radial-circle]:stroke-border",
+		"[&_.lc-grid-y-radial-line]:stroke-border [&_.lc-grid-y-radial-circle]:stroke-border",
+		"[&_.lc-legend-swatch-button]:items-center [&_.lc-legend-swatch-button]:gap-1.5",
+		"[&_.lc-legend-swatch-group]:items-center [&_.lc-legend-swatch-group]:gap-4",
+		"[&_.lc-legend-swatch]:size-2.5 [&_.lc-legend-swatch]:rounded-[2px]",
+		"[&_.lc-labels-text:not([fill])]:fill-foreground [&_text]:stroke-transparent",
+		"[&_.lc-axis-tick-label]:fill-muted-foreground [&_.lc-axis-tick-label]:font-normal",
+		"[&_.lc-tooltip-rects-g]:fill-transparent",
+		"[&_.lc-layout-svg-g]:fill-transparent",
+		"[&_.lc-root-container]:w-full",
+		className,
+	)}
+	{...restProps}
+>
+	<ChartStyle id={chartId} {config} />
+	{@render children?.()}
+</div>

package/src/charts/primitives/chart-style.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import { type ChartConfig, THEMES } from "./chart-utils.js";
+
+	let { id, config }: { id: string; config: ChartConfig } = $props();
+
+	const colorConfig = $derived(
+		config ? Object.entries(config).filter(([, c]) => c.theme || c.color) : null,
+	);
+
+	const themeContents = $derived.by(() => {
+		if (!colorConfig || !colorConfig.length) return;
+
+		const blocks: string[] = [];
+		for (const [_theme, prefix] of Object.entries(THEMES)) {
+			let content = `${prefix} [data-chart=${id}] {\n`;
+			const color = colorConfig.map(([key, itemConfig]) => {
+				const theme = _theme as keyof typeof itemConfig.theme;
+				const value = itemConfig.theme?.[theme] || itemConfig.color;
+				return value ? `\t--color-${key}: ${value};` : null;
+			});
+
+			content += `${color.join("\n")}\n}`;
+			blocks.push(content);
+		}
+
+		return blocks.join("\n");
+	});
+</script>
+
+{#if themeContents}
+	{#key id}
+		<svelte:element this={"style"}>
+			{themeContents}
+		</svelte:element>
+	{/key}
+{/if}

package/src/charts/primitives/chart-tooltip.svelte

@@ -0,0 +1,161 @@
+<script lang="ts">
+	import { getChartContext, Tooltip as TooltipPrimitive } from "layerchart";
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import { cn, type WithElementRef, type WithoutChildren } from "@heyramzi/utils";
+	import {
+		getPayloadConfigFromPayload,
+		type TooltipSeriesItem,
+		useChart,
+	} from "./chart-utils.js";
+
+	function defaultFormatter(value: unknown, _series: TooltipSeriesItem[]) {
+		return `${value}`;
+	}
+
+	let {
+		ref = $bindable(null),
+		class: className,
+		hideLabel = false,
+		indicator = "dot",
+		hideIndicator = false,
+		labelKey,
+		label,
+		labelFormatter = defaultFormatter,
+		labelClassName,
+		formatter,
+		nameKey,
+		color,
+		...restProps
+	}: WithoutChildren<WithElementRef<HTMLAttributes<HTMLDivElement>>> & {
+		hideLabel?: boolean;
+		label?: string;
+		indicator?: "line" | "dot" | "dashed";
+		nameKey?: string;
+		labelKey?: string;
+		hideIndicator?: boolean;
+		labelClassName?: string;
+		labelFormatter?:
+			| ((value: unknown, series: TooltipSeriesItem[]) => string | number | Snippet)
+			| null;
+		formatter?: Snippet<
+			[
+				{
+					value: unknown;
+					name: string;
+					item: TooltipSeriesItem;
+					index: number;
+					series: TooltipSeriesItem[];
+				},
+			]
+		>;
+	} = $props();
+
+	const chart = useChart();
+	const ctx = getChartContext();
+
+	const tooltipSeries = $derived(ctx.tooltip.series as TooltipSeriesItem[]);
+
+	const formattedLabel = $derived.by(() => {
+		if (hideLabel || !tooltipSeries?.length) return null;
+
+		const [item] = tooltipSeries;
+		const key = labelKey ?? item?.label ?? item?.key ?? "value";
+
+		const itemConfig = getPayloadConfigFromPayload(chart.config, item, key);
+
+		const value =
+			!labelKey && typeof label === "string"
+				? (chart.config[label as keyof typeof chart.config]?.label ?? label)
+				: (itemConfig?.label ?? item.label);
+
+		if (value === undefined) return null;
+		if (!labelFormatter) return value;
+		return labelFormatter(value, tooltipSeries);
+	});
+
+	const nestLabel = $derived(tooltipSeries.length === 1 && indicator !== "dot");
+</script>
+
+{#snippet TooltipLabel()}
+	{#if formattedLabel}
+		<div class={cn("font-medium", labelClassName)}>
+			{#if typeof formattedLabel === "function"}
+				{@render formattedLabel()}
+			{:else}
+				{formattedLabel}
+			{/if}
+		</div>
+	{/if}
+{/snippet}
+
+<TooltipPrimitive.Root variant="none">
+	<div
+		class={cn(
+			"border-border/50 bg-background grid min-w-[9rem] items-start gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs shadow-xl",
+			className,
+		)}
+		{...restProps}
+	>
+		{#if !nestLabel}
+			{@render TooltipLabel()}
+		{/if}
+		<div class="grid gap-1.5">
+			{#each tooltipSeries as item, i (item.key + i)}
+				{@const key = `${nameKey || item.key || "value"}`}
+				{@const itemConfig = getPayloadConfigFromPayload(chart.config, item, key)}
+				{@const indicatorColor = color || item.color}
+				<div
+					class={cn(
+						"[&>svg]:text-muted-foreground flex w-full flex-wrap items-stretch gap-2 [&>svg]:size-2.5",
+						indicator === "dot" && "items-center",
+					)}
+				>
+					{#if formatter && item.value !== undefined && item.key}
+						{@render formatter({
+							value: item.value,
+							name: item.label || item.key,
+							item,
+							index: i,
+							series: tooltipSeries,
+						})}
+					{:else}
+						{#if itemConfig?.icon}
+							<itemConfig.icon />
+						{:else if !hideIndicator}
+							<div
+								style="--color-bg: {indicatorColor}; --color-border: {indicatorColor};"
+								class={cn("border-(--color-border) bg-(--color-bg) shrink-0 rounded-[2px]", {
+									"size-2.5": indicator === "dot",
+									"h-full w-1": indicator === "line",
+									"w-0 border-[1.5px] border-dashed bg-transparent": indicator === "dashed",
+									"my-0.5": nestLabel && indicator === "dashed",
+								})}
+							></div>
+						{/if}
+						<div
+							class={cn(
+								"flex flex-1 shrink-0 justify-between leading-none",
+								nestLabel ? "items-end" : "items-center",
+							)}
+						>
+							<div class="grid gap-1.5">
+								{#if nestLabel}
+									{@render TooltipLabel()}
+								{/if}
+								<span class="text-muted-foreground">
+									{itemConfig?.label || item.label || item.key}
+								</span>
+							</div>
+							{#if item.value !== undefined}
+								<span class="text-foreground font-mono font-medium tabular-nums">
+									{typeof item.value === "number" ? item.value.toLocaleString() : item.value}
+								</span>
+							{/if}
+						</div>
+					{/if}
+				</div>
+			{/each}
+		</div>
+	</div>
+</TooltipPrimitive.Root>

package/src/charts/primitives/chart-utils.ts

@@ -0,0 +1,54 @@
+import { type Component, getContext, setContext } from "svelte";
+
+export const THEMES = { light: "", dark: ".dark" } as const;
+
+export type ChartConfig = {
+  [k in string]: {
+    label?: string;
+    icon?: Component;
+  } & (
+    | { color?: string; theme?: never }
+    | { color?: never; theme: Record<keyof typeof THEMES, string> }
+  );
+};
+
+export type TooltipSeriesItem = {
+  key: string;
+  label: string;
+  value: unknown;
+  color: string | undefined;
+  visible: boolean;
+  config: unknown;
+};
+
+export function getPayloadConfigFromPayload(
+  config: ChartConfig,
+  item: TooltipSeriesItem,
+  key: string,
+) {
+  if (typeof item !== "object" || item === null) return undefined;
+
+  let configLabelKey: string = key;
+
+  if (item.key === key) {
+    configLabelKey = item.key;
+  } else if (item.label === key) {
+    configLabelKey = item.label;
+  }
+
+  return configLabelKey in config ? config[configLabelKey] : config[key as keyof typeof config];
+}
+
+type ChartContextValue = {
+  config: ChartConfig;
+};
+
+const chartContextKey = Symbol("chart-context");
+
+export function setChartContext(value: ChartContextValue) {
+  return setContext(chartContextKey, value);
+}
+
+export function useChart() {
+  return getContext<ChartContextValue>(chartContextKey);
+}

package/src/charts/primitives/index.ts

@@ -0,0 +1,11 @@
+export { default as ChartContainer } from "./chart-container.svelte";
+export { default as ChartTooltip } from "./chart-tooltip.svelte";
+export { default as ChartStyle } from "./chart-style.svelte";
+export {
+  type ChartConfig,
+  type TooltipSeriesItem,
+  getPayloadConfigFromPayload,
+  useChart,
+  setChartContext,
+  THEMES,
+} from "./chart-utils.js";

package/src/charts/reveal.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { getChartContext } from "layerchart";
+	import { onMount, type Snippet } from "svelte";
+	import { expoInOut } from "svelte/easing";
+	import { prefersReducedMotion, Tween } from "svelte/motion";
+	import { REVEAL_MS, tokenMs } from "./motion.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		children: Snippet;
+		/** Headroom around the plot so a stroke at the series max is not cut. */
+		bleed?: number;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let { children, bleed = 6 }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const ctx = getChartContext();
+	const id = `hr-reveal-${Math.random().toString(36).slice(2, 8)}`;
+	const progress = new Tween(0, { easing: expoInOut });
+	let rect = $state<SVGRectElement>();
+
+	// =========================
+	// LIFECYCLE
+	// =========================
+	onMount(() => {
+		const duration =
+			prefersReducedMotion.current || !rect ? 0 : tokenMs(rect, "--chart-motion-reveal", REVEAL_MS);
+		progress.set(1, { duration });
+	});
+</script>
+
+<!-- =========================== -->
+<!-- REVEAL -->
+<!-- =========================== -->
+<!-- WHY a tweened width and not scaleX: scaleX needs a transform origin, and the
+     rect has to keep tracking the plot width through a resize. -->
+<defs>
+	<clipPath {id}>
+		<rect
+			bind:this={rect}
+			x={-bleed}
+			y={-bleed}
+			width={Math.max(0, (ctx.width + bleed * 2) * progress.current)}
+			height={ctx.height + bleed * 2}
+		/>
+	</clipPath>
+</defs>
+<g clip-path="url(#{id})">
+	{@render children()}
+</g>

package/src/charts/ring-chart.css

@@ -0,0 +1,96 @@
+/* Styles for RingChart. Plain stylesheet (see area-chart.css for why).
+   Selectors are namespaced under `.hr-ring` (the generic ones below would
+   otherwise collide with GaugeChart's identical names once they are no longer
+   Svelte-scoped). */
+
+.hr-ring {
+  position: relative;
+  display: inline-grid;
+  place-items: center;
+  aspect-ratio: 1;
+  container-type: size;
+}
+
+.hr-ring svg {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+.hr-ring .track {
+  opacity: 0.14;
+}
+
+.hr-ring .fill {
+  stroke-dasharray: 100;
+  cursor: pointer;
+  outline: none;
+  transition:
+    stroke-dashoffset var(--chart-motion-slow, 1.1s)
+      var(--chart-ease-out, cubic-bezier(0.22, 1, 0.36, 1)),
+    opacity 200ms ease;
+}
+
+.hr-ring .fill.animate {
+  animation: hr-ring-sweep var(--chart-motion-reveal, 1100ms)
+    var(--chart-ease-reveal, cubic-bezier(0.85, 0, 0.15, 1)) both;
+}
+
+.hr-ring.glow .fill:hover {
+  filter: drop-shadow(0 0 5px var(--ring-color));
+}
+
+@keyframes hr-ring-sweep {
+  from {
+    stroke-dashoffset: 100;
+  }
+}
+
+.hr-ring .center {
+  grid-area: 1 / 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* WHY: keep the readout inside the innermost ring's clear center so the
+	   number never collides with the green ring. */
+  max-width: 40cqmin;
+  pointer-events: none;
+  text-align: center;
+}
+
+.hr-ring .value {
+  font-size: max(0.75rem, 9.5cqmin);
+  font-weight: 650;
+  line-height: 1;
+  letter-spacing: -0.02em;
+  font-variant-numeric: tabular-nums;
+  color: var(--foreground);
+}
+
+.hr-ring .label {
+  margin-top: 1.5cqmin;
+  font-size: max(0.5rem, 5cqmin);
+  font-weight: 500;
+  color: var(--muted-foreground);
+  animation: hr-ring-label-in 180ms ease-out both;
+}
+
+@keyframes hr-ring-label-in {
+  from {
+    opacity: 0;
+    transform: translateY(2px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hr-ring .fill,
+  .hr-ring .fill.animate {
+    transition: opacity 120ms ease;
+    animation: none;
+  }
+  .hr-ring .label {
+    animation: none;
+  }
+}