@human-synthesis/norns-ui 0.0.1 → 0.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 UI library for the [Norns](https://github.com/human-synthesis/norns) ecosystem — Pug + Civet components on Tailwind v4.
 
-**Status: Phase 1 (foundation).** Currently ships `Btn` and the atom CSS layer. Forms tier (Input, Field, Form, …) lands in Phase 2; Bits-UI-backed behavior tier (Dialog, Popover, Tabs, Toast, …) in Phase 3.
+**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.
 
 ## Stack
 
@@ -23,7 +23,7 @@ bun add -D @human-synthesis/norns-ui
 
 ### 1. Wire `presetUI()` into `nornsAutoImport`
 
-So `<Btn>`, `<Card>`, `<Field>` resolve in markup without explicit imports.
+So `<Btn>`, `<Field>`, `<Input>`, etc. resolve in markup without explicit imports.
 
 ```js
 // vite.config.js
@@ -69,28 +69,32 @@ Same shape goes in `svelte.config.js`'s `preprocess` array.
 ### 3. Use components in Pug
 
 ```pug
-section.space-y-3
-	h1.text-3xl Notes
-	form(method="POST" action="?/create")
-		input.input(name="title" required)
+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
 ```
 
-## What ships
+## Component catalog
 
-### Atoms (CSS-only — Tailwind `@layer components`)
+### Phase 1 — atoms
 
-Use directly via Pug class shorthand:
+CSS classes via `@layer components`. Use directly via Pug class shorthand:
 
-- `.btn` + variants: `.btn-primary`, `.btn-secondary`, `.btn-ghost`, `.btn-danger`, `.btn-link`
-- `.btn` + sizes: `.btn-sm`, `.btn-lg` (default md is built into `.btn`)
-- `.ui-spinner` — small inline spinner
+- `.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`
 
-More atoms (`.input`, `.card`, `.badge`, `.field-*`) land in Phase 2.
-
-### Components
-
-#### `<Btn>` ([source](src/components/Btn.n))
+### Phase 1 — Btn
 
 Wrapped `<button>` with class merging, variant/size props, loading state, and snippet-prop API for icons.
 
@@ -108,12 +112,49 @@ 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?: 'button' | 'submit' | 'reset'` (default `'button'`)
-- `onclick?: (event) => void`
-- `class?: string` — merged via [`tailwind-merge`](https://github.com/dcastil/tailwind-merge)
-- `children` — default snippet (the button label)
-- `leading`, `trailing` — snippet slots for icons
+- `disabled?: boolean`, `type?`, `onclick?`, `class?`, `children`, `leading`, `trailing`
+
+### Phase 2 — forms tier
+
+#### `<Field>`
+
+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)
+```
+
+Props: `label?`, `help?`, `error?`, `required?`, `id?`, `class?`, `children`.
+
+#### `<Form>`, `<FieldGroup>`
+
+Styled `<form>` (vertical stack via `.form`) and `<fieldset>` (`.field-group` with optional legend).
+
+```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
+```
+
+#### 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"`) |
+
+Each has a hand-rolled `.d.ts` shim under `src/types/`.
 
 ## Theming
 
@@ -126,14 +167,15 @@ Dark mode: toggle via `<html data-theme="dark">`. The library's tokens.css ships
 Every component takes a `class` prop merged via `tailwind-merge` (the `cn` helper):
 
 ```svelte
-<Btn variant="primary" class="w-full" /> <!-- both classes survive; later wins on conflicts -->
+<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)
+cn('btn', isActive && 'btn-active', extra);
 ```
 
 ## Override a component

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@human-synthesis/norns-ui",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "UI library for the Norns ecosystem — Pug + Civet components on Tailwind v4.",
 	"license": "MIT",
 	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",

package/src/auto-import.js

@@ -9,21 +9,17 @@
  *
  *   const ui = presetUI();
  *
- *   // vite.config.js
  *   plugins: [
  *     nornsCivetPlugin(),
  *     nornsAutoImport({
  *       componentDirs: ['src/lib/components'],   // user folder wins
- *       components: ui.components,                // norns-ui as fallback
- *       helpers: ui.helpers
+ *       components: ui.components                 // norns-ui as fallback
  *     }),
  *     sveltekit()
  *   ]
  *
  * Components are imported via bare specifiers so the consumer's
  * `node_modules/@human-synthesis/norns-ui/...` is the resolution target.
