@human-synthesis/norns-ui 0.0.13 → 0.0.14

package/COMPONENTS.md

@@ -56,11 +56,23 @@ export type AudioProps = {
 ```ts
 export type ComboboxItem = { value: string; label: string };
 
+/** Remote option source: resolves the items for the current input, or a `{ data }` envelope. */
+export type ComboboxSource = (term: string) => Promise<ComboboxItem[] | { data?: ComboboxItem[] } | null | undefined> | ComboboxItem[];
+
 export type AutocompleteProps = {
+	/** Local options, filtered client-side by label. Ignored when `source` is set. */
 	items?: ComboboxItem[];
+	/** Remote options: called (debounced) with the typed text while the list is open. */
+	source?: ComboboxSource;
+	/** Milliseconds to wait after typing before calling `source`. Default 200. */
+	debounce?: number;
+	/** Minimum typed characters before `source` is called. Default 0. */
+	minChars?: number;
 	value?: string;
 	open?: boolean;
 	placeholder?: string;
+	emptyMessage?: string;
+	loadingMessage?: string;
 	disabled?: boolean;
 	name?: string;
 	id?: string;
@@ -381,6 +393,8 @@ export type DataTableColumn = {
 	class?: string;
 	cellClass?: string;
 	sortable?: boolean;
+	/** Render the cell value (e.g. a date or number formatter). */
+	format?: (value: unknown, row: Record<string, unknown>) => string | number;
 };
 
 export type DataTableProps = {
@@ -389,8 +403,14 @@ export type DataTableProps = {
 	striped?: boolean;
 	dense?: boolean;
 	stickyHeader?: boolean;
+	/** Dims the table and swaps the empty message while a page is being fetched (see `useList()`). */
+	loading?: boolean;
 	emptyMessage?: string;
-	/** Currently-sorted column key. Bindable. */
+	loadingMessage?: string;
+	/**
+	 * Currently-sorted column key. Bindable. The table only flips these two;
+	 * sort `rows` yourself or bind them to `useList()` for server-side ordering.
+	 */
 	sortKey?: string;
 	sortDir?: 'asc' | 'desc';
 	onrowclick?: (row: Record<string, unknown>, index: number) => void;
@@ -564,6 +584,22 @@ export type FormProps = Omit<HTMLFormAttributes, 'class' | 'children'> & {
 	 * up its own error automatically.
 	 */
 	form?: FormActionResult;
+	/**
+	 * API mode. Intercepts the submit, collects the fields into a plain object
+	 * and calls this instead of posting the form — typically
+	 * `(values) => api.post('/api/notes', values)` against a norns `route()`.
+	 * A rejection whose `body.issues` (or `issues`) is a valibot issue list is
+	 * mapped into the same errors context as `form`.
+	 */
+	submit?: (values: Record<string, FormDataEntryValue>, event: SubmitEvent) => Promise<unknown> | unknown;
+	/** Called with the resolved value of `submit`. */
+	onsuccess?: (result: unknown, values: Record<string, FormDataEntryValue>) => void;
+	/** Called when `submit` rejects (after the errors map was updated). */
+	onerror?: (error: unknown) => void;
+	/** True while `submit` is pending. Bindable. */
+	submitting?: boolean;
+	/** API mode: clear the fields after `submit` resolves. */
+	resetOnSuccess?: boolean;
 	class?: string;
 	children?: Snippet;
 };
@@ -752,10 +788,19 @@ export type MegaMenuProps = {
 
 ```ts
 export type MultiSelectProps = {
+	/** Local options, filtered client-side by label. Ignored when `source` is set. */
 	items?: ComboboxItem[];
+	/** Remote options: called (debounced) with the typed text while the list is open. Picked labels are remembered across searches. */
+	source?: ComboboxSource;
+	/** Milliseconds to wait after typing before calling `source`. Default 200. */
+	debounce?: number;
+	/** Minimum typed characters before `source` is called. Default 0. */
+	minChars?: number;
 	value?: string[];
 	open?: boolean;
 	placeholder?: string;
+	emptyMessage?: string;
+	loadingMessage?: string;
 	disabled?: boolean;
 	name?: string;
 	id?: string;

package/README.md

@@ -98,6 +98,34 @@ Form(action="?/save" form!="{form}")
 
 `<Field name="title">` reads its error from the parent `<Form>`'s context map; no per-page boilerplate.
 
+### API mode
+
+Give `Form` a `submit` function and it posts through your API client instead of a form action. A rejection carrying `issues` (a norns `route()` 400, surfaced as `ApiError.body.issues`) feeds the same errors map, so the Fields light up either way:
+
+```pug
+Form(submit!="{(values) => api.post('/api/notes', values)}" onsuccess!="{onCreated}" bind:submitting!="{busy}" resetOnSuccess!="{true}")
+  Field(label="Title" name="title" required)
+    Input(name="title")
+  Btn(type="submit" variant="primary" loading!="{busy}") Create
+```
+
+### Server-driven lists
+
+`useList()` (`@human-synthesis/norns-ui/list`) owns page / sort / search state and re-runs your loader with a query string a norns `listQuery()` route understands. Bind it to `DataTable` and `Pagination`; the server orders and slices, the page never holds more than one page:
+
+```pug
+Input(type="search" bind:value!="{list.q}")
+DataTable(columns!="{columns}" rows!="{list.rows}" bind:sortKey!="{list.sort}" bind:sortDir!="{list.dir}" loading!="{list.loading}")
+Pagination(bind:page!="{list.page}" total!="{list.total}" pageSize!="{list.pageSize}")
+
+<script>
+  import { useList } from '@human-synthesis/norns-ui/list'
+  list := useList (qs) => api.get(`/api/notes?${qs}`), { sort: 'updated_at', dir: 'desc', debounce: 150 }
+</script>
+```
+
+`Autocomplete` and `MultiSelect` accept a `source` function (debounced, out-of-order responses dropped) in place of `items`, so pickers over large sets fetch options as you type.
+
 ## What's in here
 
 - **Atoms** (CSS-only `@layer components`): `.btn`, `.input`, `.field`, `.form`, `.checkbox`, `.radio`, `.switch`, `.card`, `.surface-elevated`, `.btn-icon`, `.banner`, `.badge`, `.chip`, `.avatar`, `.skeleton`, `.progress`, `.norns-header`, `.hero`, `.stepper`, `.breadcrumbs`, `.pagination`, `.accordion`, `.carousel`, plus variants/sizes.
@@ -107,6 +135,7 @@ Form(action="?/save" form!="{form}")
 - **Composite**: `Header`, `HeroBanner`, `Stepper`, `Breadcrumbs`, `Pagination`, `Carousel`, `Tree`, `Toolbar`, `Separator`, `ButtonGroup`, `ToggleButton`, `ToggleButtonGroup`, `HierarchicalMenu`, `MegaMenu`.
 - **Inputs**: `NumberInput`, `OtpField`, `TagsInput`, `Autocomplete`, `MultiSelect`, `ColorPicker`, `Uploader`, `DatePicker`, `DateRangePicker`, `TimePicker`, `Calendar`, `DataTable`, `ScrollArea`, `CopyButton`, `ThemeToggler`, `ShinyButton`, `RippleButton`.
 - **Toast**: `ToastProvider` + `toast()` / `notify()` / `dismiss()` from `@human-synthesis/norns-ui/toast`.
+- **Lists**: `useList()` from `@human-synthesis/norns-ui/list` — server-driven paging / sorting / search state for `DataTable` + `Pagination`.
 - **Motion** (opt-in, `@human-synthesis/norns-ui/motion`): `AnimatedNumber`, `GradientBackground`, `LiquidButton`, `Reveal`, `Sparkles`.
 
 The full prop reference for every component is **[COMPONENTS.md](./COMPONENTS.md)**, generated from the `.d.ts` shims under `src/types/` (`bun run docs:components`). Live usage of every component: `norns-demo/src/routes/examples/ui/+page.n`. Override any component by dropping `src/lib/components/<Name>.n` in your project — `nornsAutoImport`'s first-match-wins shadows the library silently.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@human-synthesis/norns-ui",
-	"version": "0.0.13",
+	"version": "0.0.14",
 	"description": "UI library for the Norns ecosystem — Pug + Civet components on Tailwind v4.",
 	"license": "MIT",
 	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -28,6 +28,7 @@
 		"./behaviors": "./src/lib/behaviors/index.js",
 		"./behaviors/*": "./src/lib/behaviors/*",
 		"./toast": "./src/lib/toast.svelte.js",
+		"./list": "./src/lib/list.svelte.js",
 		"./styles": "./src/styles/index.css",
 		"./styles/tokens": "./src/styles/tokens.css",
 		"./styles/atoms": "./src/styles/atoms.css",
@@ -37,7 +38,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@human-synthesis/norns": "^0.0.18",
+		"@human-synthesis/norns": "^0.0.19",
 		"@human-synthesis/norns-core": "^0.0.11",
 		"svelte": "^5.0.0",
 		"tailwindcss": "^4.0.0"

package/src/components/Autocomplete.n

@@ -9,6 +9,7 @@
 		aria-expanded!="{open}"
 		aria-controls!="{listboxId}"
 		aria-autocomplete="list"
+		aria-busy!="{loading ? 'true' : undefined}"
 		aria-activedescendant!="{open && filtered[active] ? optionId(active) : undefined}"
 		id!="{resolvedId}"
 		aria-invalid!="{hasError ? 'true' : undefined}"
@@ -18,7 +19,7 @@
 		onblur!="{onBlur}"
 	)
 	button.combobox-trigger(type="button" tabindex="-1" aria-label="Toggle options" onclick!="{toggle}")
-		Icon(name="lucide:chevrons-up-down" size="size-4")
+		Icon(name!="{loading ? 'lucide:loader-circle' : 'lucide:chevrons-up-down'}" size="size-4" class!="{loading ? 'animate-spin' : ''}")
 
 +if('open && filtered.length > 0')
 	ul(
@@ -40,9 +41,9 @@
 			)
 				Icon(name="lucide:check" size="size-3.5" class!="{value === item.value ? '' : 'opacity-0'}")
 				span {item.label}
-+if('open && filtered.length === 0')
++if('open && filtered.length === 0 && (loading || term.length >= minChars)')
 	div(use:portal use:floatAction use:clickOutside!="{[onClose, open, wrapEl]}" class="dropdown-content combobox-listbox" data-state="open")
-		.combobox-empty No matches
+		.combobox-empty {loading ? loadingMessage : emptyMessage}
 
 <script>
 	import { getContext } from 'svelte'
@@ -53,9 +54,14 @@
 
 	{
 		items = []
+		source
+		debounce = 200
+		minChars = 0
 		value = $bindable(undefined)
 		open = $bindable(false)
 		placeholder = 'Search…'
+		emptyMessage = 'No matches'
+		loadingMessage = 'Searching…'
 		disabled = false
 		name
 		id: providedId
@@ -80,13 +86,43 @@
 	inputEl .= $state null
 	wrapEl .= $state null
 
+	// Remote mode: `source(term)` resolves the options for the current input.
+	// Results are debounced, out-of-order responses are dropped, and the
+	// picked item is remembered so its label survives a new search.
+	remote .= $state []
+	loading .= $state false
+	picked .= $state null
+	seq .= 0
+
+	all := $derived source ? remote : items
+
+	search := async (t) =>
+		id := ++seq
+		loading = true
+		try
+			res := await source t
+			return unless id === seq
+			remote = Array.isArray(res) ? res : (res?.data ?? [])
+		catch
+			remote = [] if id === seq
+		finally
+			loading = false if id === seq
+
+	$effect =>
+		return unless source && open
+		t := term
+		return if t.length < minChars
+		timer := setTimeout (=> search t), debounce
+		return () => clearTimeout timer
+
 	// Reset term to selected label when value changes externally.
 	$effect =>
 		if value !== undefined
-			match := items.find (it) => it.value === value
+			match := all.find((it) => it.value === value) ?? (picked?.value === value ? picked : null)
 			term = match?.label ?? '' if match && term !== match.label
 
 	filtered := $derived.by =>
+		return remote if source
 		return items unless term
 		t := term.toLowerCase()
 		items.filter (it) => it.label.toLowerCase().includes(t)
@@ -109,6 +145,7 @@
 		setTimeout (=> open = false), 100
 
 	pick := (item) =>
+		picked = item
 		value = item.value
 		term = item.label
 		open = false

package/src/components/DataTable.n

@@ -1,4 +1,4 @@
-.data-table-wrap(class!="{wrapClasses}")
+.data-table-wrap(class!="{wrapClasses}" aria-busy!="{loading ? 'true' : undefined}")
 	table.data-table
 		thead
 			tr
@@ -6,6 +6,7 @@
 					th(
 						class!="{col.class ?? ''}"
 						style!="{col.width ? `width: ${col.width}` : undefined}"
+						aria-sort!="{sortKey === col.key ? (sortDir === 'asc' ? 'ascending' : 'descending') : undefined}"
 					)
 						+if('col.sortable')
 							button.data-table-sort(type="button" onclick!="{() => onSort(col.key)}")
@@ -17,12 +18,12 @@
 			+if('rows.length === 0')
 				tr.data-table-empty
 					td(colspan!="{columns.length}")
-						| {emptyMessage}
+						| {loading ? loadingMessage : emptyMessage}
 			+each('rows as row, i')
 				tr(onclick!="{onrowclick ? () => onrowclick(row, i) : undefined}" class!="{onrowclick ? 'data-table-row-clickable' : ''}")
 					+each('columns as col')
 						td(class!="{col.cellClass ?? ''}")
-							| {row[col.key]}
+							| {col.format ? col.format(row[col.key], row) : row[col.key]}
 
 <script>
 	import { cn } from '@human-synthesis/norns-ui/cn'
@@ -34,20 +35,26 @@
 		striped = false
 		dense = false
 		stickyHeader = false
+		loading = false
 		emptyMessage = 'No data'
+		loadingMessage = 'Loading…'
 		sortKey = $bindable(undefined)
 		sortDir = $bindable('asc')
 		onrowclick
 		class: extra = ''
 	} .= $props()
 
-	wrapClasses := cn
+	wrapClasses := $derived cn
 		'data-table-root'
 		striped && 'data-table-striped'
 		dense && 'data-table-dense'
 		stickyHeader && 'data-table-sticky'
+		loading && 'data-table-loading'
 		extra
 
+	// Sorting is delegated: the component only flips `sortKey` / `sortDir`
+	// (both bindable). Sort the `rows` yourself, or hand both bindings to
+	// `useList()` and let the server order the page.
 	onSort := (key) =>
 		if sortKey === key
 			sortDir = sortDir === 'asc' ? 'desc' : 'asc'

package/src/components/Form.n

@@ -3,7 +3,8 @@ form(
 	action!="{action}"
 	enctype!="{enctype}"
 	class!="{classes}"
-	onsubmit!="{onsubmit}"
+	aria-busy!="{submitting ? 'true' : undefined}"
+	onsubmit!="{handleSubmit}"
 )
 	| {@render children?.()}
 
@@ -17,9 +18,40 @@ form(
 		enctype
 		onsubmit
 		form
+		submit
+		onsuccess
+		onerror
+		submitting = $bindable(false)
+		resetOnSuccess = false
 		children
 		class: extra = ''
-	} := $props()
+	} .= $props()
+
+	// API mode. With `submit`, the native POST is intercepted: the fields are
+	// collected into a plain object and handed to `submit(values, event)` —
+	// typically `api.post('/api/notes', values)` against a norns route().
+	// A rejection carrying `issues` (route()'s 400 body, surfaced as
+	// ApiError.body.issues) feeds the same errors map the action path uses,
+	// so <Field name="…"> shows the message either way.
+	apiIssues .= $state null
+
+	handleSubmit := async (e) =>
+		onsubmit?.(e)
+		return unless submit && !e.defaultPrevented
+		e.preventDefault()
+		values := Object.fromEntries new FormData(e.currentTarget)
+		submitting = true
+		apiIssues = null
+		try
+			result := await submit values, e
+			e.currentTarget?.reset?.() if resetOnSuccess
+			onsuccess?.(result, values)
+		catch err
+			issues := err?.body?.issues ?? err?.issues
+			apiIssues = issues if Array.isArray issues
+			onerror?.(err)
+		finally
+			submitting = false
 
 	// Errors-by-name map. Built reactively from the valibot issue list so
 	// descendant Fields can look up their own error by `name` without a
