@heyramzi/ui 2.1.0 → 2.3.0

package/src/components/table-view/table-view.svelte

@@ -3,6 +3,7 @@
 	import type { TableColumn } from "./types.js";
 
 	export type TableCell<Row> = { row: Row; column: TableColumn<Row>; value: unknown; text: string };
+	export type TableGroup<Row> = { key: string; rows: Row[] };
 	export type { TableColumn };
 </script>
 
@@ -10,8 +11,13 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import { CaretDown, CaretUp, CaretUpDown } from "phosphor-svelte";
 	import { cn } from "../../lib/utils.js";
 	import * as Table from "../../shadcn/table/index.js";
+	import * as ContextMenu from "../../shadcn/context-menu/index.js";
+	import { Checkbox } from "../../shadcn/checkbox/index.js";
+	import { TableSkeleton } from "../data-table/index.js";
+	import { toggleSort, type SortState } from "../data-table/data-table.js";
 
 	// =========================
 	// TYPES
@@ -30,13 +36,111 @@
 		rowClass?: (row: Row) => string | undefined;
 		/** Below this width the table scrolls sideways inside its frame. */
 		minWidth?: string;
+		/** No outer border or radius, for a table inside a card. */
+		bare?: boolean;
 		class?: string;
+		/** The sorted column and its direction. Bind it; columns with `sortable` set it. */
+		sort?: SortState<Row>;
+		/** Where a row goes. Draws a real link over the row, so middle-click and cmd-click work. */
+		rowHref?: (row: Row) => string | undefined;
+		/** The link's accessible name. Defaults to the row's first column text. */
+		rowLabel?: (row: Row) => string;
+		/** Adds a checkbox column with a select-all in the head. */
+		selectable?: boolean;
+		/** The `rowKey` of every checked row. Bind it. */
+		selected?: Set<string>;
+		selectAllLabel?: string;
+		selectRowLabel?: (row: Row) => string;
+		/** The items of a right-click menu for one row: `ContextMenu.Item`s. */
+		rowMenu?: Snippet<[Row]>;
+		/** Rows that return the same key sit under one header row. Order `rows` so a group is contiguous. */
+		group?: (row: Row) => string;
+		/** Draws a group's header. Prints the key when left out. */
+		groupHeader?: Snippet<[TableGroup<Row>]>;
+		/** Makes each group header a button that folds its rows. */
+		collapsible?: boolean;
+		/** The keys of the folded groups. Bind it. */
+		collapsed?: Set<string>;
+		/** Draws a column head its own way, an icon or a colour. Print `column.label` for the plain case. */
+		head?: Snippet<[TableColumn<Row>]>;
+		/** The row opens in place. Click or Enter on the row, unless the target is a link, button or input inside it. */
+		onRowClick?: (row: Row) => void;
+		/** Whether a row shows its `subRow`. */
+		expanded?: (row: Row) => boolean;
+		/** A full-width row under the row, for detail. */
+		subRow?: Snippet<[Row]>;
+		/** Drawn across every column when there are no rows. */
+		empty?: Snippet;
+		/** Drawn across every column under the last row: a load-more sentinel or a spinner. */
+		trailing?: Snippet;
+		/** Draws placeholder rows in the same frame instead of `rows`. */
+		loading?: boolean;
+		skeletonRows?: number;
 	}
 
 	// =========================
 	// PROPS
 	// =========================
