@heyramzi/ui 2.23.0 → 3.0.0

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

@@ -1,56 +1,86 @@
 <script lang="ts" generics="T">
+	/*
+	 * The one sortable column head, for TableView, the dashboard DataTable and hand-built
+	 * tables. Every sortable head shows its caret: hover-only makes people hunt.
+	 */
+
+	// ========================= IMPORTS
 	import type { Snippet } from "svelte";
 	import { CaretDown, CaretUp, CaretUpDown } from "phosphor-svelte";
 	import { cn } from "../../lib/utils.js";
+	import * as Table from "../../shadcn/table/index.js";
 	import type { SortDirection, SortState } from "./data-table.js";
 
 	// ========================= TYPES
 	interface Props {
 		key: keyof T & string;
 		sort: SortState<T>;
+		/** Called on click and on Enter/Space. Choosing the next direction is the caller's. */
 		onSort: (key: keyof T & string) => void;
+		/** Numbers right-align to their digits, so their caret leads the label. */
+		numeric?: boolean;
+		/** The long form of an abbreviated head, as the browser tooltip. */
+		title?: string;
 		class?: string;
+		style?: string;
 		children: Snippet;
 	}
 
 	// ========================= PROPS
-	let { key, sort, onSort, class: className, children }: Props = $props();
+	let {
+		key,
+		sort,
+		onSort,
+		numeric = false,
+		title,
+		class: className,
+		style,
+		children,
+	}: Props = $props();
 
 	// ========================= DERIVED