@@ -30,16 +62,17 @@ form(
 	// errors during initial server render.
 	errorsMap := $derived.by =>
 		out := {}
-		if form?.errors
-			for issue of form.errors
-				name := issue.path?.[0]?.key
+		issues := apiIssues ?? form?.errors
+		if issues
+			for issue of issues
+				name := issue.path?.[0]?.key ?? issue.path?.[0]
 				if name && !out[name]
 					out[name] = issue.message
 		out
 
 	// Getter wraps the $derived so context consumers re-evaluate on read.
-	ctx := { get errors() { errorsMap } }
+	ctx := { get errors() { errorsMap }, get submitting() { submitting } }
 	setContext 'norns-ui:form', ctx
 
-	classes := cn 'form', extra
+	classes := $derived cn 'form', extra
 </script>

package/src/components/MultiSelect.n

@@ -24,6 +24,7 @@
 		aria-expanded!="{open}"
 		aria-controls!="{listboxId}"
 		aria-autocomplete="list"
+		aria-busy!="{loading ? 'true' : undefined}"
 		id!="{resolvedId}"
 		aria-invalid!="{hasError ? 'true' : undefined}"
 		oninput!="{onInput}"
@@ -37,7 +38,7 @@
 		aria-label="Toggle options"
 		onclick!="{(e) => { e.stopPropagation(); toggle() }}"
 	)