-	let { columns, rows, rowKey, label, footer, cell, rowClass, minWidth = "0", class: className }: Props = $props();
+	let {
+		columns,
+		rows,
+		rowKey,
+		label,
+		footer,
+		cell,
+		rowClass,
+		minWidth = "0",
+		bare = false,
+		class: className,
+		sort = $bindable(null),
+		rowHref,
+		rowLabel,
+		selectable = false,
+		selected = $bindable(new Set<string>()),
+		selectAllLabel = "Select all rows",
+		selectRowLabel,
+		rowMenu,
+		group,
+		groupHeader,
+		collapsible = false,
+		collapsed = $bindable(new Set<string>()),
+		head,
+		onRowClick,
+		expanded,
+		subRow,
+		empty,
+		trailing,
+		loading = false,
+		skeletonRows = 5,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	let span = $derived(columns.length + (selectable ? 1 : 0));
+	let selectedCount = $derived(rows.filter((row) => selected.has(rowKey(row))).length);
+	let allSelected = $derived(rows.length > 0 && selectedCount === rows.length);
+	let someSelected = $derived(selectedCount > 0 && !allSelected);
+	let skeletonColumns = $derived([
+		...(selectable ? [{ width: "w-4" }] : []),
+		...columns.map((column) => ({
+			align: column.numeric ? ("right" as const) : ("left" as const),
+		})),
+	]);
+	let entries = $derived.by<{ group: TableGroup<Row> }[]>(() => {
+		if (!group) return [];
+		const out: { group: TableGroup<Row> }[] = [];
+		let current: TableGroup<Row> | undefined;
+		for (const row of rows) {
+			const groupKey = group(row);
+			if (!current || current.key !== groupKey) {
+				current = { key: groupKey, rows: [] };
+				out.push({ group: current });
+			}
+			current.rows.push(row);
+		}
+		return out;
+	});
 
 	// =========================
 	// FUNCTIONS
@@ -48,6 +152,61 @@
 		if (column.format) return column.format(value, row);
 		return value === null || value === undefined ? "" : String(value);
 	}
+
+	function ariaSort(column: TableColumn<Row>): "ascending" | "descending" | "none" | undefined {
+		if (!column.sortable) return undefined;
+		if (sort?.key !== column.key) return "none";
+		return sort.direction === "asc" ? "ascending" : "descending";
+	}
+
+	function toggleRow(row: Row, on: boolean) {
+		const next = new Set(selected);
+		if (on) next.add(rowKey(row));
+		else next.delete(rowKey(row));
+		selected = next;
+	}
+
+	function toggleAll(on: boolean) {
+		const next = new Set(selected);
+		for (const row of rows) {
+			if (on) next.add(rowKey(row));
+			else next.delete(rowKey(row));
+		}
+		selected = next;
+	}
+
+	const HIDE = {
+		sm: "hidden sm:table-cell",
+		md: "hidden md:table-cell",
+		lg: "hidden lg:table-cell",
+	};
+
+	function toggleGroup(groupKey: string) {
+		const next = new Set(collapsed);
+		if (next.has(groupKey)) next.delete(groupKey);
+		else next.add(groupKey);
+		collapsed = next;
+	}
+
+	// WHY the target check: a row can hold its own link, button or checkbox, and a click on one of those belongs to it.
+	const OWN_CLICK =
+		"a, button, input, select, textarea, label, [role=checkbox], [role=button], [role=menuitem]";
+
+	function rowClick(event: MouseEvent, row: Row) {
+		if ((event.target as Element).closest(OWN_CLICK)) return;
+		onRowClick?.(row);
+	}
+
+	function rowKeydown(event: KeyboardEvent, row: Row) {
+		if (event.target !== event.currentTarget) return;
+		if (event.key !== "Enter" && event.key !== " ") return;
+		event.preventDefault();
+		onRowClick?.(row);
+	}
+
+	function linkName(row: Row): string {
+		return rowLabel?.(row) ?? (columns[0] ? textOf(columns[0], row) : label);
+	}
 </script>
 
 <!-- =========================== -->
@@ -60,10 +219,19 @@
 				"align-top",
 				column.numeric ? "text-end tabular-nums" : "whitespace-normal",
 				column.muted && "text-muted-foreground",
