@heyramzi/ui 0.0.0-stage → 1.53.0

package/src/components/copy/copy-button.svelte

@@ -0,0 +1,175 @@
+<script lang="ts">
+/**
+ * The one copy control. No `text` prop draws the icon button; `text` draws the
+ * chip. `agent` marks a payload written for a model.
+ */
+
+// =========================
+// IMPORTS
+// =========================
+import { Check, Copy, StarFour } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { buttonVariants } from "../../shadcn/button/index.js";
+import type { HTMLButtonAttributes } from "svelte/elements";
+import { copyText } from "./clipboard.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props extends Omit<HTMLButtonAttributes, "value" | "onclick" | "children"> {
+	/**
+	 * What lands on the clipboard. A function runs on the click, so a long list
+	 * doesn't build every prompt up front. It may return a promise.
+	 */
+	value: string | (() => string | Promise<string>);
+	/** Names the thing being copied, for a screen reader and the tooltip. */
+	label?: string;
+	/** Announced when the write lands; see `announce`. */
+	copiedLabel?: string;
+	/** The chip's visible text. Its presence is what makes this a chip. */
+	text?: string;
+	/** Marks the payload as an instruction for an AI rather than a raw string. */
+	agent?: boolean;
+	/**
+	 * `sm` matches `OpenIn`, for the icon row inside a calendar chip. `md` is
+	 * the 28px icon `Button`, for a toolbar that sits beside other icon buttons.
+	 */
+	size?: "default" | "md" | "sm";
+	/**
+	 * The icon button's `Button` variant: ghost unless it sits beside an outline
+	 * one. `inline` is for the chip: it takes the surrounding text's font and
+	 * colour, and the icon trails it.
+	 */
+	variant?: "ghost" | "outline" | "inline";
+	/**
+	 * How a screen reader hears the copy. `region` keeps the name fixed and
+	 * announces `copiedLabel` in a live region. `name` swaps the button's own name
+	 * to `copiedLabel` (write it in full) and has no region, for a page that
+	 * renders hundreds of these.
+	 */
+	announce?: "region" | "name";
+	/** Runs after a write that landed, for a toast the call site owns. */
+	onCopied?: () => void;
+	class?: string;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	value,
+	label = "Copy",
+	copiedLabel = "Copied",
+	text,
+	agent = false,
+	size = "default",
+	variant = "ghost",
+	announce = "region",
+	onCopied,
+	class: className,
+	...restProps
+}: Props = $props();
+
+// =========================
+// STATE
+// =========================
+let copied = $state(false);
+let resetAt: ReturnType<typeof setTimeout> | undefined;
+
+// =========================
+// DERIVED
+// =========================
+const inline = $derived(text !== undefined && variant === "inline");
+
+// =========================
+// FUNCTIONS
+// =========================
+async function copy(event: MouseEvent) {
+	// Rows and cards are clickable; taking the payload out of one must not also
+	// open the record it belongs to.
+	event.stopPropagation();
+	event.preventDefault();
+	const payload = typeof value === "function" ? await value() : value;
+	if (!(await copyText(payload))) return;
+	copied = true;
+	clearTimeout(resetAt);
+	resetAt = setTimeout(() => (copied = false), 1400);
+	onCopied?.();
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<button
+	{...restProps}
+	type="button"
+	onclick={copy}
+	title={label}
+	aria-label={announce === "name" && copied ? copiedLabel : label}
+	class={cn(
+		"group/copy t-press shrink-0 outline-none focus-visible:ring-3 focus-visible:ring-ring/50",
+		text === undefined
+			? size === "sm"
+				? "grid size-5 place-items-center rounded-md hover:bg-accent"
+				: buttonVariants({
+					variant: variant === "outline" ? "outline" : "ghost",
+					size: size === "md" ? "sm" : "default",
+					icon: true,
+				})
+			: inline
+				? "inline-flex cursor-copy items-baseline gap-1.5 transition-colors hover:text-foreground"
+				: "flex items-center gap-1 rounded px-1.5 py-0.5 font-mono text-xs tabular-nums text-muted-foreground/70 transition-colors hover:bg-muted hover:text-foreground",
+		className,
+	)}
+>
+	<!-- One slot, two glyphs, per the transitions-dev icon-swap: the check
+	     arrives on the bounce, the copy glyph leaves without one. -->
+	<span
+		class={cn(
+			"relative grid place-items-center",
+			text === undefined && size !== "sm" ? "size-4" : "size-3",
+			inline && "order-last self-center opacity-60 transition-opacity group-hover/copy:opacity-100",
+		)}
+	>
+		<Check
+			class={cn(
+				"col-start-1 row-start-1 size-full transition-[opacity,transform] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)]",
+				inline ? "text-current" : "text-success-800 dark:text-success-400",
+				copied ? "scale-100 opacity-100" : "scale-50 opacity-0",
+			)}
+			weight="bold"
+			aria-hidden="true"
+		/>
+		{#if agent}
+			<StarFour
+				class={cn(
+					"col-start-1 row-start-1 size-full text-brand-indigo/70 transition-[opacity,color] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] group-hover/copy:text-brand-indigo",
+					copied ? "opacity-0" : "opacity-100",
+				)}
+				weight="bold"
+				aria-hidden="true"
+			/>
+		{:else}
+			<Copy
+				class={cn(
+					"col-start-1 row-start-1 size-full transition-[opacity,color] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)]",
+					inline
+						? "text-current"
+						: "text-muted-foreground group-hover/copy:text-foreground",
+					copied ? "opacity-0" : "opacity-100",
+				)}
+				aria-hidden="true"
+			/>
+		{/if}
+	</span>
+
+	{#if text !== undefined}
+		<span>{text}</span>
+	{/if}
+
+	<!-- The swap is invisible to a reader who cannot see it. -->
+	{#if announce === "region"}
+		<span aria-live="polite" class="sr-only">{copied ? copiedLabel : ""}</span>
+	{/if}
+</button>

package/src/components/copy/copy-button.test.ts

@@ -0,0 +1,110 @@
+import { flushSync, mount, unmount } from "svelte";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import CopyButton from "./copy-button.svelte";
+
+type Props = { value: string; [key: string]: unknown };
+
+// jsdom ships no clipboard, so the write is stubbed and asserted on directly.
+function stubClipboard(result: Promise<void> = Promise.resolve()) {
+  const writeText = vi.fn().mockReturnValue(result);
+  vi.stubGlobal("navigator", { clipboard: { writeText } });
+  return writeText;
+}
+
+function render(props: Props) {
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(CopyButton, { target, props });
+  flushSync();
+  return {
+    button: target.querySelector("button")!,
+    target,
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+async function click(button: HTMLButtonElement) {
+  button.click();
+  await vi.advanceTimersByTimeAsync(0);
+  flushSync();
+}
+
+describe("CopyButton", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("puts the value on the clipboard", async () => {
+    const writeText = stubClipboard();
+    const { button, done } = render({ value: "26011200", text: "26011200" });
+    await click(button);
+    expect(writeText).toHaveBeenCalledWith("26011200");
+    done();
+  });
+
+  it("names what it copies, so the button is not just a value", () => {
+    stubClipboard();
+    const { button, done } = render({ value: "abc123", text: "abc123", label: "Copy API key abc123" });
+    expect(button.getAttribute("aria-label")).toBe("Copy API key abc123");
+    done();
+  });
+
+  it("announces in a live region by default and keeps its name", async () => {
+    stubClipboard();
+    const { button, target, done } = render({ value: "x", label: "Copy id", copiedLabel: "Copied" });
+    await click(button);
+    expect(target.querySelector("[aria-live]")?.textContent).toBe("Copied");
+    expect(button.getAttribute("aria-label")).toBe("Copy id");
+    done();
+  });
+
+  // A page of 500 codes would read as a wall of live regions, so the name carries it.
+  it("announce name: no live region, the accessible name says it copied, then rests", async () => {
+    stubClipboard();
+    const { button, target, done } = render({
+      value: "25070080",
+      text: "25070080",
+      label: "Copy CN code 25070080",
+      copiedLabel: "CN code 25070080 copied",
+      announce: "name",
+    });
+    expect(target.querySelector("[aria-live]")).toBeNull();
+    await click(button);
+    expect(button.getAttribute("aria-label")).toBe("CN code 25070080 copied");
+    await vi.advanceTimersByTimeAsync(1500);
+    flushSync();
+    expect(button.getAttribute("aria-label")).toBe("Copy CN code 25070080");
+    done();
+  });
+
+  it("calls onCopied after a write that landed", async () => {
+    stubClipboard();
+    const onCopied = vi.fn();
+    const { button, done } = render({ value: "x", onCopied });
+    await click(button);
+    expect(onCopied).toHaveBeenCalledOnce();
+    done();
+  });
+
+  it("keeps the resting state when the browser refuses the clipboard", async () => {
+    const writeText = stubClipboard(Promise.reject(new Error("denied")));
+    const onCopied = vi.fn();
+    const { button, done } = render({
+      value: "x",
+      label: "Copy x",
+      copiedLabel: "x copied",
+      announce: "name",
+      onCopied,
+    });
+    await click(button);
+    expect(writeText).toHaveBeenCalled();
+    expect(button.getAttribute("aria-label")).toBe("Copy x");
+    expect(onCopied).not.toHaveBeenCalled();
+    done();
+  });
+});

package/src/components/copy/index.ts

@@ -0,0 +1,3 @@
+export { default as CopyButton } from "./copy-button.svelte";
+export { copyText, copyRichText, htmlToPlainText } from "./clipboard.js";
+export { Copied } from "./copied.svelte.js";

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"
+/>