-		Icon(name="lucide:chevrons-up-down" size="size-4")
+		Icon(name!="{loading ? 'lucide:loader-circle' : 'lucide:chevrons-up-down'}" size="size-4" class!="{loading ? 'animate-spin' : ''}")
 
 +if('open && filtered.length > 0')
 	ul(
@@ -59,9 +60,9 @@
 			)
 				Icon(name="lucide:check" size="size-3.5" class!="{value.includes(item.value) ? '' : 'opacity-0'}")
 				span {item.label}
-+if('open && filtered.length === 0')
++if('open && filtered.length === 0 && (loading || term.length >= minChars)')
 	div(use:portal use:floatAction use:clickOutside!="{[onClose, open, wrapEl]}" class="dropdown-content combobox-listbox" data-state="open")
-		.combobox-empty No matches
+		.combobox-empty {loading ? loadingMessage : emptyMessage}
 
 <script>
 	import { getContext } from 'svelte'
@@ -72,9 +73,14 @@
 
 	{
 		items = []
+		source
+		debounce = 200
+		minChars = 0
 		value = $bindable([])
 		open = $bindable(false)
 		placeholder = 'Pick options…'
+		emptyMessage = 'No matches'
+		loadingMessage = 'Searching…'
 		disabled = false
 		name
 		id: providedId
@@ -98,7 +104,38 @@
 	inputEl .= $state null
 	wrapEl .= $state null
 
+	// Remote mode: `source(term)` resolves the options for the current input.
+	// Labels of everything ever seen are kept in `known`, so chips for values
+	// picked from an earlier search still render after the list moved on.
+	remote .= $state []
+	loading .= $state false
+	known := $state {}
+	seq .= 0
+
+	search := async (t) =>
+		id := ++seq
+		loading = true
+		try
+			res := await source t
+			return unless id === seq
+			list := Array.isArray(res) ? res : (res?.data ?? [])
+			for it of list
+				known[it.value] = it.label
+			remote = list
+		catch
+			remote = [] if id === seq
+		finally
+			loading = false if id === seq
+
+	$effect =>
+		return unless source && open
+		t := term
+		return if t.length < minChars
+		timer := setTimeout (=> search t), debounce
+		return () => clearTimeout timer
+
 	filtered := $derived.by =>
+		return remote if source
 		return items unless term
 		t := term.toLowerCase()
 		items.filter (it) => it.label.toLowerCase().includes(t)
@@ -106,7 +143,7 @@
 	$effect =>
 		active = 0 if active >= filtered.length
 
-	labelOf := (v) => items.find((it) => it.value === v)?.label ?? v
+	labelOf := (v) => items.find((it) => it.value === v)?.label ?? known[v] ?? v
 
 	focusInput := => inputEl?.focus()
 
@@ -124,6 +161,7 @@
 		setTimeout (=> open = false), 100
 
 	pick := (item) =>
+		known[item.value] = item.label
 		if value.includes(item.value)
 			value = value.filter (v) => v !== item.value
 		else

package/src/index.js

@@ -99,3 +99,4 @@ export { cn } from './lib/cn.js';
 export { variantClasses } from './lib/variants.js';
 export { presetUI } from './auto-import.js';
 export { toast, notify, dismiss, clear } from './lib/toast.svelte.js';
+export { useList } from './lib/list.svelte.js';

package/src/lib/list.svelte.d.ts

@@ -0,0 +1,46 @@
+export interface ListQueryState {
+	page: number;
+	pageSize: number;
+	sort?: string;
+	dir: 'asc' | 'desc';
+	q: string;
+}
+
+export type ListLoader<T> = (
+	qs: string,
+	query: ListQueryState
+) => Promise<{ data?: T[]; total?: number } | T[] | null | undefined>;
+
+export interface UseListOptions<T> {
+	page?: number;
+	pageSize?: number;
+	sort?: string;
+	dir?: 'asc' | 'desc';
+	q?: string;
+	/** Debounce every reload by this many milliseconds (useful when `q` is bound to an input). */
+	debounce?: number;
+	/** First page from a `load` function; no request is made until the query changes. */
+	initial?: { data?: T[]; total?: number } | null;
+}
+
+export interface ListState<T> {
+	readonly rows: T[];
+	readonly total: number;
+	readonly loading: boolean;
+	readonly error: unknown;
+	readonly pages: number;
+	readonly params: string;
+	page: number;
+	pageSize: number;
+	sort: string | undefined;
+	dir: 'asc' | 'desc';
+	q: string;
+	refresh(): Promise<void>;
+}
+
+/**
+ * Server-driven list state for DataTable + Pagination. Call during component
+ * initialisation; every change to page / pageSize / sort / dir / q re-runs
+ * `load` with a `listQuery()`-compatible query string.
+ */
+export function useList<T = Record<string, unknown>>(load: ListLoader<T>, opts?: UseListOptions<T>): ListState<T>;

package/src/lib/list.svelte.js

@@ -0,0 +1,143 @@
+/**
+ * Server-driven list state for DataTable + Pagination (+ a search box).
+ *
+ * The component owns the page / sort / search state; the server owns the
+ * data. Every state change re-runs `load` with the query string a norns
+ * `listQuery()` route understands, and the `{ data, total }` envelope from
+ * `listResult()` lands in `rows` / `total`.
+ *
+ *   import { useList } from '@human-synthesis/norns-ui/list'
+ *   api := createApi { schemas: [noteWire] }
+ *   list := useList (qs) => api.get(`/api/notes?${qs}`), { sort: 'updated_at', dir: 'desc' }
+ *
+ *   Input(bind:value!="{list.q}")
+ *   DataTable(rows!="{list.rows}" bind:sortKey!="{list.sort}" bind:sortDir!="{list.dir}" loading!="{list.loading}")
+ *   Pagination(bind:page!="{list.page}" total!="{list.total}" pageSize!="{list.pageSize}")
+ *
+ * Call it during component initialisation (it registers a `$effect`). With
+ * `initial` (data from a `load` function) the first render is SSR-complete
+ * and no request is made until something changes. In-flight responses that
+ * arrive out of order are dropped.
+ *
+ * @template T
+ * @param {(qs: string, query: { page: number, pageSize: number, sort?: string, dir: 'asc' | 'desc', q: string }) => Promise<{ data?: T[], total?: number } | T[] | null | undefined>} load
+ * @param {{
+ *   page?: number,
+ *   pageSize?: number,
+ *   sort?: string,
+ *   dir?: 'asc' | 'desc',
+ *   q?: string,
+ *   debounce?: number,
+ *   initial?: { data?: T[], total?: number } | null
+ * }} [opts]
+ */
+export function useList(load, opts = {}) {
+	if (typeof load !== 'function') throw new Error('useList(load): `load` must be a function');
+
+	const state = $state({
+		page: opts.page ?? 1,
+		pageSize: opts.pageSize ?? 20,
+		sort: opts.sort,
+		dir: opts.dir ?? 'asc',
+		q: opts.q ?? '',
+		rows: /** @type {T[]} */ (opts.initial?.data ?? []),
+		total: opts.initial?.total ?? opts.initial?.data?.length ?? 0,
+		loading: false,
+		error: /** @type {unknown} */ (null)
+	});
+
+	let seq = 0;
+	let skipFirst = opts.initial != null;
+	const debounce = opts.debounce ?? 0;
+
+	function snapshot() {
+		return { page: state.page, pageSize: state.pageSize, sort: state.sort, dir: state.dir, q: state.q };
+	}
+
+	function params(query = snapshot()) {
+		const p = new URLSearchParams();
+		p.set('page', String(query.page));
+		p.set('pageSize', String(query.pageSize));
+		if (query.sort) {
+			p.set('sort', query.sort);
+			p.set('dir', query.dir);
+		}
+		if (query.q) p.set('q', query.q);
+		return p.toString();
+	}
+
+	async function refresh() {
+		const id = ++seq;
+		const query = snapshot();
+		state.loading = true;
+		state.error = null;
+		try {
+			const res = await load(params(query), query);
+			if (id !== seq) return;
+			const rows = Array.isArray(res) ? res : (res?.data ?? []);
+			state.rows = rows;
+			state.total = Array.isArray(res) ? rows.length : (res?.total ?? rows.length);
+		} catch (e) {
+			if (id !== seq) return;
+			state.error = e;
+		} finally {
+			if (id === seq) state.loading = false;
+		}
+	}
+
+	$effect(() => {
+		// Reading through params() subscribes to every query field.
+		params();
+		if (skipFirst) {
+			skipFirst = false;
+			return;
+		}
+		if (debounce > 0) {
+			const timer = setTimeout(refresh, debounce);
+			return () => clearTimeout(timer);
+		}
+		refresh();
+	});
+
+	return {
+		get rows() { return state.rows; },
+		get total() { return state.total; },
+		get loading() { return state.loading; },
+		get error() { return state.error; },
+		get pages() { return Math.max(1, Math.ceil(state.total / state.pageSize)); },
+		/** The query string as sent to `load` (useful for links / debugging). */
+		get params() { return params(); },
+
+		get page() { return state.page; },
+		set page(v) { state.page = Math.max(1, Number(v) || 1); },
+
+		get pageSize() { return state.pageSize; },
+		set pageSize(v) {
+			const n = Math.max(1, Number(v) || 1);
+			if (n === state.pageSize) return;
+			state.pageSize = n;
+			state.page = 1;
+		},
+
+		get sort() { return state.sort; },
+		set sort(v) {
+			if (v === state.sort) return;
+			state.sort = v;
+			state.page = 1;
+		},
+
+		get dir() { return state.dir; },
+		set dir(v) { state.dir = v === 'desc' ? 'desc' : 'asc'; },
+
+		get q() { return state.q; },
+		set q(v) {
+			const s = String(v ?? '');
+			if (s === state.q) return;
+			state.q = s;
+			state.page = 1;
+		},
+
+		/** Re-run `load` with the current query (e.g. after a mutation). */
+		refresh
+	};
+}

package/src/styles/atoms.css

@@ -1603,6 +1603,7 @@
 		cursor: pointer;
 	}
 	.data-table-sort:hover { color: var(--color-primary-600); }