+				column.interactive && "relative z-10",
+				column.hideBelow && HIDE[column.hideBelow],
+				column.sticky && "bg-background sticky left-0 z-10",
+				column.class,
 			)}
 		>
 			{#if cell}
-				{@render cell({ row, column, value: (row as Record<string, unknown>)[column.key], text: textOf(column, row) })}
+				{@render cell({
+					row,
+					column,
+					value: (row as Record<string, unknown>)[column.key],
+					text: textOf(column, row),
+				})}
 			{:else}
 				{textOf(column, row)}
 			{/if}
@@ -71,31 +239,202 @@
 	{/each}
 {/snippet}
 
-<div class={cn("overflow-hidden rounded-xl border", className)}>
-	<Table.Root aria-label={label} style={`min-width: ${minWidth}`} class="min-w-0">
+{#snippet rowOrMenu(row: Row)}
+	{#if rowMenu}
+		<ContextMenu.Root>
+			<ContextMenu.Trigger>
+				{#snippet child({ props })}
+					{@render dataRow(row, props)}
+				{/snippet}
+			</ContextMenu.Trigger>
+			<ContextMenu.Content class="w-48">
+				{@render rowMenu(row)}
+			</ContextMenu.Content>
+		</ContextMenu.Root>
+	{:else}
+		{@render dataRow(row, {})}
+	{/if}
+{/snippet}
+
+{#snippet dataRow(row: Row, triggerProps: Record<string, unknown>)}
+	{@const href = rowHref?.(row)}
+	{@const isSelected = selectable && selected.has(rowKey(row))}
+	<Table.Row
+		{...triggerProps}
+		data-state={isSelected ? "selected" : undefined}
+		tabindex={onRowClick ? 0 : undefined}
+		onclick={onRowClick ? (event: MouseEvent) => rowClick(event, row) : undefined}
+		onkeydown={onRowClick ? (event: KeyboardEvent) => rowKeydown(event, row) : undefined}
+		class={cn(
+			href && "relative t-press active:bg-muted/50",
+			onRowClick &&
+				"t-press active:bg-muted/50 focus-visible:ring-ring cursor-pointer outline-none focus-visible:ring-2 focus-visible:ring-inset",
+			rowClass?.(row),
+		)}
+	>
+		{#if selectable}
+			<Table.Cell class="relative z-10 w-10 align-top">
+				<Checkbox
+					checked={isSelected}
+					onCheckedChange={(on) => toggleRow(row, on === true)}
+					aria-label={selectRowLabel?.(row) ?? `Select ${linkName(row)}`}
+				/>
+			</Table.Cell>
+		{/if}
+		{@render body(row)}
+		{#if href}
+			<!-- WHY an empty anchor and not a wrapped cell: cells hold buttons and links of their own, and an anchor can't nest one. -->
+			<td class="p-0">
+				<a
+					{href}
+					aria-label={linkName(row)}
+					class="absolute inset-0 z-0 outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+				></a>
+			</td>
+		{/if}
+	</Table.Row>
+	{#if subRow && expanded?.(row)}
+		<Table.Row class="bg-muted/20 hover:bg-muted/20 hover:translate-y-0 hover:shadow-none">
+			<Table.Cell colspan={span + (rowHref ? 1 : 0)} class="whitespace-normal">
+				{@render subRow(row)}
+			</Table.Cell>
+		</Table.Row>
+	{/if}
+{/snippet}
+
+<div class={cn(!bare && "overflow-hidden rounded-xl border", className)}>
+	<Table.Root
+		aria-label={label}
+		aria-busy={loading || undefined}
+		style={`min-width: ${minWidth}`}
+		class="min-w-0"
+	>
 		<Table.Header>
 			<Table.Row>
+				{#if selectable}
+					<Table.Head class="w-10">
+						<Checkbox
+							checked={allSelected}
+							indeterminate={someSelected}
+							onCheckedChange={(on) => toggleAll(on === true)}
+							aria-label={selectAllLabel}
+							disabled={loading || rows.length === 0}
+						/>
+					</Table.Head>
+				{/if}
 				{#each columns as column (column.key)}
 					<Table.Head
-						class={cn("whitespace-normal", column.numeric && "text-end")}
+						class={cn(
+							"whitespace-normal",
+							column.numeric && "text-end",
+							column.sortable && "h-10 p-0",
+							column.hideBelow && HIDE[column.hideBelow],
+							column.sticky && "bg-background sticky left-0 z-20",
+							column.headClass ?? column.class,
+						)}
 						style={column.width ? `width: ${column.width}` : undefined}
+						aria-sort={ariaSort(column)}
 					>
-						{column.label}
+						{#if column.sortable}
+							{@const dir = sort?.key === column.key ? sort.direction : null}
+							<button
+								type="button"
+								class={cn(
+									"t-press hover:bg-muted/30 focus-visible:ring-ring flex h-10 w-full items-center gap-1 px-2 text-xs font-medium outline-none focus-visible:ring-2 focus-visible:ring-inset",
+									column.numeric ? "justify-end" : "justify-start",
+								)}
+								onclick={() => (sort = toggleSort(sort, column.key as keyof Row & string))}
+							>
+								{#if head}{@render head(column)}{:else}{column.label}{/if}
+								{#if dir === "asc"}
+									<CaretUp class="text-foreground size-3.5" weight="bold" aria-hidden="true" />
+								{:else if dir === "desc"}
+									<CaretDown class="text-foreground size-3.5" weight="bold" aria-hidden="true" />
+								{:else}
+									<CaretUpDown class="text-muted-foreground/75 size-3.5" aria-hidden="true" />
+								{/if}
+							</button>
+						{:else if head}
+							{@render head(column)}
+						{:else}
+							{column.label}
+						{/if}
 					</Table.Head>
 				{/each}
+				{#if rowHref}
+					<th class="w-0 p-0"><span class="sr-only">Open</span></th>
+				{/if}
 			</Table.Row>
 		</Table.Header>
-		<Table.Body>
-			{#each rows as row (rowKey(row))}
-				<Table.Row class={rowClass?.(row)}>
-					{@render body(row)}
-				</Table.Row>
-			{/each}
-		</Table.Body>
+		{#if loading}
+			<TableSkeleton rows={skeletonRows} columns={skeletonColumns} />
+		{:else}
+			{#if group}
+				{#each entries as entry (entry.group.key)}
+					{@const folded = collapsible && collapsed.has(entry.group.key)}
+					<Table.Body>
+						<Table.Row class="bg-muted/40 hover:bg-muted/40 hover:translate-y-0 hover:shadow-none">
+							<Table.Head
+								colspan={span + (rowHref ? 1 : 0)}
+								scope="colgroup"
+								class="text-foreground h-10 p-0"
+							>
+								{#if collapsible}
+									<button
+										type="button"
+										aria-expanded={!folded}
+										class="t-press focus-visible:ring-ring flex h-10 w-full items-center gap-2 px-2 text-start outline-none focus-visible:ring-2 focus-visible:ring-inset"
+										onclick={() => toggleGroup(entry.group.key)}
+									>
+										<CaretDown
+											class={cn(
+												"size-3.5 shrink-0 transition-transform duration-[var(--duration-quick)] ease-[var(--ease-smooth-out)] motion-reduce:transition-none",
+												folded && "-rotate-90",
+											)}
+											aria-hidden="true"
+										/>
+										{#if groupHeader}{@render groupHeader(entry.group)}{:else}{entry.group.key}{/if}
+									</button>
+								{:else}
+									<span class="flex h-10 items-center px-2">
+										{#if groupHeader}{@render groupHeader(entry.group)}{:else}{entry.group.key}{/if}
+									</span>
+								{/if}
+							</Table.Head>
+						</Table.Row>
+						{#if !folded}
+							{#each entry.group.rows as row (rowKey(row))}
+								{@render rowOrMenu(row)}
+							{/each}
+						{/if}
+					</Table.Body>
+				{/each}
+			{:else}
+				<Table.Body>
+					{#each rows as row (rowKey(row))}
+						{@render rowOrMenu(row)}
+					{/each}
+					{#if rows.length === 0 && empty}
+						<Table.Row class="hover:bg-transparent hover:translate-y-0 hover:shadow-none">
+							<Table.Cell colspan={span + (rowHref ? 1 : 0)} class="whitespace-normal"
+								>{@render empty()}</Table.Cell
+							>
+						</Table.Row>
+					{/if}
+				</Table.Body>
+			{/if}
+			{#if trailing}
+				<tbody>
+					<tr><td colspan={span + (rowHref ? 1 : 0)} class="p-0">{@render trailing()}</td></tr>
+				</tbody>
+			{/if}
+		{/if}
 		{#if footer}
 			<Table.Footer>
 				<Table.Row>
+					{#if selectable}<Table.Cell></Table.Cell>{/if}
 					{@render body(footer)}
+					{#if rowHref}<td></td>{/if}
 				</Table.Row>
 			</Table.Footer>
 		{/if}

package/src/components/table-view/table-view.test.ts

@@ -25,7 +25,13 @@ function render(extra: Record<string, unknown> = {}) {
     },
   });
   flushSync();
-  return { target, done: () => { void unmount(app); target.remove(); } };
+  return {
+    target,
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
 }
 
 describe("TableView", () => {
@@ -51,3 +57,104 @@ describe("TableView", () => {
     done();
   });
 });
+
+describe("TableView extensions", () => {
+  const sortable = [
+    { key: "name", label: "Name", sortable: true },
+    { key: "total", label: "Total", numeric: true, sortable: true },
+  ];
+
+  it("sorts from a head button and sets aria-sort", () => {
+    const { target, done } = render({ columns: sortable, sort: { key: "name", direction: "asc" } });
+    const heads = target.querySelectorAll("thead th");
+    expect(heads[0].getAttribute("aria-sort")).toBe("ascending");
+    expect(heads[1].getAttribute("aria-sort")).toBe("none");
+    (heads[1].querySelector("button") as HTMLButtonElement).click();
+    flushSync();
+    expect(target.querySelectorAll("thead th")[1].getAttribute("aria-sort")).toBe("ascending");
+    done();
+  });
+
+  it("draws a real link per row", () => {
+    const { target, done } = render({ rowHref: (row: Row) => `/lines/${row.id}` });
+    const links = [...target.querySelectorAll("tbody a")].map((a) => a.getAttribute("href"));
+    expect(links).toEqual(["/lines/a", "/lines/b"]);
+    expect(target.querySelector("tbody a")?.getAttribute("aria-label")).toBe("Audit");
+    done();
+  });
+
+  it("selects rows and shows select-all as indeterminate", () => {
+    const selected = new Set<string>(["a"]);
+    const { target, done } = render({ selectable: true, selected });
+    const boxes = target.querySelectorAll<HTMLElement>("[role=checkbox]");
+    expect(boxes.length).toBe(3);
+    expect(boxes[0].getAttribute("aria-checked")).toBe("mixed");
+    expect(target.querySelectorAll("tbody tr")[0].getAttribute("data-state")).toBe("selected");
+    done();
+  });
+
+  it("puts a header row over each group, spanning every column", () => {
+    const { target, done } = render({ group: (row: Row) => (row.id === "a" ? "One" : "Two") });
+    const heads = target.querySelectorAll("tbody th[colspan]");
+    expect([...heads].map((h) => h.textContent?.trim())).toEqual(["One", "Two"]);
+    expect(heads[0].getAttribute("colspan")).toBe("2");
+    done();
+  });
+
+  it("swaps rows for skeletons inside the same frame while loading", () => {
+    const { target, done } = render({ loading: true, skeletonRows: 3 });
+    expect(target.querySelector("table")?.getAttribute("aria-busy")).toBe("true");
+    expect(target.querySelectorAll("tbody tr").length).toBe(3);
+    expect(target.querySelector("tbody td")?.textContent?.trim()).toBe("");
+    done();
+  });
+
+  it("drops the frame when bare", () => {
+    const { target, done } = render({ bare: true });
+    expect((target.firstElementChild as HTMLElement).className).not.toContain("border");
+    done();
+  });
+});
+
+describe("TableView row actions", () => {
+  it("opens a row on click and Enter, but leaves a nested button alone", () => {
+    const calls: string[] = [];
+    const cell = createRawSnippet<[{ text: string }]>((cellProps) => ({
+      render: () => `<span><button>${cellProps().text}</button></span>`,
+    }));
+    const { target, done } = render({ onRowClick: (row: Row) => calls.push(row.id), cell });
+    const tr = target.querySelector("tbody tr") as HTMLElement;
+    tr.click();
+    tr.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    (tr.querySelector("button") as HTMLButtonElement).click();
+    expect(calls).toEqual(["a", "a"]);
+    done();
+  });
+
+  it("folds a group, hides a column below a breakpoint and shows a sub-row", () => {
+    const subRow = createRawSnippet(() => ({ render: () => `<i>detail</i>` }));
+    const { target, done } = render({
+      group: () => "All",
+      collapsible: true,
+      subRow,
+      expanded: (row: Row) => row.id === "a",
+      columns: [
+        { key: "name", label: "Name" },
+        { key: "total", label: "Total", hideBelow: "md" },
+      ],
+    });
+    expect(target.querySelector("tbody i")).not.toBeNull();
+    expect(target.querySelector("thead th:last-child")?.className).toContain("md:table-cell");
+    (target.querySelector("tbody th button") as HTMLButtonElement).click();
+    flushSync();
+    expect(target.querySelectorAll("tbody tr").length).toBe(1);
+    done();
+  });
+
+  it("draws the empty snippet across the columns", () => {
+    const empty = createRawSnippet(() => ({ render: () => `<p>Nothing</p>` }));
+    const { target, done } = render({ rows: [], empty });
+    expect(target.querySelector("tbody td")?.getAttribute("colspan")).toBe("2");
+    done();
+  });
+});

package/src/components/table-view/types.ts

@@ -1,14 +1,25 @@
 /** One column of a `TableView`. */
 export interface TableColumn<Row> {
-	/** The key of the value in the row. */
-	key: string;
-	label: string;
-	/** A number or an amount: right-aligned, tabular figures, never wraps. */
-	numeric?: boolean;
-	/** Turns the raw value into the text shown. A string value that has no `format` prints as it is. A money column passes its own currency formatter. */
-	format?: (value: unknown, row: Row) => string;
-	/** A column width such as `"30%"` or `"8rem"`. Leave it out and the table shares the rest. */
-	width?: string;
-	/** Draws the column in the muted colour. */
-	muted?: boolean;
+  /** The key of the value in the row. */
+  key: string;
+  label: string;
+  /** A number or an amount: right-aligned, tabular figures, never wraps. */
+  numeric?: boolean;
+  /** Turns the raw value into the text shown. A string value that has no `format` prints as it is. A money column passes its own currency formatter. */
+  format?: (value: unknown, row: Row) => string;
+  /** A column width such as `"30%"` or `"8rem"`. Leave it out and the table shares the rest. */
+  width?: string;
+  /** Draws the column in the muted colour. */
+  muted?: boolean;
+  /** Click or press Enter on the head to sort. The table sorts nothing itself: bind `sort` and order `rows` with `sortRows`. */
+  sortable?: boolean;
+  /** Lifts the column's cells above the row link, so a button or a link inside it takes its own click. */
+  interactive?: boolean;
+  /** Hidden below this breakpoint, head and cells both. */
+  hideBelow?: "sm" | "md" | "lg";
+  /** Pins the column to the left edge while the table scrolls sideways. */
+  sticky?: boolean;
+  /** Extra classes on the column's cells (and its head, unless `headClass` is set). */
+  class?: string;
+  headClass?: string;
 }

package/src/components/tags-input/index.ts

@@ -0,0 +1,13 @@
+export { default as TagsInput } from "./tags-input.svelte";
+export {
+  addTag,
+  canCreate,
+  cleanTags,
+  collectOptions,
+  editDistance,
+  findOption,
+  fold,
+  matchOptions,
+  removeTag,
+  splitTags,
+} from "./tags.js";