@heyramzi/ui 1.54.1 → 2.0.0

package/src/charts/dashboard/data-table.svelte

@@ -0,0 +1,278 @@
+<script lang="ts" module>
+import type { Snippet } from "svelte";
+
+/** Narrow screens drop the columns that only add detail. */
+export type DataColumnBreakpoint = "sm" | "md" | "lg";
+
+/** One column after the lead. Give it `value`, `rating` or a `cell` snippet. */
+export type DataColumn<T> = {
+	key: string;
+	label: string;
+	/** The long form of the head, as its tooltip. */
+	hint?: string;
+	/** A Tailwind width class. Fixed widths are what keep the lead column wide. */
+	width: string;
+	/** Figures run to the end, so digits line up. Text, pills and bars start. */
+	align?: "start" | "end";
+	/** Makes the head rank the table. Higher is better; a new column starts descending. */
+	sort?: (row: T) => number;
+	/** Null draws the table's empty label, muted. */
+	value?: (row: T) => string | null;
+	rating?: (row: T) => { grade: string; hint?: string } | null;
+	cell?: Snippet<[T]>;
+	/** 0 to 1, a share-of-max track drawn before the value. */
+	bar?: (row: T) => number;
+	/** Cell tooltip. */
+	title?: (row: T) => string | undefined;
+	muted?: boolean | ((row: T) => boolean);
+	/** A loss, an overrun: the value turns the destructive colour. */
+	negative?: (row: T) => boolean;
+	/** The column the eye lands on first. */
+	strong?: boolean;
+	/** A hairline before this column, opening a group. */
+	rule?: boolean;
+	/** Hidden under this breakpoint. */
+	hideBelow?: DataColumnBreakpoint;
+};
+</script>
+
+<script lang="ts" generics="T">
+/*
+ * The one data table: wide lead cell, fixed figure columns, sortable heads,
+ * optional pager. A row opens by `rowHref` or `onRowClick`, stretched over the row from the lead.
+ */
+import { cn } from "../../lib/utils.js";
+import DataSortHead from "./data-sort-head.svelte";
+import RatingChip from "./rating-chip.svelte";
+import { Pagination, paginateRows, totalPages } from "../../components/data-table/index.js";
+import {
+	dataTableClass,
+	dataTdClass,
+	dataTdNumClass,
+	dataThClass,
+	dataThNumClass,
+	dataTheadClass,
+	dataTrClass,
+} from "./data-table.js";
+
+interface Props {
+	rows: T[];
+	columns: DataColumn<T>[];
+	rowKey: (row: T) => string;
+	leadLabel: string;
+	lead: Snippet<[T]>;
+	/** Drawn where a value or rating is null. */
+	emptyLabel: string;
+	/** A Tailwind width class. Omit and the lead takes whatever the figures leave. */
+	leadWidth?: string;
+	/** A Tailwind min-width class, past which the panel scrolls sideways. */
+	minWidth?: string;
+	/** Omit for every row on one page. */
+	pageSize?: number;
+	sortKey?: string | null;
+	descending?: boolean;
+	page?: number;
+	/** The row opens a page. The lead becomes the link. */
+	rowHref?: (row: T) => string;
+	/** The row opens in place: a panel, a detail view. The lead becomes the button. */
+	onRowClick?: (row: T) => void;
+	/** Placeholder rows while the data is on its way. */
+	loading?: boolean;
+	/** Drawn in place of the body when there are no rows. */
+	empty?: Snippet;
+};
+
+let {
+	rows,
+	columns,
+	rowKey,
+	leadLabel,
+	lead,
+	emptyLabel,
+	leadWidth,
+	minWidth = "min-w-[48rem]",
+	pageSize,
+	sortKey = $bindable(null),
+	descending = $bindable(true),
+	page = $bindable(1),
+	rowHref,
+	onRowClick,
+	loading = false,
+	empty,
+}: Props = $props();
+
+const pad = "px-3";
+const LOADING_ROWS = 5;
+
+// Literal classes, so Tailwind sees each one.
+const HIDE_BELOW: Record<DataColumnBreakpoint, string> = {
+	sm: "hidden sm:table-cell",
+	md: "hidden md:table-cell",
+	lg: "hidden lg:table-cell",
+};
+
+// The ::after covers the whole row, so any cell opens it and the lead stays the one tab stop.
+const stretch =
+	"text-left outline-none after:absolute after:inset-0 after:content-[''] focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-ring";
+
+const sorted = $derived.by(() => {
+	const by = columns.find((column) => column.key === sortKey)?.sort;
+	if (!by) return rows;
+	const direction = descending ? -1 : 1;
+	return [...rows].sort((left, right) => (by(left) - by(right)) * direction);
+});
+
+const visible = $derived(pageSize ? paginateRows(sorted, page, pageSize) : sorted);
+const opens = $derived(Boolean(rowHref || onRowClick));
+
+// Fewer rows than the page you stand on would draw an empty table.
+$effect(() => {
+	if (!pageSize) return;
+	const last = totalPages(sorted.length, pageSize);
+	if (page > last) page = last;
+});
+
+function rankBy(key: string) {
+	page = 1;
+	if (sortKey === key) {
+		descending = !descending;
+		return;
+	}
+	sortKey = key;
+	descending = true;
+}
+
+function isMuted(column: DataColumn<T>, row: T) {
+	return typeof column.muted === "function" ? column.muted(row) : Boolean(column.muted);
+}
+
+function columnClass(column: DataColumn<T>) {
+	return cn(
+		pad,
+		column.align === "start" && "text-left",
+		column.rule && "border-l border-border",
+		column.hideBelow && HIDE_BELOW[column.hideBelow],
+	);
+}
+</script>
+
+<table class={cn(dataTableClass, minWidth, "table-fixed")}>
+	<colgroup>
+		<col class={leadWidth} />
+		{#each columns as column (column.key)}
+			<col class={cn(column.width, column.hideBelow && HIDE_BELOW[column.hideBelow])} />
+		{/each}
+	</colgroup>
+	<thead class={dataTheadClass}>
+		<tr>
+			<th scope="col" class={dataThClass}>{leadLabel}</th>
+			{#each columns as column (column.key)}
+				{#if column.sort}
+					<DataSortHead
+						numeric={column.align !== "start"}
+						class={columnClass(column)}
+						active={sortKey === column.key}
+						{descending}
+						onSort={() => rankBy(column.key)}
+						title={column.hint}
+					>
+						{column.label}
+					</DataSortHead>
+				{:else}
+					<th
+						scope="col"
+						class={cn(column.align === "start" ? dataThClass : dataThNumClass, columnClass(column))}
+						title={column.hint}
+					>
+						{column.label}
+					</th>
+				{/if}
+			{/each}
+		</tr>
+	</thead>
+	<tbody>
+		{#if loading}
+			{#each { length: LOADING_ROWS }, index (index)}
+				<tr class={dataTrClass} aria-hidden="true">
+					<td class={cn(dataTdClass, "py-3")}>
+						<span class="block h-4 w-2/3 animate-pulse rounded bg-muted"></span>
+					</td>
+					{#each columns as column (column.key)}
+						<td class={cn(dataTdNumClass, columnClass(column), "align-middle")}>
+							<span
+								class={cn(
+									"block h-4 w-3/4 animate-pulse rounded bg-muted",
+									column.align !== "start" && "ml-auto",
+								)}
+							></span>
+						</td>
+					{/each}
+				</tr>
+			{/each}
+		{:else if visible.length === 0 && empty}
+			<tr>
+				<td colspan={columns.length + 1}>{@render empty()}</td>
+			</tr>
+		{:else}
+			{#each visible as row (rowKey(row))}
+				<tr class={cn(dataTrClass, "group", opens && "relative cursor-pointer")}>
+					<td class={cn(dataTdClass, "py-3")}>
+						{#if rowHref}
+							<a href={rowHref(row)} class={stretch}>{@render lead(row)}</a>
+						{:else if onRowClick}
+							<button type="button" class={stretch} onclick={() => onRowClick(row)}>
+								{@render lead(row)}
+							</button>
+						{:else}
+							{@render lead(row)}
+						{/if}
+					</td>
+					{#each columns as column (column.key)}
+						<td
+							class={cn(
+								dataTdNumClass,
+								columnClass(column),
+								"align-middle whitespace-nowrap",
+								column.strong && "font-medium",
+								isMuted(column, row) && "text-muted-foreground",
+								column.negative?.(row) && "text-destructive",
+							)}
+							title={column.title?.(row)}
+						>
+							{#if column.cell}
+								{@render column.cell(row)}
+							{:else if column.rating}
+								{@const rating = column.rating(row)}
+								{#if rating}
+									<RatingChip grade={rating.grade} hint={rating.hint} />
+								{:else}
+									<span class="text-muted-foreground">{emptyLabel}</span>
+								{/if}
+							{:else}
+								{@const value = column.value?.(row) ?? null}
+								{#if value === null}
+									<span class="text-muted-foreground">{emptyLabel}</span>
+								{:else if column.bar}
+									<span class="flex items-center justify-end gap-3">
+										<span class="h-1.5 min-w-0 flex-1 overflow-hidden rounded-full bg-muted">
+											<span
+												class="block h-full origin-left rounded-full bg-primary/70"
+												style:transform="scaleX({Math.min(1, Math.max(0, column.bar(row)))})"
+											></span>
+										</span>
+										<span>{value}</span>
+									</span>
+								{:else}
+									{value}
+								{/if}
+							{/if}
+						</td>
+					{/each}
+				</tr>
+			{/each}
+		{/if}
+	</tbody>
+</table>
+{#if pageSize && !loading}
+	<Pagination {page} {pageSize} total={sorted.length} onPageChange={(next) => (page = next)} />
+{/if}

package/src/charts/dashboard/data-table.ts

@@ -0,0 +1,26 @@
+/**
+ * The one skin for a dashboard data table. Classes, not a component: two
+ * dashboards share nothing but the look, and each drew its own slightly different one.
+ */
+
+// Heads aren't uppercase. `SectionLabel` already is, and a nine-column head in
+// the same style fights the panel title and reads worse where density matters.
+export const dataTableClass = "w-full text-sm";
+
+export const dataTheadClass = "bg-muted/40 text-xs text-muted-foreground";
+
+export const dataThClass = "px-4 py-2.5 text-left font-medium";
+
+/** A head over numbers. Right-aligned to the digits under it. */
+export const dataThNumClass = "px-4 py-2.5 text-right font-medium";
+
+export const dataTrClass =
+  "border-b border-border transition-colors last:border-0 hover:bg-muted/40";
+
+export const dataTdClass = "px-4 py-2.5 align-top";
+
+/**
+ * A cell holding a number. `tabular-nums` is required: proportional digits make
+ * a spend column ragged, and then nobody can scan it.
+ */
+export const dataTdNumClass = "px-4 py-2.5 text-right align-top tabular-nums";

package/src/charts/dashboard/index.ts

@@ -0,0 +1,25 @@
+export { default as DataPanel } from "./data-panel.svelte";
+export { default as DataSortHead } from "./data-sort-head.svelte";
+export {
+  default as DataTable,
+  type DataColumn,
+  type DataColumnBreakpoint,
+} from "./data-table.svelte";
+export { default as RatingChip } from "./rating-chip.svelte";
+export { default as DashboardEmpty } from "./dashboard-empty.svelte";
+export { default as DashboardSection } from "./dashboard-section.svelte";
+export { default as PanelGrid } from "./panel-grid.svelte";
+export { default as PeriodFilter } from "./period-filter.svelte";
+export { default as StatBand } from "./stat-band.svelte";
+export { default as StatTile, type StatDirection } from "./stat-tile.svelte";
+export { CHART_HEIGHT } from "./chart.js";
+export { DAY_WINDOWS, type DayWindow } from "./windows.js";
+export {
+  dataTableClass,
+  dataTdClass,
+  dataTdNumClass,
+  dataThClass,
+  dataThNumClass,
+  dataTheadClass,
+  dataTrClass,
+} from "./data-table.js";

package/src/charts/dashboard/panel-grid.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "../../lib/utils.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	/** `<DataPanel>` children, or tiles standing beside one. */
+	children: Snippet;
+	/**
+	 * Panels per row: two charts, three breakdowns, or `main`, where the first
+	 * child takes two thirds and the rates beside it one third.
+	 */
+	columns?: 2 | 3 | "main";
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { children, columns = 2, class: className }: Props = $props();
+
+// =========================
+// CONSTANTS
+// =========================
+const COLUMNS: Record<2 | 3 | "main", string> = {
+	2: "lg:grid-cols-2",
+	3: "lg:grid-cols-2 xl:grid-cols-3",
+	main: "lg:grid-cols-3 lg:[&>*:first-child]:col-span-2",
+};
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The one row of panels side by side. -->
+<div class={cn("grid gap-4", COLUMNS[columns], className)}>
+	{@render children()}
+</div>

package/src/charts/dashboard/period-filter.svelte

@@ -0,0 +1,53 @@
+<script lang="ts" generics="T extends string">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "../../lib/utils.js";
+import { SegmentedFilter, SegmentedNav, type TabDef } from "../../components/segmented/index.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	options: readonly TabDef<T>[];
+	value: T;
+	/**
+	 * Give this and the strip is links, so the choice survives reload, back and a
+	 * shared link. Omit it and the strip is a `<SegmentedFilter>` the caller owns.
+	 */
+	href?: (value: T) => string;
+	/** Filter mode only. Ignored when `href` is set. */
+	onValueChange?: (value: T) => void;
+	ariaLabel: string;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { options, value, href, onValueChange, ariaLabel, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY one component for the window, not a `SegmentedNav` here and a
+     `SegmentedFilter` there: identical pages announced themselves differently.
+     Place it first in the toolbar's right cluster. -->
+{#if href}
+	<SegmentedNav
+		items={options.map((option) => ({ ...option, href: href(option.value) }))}
+		current={href(value)}
+		{ariaLabel}
+		class={className}
+	/>
+{:else}
+	<SegmentedFilter
+		{options}
+		{value}
+		{onValueChange}
+		{ariaLabel}
+		block={false}
+		class={cn("shrink-0", className)}
+	/>
+{/if}

package/src/charts/dashboard/rating-chip.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+/*
+ * One A to E grade on one colour scale, so a C means one thing everywhere.
+ * Light mode takes the 800 shades, since amber on cream fails contrast.
+ */
+import { cn } from "../../lib/utils.js";
+
+interface Props {
+	grade: string;
+	/** What the letter hides: the score and what it was charged for. */
+	hint?: string;
+	class?: string;
+};
+
+let { grade, hint, class: className }: Props = $props();
+
+const TONE: Record<string, string> = {
+	A: "bg-success/12 text-success-800 dark:text-success",
+	B: "bg-success/12 text-success-800 dark:text-success",
+	C: "bg-muted text-foreground",
+	D: "bg-warning/18 text-warning-800 dark:text-warning",
+	E: "bg-destructive/12 text-destructive",
+};
+</script>
+
+<span
+	class={cn(
+		"inline-flex h-6 min-w-6 items-center justify-center rounded-md px-1.5 text-xs font-semibold tabular-nums",
+		TONE[grade] ?? TONE.C,
+		className,
+	)}
+	title={hint}
+>
+	{grade}
+</span>

package/src/charts/dashboard/stat-band.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "../../lib/utils.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	/** `<StatTile>` children. Four to a row on a desk, two on a phone. */
+	children: Snippet;
+	/**
+	 * Cards per row at the widest breakpoint, four unless the set is smaller.
+	 * Five and six are only for a fixed scorecard. The headline stays one row.
+	 */
+	columns?: 2 | 3 | 4 | 5 | 6;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { children, columns = 4, class: className }: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+const COLUMNS: Record<2 | 3 | 4 | 5 | 6, string> = {
+	2: "sm:grid-cols-2",
+	3: "sm:grid-cols-2 lg:grid-cols-3",
+	4: "sm:grid-cols-2 lg:grid-cols-4",
+	5: "sm:grid-cols-3 lg:grid-cols-5",
+	6: "sm:grid-cols-3 xl:grid-cols-6",
+};
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- Numbers get number cards. One panel with hairlines made four figures float
+     in one box on a dark theme, where hairlines vanish. -->
+<!-- No border on the band itself: the cards carry it, or it's a box of boxes. -->
+<div class={cn("grid grid-cols-2 gap-4", COLUMNS[columns], className)}>
+	{@render children()}
+</div>

package/src/charts/dashboard/stat-tile.svelte

@@ -0,0 +1,176 @@
+<script lang="ts" module>
+/**
+ * Which way a metric has to move to be good news. `neutral` fits a figure like
+ * spend, which isn't a win or a loss until the return sits beside it.
+ */
+export type StatDirection = "up-good" | "down-good" | "neutral";
+</script>
+
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import NumberChart from "../number-chart.svelte";
+import Sparkline from "../sparkline.svelte";
+import type { Snippet } from "svelte";
+import { cn } from "../../lib/utils.js";
+import { Icon } from "../../components/icon/index.js";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	label: string;
+	/** Already formatted. The tile never guesses a currency or a locale. */
+	value: string;
+	/**
+	 * Percent change against the previous period. `null` means nothing to
+	 * compare yet and draws a dash. Omit it when the figure has no period at all.
+	 */
+	deltaPct?: number | null;
+	direction?: StatDirection;
+	/** The one figure the screen was opened to read. Set it on exactly one tile. */
+	lead?: boolean;
+	/** A quiet line under the value: what it was measured over, or why it is a dash. */
+	hint?: string;
+	/**
+	 * 0 to 1, drawn as a track under the value: share of a total or progress to
+	 * a target. Omit it for a cash balance.
+	 */
+	share?: number;
+	/** What `share` is measured against, e.g. "of revenue". Only with `share`. */
+	shareLabel?: string;
+	/** Track colour. The first series token unless a tile means something else. */
+	color?: string;
+	/**
+	 * A shape behind the figure, oldest first, bled along the card's bottom.
+	 * The treatment every tile gives a number with a history. Omit when there
+	 * is none.
+	 */
+	series?: number[];
+	/** Leading mark before the label. */
+	icon?: PhosphorIcon;
+	/**
+	 * Makes the tile a link, like a balance that opens the bank. It lives here so
+	 * a linked figure isn't drawn as a second, different card style.
+	 */
+	href?: string;
+	/** What the link opens, shown on hover. Only with `href`. */
+	hrefLabel?: string;
+	/**
+	 * `_blank` for a figure that leaves the app (a bank, a provider console),
+	 * `_self` for one that is another page of this app. Only with `href`.
+	 */
+	target?: "_self" | "_blank";
+	/**
+	 * A chip at the end of the label row: the limit the figure is judged against,
+	 * the state it is in. Wins over `hrefLabel`, which is only a hover hint.
+	 */
+	badge?: Snippet;
+	/** A loss or an overrun: the figure turns the destructive colour. */
+	negative?: boolean;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	label,
+	value,
+	deltaPct,
+	direction = "neutral",
+	lead = false,
+	hint,
+	share,
+	shareLabel,
+	color,
+	series,
+	icon,
+	href,
+	hrefLabel,
+	target = "_blank",
+	badge,
+	negative = false,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+// `Sparkline` plots rows, and a card carries a bare series. Two points is a
+// line, not a shape, so it is not drawn.
+let points = $derived(series?.map((value, index) => ({ i: index, v: value })) ?? []);
+let hasSeries = $derived(points.length > 2);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The figure is `NumberChart` from the chart library, because this tile and
+     the numbers on the panels beside it are the same object and drawn twice
+     they drift. -->
+<svelte:element
+	this={href ? "a" : "div"}
+	{href}
+	target={href ? target : undefined}
+	rel={href && target === "_blank" ? "noopener noreferrer" : undefined}
+	data-series={hasSeries ? "" : undefined}
+	class={cn(
+		"hr-stat-tile group/tile relative block rounded-xl",
+		href && "t-press focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-none",
+		className,
+	)}
+>
+	{#snippet tileIcon()}
+		{#if icon}<Icon {icon} size={14} class="shrink-0" />{/if}
+	{/snippet}
+
+	<NumberChart
+		{label}
+		{value}
+		delta={deltaPct}
+		{direction}
+		{share}
+		{shareLabel}
+		{color}
+		icon={icon ? tileIcon : undefined}
+		size={lead ? "lg" : "md"}
+		caption={hint}
+		class={cn(
+			"h-full",
+			// A label is never clipped: a chip that doesn't fit drops under it.
+			"[&_.hr-number-label]:flex-wrap [&_.hr-number-label-text]:shrink-0",
+			deltaPct === undefined && "[&_.hr-number-delta]:hidden!",
+		)}
+		{negative}
+		trailing={badge ?? (href && hrefLabel ? linkHint : undefined)}
+	/>
+
+	<!-- The shape behind the number, bled to the card's bottom corners. The
+	     scoped rule below reserves the room so it never sits on the caption. -->
+	{#if hasSeries}
+		<div
+			class="pointer-events-none absolute inset-x-px bottom-px h-12 overflow-hidden rounded-b-[calc(var(--radius-xl)-1px)]"
+			aria-hidden="true"
+		>
+			<Sparkline data={points} xKey="i" yKey="v" color={color ?? "var(--chart-1)"} height={48} bare />
+		</div>
+	{/if}
+</svelte:element>
+
+{#snippet linkHint()}
+	<span class="opacity-0 transition-opacity group-hover/tile:opacity-100">{hrefLabel}</span>
+{/snippet}
+
+<!-- =========================== -->
+<!-- STYLE -->
+<!-- =========================== -->
+<style>
+	/* WHY scoped here: `NumberChart` has no
+	   series, so the sparkline's bottom room is added on the tile that draws it. */
+	.hr-stat-tile[data-series] :global(.hr-number-chart) {
+		padding-bottom: 4.25rem;
+	}
+</style>

package/src/charts/dashboard/windows.ts

@@ -0,0 +1,8 @@
+/**
+ * Day windows a strip offers: seven, thirty, ninety, the three every dataset
+ * has. A page may add an option its data carries; labels translate at the
+ * call site.
+ */
+export const DAY_WINDOWS = [7, 30, 90] as const;
+
+export type DayWindow = (typeof DAY_WINDOWS)[number];