-	let active = $derived(sort?.key === key);
-	let direction = $derived<SortDirection | null>(sort && active ? sort.direction : null);
+	let direction = $derived<SortDirection | null>(sort?.key === key ? 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"
+<!-- A real button, so a screen reader calls the head a control; aria-sort stays on the th.
+     Its ::after covers the cell, so the whole head takes the click. -->
+<Table.Head
+	scope="col"
+	{title}
+	{style}
 	class={cn(
-		"text-muted-foreground h-8 px-2 text-left align-middle text-xs font-medium whitespace-nowrap select-none",
+		"relative select-none",
 		"cursor-pointer transition-colors duration-quick ease-smooth-out hover:bg-foreground/4 motion-reduce:transition-none",
+		"has-[button:focus-visible]:shadow-(--ring-focus-inset)",
+		numeric && "text-right",
 		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" />
+	<!-- Pinned to the line's top, not its baseline: a leading caret gave the span the icon's foot
+	     as its baseline and lifted a numeric label 1.5px above the plain heads beside it. -->
+	<button
+		type="button"
+		class="inline-flex cursor-pointer items-center gap-1 align-top outline-none after:absolute after:inset-0 focus-visible:shadow-none"
+		onclick={() => onSort(key)}
+	>
+		{#if numeric}
+			{@render caret()}{@render children()}
 		{:else}
-			<CaretUpDown class="size-3.5 text-muted-foreground" />
+			{@render children()}{@render caret()}
 		{/if}
-	</span>
-</th>
+	</button>
+</Table.Head>
+
+{#snippet caret()}
+	{#if direction === "asc"}
+		<CaretUp class="size-3.5 shrink-0 text-foreground" weight="bold" aria-hidden="true" />
+	{:else if direction === "desc"}
+		<CaretDown class="size-3.5 shrink-0 text-foreground" weight="bold" aria-hidden="true" />
+	{:else}
+		<CaretUpDown class="size-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
+	{/if}
+{/snippet}

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

@@ -0,0 +1,38 @@
+import type { Snippet } from "svelte";
+import type { SortState } from "./data-table.js";
+declare function $$render<T>(): {
+    props: {
+        key: keyof T & string;
+        sort: SortState<T>;
+        /** Called on click and on Enter/Space. Choosing the next direction is the caller's. */
+        onSort: (key: keyof T & string) => void;
+        /** Numbers right-align to their digits, so their caret leads the label. */
+        numeric?: boolean;
+        /** The long form of an abbreviated head, as the browser tooltip. */
+        title?: string;
+        class?: string;
+        style?: string;
+        children: Snippet;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<T> = InstanceType<typeof $$Component<T>>;
+export default $$Component;

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

@@ -0,0 +1,18 @@
+type ColumnDef = {
+    width?: string;
+    align?: "left" | "center" | "right";
+    /** Show a small circle before the skeleton bar (e.g. logo/avatar column) */
+    circle?: boolean;
+};
+interface 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;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/docs/doc-page.svelte

@@ -17,7 +17,11 @@
 		title: string;
 		/** One line under the title. Optional: a page with nothing to add leaves it out. */
 		summary?: string;
-		icon?: Component<{ class?: string; weight?: "bold" }>;
+		icon?: Component<{
+			class?: string;
+			weight?: "bold";
+			"aria-hidden"?: boolean | "true" | "false";
+		}>;
 		/** Where the page lives, as a reader would say it: "Marketing / Reports". */
 		section?: string;
 		/** Already worded and localised: "Updated 30 Jul 2026". */
@@ -95,7 +99,7 @@
 				items={headings}
 				active={spy.active}
 				label={contentsLabel}
-				onselect={(id) => spy.jump(id)}
+				onSelect={(id) => spy.jump(id)}
 			/>
 		</div>
 	{/if}
@@ -112,7 +116,7 @@
 						<span
 							class="flex size-11 shrink-0 items-center justify-center rounded-xl bg-brand-100 text-brand dark:bg-brand-800/30 dark:text-brand-light"
 						>
-							<Icon class="size-5" weight="bold" />
+							<Icon aria-hidden="true" class="size-5" weight="bold" />
 						</span>
 					{/if}
 					<div class="min-w-0 flex-1">
@@ -160,7 +164,7 @@
 					items={headings}
 					active={spy.active}
 					label={contentsLabel}
-					onselect={(id) => spy.jump(id)}
+					onSelect={(id) => spy.jump(id)}
 				/>
 			</aside>
 		{/if}

package/src/components/docs/doc-page.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { Component, Snippet } from "svelte";
+import { type DocHeading, type LocateHeading } from "./scroll-spy.svelte.js";
+interface Props {
+    title: string;
+    /** One line under the title. Optional: a page with nothing to add leaves it out. */
+    summary?: string;
+    icon?: Component<{
+        class?: string;
+        weight?: "bold";
+        "aria-hidden"?: boolean | "true" | "false";
+    }>;
+    /** Where the page lives, as a reader would say it: "Marketing / Reports". */
+    section?: string;
+    /** Already worded and localised: "Updated 30 Jul 2026". */
+    updated?: string;
+    /** Room at the right of the title for a page's own controls. */
+    actions?: Snippet;
+    /** The document's h2s, which the contents rail walks. Under two, there's no rail. */
+    headings?: DocHeading[];
+    /** The rail's name: "On this page". */
+    contentsLabel: string;
+    /** Supplied by a document that lives in a frame; the default reads the DOM by id. */
+    locate?: LocateHeading;
+    /** Changes when the page is swapped without navigation, so the pane returns to the top. */
+    resetKey?: string;
+    /** The reading column's width. `wide` is for a document that brings tables and boards. */
+    measure?: "prose" | "wide";
+    /** The scroll box, for a document that has to place things inside it. */
+    scroller?: HTMLElement | null;
+    children: Snippet;
+}
+declare const $$Component: Component<Props, {}, "scroller">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/docs/on-this-page.svelte

@@ -2,8 +2,9 @@
 	// =========================
 	// IMPORTS
 	// =========================
-	import { tick } from "svelte";
 	import { CaretDown, List } from "phosphor-svelte";
+	import * as Popover from "../../shadcn/popover/index.js";
+	import { focusAfterRender } from "../../lib/focus.js";
 	import type { DocHeading } from "./scroll-spy.svelte.js";
 
 	// =========================
@@ -15,7 +16,7 @@
 		active: string;
 		/** What the rail is called: "On this page". Passed in so the library holds no copy. */
 		label: string;
-		onselect: (id: string) => void;
+		onSelect: (id: string) => void;
 		/**
 		 * `rail` sits beside the document, `bar` replaces it on a narrow pane, and `ticks` marks
 		 * each heading in the gutter with a card of headings on hover or focus.
@@ -26,7 +27,7 @@
 	// =========================
 	// PROPS
 	// =========================
-	let { items, active, label, onselect, variant = "rail" }: Props = $props();
+	let { items, active, label, onSelect, variant = "rail" }: Props = $props();
 
 	let hovering = $state(false);
 	let focusing = $state(false);
@@ -37,6 +38,7 @@
 	// =========================
 	let list = $state<HTMLElement | null>(null);
 	let open = $state(false);
+	let menu = $state<HTMLElement | null>(null);
 	let marker = $state({ y: 0, h: 0, ready: false });
 	// Plain, not state: the effect below writes `marker`, so it can't also read it.
 	let placed = false;
@@ -85,22 +87,18 @@
 		}
 	});
 
+	// Closing hands focus back to the bar's trigger, which Bits UI's Popover does.
 	function pick(id: string) {
 		open = false;
-		onselect(id);
-		void tick();
+		onSelect(id);
 	}
-</script>
 
-<svelte:window
-	onkeydown={(event) => {
-		if (event.key === "Escape") open = false;
-	}}
-	onpointerdown={(event) => {
-		if (!open) return;
-		if (!(event.target as HTMLElement).closest("[data-otp-bar]")) open = false;
-	}}
-/>
+	// The menu opens on the heading the reader is in, not on the first one.
+	function focusCurrent(event: Event) {
+		event.preventDefault();
+		void focusAfterRender(menu, '[aria-current="location"]', "button");
+	}
+</script>
 
 <!-- =========================== -->
 <!-- MARKUP -->
@@ -203,105 +201,115 @@
 		</div>
 	</nav>
 {:else}
-	<div data-otp-bar class="relative">
-		<button
-			type="button"
-			aria-expanded={open}
-			aria-label={label}
-			onclick={() => (open = !open)}
-			class="flex h-11 w-full items-center gap-2.5 px-4 text-left transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] hover:bg-muted/50"
-		>
-			<List size={16} class="shrink-0 text-muted-foreground" aria-hidden="true" />
-			<span class="shrink-0 text-xs font-medium text-muted-foreground">{label}</span>
-			<span class="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{activeLabel}</span>
-			<CaretDown
-				size={14}
-				class="shrink-0 text-muted-foreground transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {open
-					? 'rotate-180'
-					: ''}"
-			/>
-		</button>
-		<!-- How far through the reader is. The only motion here, and it is the state. -->
-		<span aria-hidden="true" class="absolute inset-x-0 bottom-0 h-px bg-border">
-			<span
-				class="otp-progress block h-full origin-left bg-brand dark:bg-brand-light"
-				style="transform: scaleX({progress});"
-			></span>
-		</span>
-
-		{#if open}
-			<nav
+	<Popover.Root bind:open>
+		<div class="relative">
+			<Popover.Trigger
 				aria-label={label}
-				class="thin-scrollbar absolute inset-x-2 top-full z-20 mt-1 max-h-[60svh] overflow-y-auto rounded-2xl bg-popover p-1.5 shadow-edge-raised"
+				class="flex h-11 w-full items-center gap-2.5 px-4 text-left transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] hover:bg-muted/50"
 			>
-				<ul class="flex flex-col">
-					{#each items as item (item.id)}
-						{@const current = item.id === active}
-						<li>
-							<button
-								type="button"
-								aria-current={current ? "location" : undefined}
-								onclick={() => pick(item.id)}
-								class="block w-full rounded-lg px-3 py-2.5 text-left text-sm leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {current
-									? 'bg-muted font-medium text-foreground'
-									: 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'}"
-							>
-								{item.label}
-							</button>
-						</li>
-					{/each}
-				</ul>
-			</nav>
-		{/if}
-	</div>
+				<List size={16} class="shrink-0 text-muted-foreground" aria-hidden="true" />
+				<span class="shrink-0 text-xs font-medium text-muted-foreground">{label}</span>
+				<span class="min-w-0 flex-1 truncate text-sm font-medium text-foreground"
+					>{activeLabel}</span
+				>
+				<CaretDown
+					aria-hidden="true"
+					size={14}
+					class="shrink-0 text-muted-foreground transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {open
+						? 'rotate-180'
+						: ''}"
+				/>
+			</Popover.Trigger>
+			<!-- How far through the reader is. The only motion here, and it is the state. -->
+			<span aria-hidden="true" class="absolute inset-x-0 bottom-0 h-px bg-border">
+				<span
+					class="otp-progress block h-full origin-left bg-brand dark:bg-brand-light"
+					style="transform: scaleX({progress});"
+				></span>
+			</span>
+
+			<!-- Bits UI moves focus into the menu, closes it on Esc or a click outside, and returns focus to the trigger. -->
+			<Popover.Content
+				bind:ref={menu}
+				align="start"
+				alignOffset={8}
+				onOpenAutoFocus={focusCurrent}
+				class="thin-scrollbar max-h-[60svh] w-[calc(var(--bits-popover-anchor-width)-1rem)] p-1.5"
+			>
+				<nav aria-label={label}>
+					<ul class="flex flex-col">
+						{#each items as item (item.id)}
+							{@const current = item.id === active}
+							<li>
+								<button
+									type="button"
+									aria-current={current ? "location" : undefined}
+									onclick={() => pick(item.id)}
+									class="block w-full rounded-lg px-3 py-2.5 text-left text-sm leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {current
+										? 'bg-muted font-medium text-foreground'
+										: 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'}"
+								>
+									{item.label}
+								</button>
+							</li>
+						{/each}
+					</ul>
+				</nav>
+			</Popover.Content>
+		</div>
+	</Popover.Root>
 {/if}
 
 <!-- =========================== -->
 <!-- STYLE -->
 <!-- =========================== -->
 <style>
-	.otp-marker.is-ready {
-		transition:
-			transform var(--duration-medium) var(--ease-smooth-out),
-			height var(--duration-medium) var(--ease-smooth-out);
-	}
+	@layer theme, base, components, utilities;
 
-	.otp-progress {
-		transition: transform var(--duration-medium) var(--ease-smooth-out);
-	}
-
-	/* A long list fades into its edges instead of ending on a hard cut. */
-	.otp-fade {
-		mask-image: linear-gradient(
-			to bottom,
-			transparent,
-			#000 0.5rem,
-			#000 calc(100% - 1.5rem),
-			transparent
-		);
-	}
+	@layer components {
+		.otp-marker.is-ready {
+			transition:
+				transform var(--duration-medium) var(--ease-smooth-out),
+				height var(--duration-medium) var(--ease-smooth-out);
+		}
 
-	/* Opacity and a short slide, no scale: the card is anchored to a line of ticks. */
-	.otp-card {
-		opacity: 0;
-		translate: -4px -50%;
-		pointer-events: none;
-		transition:
-			opacity var(--duration-fast) var(--ease-smooth-out),
-			translate var(--duration-fast) var(--ease-smooth-out);
-	}
+		.otp-progress {
+			transition: transform var(--duration-medium) var(--ease-smooth-out);
+		}
 
-	.otp-card[data-open="true"] {
-		opacity: 1;
-		translate: 0 -50%;
-		pointer-events: auto;
-	}
+		/* A long list fades into its edges instead of ending on a hard cut. */
+		.otp-fade {
+			mask-image: linear-gradient(
+				to bottom,
+				transparent,
+				#000 0.5rem,
+				#000 calc(100% - 1.5rem),
+				transparent
+			);
+		}
 
-	@media (prefers-reduced-motion: reduce) {
-		.otp-marker.is-ready,
-		.otp-progress,
+		/* Opacity and a short slide, no scale: the card is anchored to a line of ticks. */
 		.otp-card {
-			transition: none;
+			opacity: 0;
+			translate: -4px -50%;
+			pointer-events: none;
+			transition:
+				opacity var(--duration-fast) var(--ease-smooth-out),
+				translate var(--duration-fast) var(--ease-smooth-out);
+		}
+
+		.otp-card[data-open="true"] {
+			opacity: 1;
+			translate: 0 -50%;
+			pointer-events: auto;
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			.otp-marker.is-ready,
+			.otp-progress,
+			.otp-card {
+				transition: none;
+			}
 		}
 	}
 </style>

package/src/components/docs/on-this-page.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { DocHeading } from "./scroll-spy.svelte.js";
+interface Props {
+    items: DocHeading[];
+    /** The id the reader is in. */
+    active: string;
+    /** What the rail is called: "On this page". Passed in so the library holds no copy. */
+    label: string;
+    onSelect: (id: string) => void;
+    /**
+     * `rail` sits beside the document, `bar` replaces it on a narrow pane, and `ticks` marks
+     * each heading in the gutter with a card of headings on hover or focus.
+     */
+    variant?: "rail" | "bar" | "ticks";
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/field-row/field-row.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from "svelte";
+interface Props {
+    label: string;
+    /** Id of the control, so the label focuses it. */
+    for: string;
+    description?: string;
+    error?: string;
+    class?: string;
+    /** The control: an Input, a Select trigger. It takes the width the action leaves. */
+    children: Snippet;
+    /** The button that acts on the control. Same height as the control, bottom of the row. */
+    action?: Snippet;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;