@heyramzi/ui 6.1.0 → 8.0.0

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

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  toggleSort,
+  sortRows,
+  paginateRows,
+  totalPages,
+  normalizeQuery,
+  containsQuery,
+  anyContainsQuery,
+  formatCount,
+} from "./data-table.js";
+
+type Item = { name: string; value: number; date: string | null };
+
+const items: Item[] = [
+  { name: "Charlie", value: 3, date: "2025-03-01" },
+  { name: "Alice", value: 1, date: "2025-01-01" },
+  { name: "Bob", value: 2, date: null },
+];
+
+describe("toggleSort", () => {
+  it("returns asc when no current sort", () => {
+    expect(toggleSort<Item>(null, "name")).toEqual({ key: "name", direction: "asc" });
+  });
+
+  it("returns desc when current is asc on same key", () => {
+    expect(toggleSort<Item>({ key: "name", direction: "asc" }, "name")).toEqual({
+      key: "name",
+      direction: "desc",
+    });
+  });
+
+  it("returns null when current is desc on same key", () => {
+    expect(toggleSort<Item>({ key: "name", direction: "desc" }, "name")).toBeNull();
+  });
+
+  it("returns asc on new key", () => {
+    expect(toggleSort<Item>({ key: "name", direction: "desc" }, "value")).toEqual({
+      key: "value",
+      direction: "asc",
+    });
+  });
+});
+
+describe("sortRows", () => {
+  it("returns same order when sort is null", () => {
+    expect(sortRows(items, null)).toEqual(items);
+  });
+
+  it("sorts strings ascending", () => {
+    const sorted = sortRows(items, { key: "name", direction: "asc" });
+    expect(sorted.map((i) => i.name)).toEqual(["Alice", "Bob", "Charlie"]);
+  });
+
+  it("sorts strings descending", () => {
+    const sorted = sortRows(items, { key: "name", direction: "desc" });
+    expect(sorted.map((i) => i.name)).toEqual(["Charlie", "Bob", "Alice"]);
+  });
+
+  it("sorts numbers ascending", () => {
+    const sorted = sortRows(items, { key: "value", direction: "asc" });
+    expect(sorted.map((i) => i.value)).toEqual([1, 2, 3]);
+  });
+
+  it("pushes nulls to end", () => {
+    const sorted = sortRows(items, { key: "date", direction: "asc" });
+    expect(sorted[2].date).toBeNull();
+  });
+
+  it("does not mutate original array", () => {
+    const original = [...items];
+    sortRows(items, { key: "name", direction: "asc" });
+    expect(items).toEqual(original);
+  });
+});
+
+describe("paginateRows", () => {
+  const rows = Array.from({ length: 25 }, (_, i) => ({ id: i }));
+
+  it("returns first page", () => {
+    const result = paginateRows(rows, 1, 10);
+    expect(result).toHaveLength(10);
+    expect(result[0].id).toBe(0);
+  });
+
+  it("returns last partial page", () => {
+    const result = paginateRows(rows, 3, 10);
+    expect(result).toHaveLength(5);
+    expect(result[0].id).toBe(20);
+  });
+
+  it("returns empty for out-of-range page", () => {
+    expect(paginateRows(rows, 5, 10)).toHaveLength(0);
+  });
+});
+
+describe("totalPages", () => {
+  it("calculates correct total", () => {
+    expect(totalPages(25, 10)).toBe(3);
+    expect(totalPages(20, 10)).toBe(2);
+    expect(totalPages(0, 10)).toBe(1);
+  });
+});
+
+describe("formatCount", () => {
+  it("shows total when no filter active", () => {
+    expect(formatCount(10, 10, "items")).toBe("10 items");
+  });
+  it("shows filtered of total when filtered", () => {
+    expect(formatCount(3, 10, "items")).toBe("3 of 10 items");
+  });
+  it("singularizes when count is 1", () => {
+    expect(formatCount(1, 1, "items")).toBe("1 item");
+  });
+  it("singularizes filtered count", () => {
+    expect(formatCount(1, 10, "items")).toBe("1 of 10 items");
+  });
+});
+
+describe("existing utilities", () => {
+  it("normalizeQuery trims and lowercases", () => {
+    expect(normalizeQuery("  Hello  ")).toBe("hello");
+  });
+
+  it("containsQuery handles null", () => {
+    expect(containsQuery(null, "test")).toBe(false);
+    expect(containsQuery("testing", "test")).toBe(true);
+  });
+
+  it("anyContainsQuery matches any value", () => {
+    expect(anyContainsQuery(["foo", null, "bar"], "bar")).toBe(true);
+    expect(anyContainsQuery(["foo", null], "bar")).toBe(false);
+  });
+});