- * Helpers (functional APIs like `toast()`) are added incrementally as the
- * library grows.
  *
  * @typedef {Object} UIPreset
  * @property {Record<string, string>} components  name → bare-specifier import path
@@ -34,11 +30,23 @@
 export function presetUI() {
 	return {
 		components: {
-			Btn: '@human-synthesis/norns-ui/components/Btn.n'
-			// Phase 2+ adds: Input, Textarea, Select, Checkbox, Radio, Switch,
-			// Field, Form, FieldGroup, Card, Dialog, Sheet, Popover, Dropdown,
-			// Tooltip, Tabs, Accordion, Toast, Listbox, Combobox, Pagination,
-			// Avatar, Badge, Spinner, Progress, Skeleton, Icon
+			// Phase 1
+			Btn: '@human-synthesis/norns-ui/components/Btn.n',
+
+			// 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'
+
+			// Phase 3+ adds: Card, Dialog, Sheet, Popover, Dropdown, Tooltip,
+			// Tabs, Accordion, Toast + ToastProvider, Listbox, Combobox,
+			// Pagination, Avatar, Badge, Spinner, Progress, Skeleton, Icon
 		},
 		helpers: [
 			// Phase 3+: { from: '@human-synthesis/norns-ui', imports: ['toast'] }

package/src/components/Checkbox.n

@@ -0,0 +1,33 @@
+input(
+	type="checkbox"
+	id!="{resolvedId}"
+	name!="{name}"
+	value!="{value}"
+	bind:checked
+	required!="{required}"
+	disabled!="{disabled}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	class!="{classes}"
+)
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		checked = $bindable(false)
+		value
+		name
+		id: providedId
+		required = false
+		disabled = false
+		error: explicitError = false
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+
+	classes := cn 'checkbox', hasError && 'checkbox-err', extra
+</script>

package/src/components/Field.n

@@ -0,0 +1,47 @@
+.field(class!="{classes}")
+	+if('label')
+		label.field-label(for!="{ctx.id}")
+			| {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}")
+			| {help}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { setContext } from 'svelte'
+
+	{
+		label
+		help
+		error
+		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
+	slugify := (s) => s.toLowerCase().trim().replace(/[^\w]+/g, '-').replace(/^-+|-+$/g, '')
+	resolvedId := providedId ?? (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
+	setContext 'norns-ui:field', ctx
+
+	classes := cn 'field', extra
+</script>

package/src/components/FieldGroup.n

@@ -0,0 +1,17 @@
+fieldset(class!="{classes}")
+	+if('legend')
+		legend.field-group-legend
+			| {legend}
+	| {@render children?.()}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		legend
+		children
+		class: extra = ''
+	} := $props()
+
+	classes := cn 'field-group', extra
+</script>

package/src/components/Form.n

@@ -0,0 +1,23 @@
+form(
+	method!="{method}"
+	action!="{action}"
+	enctype!="{enctype}"
+	class!="{classes}"
+	onsubmit!="{onsubmit}"
+)
+	| {@render children?.()}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+
+	{
+		method = 'POST'
+		action
+		enctype
+		onsubmit
+		children
+		class: extra = ''
+	} := $props()
+
+	classes := cn 'form', extra
+</script>

package/src/components/Input.n

@@ -0,0 +1,41 @@
+input(
+	type!="{type}"
+	id!="{resolvedId}"
+	name!="{name}"
+	bind:value
+	placeholder!="{placeholder}"
+	required!="{required}"
+	disabled!="{disabled}"
+	readonly!="{readonly}"
+	autocomplete!="{autocomplete}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	aria-describedby!="{describedBy}"
+	class!="{classes}"
+)
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		value = $bindable('')
+		type = 'text'
+		size = 'md'
+		name
+		id: providedId
+		placeholder
+		required = false
+		disabled = false
+		readonly = false
+		autocomplete
+		error: explicitError = false
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+	describedBy := resolvedId && hasError ? `${resolvedId}-error` : undefined
+
+	classes := cn 'input', size !== 'md' && `input-${size}`, hasError && 'input-err', extra
+</script>

package/src/components/Radio.n

@@ -0,0 +1,33 @@
+input(
+	type="radio"
+	id!="{resolvedId}"
+	name!="{name}"
+	value!="{value}"
+	bind:group
+	required!="{required}"
+	disabled!="{disabled}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	class!="{classes}"
+)
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		group = $bindable()
+		value
+		name
+		id: providedId
+		required = false
+		disabled = false
+		error: explicitError = false
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+
+	classes := cn 'radio', hasError && 'radio-err', extra
+</script>

package/src/components/Select.n

@@ -0,0 +1,34 @@
+select(
+	id!="{resolvedId}"
+	name!="{name}"
+	bind:value
+	required!="{required}"
+	disabled!="{disabled}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	aria-describedby!="{describedBy}"
+	class!="{classes}"
+)
+	| {@render children?.()}
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		value = $bindable()
+		name
+		id: providedId
+		required = false
+		disabled = false
+		error: explicitError = false
+		children
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+	describedBy := resolvedId && hasError ? `${resolvedId}-error` : undefined
+
+	classes := cn 'select', hasError && 'select-err', extra
+</script>

package/src/components/Switch.n

@@ -0,0 +1,34 @@
+input(
+	type="checkbox"
+	role="switch"
+	id!="{resolvedId}"
+	name!="{name}"
+	value!="{value}"
+	bind:checked
+	required!="{required}"
+	disabled!="{disabled}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	class!="{classes}"
+)
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		checked = $bindable(false)
+		value
+		name
+		id: providedId
+		required = false
+		disabled = false
+		error: explicitError = false
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+
+	classes := cn 'switch', extra
+</script>

package/src/components/Textarea.n

@@ -0,0 +1,38 @@
+textarea(
+	id!="{resolvedId}"
+	name!="{name}"
+	bind:value
+	placeholder!="{placeholder}"
+	rows!="{rows}"
+	required!="{required}"
+	disabled!="{disabled}"
+	readonly!="{readonly}"
+	aria-invalid!="{hasError ? 'true' : undefined}"
+	aria-describedby!="{describedBy}"
+	class!="{classes}"
+)
+
+<script>
+	import { cn } from '@human-synthesis/norns-ui/cn'
+	import { getContext } from 'svelte'
+
+	{
+		value = $bindable('')
+		name
+		id: providedId
+		placeholder
+		rows = 4
+		required = false
+		disabled = false
+		readonly = false
+		error: explicitError = false
+		class: extra = ''
+	} .= $props()
+
+	field := getContext 'norns-ui:field'
+	resolvedId := providedId ?? field?.id
+	hasError := explicitError || field?.hasError || false
+	describedBy := resolvedId && hasError ? `${resolvedId}-error` : undefined
+
+	classes := cn 'textarea', hasError && 'textarea-err', extra
+</script>

package/src/index.js

@@ -7,7 +7,21 @@
  * code that auto-import doesn't process (e.g. dynamic mount).
  */
 
+// Phase 1
 export { default as Btn } from './components/Btn.n';
+
+// Phase 2 — forms tier
+export { default as Checkbox } from './components/Checkbox.n';
+export { default as Field } from './components/Field.n';
+export { default as FieldGroup } from './components/FieldGroup.n';
+export { default as Form } from './components/Form.n';
+export { default as Input } from './components/Input.n';
+export { default as Radio } from './components/Radio.n';
+export { default as Select } from './components/Select.n';
+export { default as Switch } from './components/Switch.n';
+export { default as Textarea } from './components/Textarea.n';
+
+// Helpers
 export { cn } from './lib/cn.js';
 export { variantClasses } from './lib/variants.js';
 export { presetUI } from './auto-import.js';

package/src/styles/atoms.css

@@ -59,4 +59,138 @@
 	.ui-spinner {
 		@apply inline-block size-4 animate-spin rounded-full border-2 border-current border-t-transparent;
 	}
+
+	/* --- Text inputs --- */
+	.input {
+		@apply block w-full rounded-md border border-neutral-300 bg-white text-sm text-neutral-900 shadow-sm;
+		@apply placeholder:text-neutral-400;
+		@apply transition-[border-color,box-shadow] duration-150 ease-out;
+		@apply focus:outline-none focus:border-primary-500 focus:ring-2 focus:ring-primary-500/30;
+		@apply disabled:cursor-not-allowed disabled:bg-neutral-50 disabled:opacity-70;
+		height: var(--ui-h-md);
+		padding-inline: 0.75rem;
+	}
+
+	.input-sm {
+		@apply text-xs;
+		height: var(--ui-h-sm);
+		padding-inline: 0.625rem;
+	}
+
+	.input-lg {
+		@apply text-base;
+		height: var(--ui-h-lg);
+		padding-inline: 0.875rem;
+	}
+
+	.input-err {
+		@apply border-red-500 focus:border-red-500 focus:ring-red-500/30;
+	}
+
+	/* Textarea overrides .input's height */
+	.textarea {
+		@apply block w-full rounded-md border border-neutral-300 bg-white px-3 py-2 text-sm text-neutral-900 shadow-sm;
+		@apply placeholder:text-neutral-400;
+		@apply transition-[border-color,box-shadow] duration-150 ease-out;
+		@apply focus:outline-none focus:border-primary-500 focus:ring-2 focus:ring-primary-500/30;
+		@apply disabled:cursor-not-allowed disabled:bg-neutral-50 disabled:opacity-70;
+		min-height: calc(var(--ui-h-md) * 2);
+	}
+
+	.textarea-err {
+		@apply border-red-500 focus:border-red-500 focus:ring-red-500/30;
+	}
+
+	.select {
+		@apply block w-full rounded-md border border-neutral-300 bg-white text-sm text-neutral-900 shadow-sm;
+		@apply transition-[border-color,box-shadow] duration-150 ease-out;
+		@apply focus:outline-none focus:border-primary-500 focus:ring-2 focus:ring-primary-500/30;
+		@apply disabled:cursor-not-allowed disabled:bg-neutral-50 disabled:opacity-70;
+		height: var(--ui-h-md);
+		padding-inline: 0.75rem;
+	}
+
+	.select-err {
+		@apply border-red-500 focus:border-red-500 focus:ring-red-500/30;
+	}
+
+	/* --- Checkbox / Radio --- */
+	.checkbox {
+		@apply size-4 cursor-pointer rounded border-neutral-300 text-primary-600 shadow-sm;
+		@apply focus:outline-none focus:ring-2 focus:ring-primary-500/30 focus:ring-offset-1;
+		@apply disabled:cursor-not-allowed disabled:opacity-60;
+	}
+
+	.checkbox-err {
+		@apply border-red-500 focus:ring-red-500/30;
+	}
+
+	.radio {
+		@apply size-4 cursor-pointer border-neutral-300 text-primary-600 shadow-sm;
+		@apply focus:outline-none focus:ring-2 focus:ring-primary-500/30 focus:ring-offset-1;
+		@apply disabled:cursor-not-allowed disabled:opacity-60;
+	}
+
+	.radio-err {
+		@apply border-red-500 focus:ring-red-500/30;
+	}
+
+	/* --- Switch (styled checkbox / toggle) ---
+	 * Implemented as a checkbox the user wraps in a label; we provide the
+	 * pill track via .switch and the moving knob via ::before.
+	 */
+	.switch {
+		@apply relative inline-flex h-5 w-9 shrink-0 cursor-pointer appearance-none rounded-full bg-neutral-200 shadow-inner;
+		@apply transition-colors duration-150 ease-out;
+		@apply checked:bg-primary-600;
+		@apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/30 focus-visible:ring-offset-1;
+		@apply disabled:cursor-not-allowed disabled:opacity-60;
+	}
+	.switch::before {
+		content: '';
+		@apply absolute left-0.5 top-0.5 size-4 rounded-full bg-white shadow;
+		@apply transition-transform duration-150 ease-out;
+	}
+	.switch:checked::before {
+		transform: translateX(1rem);
+	}
+
+	/* --- Field (label + control + help/error) --- */
+	.field {
+		@apply flex flex-col;
+	}
+
+	.field-label {
+		@apply mb-1 block text-sm font-medium text-neutral-700;
+	}
+
+	.field-required {
+		@apply ml-0.5 text-red-600;
+	}
+
+	.field-help {
+		@apply mt-1 text-xs text-neutral-500;
+	}
+
+	.field-error {
+		@apply mt-1 text-xs text-red-600;
+	}
+
+	.field-row {
+		@apply flex items-center gap-2;
+	}
+
+	/* Field-group: border-grouped collection of fields */
+	.field-group {
+		@apply space-y-3 rounded-md border border-neutral-200 p-4;
+	}
+
+	.field-group-legend {
+		@apply -mx-1 -mt-1 px-1 text-sm font-medium text-neutral-700;
+	}
+
+	/* --- Form (vertical stack of fields) --- */
+	.form {
+		@apply space-y-4;
+	}
 }

package/src/types/Checkbox.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from 'svelte';
+import type { HTMLInputAttributes } from 'svelte/elements';
+
+export type CheckboxProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'checked'> & {
+	checked?: boolean;
+	error?: boolean;
+	class?: string;
+};
+
+declare const Checkbox: Component<CheckboxProps>;
+export default Checkbox;

package/src/types/Field.d.ts

@@ -0,0 +1,21 @@
+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?: 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. */
+	error?: 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. */
+	id?: string;
+	/** Optional class merged into the field wrapper. */
+	class?: string;
+	/** Snippet that renders the actual control. Children should call `<Input />`, `<Textarea />`, etc. */
+	children?: Snippet;
+};
+
+declare const Field: Component<FieldProps>;
+export default Field;

package/src/types/FieldGroup.d.ts

@@ -0,0 +1,11 @@
+import type { Component, Snippet } from 'svelte';
+
+export type FieldGroupProps = {
+	/** Optional legend text rendered as the fieldset's `<legend>`. */
+	legend?: string;
+	class?: string;
+	children?: Snippet;
+};
+
+declare const FieldGroup: Component<FieldGroupProps>;
+export default FieldGroup;

package/src/types/Form.d.ts

@@ -0,0 +1,13 @@
+import type { Component, Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+
+export type FormProps = Omit<HTMLFormAttributes, 'class' | 'children'> & {
+	method?: 'GET' | 'POST';
+	action?: string;
+	enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+	class?: string;
+	children?: Snippet;
+};
+
+declare const Form: Component<FormProps>;
+export default Form;

package/src/types/Input.d.ts

@@ -0,0 +1,29 @@
+import type { Component } from 'svelte';
+import type { HTMLInputAttributes } from 'svelte/elements';
+
+export type InputSize = 'sm' | 'md' | 'lg';
+export type InputType =
+	| 'text'
+	| 'email'
+	| 'password'
+	| 'number'
+	| 'tel'
+	| 'url'
+	| 'search'
+	| 'date'
+	| 'time'
+	| 'datetime-local'
+	| 'month'
+	| 'week';
+
+export type InputProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'size' | 'value'> & {
+	value?: string | number;
+	type?: InputType;
+	size?: InputSize;
+	/** Force the error styling regardless of the parent Field's error state. */
+	error?: boolean;
+	class?: string;
+};
+
+declare const Input: Component<InputProps>;
+export default Input;

package/src/types/Radio.d.ts

@@ -0,0 +1,13 @@
+import type { Component } from 'svelte';
+import type { HTMLInputAttributes } from 'svelte/elements';
+
+export type RadioProps = Omit<HTMLInputAttributes, 'class' | 'type'> & {
+	/** Two-way bound shared group value — pass `bind:group={selected}` from parent. */
+	group?: string;
+	value?: string;
+	error?: boolean;
+	class?: string;
+};
+
+declare const Radio: Component<RadioProps>;
+export default Radio;

package/src/types/Select.d.ts

@@ -0,0 +1,13 @@
+import type { Component, Snippet } from 'svelte';
+import type { HTMLSelectAttributes } from 'svelte/elements';
+
+export type SelectProps = Omit<HTMLSelectAttributes, 'class' | 'value' | 'children'> & {
+	value?: string | number | string[];
+	error?: boolean;
+	class?: string;
+	/** `<option>` children. Pass via Pug body. */
+	children?: Snippet;
+};
+
+declare const Select: Component<SelectProps>;
+export default Select;

package/src/types/Switch.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from 'svelte';
+import type { HTMLInputAttributes } from 'svelte/elements';
+
+export type SwitchProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'checked' | 'role'> & {
+	checked?: boolean;
+	error?: boolean;
+	class?: string;
+};
+
+declare const Switch: Component<SwitchProps>;
+export default Switch;

package/src/types/Textarea.d.ts

@@ -0,0 +1,12 @@
+import type { Component } from 'svelte';
+import type { HTMLTextareaAttributes } from 'svelte/elements';
+
+export type TextareaProps = Omit<HTMLTextareaAttributes, 'class' | 'value' | 'rows'> & {
+	value?: string;
+	rows?: number;
+	error?: boolean;
+	class?: string;
+};
+
+declare const Textarea: Component<TextareaProps>;
+export default Textarea;