@human-synthesis/norns-ui 0.0.3 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Teodoroiu / Human Synthesis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,6 @@
 # `@human-synthesis/norns-ui`
 
-UI library for the [Norns](https://github.com/human-synthesis/norns) ecosystem — Pug + Civet components on Tailwind v4.
-
-**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.
+**UI library for the Norns ecosystem.** Pug + Civet components on Tailwind v4, with custom headless behaviors built on `@floating-ui/dom` and Iconify behind the icon system.
 
 ## Stack
 
@@ -12,9 +8,11 @@ UI library for the [Norns](https://github.com/human-synthesis/norns) ecosystem
 - [Pug](https://pugjs.org) — templates (in `.n` files)
 - [Civet](https://civet.dev) — `<script>` language
 - [Tailwind CSS v4](https://tailwindcss.com) — styling, **hard peer dep**
+- [@floating-ui/dom](https://floating-ui.com) — overlay positioning (Popover, Dropdown, Tooltip, ContextMenu, pickers)
+- Custom in-tree headless behaviors (focus-trap, scroll-lock, click-outside, escape, portal, roving-tabindex) — exported at `@human-synthesis/norns-ui/behaviors`
+- [Iconify](https://iconify.design) — icons; ships with [Lucide](https://lucide.dev) preset
 - [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)
+- [`@human-synthesis/norns`](https://github.com/human-synthesis/norns) — peer (`nornsAutoImport`)
 
 ## Install
 
@@ -24,272 +22,130 @@ bun add -D @human-synthesis/norns-ui
 
 ## Setup
 
-### 1. Wire `presetUI()` into `nornsAutoImport`
-
-So `<Btn>`, `<Field>`, `<Input>`, etc. resolve in markup without explicit imports.
+`vite.config.js`:
 
 ```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import { sveltekit } from '@sveltejs/kit/vite';
-import tailwindcss from '@tailwindcss/vite';
 import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
-import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
 import { presetUI } from '@human-synthesis/norns-ui/auto-import';
 
 const ui = presetUI();
 
-export default defineConfig({
-	plugins: [
-		nornsCivetPlugin(),
-		nornsAutoImport({
-			componentDirs: ['src/lib/components'],
-			components: ui.components
-		}),
-		tailwindcss(),
-		sveltekit()
-	]
-});
-```
-
-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({ /* … */ }))
-	]
-});
+export default {
+  plugins: [
+    nornsCivetPlugin(),
+    nornsAutoImport({
+      componentDirs: ['src/lib/components'],
+      components: ui.components
+    }),
+    tailwindcss(),
+    sveltekit()
+  ]
+};
 ```
 
-### 2. Import the styles
+`app.css`:
 
 ```css
-/* app.css */
 @import 'tailwindcss';
 @import '@human-synthesis/norns-ui/styles';
-
-/* override tokens here if you want a different brand color */
-@theme {
-	--color-primary-500: oklch(60% 0.2 200);
-}
-```
-
-### 3. Use components in Pug
-
-```pug
-section.space-y-4
-	h1.text-3xl New note
-
-	Form(method="POST" action="?/create")
-		Field(label="Title" required error!="{form?.errors?.title}")
-			Input(name="title" required)
-		Field(label="Body" help="Optional — supports plain text only")
-			Textarea(name="body" rows="4")
-		Btn(type="submit" variant="primary") Create note
 ```
 
-## Component catalog
-
-### Phase 1 — atoms
-
-CSS classes via `@layer components`. Use directly via Pug class shorthand:
-
-- `.btn` + variants (`primary`, `secondary`, `ghost`, `danger`, `link`) + sizes (`sm`, `lg`)
-- `.input` / `.textarea` / `.select` + `-err` modifier
-- `.checkbox` / `.radio` / `.switch` + `-err` modifier
-- `.field` / `.field-label` / `.field-required` / `.field-help` / `.field-error`
-- `.field-group` / `.field-group-legend`
-- `.form`
-- `.ui-spinner`
+## Dark mode
 
-### Phase 1 — Btn
+Toggle via `<html data-theme="dark">` — every component swaps. Persist the choice with a small inline script in `app.html` to avoid FOUC:
 
-Wrapped `<button>` with class merging, variant/size props, loading state, and snippet-prop API for icons.
-
-```pug
-Btn(variant="primary") Save
-Btn(variant="secondary" size="sm") Cancel
-Btn(loading!="{saving}" type="submit") Save
-Btn(variant="danger" onclick!="{remove}")
-	+snippet('leading')
-		// icon goes here
-	| Delete
+```html
+<script>
+  (function () {
+    try {
+      var t = localStorage.getItem('theme');
+      if (t === 'dark' || (t === null && matchMedia('(prefers-color-scheme: dark)').matches)) {
+        document.documentElement.dataset.theme = 'dark';
+      }
+    } catch (_) {}
+  })();
+</script>
 ```
 
-Props (see [`src/types/Btn.d.ts`](src/types/Btn.d.ts)):
-- `variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link'` (default `'primary'`)
-- `size?: 'sm' | 'md' | 'lg'` (default `'md'`)
-- `loading?: boolean` — replaces leading icon with `.ui-spinner`, sets `disabled` and `aria-busy`
-- `disabled?: boolean`, `type?`, `onclick?`, `class?`, `children`, `leading`, `trailing`
-
-### Phase 2 — forms tier
+## Icons
 
-#### `<Field>`
+The library ships [`@iconify/svelte`](https://iconify.design/docs/icon-components/svelte/) with the [Lucide](https://lucide.dev) collection bundled. Register the collection once in your app entry so icons render in SSR and the client:
 
-Wraps a control with label + optional help/error text. Provides `id` and `hasError` to descendant controls via Svelte context — child Inputs auto-pick up the right `id` for `<label for=>` and switch to error styling.
-
-```pug
-Field(label="Email" required error!="{form?.errors?.email}" help="We'll never share it")
-	Input(name="email" type="email" required)
+```js
+// src/routes/+layout.svelte (or wherever fits)
+import { addCollection } from '@iconify/svelte';
+import lucide from '@iconify-json/lucide/icons.json';
+addCollection(lucide);
 ```
 
-Props: `label?`, `help?`, `error?`, `required?`, `id?`, `class?`, `children`.
-
-#### `<Form>`, `<FieldGroup>`
-
-Styled `<form>` (vertical stack via `.form`) and `<fieldset>` (`.field-group` with optional legend).
+Then use `<Icon>` anywhere:
 
 ```pug
-Form(action="?/save")
-	FieldGroup(legend="Profile")
-		Field(label="Name")
-			Input(name="name" required)
-		Field(label="Bio")
-			Textarea(name="bio" rows="3")
-	Btn(type="submit") Save
+Icon(name="lucide:check" size="size-5")
+Btn(icon="lucide:save") Save
 ```
 
-#### Form controls
-
-All accept `class?` (merged via `cn`), pull `id` + `hasError` from a parent `<Field>` automatically, and surface `aria-invalid` + `aria-describedby` for accessibility:
-
-| Component | Bind | Common props |
-|---|---|---|
-| `<Input>` | `bind:value` | `type`, `size`, `name`, `placeholder`, `required`, `disabled`, `readonly`, `autocomplete` |
-| `<Textarea>` | `bind:value` | `name`, `placeholder`, `rows` (default 4), `required`, `disabled`, `readonly` |
-| `<Select>` | `bind:value` | `name`, `required`, `disabled`. Children: `<option>` elements |
-| `<Checkbox>` | `bind:checked` | `name`, `value`, `required`, `disabled` |
-| `<Radio>` | `bind:group` | `name`, `value`, `required`, `disabled` |
-| `<Switch>` | `bind:checked` | `name`, `value`, `required`, `disabled`. Renders as a styled toggle (`role="switch"`) |
+To mix in another icon set, install its JSON package (e.g. `@iconify-json/heroicons`) and `addCollection(...)` it the same way.
 
-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>`
+## Usage
 
 ```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
+Form(action="?/save" form!="{form}")
+  Field(label="Title" name="title" required)
+    Input(name="title" placeholder="title…" required)
+  Btn(type="submit" variant="primary" icon="lucide:save") Save
 ```
 
-Props: `open` (bindable), `title`, `description`, `hideClose`, `trigger`, `actions`, `children`, `class`, `overlayClass`, `triggerClass`.
-
-#### `<Sheet>`
+`<Field name="title">` reads its error from the parent `<Form>`'s context map; no per-page boilerplate.
 
-Same API as `Dialog` plus `side?: 'top' | 'right' | 'bottom' | 'left'` (default `'right'`). Slides in from the chosen edge instead of centering.
+## What's in here
 
-#### `<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") ⋯
-```
+- **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.
+- **Forms**: `Btn`, `Form`, `Field`, `FieldGroup`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`.
+- **Behavior** (custom on `@floating-ui/dom`): `Dialog`, `Sheet`, `Popover`, `Dropdown`, `Tooltip`, `Tabs`, `Accordion`, `ContextMenu`, `Collapsible`.
+- **Display**: `Card`, `Surface`, `Banner`, `Badge`, `Chip`, `Avatar`, `Skeleton`, `Progress`, `ProgressCircular`, `Icon`.
+- **Composite**: `Header`, `HeroBanner`, `Stepper`, `Breadcrumbs`, `Pagination`, `Carousel`.
+- **Toast**: `ToastProvider` + `toast()` / `notify()` / `dismiss()` from `@human-synthesis/norns-ui/toast`.
 
-#### `<Tooltip>`
+Hand-rolled `.d.ts` shims live under `src/types/`. Override any component by dropping `src/lib/components/<Name>.n` in your project — `nornsAutoImport`'s first-match-wins shadows the library silently.
 
-```pug
-Tooltip(content="Saved 2 minutes ago")
-	+snippet('trigger')
-		Btn(variant="ghost" size="sm") ⓘ
-```
+## Behaviors
 
-#### `<Tabs>`
+A small set of headless behaviors is exposed at `@human-synthesis/norns-ui/behaviors` for use in your own components:
 
-```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 }
-]}")
+```js
+import {
+  portal, clickOutside, escape, focusTrap,
+  scrollLock, useFloating, rovingTabindex
+} from '@human-synthesis/norns-ui/behaviors';
 ```
 
-#### `<ToastProvider>` + `toast()`
-
-Mount once near the app root, then call `toast()` from anywhere:
-
-```pug
-// +layout.n
-ToastProvider
-| {@render children?.()}
-```
+These are Svelte 5 actions (`use:portal`, `use:clickOutside={handler}`, etc.) and a small `useFloating()` factory that wraps `@floating-ui/dom`. They're what every overlay component in this library is built on, so reaching for them in your own code keeps interactions consistent.
 
-```civet
-import { toast } from '@human-synthesis/norns-ui/toast'
+## Migrating from 0.0.5 → 0.0.6
 
-handleSave := =>
-	await save()
-	toast 'Saved!', { variant: 'success' }
-```
+bits-ui has been removed; overlays are now built on `@floating-ui/dom` plus the in-tree behaviors module. Most APIs are unchanged. The breaking changes:
 
-Variants: `info` (default), `success`, `warning`, `error`. Default duration 4000ms; pass `duration: 0` for sticky.
+- `<Drawer>` is gone. Use `<Sheet side="left">` (it now defaults to `'right'`; pass the side you want).
+- `<RichTooltip>` is gone. Use `<Tooltip rich>`.
+- `<PreviewCard>` is gone. Use `<Tooltip>` with the trigger as a link, e.g. `<Tooltip rich content="...">{#snippet trigger()}<a href=...>{/snippet}</Tooltip>`.
+- `<ContextMenu>` no longer renders nested submenus. The `children` field on items is accepted but ignored.
+- The `svelte.config.js` `scopeToProject` workaround is no longer needed (it existed only to keep svelte-preprocess from corrupting bits-ui's TypeScript source). Remove it from your config.
 
 ## 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.
-
-Dark mode: toggle via `<html data-theme="dark">`. The library's tokens.css ships dark-theme overrides; Tailwind's existing dark-aware utilities continue to work.
-
-## Class merging
-
-Every component takes a `class` prop merged via `tailwind-merge` (the `cn` helper):
-
-```svelte
-<Btn variant="primary" class="w-full" />
-<Input class="font-mono" />
-```
-
-`cn` is exported from `@human-synthesis/norns-ui/cn` if you want to swap in plain `clsx` for smaller bundle:
-
-```js
-import { cn } from '@human-synthesis/norns-ui/cn';
-cn('btn', isActive && 'btn-active', extra);
-```
+Tokens are in [`src/styles/tokens.css`](src/styles/tokens.css) as a Tailwind v4 `@theme` block. The library exposes:
 
-## Override a component
+- **Color scales** (50–950) for `primary`, `success`, `warning`, `danger`, `info` — all in `oklch` for perceptual uniformity. Use as `bg-primary-500`, `text-danger-700`, etc.
+- **Role tokens** that atoms reference (and that you should reach for in your own components): `--color-fg`, `--color-fg-muted`, `--color-fg-subtle`, `--color-bg`, `--color-bg-muted`, `--color-bg-subtle`, `--color-bg-elevated`, `--color-border`, `--color-border-strong`, `--color-ring`. These swap automatically on dark mode.
+- **Feedback tokens**: `--color-{success,warning,danger,info}-{bg,fg,border}` for tinted surfaces.
+- **Typography tokens**: `--font-sans`, `--font-mono`.
+- **Sizing**: `--ui-radius-{sm,,lg,full}`, `--ui-h-{sm,md,lg}` (full button heights), `--ui-icon-btn-{sm,md,lg}` (square icon-button sizes).
+- **Motion**: `--ui-motion-{fast,med,slow}` durations + `--ui-motion-ease`. All component transitions reference these.
+- **Elevation**: `--ui-elev-{1,2,3}` (subtle / floating / modal). Dark mode swaps to deeper shadows.
+- **Focus**: `--ui-focus-ring` — the single canonical focus indicator. Apply as `box-shadow: var(--ui-focus-ring)` on `:focus-visible`.
 
-Drop a same-name file in your `src/lib/components/` and `nornsAutoImport`'s first-match-wins resolves to your version silently. No fork needed.
-
-```
-src/lib/components/Btn.n         ← your override wins
-node_modules/@human-synthesis/norns-ui/src/components/Btn.n   ← fallback
-```
+Override by re-declaring `@theme { … }` in your `app.css` after the library import.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@human-synthesis/norns-ui",
-	"version": "0.0.3",
+	"version": "0.0.6",
 	"description": "UI library for the Norns ecosystem — Pug + Civet components on Tailwind v4.",
 	"license": "MIT",
 	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -14,17 +14,23 @@
 		"README.md"
 	],
 	"scripts": {
-		"test": "bun test"
+		"test": "bun test",
+		"check:shims": "bun scripts/check-shims.mjs",
+		"check:shims:strict": "bun scripts/check-shims.mjs --strict"
 	},
 	"exports": {
 		".": "./src/index.js",
 		"./auto-import": "./src/auto-import.js",
 		"./cn": "./src/lib/cn.js",
+		"./behaviors": "./src/lib/behaviors/index.js",
+		"./behaviors/*": "./src/lib/behaviors/*",
 		"./toast": "./src/lib/toast.svelte.js",
 		"./styles": "./src/styles/index.css",
 		"./styles/tokens": "./src/styles/tokens.css",
 		"./styles/atoms": "./src/styles/atoms.css",
 		"./components/*": "./src/components/*",
+		"./motion": "./src/motion/index.js",
+		"./motion/*": "./src/motion/*",
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
@@ -42,7 +48,11 @@
 		}
 	},
 	"dependencies": {
-		"bits-ui": "^2.18.1",
+		"@floating-ui/dom": "^1.7.6",
+		"@fontsource-variable/outfit": "^5.2.8",
+		"@iconify-json/lucide": "^1.2.105",
+		"@iconify/svelte": "^5.2.1",
+		"motion": "^12.38.0",
 		"tailwind-merge": "^2.5.0"
 	},
 	"engines": {

package/src/auto-import.js

@@ -26,33 +26,95 @@
  * @returns {UIPreset}
  */
 export function presetUI() {
+	const c = (name) => `@human-synthesis/norns-ui/components/${name}.n`;
 	return {
 		components: {
 			// Phase 1
-			Btn: '@human-synthesis/norns-ui/components/Btn.n',
+			Btn: c('Btn'),
 
 			// Phase 2 — forms tier
-			Field: '@human-synthesis/norns-ui/components/Field.n',
-			FieldGroup: '@human-synthesis/norns-ui/components/FieldGroup.n',
-			Form: '@human-synthesis/norns-ui/components/Form.n',
-			Input: '@human-synthesis/norns-ui/components/Input.n',
-			Textarea: '@human-synthesis/norns-ui/components/Textarea.n',
-			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',
+			Field: c('Field'),
+			FieldGroup: c('FieldGroup'),
+			Form: c('Form'),
+			Input: c('Input'),
+			Textarea: c('Textarea'),
+			Select: c('Select'),
+			Checkbox: c('Checkbox'),
+			Radio: c('Radio'),
+			Switch: c('Switch'),
 
 			// 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'
+			Dialog: c('Dialog'),
+			Sheet: c('Sheet'),
+			Popover: c('Popover'),
+			Dropdown: c('Dropdown'),
+			Tooltip: c('Tooltip'),
+			Tabs: c('Tabs'),
+			ToastProvider: c('ToastProvider'),
 
-			// Phase 4+ adds: Accordion, Listbox, Combobox, Pagination,
-			// Avatar, Badge, Spinner, Progress, Skeleton, Icon, Card
+			// 0.0.4 — display layer
+			Icon: c('Icon'),
+			Card: c('Card'),
+			Surface: c('Surface'),
+			Banner: c('Banner'),
+			Badge: c('Badge'),
+			Chip: c('Chip'),
+			Avatar: c('Avatar'),
+			Skeleton: c('Skeleton'),
+			Progress: c('Progress'),
+			ProgressCircular: c('ProgressCircular'),
+
+			// 0.0.4 — composite layer
+			Header: c('Header'),
+			HeroBanner: c('HeroBanner'),
+			Stepper: c('Stepper'),
+			Breadcrumbs: c('Breadcrumbs'),
+			Pagination: c('Pagination'),
+			Accordion: c('Accordion'),
+			Carousel: c('Carousel'),
+			Tree: c('Tree'),
+
+			// 0.0.4 — wave A: small/standalone
+			Separator: c('Separator'),
+			Toolbar: c('Toolbar'),
+			ButtonGroup: c('ButtonGroup'),
+			ToggleButton: c('ToggleButton'),
+			ToggleButtonGroup: c('ToggleButtonGroup'),
+			Collapsible: c('Collapsible'),
+			NumberInput: c('NumberInput'),
+			OtpField: c('OtpField'),
+			TagsInput: c('TagsInput'),
+			Image: c('Image'),
+			Audio: c('Audio'),
+			Video: c('Video'),
+			Timeline: c('Timeline'),
+
+			// 0.0.4 — wave B: medium-complexity (custom; ex Bits-UI-backed)
+			Autocomplete: c('Autocomplete'),
+			MultiSelect: c('MultiSelect'),
+			ContextMenu: c('ContextMenu'),
+			ScrollArea: c('ScrollArea'),
+			ColorPicker: c('ColorPicker'),
+			Uploader: c('Uploader'),
+			HierarchicalMenu: c('HierarchicalMenu'),
+			MegaMenu: c('MegaMenu'),
+
+			// 0.0.4 — wave C: pickers + table
+			DatePicker: c('DatePicker'),
+			DateRangePicker: c('DateRangePicker'),
+			TimePicker: c('TimePicker'),
+			Calendar: c('Calendar'),
+			DataTable: c('DataTable'),
+
+			// 0.0.5 — CSS-only motion components
+			AvatarGroup: c('AvatarGroup'),
+			GradientText: c('GradientText'),
+			CopyButton: c('CopyButton'),
+			ThemeToggler: c('ThemeToggler'),
+			ShinyButton: c('ShinyButton'),
+			RippleButton: c('RippleButton')
+			// Motion-driven components live in `@human-synthesis/norns-ui/motion`
+			// and are NOT registered here (opt-in import only).
 		},
 		helpers: [
 			{

package/src/components/Accordion.n

@@ -0,0 +1,39 @@
+.accordion(class!="{classes}")
+	+each('items as item (item.value)')
+		details.accordion-item(
+			open!="{isOpen(item.value)}"
+			ontoggle!="{(e) => onToggle(item.value, e.target.open)}"
+		)
+			summary.accordion-trigger
+				span {item.title}
+				.accordion-chevron
+					Icon(name="lucide:chevron-down" size="size-4")
+			.accordion-content
+				| {@render item.content?.()}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import Icon from './Icon.n'
+
+	{
+		items = []
+		multiple = false
+		value = $bindable(undefined)
+		class: extra = ''
+	} .= $props()
+
+	classes := cn 'accordion', extra
+
+	isOpen := (v) =>
+		if multiple
+			Array.isArray(value) && value.includes v
+		else
+			value === v
+
+	onToggle := (v, isNowOpen) =>
+		if multiple
+			cur := Array.isArray(value) ? value : []
+			value = isNowOpen ? [...new Set([...cur, v])] : cur.filter((x) => x !== v)
+		else
+			value = isNowOpen ? v : (value === v ? undefined : value)
+</script>

package/src/components/Audio.n

@@ -0,0 +1,24 @@
+audio(src!="{src}" controls!="{controls}" autoplay!="{autoplay}" loop!="{looping}" muted!="{muted}" preload!="{preload}" class!="{classes}")
+	+each('sources as source')
+		source(src!="{source.src}" type!="{source.type}")
+	| {fallback}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	// Note: HTML attribute `loop` becomes `looping` here because `loop` is a
+	// Civet reserved word.
+	{
+		src
+		sources = []
+		controls = true
+		autoplay = false
+		loop: looping = false
+		muted = false
+		preload = 'metadata'
+		fallback = 'Your browser does not support the audio element.'
+		class: extra = ''
+	} := $props()
+
+	classes := cn 'audio-player w-full', extra
+</script>