@human-synthesis/norns-ui 0.0.2 → 0.0.3

package/README.md

@@ -2,7 +2,9 @@
 
 UI library for the [Norns](https://github.com/human-synthesis/norns) ecosystem — Pug + Civet components on Tailwind v4.
 
-**Status: Phase 2 (forms tier).** Currently ships `Btn`, `Form`, `Field`, `FieldGroup`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`. Bits-UI-backed behavior tier (Dialog, Popover, Tabs, Toast, …) lands in Phase 3.
+**Status: Phase 3 (behavior tier).** Currently ships `Btn`, `Form`, `Field`, `FieldGroup`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, the in-house `ToastProvider` + `toast()` helper, and the Bits-UI-backed `Dialog`, `Sheet`, `Popover`, `Dropdown`, `Tooltip`, `Tabs`. Data tier (Combobox, Listbox, Pagination, Accordion) and polish tier (Avatar, Badge, Spinner, …) land in Phase 4–5.
+
+> **Required: scope your preprocessors to project files.** Bits UI ships TypeScript-typed `<script lang="ts">` source, and the default Norns preprocess pipeline (svelte-preprocess + auto-import) corrupts those node_modules files. Wrap each preprocessor with a `node_modules` guard so they no-op on third-party `.svelte` files; vite-plugin-svelte handles them natively from there. See the **Setup** section below for the four-line `scopeToProject` helper.
 
 ## Stack
 
@@ -11,6 +13,7 @@ UI library for the [Norns](https://github.com/human-synthesis/norns) ecosystem
 - [Civet](https://civet.dev) — `<script>` language
 - [Tailwind CSS v4](https://tailwindcss.com) — styling, **hard peer dep**
 - [tailwind-merge](https://github.com/dcastil/tailwind-merge) — class deduplication
+- [Bits UI](https://bits-ui.com) — headless behavior backing `Dialog`/`Popover`/`Tabs`/etc.
 - `@human-synthesis/norns` `^0.0.7` — peer (`nornsAutoImport` for the registration flow)
 
 ## Install
@@ -53,6 +56,27 @@ Same shape goes in `svelte.config.js`'s `preprocess` array.
 
 `componentDirs` resolves first — your `src/lib/components/Btn.n` silently shadows the library's `Btn` whenever you want to override.
 
+### 1b. Scope project preprocessors to skip `node_modules`
+
+Wrap `nornsPreprocess()` outputs and `nornsAutoImport(...)` so their hooks no-op on third-party `.svelte` files. Bits UI's `lang="ts"` source compiles cleanly under vite-plugin-svelte's native TS handling, but breaks under our project-side svelte-preprocess + auto-import pipeline.
+
+```js
+// svelte.config.js
+const scopeToProject = (p) => ({
+	name: p.name,
+	markup: p.markup ? (a) => (a.filename?.includes('/node_modules/') ? null : p.markup(a)) : undefined,
+	script: p.script ? (a) => (a.filename?.includes('/node_modules/') ? null : p.script(a)) : undefined,
+	style: p.style ? (a) => (a.filename?.includes('/node_modules/') ? null : p.style(a)) : undefined
+});
+
+export default nornsConfig({
+	preprocess: [
+		...nornsPreprocess().map(scopeToProject),
+		scopeToProject(nornsAutoImport({ /* … */ }))
+	]
+});
+```
+
 ### 2. Import the styles
 
 ```css
@@ -156,6 +180,86 @@ All accept `class?` (merged via `cn`), pull `id` + `hasError` from a parent `<Fi
 
 Each has a hand-rolled `.d.ts` shim under `src/types/`.
 
+### Phase 3 — behavior tier (Bits UI)
+
+Headless behavior + accessibility from [Bits UI](https://bits-ui.com), wrapped with default Tailwind styling and a snippet-prop API designed for Pug.
+
+#### `<Dialog>`
+
+```pug
+Dialog(bind:open!="{deleteOpen}" title="Delete note?" description="This cannot be undone.")
+	+snippet('trigger')
+		Btn(variant="danger" size="sm") Delete
+	+snippet('actions')
+		Btn(variant="ghost" onclick!="{() => deleteOpen = false}") Cancel
+		Btn(variant="danger" onclick!="{confirm}") Delete
+```
+
+Props: `open` (bindable), `title`, `description`, `hideClose`, `trigger`, `actions`, `children`, `class`, `overlayClass`, `triggerClass`.
+
+#### `<Sheet>`
+
+Same API as `Dialog` plus `side?: 'top' | 'right' | 'bottom' | 'left'` (default `'right'`). Slides in from the chosen edge instead of centering.
+
+#### `<Popover>` and `<Dropdown>`
+
+```pug
+Popover
+	+snippet('trigger')
+		Btn(variant="ghost" size="sm") Filters
+	.space-y-2
+		Field(label="Status")
+			Select(name="status")
+				option(value="all") All
+				option(value="open") Open
+
+Dropdown(items!="{[{label:'Edit', onSelect: edit}, {separator: true}, {label:'Delete', onSelect: del}]}")
+	+snippet('trigger')
+		Btn(variant="ghost") ⋯
+```
+
+#### `<Tooltip>`
+
+```pug
+Tooltip(content="Saved 2 minutes ago")
+	+snippet('trigger')
+		Btn(variant="ghost" size="sm") ⓘ
+```
+
+#### `<Tabs>`
+
+```pug
++snippet('panelHuman')
+	p Play against another person on this device.
++snippet('panelCpu')
+	p Play against a simple CPU.
+
+Tabs(bind:value!="{mode}" items!="{[
+	{ value: 'human', label: 'Human', panel: panelHuman },
+	{ value: 'cpu',   label: 'CPU',   panel: panelCpu }
+]}")
+```
+
+#### `<ToastProvider>` + `toast()`
+
+Mount once near the app root, then call `toast()` from anywhere:
+
+```pug
+// +layout.n
+ToastProvider
+| {@render children?.()}
+```
+
+```civet
+import { toast } from '@human-synthesis/norns-ui/toast'
+
+handleSave := =>
+	await save()
+	toast 'Saved!', { variant: 'success' }
+```
+
+Variants: `info` (default), `success`, `warning`, `error`. Default duration 4000ms; pass `duration: 0` for sticky.
+
 ## Theming
 
 Tokens live in [`src/styles/tokens.css`](src/styles/tokens.css) as a Tailwind v4 `@theme` block — colors, radii, sizes. Override by re-declaring `@theme { ... }` in your own `app.css` after the library import. Tailwind v4 merges layered theme blocks.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@human-synthesis/norns-ui",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "UI library for the Norns ecosystem — Pug + Civet components on Tailwind v4.",
 	"license": "MIT",
 	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -20,6 +20,7 @@
 		".": "./src/index.js",
 		"./auto-import": "./src/auto-import.js",
 		"./cn": "./src/lib/cn.js",
+		"./toast": "./src/lib/toast.svelte.js",
 		"./styles": "./src/styles/index.css",
 		"./styles/tokens": "./src/styles/tokens.css",
 		"./styles/atoms": "./src/styles/atoms.css",
@@ -34,19 +35,20 @@
 	},
 	"peerDependenciesMeta": {
 		"@human-synthesis/norns": {
-		"optional": false
+			"optional": false
+		},
+		"@human-synthesis/norns-core": {
+			"optional": false
+		}
 	},
-	"@human-synthesis/norns-core": {
-	"optional": false
-}
-},
-"dependencies": {
-	"tailwind-merge": "^2.5.0"
-},
-"engines": {
-	"node": ">=18"
-},
-"publishConfig": {
-	"access": "public"
-}
+	"dependencies": {
+		"bits-ui": "^2.18.1",
+		"tailwind-merge": "^2.5.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }

package/src/auto-import.js

@@ -12,18 +12,16 @@
  *   plugins: [
  *     nornsCivetPlugin(),
  *     nornsAutoImport({
- *       componentDirs: ['src/lib/components'],   // user folder wins
- *       components: ui.components                 // norns-ui as fallback
+ *       componentDirs: ['src/lib/components'],
+ *       components: ui.components,
+ *       helpers: [...DEFAULT_HELPERS, ...ui.helpers]
  *     }),
  *     sveltekit()
  *   ]
  *
- * Components are imported via bare specifiers so the consumer's
- * `node_modules/@human-synthesis/norns-ui/...` is the resolution target.
- *
  * @typedef {Object} UIPreset
- * @property {Record<string, string>} components  name → bare-specifier import path
- * @property {Array<{ from: string, imports: string[] }>} helpers  name groups for nornsAutoImport
+ * @property {Record<string, string>} components
+ * @property {Array<{ from: string, imports: string[] }>} helpers
  *
  * @returns {UIPreset}
  */
@@ -42,14 +40,25 @@ export function presetUI() {
 			Select: '@human-synthesis/norns-ui/components/Select.n',
 			Checkbox: '@human-synthesis/norns-ui/components/Checkbox.n',
 			Radio: '@human-synthesis/norns-ui/components/Radio.n',
-			Switch: '@human-synthesis/norns-ui/components/Switch.n'
+			Switch: '@human-synthesis/norns-ui/components/Switch.n',
+
+			// Phase 3 — behavior tier (Bits UI)
+			Dialog: '@human-synthesis/norns-ui/components/Dialog.n',
+			Sheet: '@human-synthesis/norns-ui/components/Sheet.n',
+			Popover: '@human-synthesis/norns-ui/components/Popover.n',
+			Dropdown: '@human-synthesis/norns-ui/components/Dropdown.n',
+			Tooltip: '@human-synthesis/norns-ui/components/Tooltip.n',
+			Tabs: '@human-synthesis/norns-ui/components/Tabs.n',
+			ToastProvider: '@human-synthesis/norns-ui/components/ToastProvider.n'
 
-			// Phase 3+ adds: Card, Dialog, Sheet, Popover, Dropdown, Tooltip,
-			// Tabs, Accordion, Toast + ToastProvider, Listbox, Combobox,
-			// Pagination, Avatar, Badge, Spinner, Progress, Skeleton, Icon
+			// Phase 4+ adds: Accordion, Listbox, Combobox, Pagination,
+			// Avatar, Badge, Spinner, Progress, Skeleton, Icon, Card
 		},
 		helpers: [
-			// Phase 3+: { from: '@human-synthesis/norns-ui', imports: ['toast'] }
+			{
+				from: '@human-synthesis/norns-ui/toast',
+				imports: ['toast', 'notify', 'dismiss']
+			}
 		]
 	};
 }

package/src/components/Dialog.n

@@ -0,0 +1,54 @@
+DialogRoot(bind:open)
+	+if('trigger')
+		DialogTrigger(class!="{triggerClass ?? undefined}")
+			| {@render trigger()}
+	DialogPortal
+		DialogOverlay(class!="{overlayClasses}")
+		DialogContent(class!="{contentClasses}")
+			+if('title')
+				DialogTitle.dialog-title
+					| {title}
+			+if('description')
+				DialogDescription.dialog-description
+					| {description}
+			+if('children')
+				.dialog-body
+					| {@render children()}
+			+if('actions')
+				.dialog-actions
+					| {@render actions()}
+			+if('!hideClose')
+				DialogClose.dialog-close(aria-label="Close")
+					| ✕
+
+<script>
+	import { Dialog } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Root: DialogRoot
+		Trigger: DialogTrigger
+		Portal: DialogPortal
+		Overlay: DialogOverlay
+		Content: DialogContent
+		Title: DialogTitle
+		Description: DialogDescription
+		Close: DialogClose
+	} := Dialog
+
+	{
+		open = $bindable(false)
+		title
+		description
+		hideClose = false
+		trigger
+		actions
+		children
+		triggerClass
+		overlayClass = ''
+		class: extra = ''
+	} .= $props()
+
+	overlayClasses := cn 'dialog-overlay', overlayClass
+	contentClasses := cn 'dialog-content', extra
+</script>

package/src/components/Dropdown.n

@@ -0,0 +1,41 @@
+MenuRoot(bind:open)
+	+if('trigger')
+		MenuTrigger(class!="{triggerClass ?? undefined}")
+			| {@render trigger()}
+	MenuPortal
+		MenuContent(class!="{contentClasses}" side!="{side}" align!="{align}" sideOffset!="{sideOffset}")
+			+each('items as item, i')
+				+if('item.separator')
+					MenuSeparator.dropdown-separator
+				+if('!item.separator')
+					MenuItem.dropdown-item(disabled!="{item.disabled}" onSelect!="{item.onSelect}")
+						| {item.label}
+			| {@render children?.()}
+
+<script>
+	import { DropdownMenu } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Root: MenuRoot
+		Trigger: MenuTrigger
+		Portal: MenuPortal
+		Content: MenuContent
+		Item: MenuItem
+		Separator: MenuSeparator
+	} := DropdownMenu
+
+	{
+		open = $bindable(false)
+		side = 'bottom'
+		align = 'start'
+		sideOffset = 4
+		items = []
+		trigger
+		children
+		triggerClass
+		class: extra = ''
+	} .= $props()
+
+	contentClasses := cn 'dropdown-content', extra
+</script>

package/src/components/Field.n

@@ -1,46 +1,55 @@
 .field(class!="{classes}")
 	+if('label')
-		label.field-label(for!="{ctx.id}")
+		label.field-label(for!="{resolvedId}")
 			| {label}
 			+if('required')
 				span.field-required *
 	| {@render children?.()}
-	+if('error')
-		p.field-error(role="alert" id!="{ctx.id ? `${ctx.id}-error` : undefined}")
-			| {error}
-	+if('!error && help')
-		p.field-help(id!="{ctx.id ? `${ctx.id}-help` : undefined}")
+	+if('resolvedError')
+		p.field-error(role="alert" id!="{resolvedId ? `${resolvedId}-error` : undefined}")
+			| {resolvedError}
+	+if('!resolvedError && help')
+		p.field-help(id!="{resolvedId ? `${resolvedId}-help` : undefined}")
 			| {help}
 
 <script>
 	import { cn } from '@human-synthesis/norns-ui/cn'
-	import { setContext } from 'svelte'
+	import { setContext, getContext } from 'svelte'
 
 	{
 		label
 		help
 		error
+		name
 		required = false
 		id: providedId
 		children
 		class: extra = ''
 	} := $props()
 
-	// Deterministic id derivation:
-	//   1. explicit prop wins
-	//   2. otherwise slugify the label so SSR + hydrate produce the same id
-	//   3. otherwise undefined — without a label, no <label for=> association
-	//      is needed anyway
+	// Error resolution order:
+	//   1. explicit `error` prop wins (caller has full control)
+	//   2. else look up `name` in the parent <Form>'s errors map (auto-wired)
+	//   3. else no error
+	formCtx := getContext 'norns-ui:form'
+	resolvedError := $derived error ?? (name && formCtx?.errors?.[name]) ?? undefined
+
+	// Deterministic id derivation. SSR-safe (no random fallback):
+	//   1. explicit `id` prop wins
+	//   2. else `name` (single source of truth for submission + id)
+	//   3. else slugify the label
+	//   4. else undefined — no label, no <label for=> association needed
 	slugify := (s) => s.toLowerCase().trim().replace(/[^\w]+/g, '-').replace(/^-+|-+$/g, '')
-	resolvedId := providedId ?? (label && `field-${slugify(label)}`) ?? undefined
+	resolvedId := $derived providedId ?? name ?? (label && `field-${slugify(label)}`) ?? undefined
 
-	// Shared with descendants (Input, Textarea, Select, etc.) so they pick up
-	// the id automatically and switch to error styling. $state proxy so
-	// children's reads are reactive when `error` changes.
-	ctx := $state({ id: resolvedId, hasError: !!error })
-	$effect ->
-		ctx.id = resolvedId
-		ctx.hasError = !!error
+	// Shared with descendants. Getters wrap $derived so context reads
+	// remain reactive in both SSR (synchronous) and client (post-mount)
+	// — `$effect` would only fire client-side, leaving SSR with stale
+	// initial values.
+	ctx := {
+		get id() { resolvedId }
+		get hasError() { !!resolvedError }
+	}
 	setContext 'norns-ui:field', ctx
 
 	classes := cn 'field', extra

package/src/components/Form.n

@@ -9,15 +9,37 @@ form(
 
 <script>
 	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { setContext } from 'svelte'
 
 	{
 		method = 'POST'
 		action
 		enctype
 		onsubmit
+		form
 		children
 		class: extra = ''
 	} := $props()
 
+	// Errors-by-name map. Built reactively from the valibot issue list so
+	// descendant Fields can look up their own error by `name` without a
+	// per-page $derived helper.
+	//
+	// $derived (not $state + $effect) is critical for SSR — $effect runs
+	// only client-side, so an effect-based context would produce empty
+	// errors during initial server render.
+	errorsMap := $derived.by =>
+		out := {}
+		if form?.errors
+			for issue of form.errors
+				name := issue.path?.[0]?.key
+				if name && !out[name]
+					out[name] = issue.message
+		out
+
+	// Getter wraps the $derived so context consumers re-evaluate on read.
+	ctx := { get errors() { errorsMap } }
+	setContext 'norns-ui:form', ctx
+
 	classes := cn 'form', extra
 </script>

package/src/components/Popover.n

@@ -0,0 +1,32 @@
+PopoverRoot(bind:open)
+	+if('trigger')
+		PopoverTrigger(class!="{triggerClass ?? undefined}")
+			| {@render trigger()}
+	PopoverPortal
+		PopoverContent(class!="{contentClasses}" side!="{side}" align!="{align}" sideOffset!="{sideOffset}")
+			| {@render children?.()}
+
+<script>
+	import { Popover } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Root: PopoverRoot
+		Trigger: PopoverTrigger
+		Portal: PopoverPortal
+		Content: PopoverContent
+	} := Popover
+
+	{
+		open = $bindable(false)
+		side = 'bottom'
+		align = 'center'
+		sideOffset = 8
+		trigger
+		children
+		triggerClass
+		class: extra = ''
+	} .= $props()
+
+	contentClasses := cn 'popover-content', extra
+</script>

package/src/components/Sheet.n

@@ -0,0 +1,55 @@
+DialogRoot(bind:open)
+	+if('trigger')
+		DialogTrigger(class!="{triggerClass ?? undefined}")
+			| {@render trigger()}
+	DialogPortal
+		DialogOverlay(class!="{overlayClasses}")
+		DialogContent(class!="{contentClasses}" data-side!="{side}")
+			+if('title')
+				DialogTitle.dialog-title
+					| {title}
+			+if('description')
+				DialogDescription.dialog-description
+					| {description}
+			+if('children')
+				.sheet-body
+					| {@render children()}
+			+if('actions')
+				.dialog-actions
+					| {@render actions()}
+			+if('!hideClose')
+				DialogClose.dialog-close(aria-label="Close")
+					| ✕
+
+<script>
+	import { Dialog } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Root: DialogRoot
+		Trigger: DialogTrigger
+		Portal: DialogPortal
+		Overlay: DialogOverlay
+		Content: DialogContent
+		Title: DialogTitle
+		Description: DialogDescription
+		Close: DialogClose
+	} := Dialog
+
+	{
+		open = $bindable(false)
+		side = 'right'
+		title
+		description
+		hideClose = false
+		trigger
+		actions
+		children
+		triggerClass
+		overlayClass = ''
+		class: extra = ''
+	} .= $props()
+
+	overlayClasses := cn 'dialog-overlay', overlayClass
+	contentClasses := cn 'sheet-content', `sheet-${side}`, extra
+</script>

package/src/components/Tabs.n

@@ -0,0 +1,28 @@
+TabsRoot(bind:value class!="{rootClasses}")
+	TabsList.tabs-list
+		+each('items as item (item.value)')
+			TabsTrigger.tabs-trigger(value!="{item.value}" disabled!="{item.disabled}")
+				| {item.label}
+	+each('items as item (item.value)')
+		TabsContent.tabs-content(value!="{item.value}")
+			| {@render item.panel?.()}
+
+<script>
+	import { Tabs } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Root: TabsRoot
+		List: TabsList
+		Trigger: TabsTrigger
+		Content: TabsContent
+	} := Tabs
+
+	{
+		value = $bindable()
+		items = []
+		class: extra = ''
+	} .= $props()
+
+	rootClasses := cn 'tabs-root', extra
+</script>

package/src/components/ToastProvider.n

@@ -0,0 +1,16 @@
+div(role="region" aria-label="Notifications" class!="{regionClasses}")
+	+each('toastStore.items as item (item.id)')
+		div(class!="{`toast toast-${item.variant}`}" role="status" data-id!="{item.id}")
+			.toast-message
+				| {item.message}
+			button.toast-close(type="button" aria-label="Dismiss" onclick!="{() => dismiss(item.id)}")
+				| ✕
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { toastStore, dismiss } from '@human-synthesis/norns-ui/toast'
+
+	{ class: extra = '' } := $props()
+
+	regionClasses := cn 'toast-region', extra
+</script>

package/src/components/Tooltip.n

@@ -0,0 +1,34 @@
+TooltipProvider(delayDuration!="{delay}")
+	TooltipRoot
+		TooltipTrigger(class!="{triggerClass ?? undefined}")
+			| {@render trigger?.()}
+		TooltipPortal
+			TooltipContent(class!="{contentClasses}" side!="{side}" sideOffset!="{sideOffset}")
+				| {content ?? ''}
+				| {@render children?.()}
+
+<script>
+	import { Tooltip } from 'bits-ui'
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		Provider: TooltipProvider
+		Root: TooltipRoot
+		Trigger: TooltipTrigger
+		Portal: TooltipPortal
+		Content: TooltipContent
+	} := Tooltip
+
+	{
+		content
+		side = 'top'
+		sideOffset = 6
+		delay = 300
+		trigger
+		children
+		triggerClass
+		class: extra = ''
+	} .= $props()
+
+	contentClasses := cn 'tooltip-content', extra
+</script>

package/src/index.js

@@ -21,7 +21,17 @@ export { default as Select } from './components/Select.n';
 export { default as Switch } from './components/Switch.n';
 export { default as Textarea } from './components/Textarea.n';
 
+// Phase 3 — behavior tier (Bits UI)
+export { default as Dialog } from './components/Dialog.n';
+export { default as Sheet } from './components/Sheet.n';
+export { default as Popover } from './components/Popover.n';
+export { default as Dropdown } from './components/Dropdown.n';
+export { default as Tooltip } from './components/Tooltip.n';
+export { default as Tabs } from './components/Tabs.n';
+export { default as ToastProvider } from './components/ToastProvider.n';
+
 // Helpers
 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';

package/src/lib/toast.svelte.js

@@ -0,0 +1,42 @@
+/**
+ * Toast store + helpers. Single in-process queue, mounted once via
+ * <ToastProvider>. `toast(msg)` pushes from anywhere — server actions,
+ * client effects, button handlers.
+ */
+
+let nextId = 0;
+
+export const toastStore = $state({ items: [] });
+
+/**
+ * Push a toast. Returns the toast id so the caller can dismiss early.
+ *
+ * @param {string} message
+ * @param {{ variant?: 'info' | 'success' | 'warning' | 'error', duration?: number }} [opts]
+ *   `duration` in ms, default 4000. Set to 0 for sticky.
+ */
+export function toast(message, opts = {}) {
+	const id = ++nextId;
+	const item = {
+		id,
+		message,
+		variant: opts.variant ?? 'info',
+		duration: opts.duration ?? 4000
+	};
+	toastStore.items.push(item);
+	if (item.duration > 0) {
+		setTimeout(() => dismiss(id), item.duration);
+	}
+	return id;
+}
+
+export const notify = toast;
+
+export function dismiss(id) {
+	const i = toastStore.items.findIndex((t) => t.id === id);
+	if (i >= 0) toastStore.items.splice(i, 1);
+}
+
+export function clear() {
+	toastStore.items.length = 0;
+}

package/src/styles/atoms.css

@@ -193,4 +193,172 @@
 	.form {
 		@apply space-y-4;
 	}
+
+	/* --- Dialog (modal) ---
+	 * Bits UI toggles `data-state="open|closed"`. We use plain CSS transitions
+	 * targeting that attribute for fade + scale; no `tailwindcss-animate`
+	 * dependency, no v4 plugin.
+	 */
+	.dialog-overlay {
+		@apply fixed inset-0 z-50 bg-black/50 backdrop-blur-sm opacity-0 transition-opacity duration-150;
+	}
+	.dialog-overlay[data-state='open'] {
+		@apply opacity-100;
+	}
+
+	.dialog-content {
+		@apply fixed left-1/2 top-1/2 z-50 w-full max-w-lg -translate-x-1/2 -translate-y-1/2;
+		@apply rounded-lg border border-neutral-200 bg-white p-6 shadow-xl;
+		@apply opacity-0 scale-95 transition duration-150;
+	}
+	.dialog-content[data-state='open'] {
+		@apply opacity-100 scale-100;
+	}
+
+	.dialog-title {
+		@apply text-lg font-semibold leading-tight tracking-tight text-neutral-900;
+	}
+
+	.dialog-description {
+		@apply mt-1 text-sm text-neutral-600;
+	}
+
+	.dialog-body {
+		@apply mt-4;
+	}
+
+	.dialog-actions {
+		@apply mt-6 flex items-center justify-end gap-2;
+	}
+
+	.dialog-close {
+		@apply absolute right-3 top-3 inline-flex size-7 items-center justify-center rounded-md text-neutral-500;
+		@apply hover:bg-neutral-100 hover:text-neutral-900;
+		@apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500;
+	}
+
+	/* --- Sheet (side panel) --- */
+	.sheet-content {
+		@apply fixed z-50 border border-neutral-200 bg-white shadow-xl transition-transform duration-200 ease-out;
+	}
+	.sheet-right {
+		@apply right-0 top-0 h-full w-full max-w-md translate-x-full p-6;
+	}
+	.sheet-right[data-state='open'] {
+		@apply translate-x-0;
+	}
+	.sheet-left {
+		@apply left-0 top-0 h-full w-full max-w-md -translate-x-full p-6;
+	}
+	.sheet-left[data-state='open'] {
+		@apply translate-x-0;
+	}
+	.sheet-top {
+		@apply left-0 top-0 w-full -translate-y-full p-6;
+	}
+	.sheet-top[data-state='open'] {
+		@apply translate-y-0;
+	}
+	.sheet-bottom {
+		@apply bottom-0 left-0 w-full translate-y-full p-6;
+	}
+	.sheet-bottom[data-state='open'] {
+		@apply translate-y-0;
+	}
+
+	.sheet-body {
+		@apply mt-4;
+	}
+
+	/* --- Popover --- */
+	.popover-content {
+		@apply z-50 rounded-md border border-neutral-200 bg-white p-3 text-sm shadow-md;
+		@apply opacity-0 scale-95 transition duration-150;
+	}
+	.popover-content[data-state='open'] {
+		@apply opacity-100 scale-100;
+	}
+
+	/* --- Dropdown menu --- */
+	.dropdown-content {
+		@apply z-50 min-w-[8rem] rounded-md border border-neutral-200 bg-white p-1 text-sm shadow-md;
+		@apply opacity-0 scale-95 transition duration-150;
+	}
+	.dropdown-content[data-state='open'] {
+		@apply opacity-100 scale-100;
+	}
+	.dropdown-item {
+		@apply flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm text-neutral-800 outline-none;
+		@apply data-[highlighted]:bg-neutral-100 data-[highlighted]:text-neutral-900;
+		@apply data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50;
+	}
+	.dropdown-separator {
+		@apply -mx-1 my-1 h-px bg-neutral-200;
+	}
+
+	/* --- Tooltip --- */
+	.tooltip-content {
+		@apply z-50 overflow-hidden rounded-md bg-neutral-900 px-2 py-1 text-xs text-white shadow-md;
+		@apply opacity-0 scale-95 transition duration-150;
+	}
+	.tooltip-content[data-state='delayed-open'],
+	.tooltip-content[data-state='instant-open'] {
+		@apply opacity-100 scale-100;
+	}
+
+	/* --- Tabs --- */
+	.tabs-root {
+		@apply space-y-3;
+	}
+	.tabs-list {
+		@apply inline-flex h-9 items-center justify-center rounded-md bg-neutral-100 p-1 text-neutral-600;
+	}
+	.tabs-trigger {
+		@apply inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1 text-sm font-medium;
+		@apply transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500;
+		@apply data-[state=active]:bg-white data-[state=active]:text-neutral-900 data-[state=active]:shadow-sm;
+		@apply disabled:cursor-not-allowed disabled:opacity-50;
+	}
+	.tabs-content {
+		@apply focus-visible:outline-none;
+	}
+
+	/* --- Toast --- */
+	.toast-region {
+		@apply pointer-events-none fixed bottom-4 right-4 z-[100] flex w-full max-w-sm flex-col gap-2;
+	}
+	.toast {
+		@apply pointer-events-auto flex items-start gap-3 rounded-md border border-neutral-200 bg-white p-3 shadow-md;
+		animation: norns-toast-in 200ms ease-out;
+	}
+	@keyframes norns-toast-in {
+		from {
+			opacity: 0;
+			transform: translateX(1rem);
+		}
+		to {
+			opacity: 1;
+			transform: translateX(0);
+		}
+	}
+	.toast-info {
+		@apply border-neutral-200;
+	}
+	.toast-success {
+		@apply border-green-200 bg-green-50 text-green-900;
+	}
+	.toast-warning {
+		@apply border-amber-200 bg-amber-50 text-amber-900;
+	}
+	.toast-error {
+		@apply border-red-200 bg-red-50 text-red-900;
+	}
+	.toast-message {
+		@apply flex-1 text-sm leading-snug;
+	}
+	.toast-close {
+		@apply -mr-1 -mt-0.5 inline-flex size-6 shrink-0 items-center justify-center rounded text-neutral-500;
+		@apply hover:bg-neutral-100 hover:text-neutral-900;
+		@apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500;
+	}
 }

package/src/types/Dialog.d.ts

@@ -0,0 +1,17 @@
+import type { Component, Snippet } from 'svelte';
+
+export type DialogProps = {
+	open?: boolean;
+	title?: string;
+	description?: string;
+	hideClose?: boolean;
+	trigger?: Snippet;
+	actions?: Snippet;
+	children?: Snippet;
+	triggerClass?: string;
+	overlayClass?: string;
+	class?: string;
+};
+
+declare const Dialog: Component<DialogProps>;
+export default Dialog;

package/src/types/Dropdown.d.ts

@@ -0,0 +1,23 @@
+import type { Component, Snippet } from 'svelte';
+
+export type DropdownItem = {
+	label?: string;
+	separator?: boolean;
+	disabled?: boolean;
+	onSelect?: (event: Event) => void;
+};
+
+export type DropdownProps = {
+	open?: boolean;
+	side?: 'top' | 'right' | 'bottom' | 'left';
+	align?: 'start' | 'center' | 'end';
+	sideOffset?: number;
+	items?: DropdownItem[];
+	trigger?: Snippet;
+	children?: Snippet;
+	triggerClass?: string;
+	class?: string;
+};
+
+declare const Dropdown: Component<DropdownProps>;
+export default Dropdown;

package/src/types/Field.d.ts

@@ -1,15 +1,26 @@
 import type { Component, Snippet } from 'svelte';
 
 export type FieldProps = {
-	/** Label text rendered above the control. Used as id-derivation fallback if no `id` is given. */
+	/** Label text rendered above the control. Used as id-derivation fallback if no `id`/`name` is given. */
 	label?: string;
 	/** Helper text shown below the control when there's no error. */
 	help?: string;
-	/** Error message shown below the control. Switches the inner control to error styling via context. */
+	/**
+	 * Explicit error message. Overrides any auto-resolved error from the
+	 * parent `<Form form={...}>` context. Switches the inner control to
+	 * error styling.
+	 */
 	error?: string;
+	/**
+	 * Field name — used to look up an auto-error from the parent `<Form>`
+	 * context (matching `form.errors[*].path[0].key`) and as the default
+	 * id for the inner control. When set, an inner `<Input>` doesn't need
+	 * an explicit `name=` either if it inherits from this Field.
+	 */
+	name?: string;
 	/** Adds a red asterisk after the label. Cosmetic; pair with `required` on the actual input. */
 	required?: boolean;
-	/** Explicit id for the control. Otherwise derived from `label`, otherwise undefined. */
+	/** Explicit id for the control. Otherwise: `name`, then slugified `label`, then undefined. */
 	id?: string;
 	/** Optional class merged into the field wrapper. */
 	class?: string;

package/src/types/Form.d.ts

@@ -1,10 +1,27 @@
 import type { Component, Snippet } from 'svelte';
 import type { HTMLFormAttributes } from 'svelte/elements';
 
+/**
+ * The shape returned by `fail(400, { errors, values })` from a SvelteKit
+ * action — what `+page.server.c`'s `page.actions` produces on validation
+ * failure (or a manually-constructed equivalent). `errors` is a valibot
+ * issue list; `values` is the raw form data echoed back for re-rendering.
+ */
+export type FormActionResult = {
+	errors?: Array<{ path?: Array<{ key?: string }>; message: string }>;
+	values?: Record<string, string>;
+} | null | undefined;
+
 export type FormProps = Omit<HTMLFormAttributes, 'class' | 'children'> & {
 	method?: 'GET' | 'POST';
 	action?: string;
 	enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+	/**
+	 * Pass the page's `form` prop here. Form derives a `name → message` errors
+	 * map and exposes it via context so descendant `<Field name="...">` looks
+	 * up its own error automatically.
+	 */
+	form?: FormActionResult;
 	class?: string;
 	children?: Snippet;
 };

package/src/types/Popover.d.ts

@@ -0,0 +1,18 @@
+import type { Component, Snippet } from 'svelte';
+
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
+export type PopoverAlign = 'start' | 'center' | 'end';
+
+export type PopoverProps = {
+	open?: boolean;
+	side?: PopoverSide;
+	align?: PopoverAlign;
+	sideOffset?: number;
+	trigger?: Snippet;
+	children?: Snippet;
+	triggerClass?: string;
+	class?: string;
+};
+
+declare const Popover: Component<PopoverProps>;
+export default Popover;

package/src/types/Sheet.d.ts

@@ -0,0 +1,20 @@
+import type { Component, Snippet } from 'svelte';
+
+export type SheetSide = 'top' | 'right' | 'bottom' | 'left';
+
+export type SheetProps = {
+	open?: boolean;
+	side?: SheetSide;
+	title?: string;
+	description?: string;
+	hideClose?: boolean;
+	trigger?: Snippet;
+	actions?: Snippet;
+	children?: Snippet;
+	triggerClass?: string;
+	overlayClass?: string;
+	class?: string;
+};
+
+declare const Sheet: Component<SheetProps>;
+export default Sheet;

package/src/types/Tabs.d.ts

@@ -0,0 +1,17 @@
+import type { Component, Snippet } from 'svelte';
+
+export type TabsItem = {
+	value: string;
+	label: string;
+	panel?: Snippet;
+	disabled?: boolean;
+};
+
+export type TabsProps = {
+	value?: string;
+	items?: TabsItem[];
+	class?: string;
+};
+
+declare const Tabs: Component<TabsProps>;
+export default Tabs;

package/src/types/ToastProvider.d.ts

@@ -0,0 +1,15 @@
+import type { Component } from 'svelte';
+
+export type ToastVariant = 'info' | 'success' | 'warning' | 'error';
+
+export type ToastProviderProps = {
+	class?: string;
+};
+
+export type ToastOpts = {
+	variant?: ToastVariant;
+	duration?: number;
+};
+
+declare const ToastProvider: Component<ToastProviderProps>;
+export default ToastProvider;

package/src/types/Tooltip.d.ts

@@ -0,0 +1,15 @@
+import type { Component, Snippet } from 'svelte';
+
+export type TooltipProps = {
+	content?: string;
+	side?: 'top' | 'right' | 'bottom' | 'left';
+	sideOffset?: number;
+	delay?: number;
+	trigger?: Snippet;
+	children?: Snippet;
+	triggerClass?: string;
+	class?: string;
+};
+
+declare const Tooltip: Component<TooltipProps>;
+export default Tooltip;