+	.data-table-loading tbody { @apply opacity-60 transition-opacity; }
 
 	/* ============================================================ */
 	/* Tree                                                         */

package/src/types/Autocomplete.d.ts

@@ -2,11 +2,23 @@ import type { Component } from 'svelte';
 
 export type ComboboxItem = { value: string; label: string };
 
+/** Remote option source: resolves the items for the current input, or a `{ data }` envelope. */
+export type ComboboxSource = (term: string) => Promise<ComboboxItem[] | { data?: ComboboxItem[] } | null | undefined> | ComboboxItem[];
+
 export type AutocompleteProps = {
+	/** Local options, filtered client-side by label. Ignored when `source` is set. */
 	items?: ComboboxItem[];
+	/** Remote options: called (debounced) with the typed text while the list is open. */
+	source?: ComboboxSource;
+	/** Milliseconds to wait after typing before calling `source`. Default 200. */
+	debounce?: number;
+	/** Minimum typed characters before `source` is called. Default 0. */
+	minChars?: number;
 	value?: string;
 	open?: boolean;
 	placeholder?: string;
+	emptyMessage?: string;
+	loadingMessage?: string;
 	disabled?: boolean;
 	name?: string;
 	id?: string;

package/src/types/DataTable.d.ts

@@ -7,6 +7,8 @@ export type DataTableColumn = {
 	class?: string;
 	cellClass?: string;
 	sortable?: boolean;
+	/** Render the cell value (e.g. a date or number formatter). */
+	format?: (value: unknown, row: Record<string, unknown>) => string | number;
 };
 
 export type DataTableProps = {
@@ -15,8 +17,14 @@ export type DataTableProps = {
 	striped?: boolean;
 	dense?: boolean;
 	stickyHeader?: boolean;
+	/** Dims the table and swaps the empty message while a page is being fetched (see `useList()`). */
+	loading?: boolean;
 	emptyMessage?: string;
-	/** Currently-sorted column key. Bindable. */
+	loadingMessage?: string;
+	/**
+	 * Currently-sorted column key. Bindable. The table only flips these two;
+	 * sort `rows` yourself or bind them to `useList()` for server-side ordering.
+	 */
 	sortKey?: string;
 	sortDir?: 'asc' | 'desc';
 	onrowclick?: (row: Record<string, unknown>, index: number) => void;

package/src/types/Form.d.ts

@@ -22,6 +22,22 @@ export type FormProps = Omit<HTMLFormAttributes, 'class' | 'children'> & {
 	 * up its own error automatically.
 	 */
 	form?: FormActionResult;
+	/**
+	 * API mode. Intercepts the submit, collects the fields into a plain object
+	 * and calls this instead of posting the form — typically
+	 * `(values) => api.post('/api/notes', values)` against a norns `route()`.
+	 * A rejection whose `body.issues` (or `issues`) is a valibot issue list is
+	 * mapped into the same errors context as `form`.
+	 */
+	submit?: (values: Record<string, FormDataEntryValue>, event: SubmitEvent) => Promise<unknown> | unknown;
+	/** Called with the resolved value of `submit`. */
+	onsuccess?: (result: unknown, values: Record<string, FormDataEntryValue>) => void;
+	/** Called when `submit` rejects (after the errors map was updated). */
+	onerror?: (error: unknown) => void;
+	/** True while `submit` is pending. Bindable. */
+	submitting?: boolean;
+	/** API mode: clear the fields after `submit` resolves. */
+	resetOnSuccess?: boolean;
 	class?: string;
 	children?: Snippet;
 };

package/src/types/MultiSelect.d.ts

@@ -1,11 +1,20 @@
 import type { Component } from 'svelte';
-import type { ComboboxItem } from './Autocomplete';
+import type { ComboboxItem, ComboboxSource } from './Autocomplete';
 
 export type MultiSelectProps = {
+	/** Local options, filtered client-side by label. Ignored when `source` is set. */
 	items?: ComboboxItem[];
+	/** Remote options: called (debounced) with the typed text while the list is open. Picked labels are remembered across searches. */
+	source?: ComboboxSource;
+	/** Milliseconds to wait after typing before calling `source`. Default 200. */
+	debounce?: number;
+	/** Minimum typed characters before `source` is called. Default 0. */
+	minChars?: number;
 	value?: string[];
 	open?: boolean;
 	placeholder?: string;
+	emptyMessage?: string;
+	loadingMessage?: string;
 	disabled?: boolean;
 	name?: string;
 	id?: string;