package/src/components/data-table/data-table.ts

@@ -0,0 +1,77 @@
+import type { Snippet } from "svelte";
+
+export type DataTableFilter<T> = (row: T, query: string) => boolean;
+
+export type DataTableEmptyState = {
+  title: string;
+  description: string;
+  searchDescription?: string;
+  action?: Snippet;
+};
+
+export function normalizeQuery(query: string): string {
+  return query.trim().toLowerCase();
+}
+
+export function containsQuery(value: string | null | undefined, query: string): boolean {
+  if (!query) return true;
+
+  return value?.toLowerCase().includes(query) ?? false;
+}
+
+export function anyContainsQuery(values: Array<string | null | undefined>, query: string): boolean {
+  return values.some((value) => containsQuery(value, query));
+}
+
+// ========================= TYPES
+export type SortDirection = "asc" | "desc";
+
+export type SortState<T> = {
+  key: keyof T & string;
+  direction: SortDirection;
+} | null;
+
+// ========================= FUNCTIONS
+export function toggleSort<T>(current: SortState<T>, key: keyof T & string): SortState<T> {
+  if (current?.key !== key) return { key, direction: "asc" };
+  if (current.direction === "asc") return { key, direction: "desc" };
+  return null;
+}
+
+export function sortRows<T>(rows: T[], sort: SortState<T>): T[] {
+  if (!sort) return rows;
+  const { key, direction } = sort;
+  const multiplier = direction === "asc" ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const aVal = a[key];
+    const bVal = b[key];
+    if (aVal == null && bVal == null) return 0;
+    if (aVal == null) return 1;
+    if (bVal == null) return -1;
+    if (typeof aVal === "string" && typeof bVal === "string") {
+      return multiplier * aVal.localeCompare(bVal);
+    }
+    if (typeof aVal === "number" && typeof bVal === "number") {
+      return multiplier * (aVal - bVal);
+    }
+    return multiplier * String(aVal).localeCompare(String(bVal));
+  });
+}
+
+export function paginateRows<T>(rows: T[], page: number, pageSize: number): T[] {
+  const start = (page - 1) * pageSize;
+  return rows.slice(start, start + pageSize);
+}
+
+export function totalPages(total: number, pageSize: number): number {
+  return Math.max(1, Math.ceil(total / pageSize));
+}
+
+export function formatCount(visible: number, total: number, label: string): string {
+  const singular = label.endsWith("s") ? label.slice(0, -1) : label;
+  if (visible === total) {
+    const displayLabel = visible === 1 ? singular : label;
+    return `${total} ${displayLabel}`;
+  }
+  return `${visible} of ${total} ${label}`;
+}

package/src/components/data-table/index.ts

@@ -0,0 +1,20 @@
+export { default as InfiniteScroll } from "./infinite-scroll.svelte";
+export { default as Pagination } from "./pagination.svelte";
+export { default as RowArrow } from "./row-arrow.svelte";
+export { default as RowContextMenu } from "./row-context-menu.svelte";
+export { default as SortableHead } from "./sortable-head.svelte";
+export { default as TableSkeleton } from "./table-skeleton.svelte";
+export {
+  anyContainsQuery,
+  containsQuery,
+  formatCount,
+  normalizeQuery,
+  paginateRows,
+  sortRows,
+  toggleSort,
+  totalPages,
+  type DataTableEmptyState,
+  type DataTableFilter,
+  type SortDirection,
+  type SortState,
+} from "./data-table.js";

package/src/components/data-table/infinite-scroll.svelte

@@ -0,0 +1,69 @@
+<script lang="ts" generics="T">
+// ========================= IMPORTS
+import type { Snippet } from "svelte";
+import { Spinner } from "../../shadcn/spinner/index.js";
+
+// ========================= TYPES
+type Props = {
+	items: T[];
+	isDone: boolean;
+	isLoading: boolean;
+	children: Snippet<[{ items: T[] }]>;
+	/** Skeleton snippet rendered while loading more */
+	skeleton?: Snippet;
+	onLoadMore: () => void;
+	threshold?: number;
+	loadingClass?: string;
+};
+
+// ========================= PROPS
+let {
+	items,
+	isDone,
+	isLoading,
+	children,
+	skeleton,
+	onLoadMore,
+	threshold = 200,
+	loadingClass,
+}: Props = $props();
+
+// ========================= STATE
+let sentinelEl: HTMLDivElement | undefined = $state();
+
+// ========================= EFFECTS
+$effect(() => {
+	if (!sentinelEl || isDone) return;
+
+	const observer = new IntersectionObserver(
+		(entries) => {
+			if (entries[0]?.isIntersecting && !isLoading && !isDone) {
+				onLoadMore();
+			}
+		},
+		{ rootMargin: `${threshold}px` },
+	);
+
+	observer.observe(sentinelEl);
+	return () => observer.disconnect();
+});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{@render children({ items })}
+
+{#if !isDone}
+	<div bind:this={sentinelEl} class={loadingClass ?? ""}>
+		{#if isLoading}
+			{#if skeleton}
+				{@render skeleton()}
+			{:else}
+				<div class="flex items-center justify-center py-4">
+					<Spinner class="size-5 text-muted-foreground" />
+				</div>
+			{/if}
+		{/if}
+	</div>
+{/if}

package/src/components/data-table/pagination.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+import { CaretLeft, CaretRight } from "phosphor-svelte";
+import { Button } from "../../shadcn/button/index.js";
+import { totalPages as calcTotalPages } from "./data-table.js";
+
+// ========================= TYPES
+type Props = {
+	page: number;
+	pageSize: number;
+	total: number;
+	onPageChange?: (page: number) => void;
+	/** If provided, renders <a> tags instead of buttons (for server-side pagination) */
+	buildHref?: (page: number) => string;
+};
+
+// ========================= PROPS
+let { page, pageSize, total, onPageChange, buildHref }: Props = $props();
+
+// ========================= DERIVED
+let pages = $derived(calcTotalPages(total, pageSize));
+let hasPrev = $derived(page > 1);
+let hasNext = $derived(page < pages);
+let start = $derived((page - 1) * pageSize + 1);
+let end = $derived(Math.min(page * pageSize, total));
+</script>
+
+{#if pages > 1}
+	<div class="flex items-center justify-between border-t px-4 py-3 text-sm text-muted-foreground">
+		<span>{start}-{end} of {total}</span>
+		<div class="flex items-center gap-1">
+			{#if buildHref}
+				{#if hasPrev}
+					<Button variant="outline" size="sm" icon href={buildHref(page - 1)}>
+						<CaretLeft class="size-4" />
+					</Button>
+				{:else}
+					<Button variant="outline" size="sm" icon disabled>
+						<CaretLeft class="size-4" />
+					</Button>
+				{/if}
+				<span class="mx-2 tabular-nums">{page} / {pages}</span>
+				{#if hasNext}
+					<Button variant="outline" size="sm" icon href={buildHref(page + 1)}>
+						<CaretRight class="size-4" />
+					</Button>
+				{:else}
+					<Button variant="outline" size="sm" icon disabled>
+						<CaretRight class="size-4" />
+					</Button>
+				{/if}
+			{:else}
+				<Button variant="outline" size="sm" icon disabled={!hasPrev} onclick={() => onPageChange?.(page - 1)}>
+					<CaretLeft class="size-4" />
+				</Button>
+				<span class="mx-2 tabular-nums">{page} / {pages}</span>
+				<Button variant="outline" size="sm" icon disabled={!hasNext} onclick={() => onPageChange?.(page + 1)}>
+					<CaretRight class="size-4" />
+				</Button>
+			{/if}
+		</div>
+	</div>
+{/if}

package/src/components/data-table/row-arrow.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { CaretRight } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<CaretRight
+	class={cn("size-3.5 text-muted-foreground opacity-0 transition-opacity group-hover/row:opacity-100", className)}
+	weight="bold"
+	aria-hidden="true"
+/>

package/src/components/data-table/row-context-menu.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import * as ContextMenu from "../../shadcn/context-menu/index.js";
+import { HoldToConfirm } from "../hold-to-confirm/index.js";
+import { ArrowUpRight, Copy, LinkSimple, Trash } from "phosphor-svelte";
+import type { Snippet } from "svelte";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	onDelete: () => void;
+	href?: string;
+	id?: string;
+	deleteLabel?: string;
+	copyLinkLabel?: string;
+	copyIdLabel?: string;
+	/** Called after a successful clipboard copy so consumers can show their own toast */
+	onCopied?: () => void;
+	children: Snippet<[Record<string, unknown>]>;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	onDelete,
+	href,
+	id,
+	deleteLabel = "Delete",
+	copyLinkLabel = "Copy link",
+	copyIdLabel = "Copy ID",
+	onCopied,
+	children,
+}: Props = $props();
+
+// =========================
+// FUNCTIONS
+// =========================
+function handleOpen() {
+	if (href) window.location.href = href;
+}
+
+// WHY the whole URL and not the path: what leaves this menu is pasted into a
+// message, a doc or an agent prompt, none of which can resolve "/clients/42".
+async function handleCopyLink() {
+	if (!href) return;
+	await navigator.clipboard.writeText(new URL(href, window.location.origin).href);
+	onCopied?.();
+}
+
+async function handleCopyId() {
+	if (!id) return;
+	await navigator.clipboard.writeText(id);
+	onCopied?.();
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<ContextMenu.Root>
+	<ContextMenu.Trigger>
+		{#snippet child({ props })}
+			{@render children(props)}
+		{/snippet}
+	</ContextMenu.Trigger>
+	<ContextMenu.Content class="w-48">
+		{#if href}
+			<ContextMenu.Item onclick={handleOpen}>
+				<ArrowUpRight size={14} />
+				Open
+			</ContextMenu.Item>
+		{/if}
+		{#if href}
+			<ContextMenu.Item onclick={handleCopyLink}>
+				<LinkSimple size={14} />
+				{copyLinkLabel}
+			</ContextMenu.Item>
+		{/if}
+		{#if id}
+			<ContextMenu.Item onclick={handleCopyId}>
+				<Copy size={14} />
+				{copyIdLabel}
+			</ContextMenu.Item>
+		{/if}
+		{#if href || id}
+			<ContextMenu.Separator />
+		{/if}
+		<HoldToConfirm
+			duration={800}
+			onConfirm={onDelete}
+			class="relative flex w-full cursor-default items-center justify-start gap-2 rounded-md px-1.5 py-1 text-sm text-destructive outline-hidden"
+		>
+			{#snippet idle()}
+				<Trash size={14} />
+				{deleteLabel}
+			{/snippet}
+			{#snippet holding()}
+				Hold to delete...
+			{/snippet}
+		</HoldToConfirm>
+	</ContextMenu.Content>
+</ContextMenu.Root>

package/src/components/data-table/row-context-menu.test.ts

@@ -0,0 +1,18 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vite-plus/test";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const sourcePath = resolve(here, "row-context-menu.svelte");
+if (!existsSync(sourcePath)) {
+  throw new Error(`Unable to find source file: ${sourcePath}`);
+}
+const source = readFileSync(sourcePath, "utf8");
+
+describe("row context menu delete affordance", () => {
+  it("renders the hold-to-delete action at full menu-item width", () => {
+    expect(source).toContain("w-full");
+    expect(source).toContain("justify-start");
+  });
+});

package/src/components/data-table/sortable-head.svelte

@@ -0,0 +1,56 @@
+<script lang="ts" generics="T">
+import type { Snippet } from "svelte";
+import { CaretDown, CaretUp, CaretUpDown } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import type { SortDirection, SortState } from "./data-table.js";
+
+// ========================= TYPES
+type Props = {
+	key: keyof T & string;
+	sort: SortState<T>;
+	onSort: (key: keyof T & string) => void;
+	class?: string;
+	children: Snippet;
+};
+
+// ========================= PROPS
+let { key, sort, onSort, class: className, children }: Props = $props();
+
+// ========================= DERIVED
+let active = $derived(sort?.key === key);
+let direction = $derived<SortDirection | null>(sort && active ? sort.direction : null);
+let ariaSort = $derived<"ascending" | "descending" | "none">(
+	direction === "asc" ? "ascending" : direction === "desc" ? "descending" : "none",
+);
+
+function handleKeydown(e: KeyboardEvent) {
+	if (e.key === "Enter" || e.key === " ") {
+		e.preventDefault();
+		onSort(key);
+	}
+}
+</script>
+
+<th
+	data-slot="table-head"
+	class={cn(
+		"text-muted-foreground h-8 px-2 text-left align-middle text-xs font-medium whitespace-nowrap select-none",
+		"cursor-pointer hover:bg-muted/30 transition-colors",
+		className,
+	)}
+	tabindex="0"
+	aria-sort={ariaSort}
+	onclick={() => onSort(key)}
+	onkeydown={handleKeydown}
+>
+	<span class="inline-flex items-center gap-1">
+		{@render children()}
+		{#if direction === "asc"}
+			<CaretUp class="size-3.5 text-foreground" weight="bold" />
+		{:else if direction === "desc"}
+			<CaretDown class="size-3.5 text-foreground" weight="bold" />
+		{:else}
+			<CaretUpDown class="size-3.5 text-muted-foreground/50" />
+		{/if}
+	</span>
+</th>

package/src/components/data-table/table-skeleton.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+// ========================= IMPORTS
+import { Skeleton } from "../../shadcn/skeleton/index.js";
+
+// ========================= TYPES
+type ColumnDef = {
+	width?: string;
+	align?: "left" | "center" | "right";
+	/** Show a small circle before the skeleton bar (e.g. logo/avatar column) */
+	circle?: boolean;
+};
+
+type Props = {
+	/** Number of skeleton rows to render */
+	rows?: number;
+	/** Column definitions control skeleton widths and alignment */
+	columns?: ColumnDef[];
+	/** Simple mode: just specify column count */
+	columnCount?: number;
+	class?: string;
+};
+
+// ========================= PROPS
+let {
+	rows = 5,
+	columns,
+	columnCount = 6,
+	class: className,
+}: Props = $props();
+
+// ========================= DERIVED
+let cols = $derived(
+	columns ??
+		Array.from<unknown, ColumnDef>({ length: columnCount }, () => ({
+			width: undefined,
+			align: "left" as const,
+		})),
+);
+
+const WIDTHS = ["w-24", "w-20", "w-28", "w-16", "w-32", "w-20"];
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<tbody class={className}>
+	{#each { length: rows } as _, rowIdx (rowIdx)}
+		<tr
+			data-slot="table-row"
+			class="border-b border-border/50 transition-opacity"
+			style="animation: skeleton-fade-in var(--duration-slow) var(--ease-out) calc(var(--duration-stagger) * {rowIdx}) both"
+		>
+			{#each cols as col, colIdx (colIdx)}
+				<td
+					data-slot="table-cell"
+					class="h-11 px-2 {col.align === 'center' ? 'text-center' : col.align === 'right' ? 'text-right' : ''}"
+				>
+					<div class="flex items-center gap-2 {col.align === 'center' ? 'justify-center' : col.align === 'right' ? 'justify-end' : ''}">
+						{#if col.circle}
+							<Skeleton class="size-6 shrink-0 rounded-md" />
+						{/if}
+						<Skeleton
+							class="h-3.5 rounded {col.width ?? WIDTHS[(rowIdx + colIdx) % WIDTHS.length]}"
+						/>
+					</div>
+				</td>
+			{/each}
+		</tr>
+	{/each}
+</tbody>
+
+<style>
+	@keyframes skeleton-fade-in {
+		from {
+			opacity: 0;
+			transform: translateY(4px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+</style>