themelia-ui 2.0.0 → 3.0.0

package/docs/generated/components/base--repeaters.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/repeaters.css"
 
 ## Composition
 
-This family composes `base/buttons`, `base/choice-inputs`, `base/display`, `base/forms`, `base/structure`, `base/text-inputs`.
+This module composes `base/buttons`, `base/choice-inputs`, `base/display`, `base/forms`, `base/structure`, `base/text-inputs`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -55,6 +55,9 @@ RepeaterStrings
 
 Kind: callable.
 
+Key/value pairs rather than an object, so a half-typed or blank key keeps its row and its
+value. Convert to an object on submit.
+
 ```text
 ({ value, onValueChange, strings, emptyState, maxItems, sortable, disabled, invalid, flagDuplicateKeys, className, }: KeyValueEditorProps) => import("react").JSX.Element
 ```
@@ -70,10 +73,10 @@ Kind: interface.
 | `strings` | no | `Partial<KeyValueEditorStrings>` | Overrides this editor's own copy — the two placeholders, add, and remove. |
 | `emptyState` | no | `React.ReactNode` |  |
 | `maxItems` | no | `number` |  |
-| `sortable` | no | `boolean` |  |
+| `sortable` | no | `boolean` | Adds the drag handle and arrow-key reordering. |
 | `disabled` | no | `boolean` |  |
 | `invalid` | no | `boolean` |  |
-| `flagDuplicateKeys` | no | `boolean` | Flags a key that is already used elsewhere in the list. |
+| `flagDuplicateKeys` | no | `boolean` | Flags a key that is already used elsewhere in the list. A blank key is not a<br>duplicate — it is an unfinished row. |
 | `className` | no | `string` |  |
 
 ### `KeyValueEditorStrings`
@@ -111,7 +114,9 @@ Kind: interface.
 
 Kind: callable.
 
-Several fields per locale — a title and a body, say — behind one switcher.
+Several fields per locale — a title and a body, say — behind one switcher, with the
+active locale switchable in place. A translation UI built out of plain repeaters loses
+which language a row belongs to the moment rows reorder.
 
 ```text
 ({ locales, fields, value, onValueChange, disabled, invalid, className, }: LocalizedObjectFieldProps) => import("react").JSX.Element
@@ -156,6 +161,10 @@ Record<string, Record<string, string>>
 
 Kind: callable.
 
+One value per locale behind a single field with a locale switcher, so a translated field
+costs one row instead of one row per language. The active locale is view state, not part
+of the value.
+
 ```text
 ({ locales, value, onValueChange, multiline, placeholder, disabled, invalid, requiredLocales, className, "aria-label": ariaLabel, "aria-labelledby": labelledBy, "aria-describedby": describedBy, "aria-invalid": ariaInvalid, }: LocalizedStringFieldProps) => import("react").JSX.Element
 ```
@@ -166,7 +175,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `locales` | yes | `(string \| LocaleDescriptor)[]` |  |
+| `locales` | yes | `(string \| LocaleDescriptor)[]` | Which locales the switcher offers, in order. The first is the default. |
 | `value` | no | `LocalizedValue` |  |
 | `onValueChange` | no | `(value: LocalizedValue) => void` |  |
 | `multiline` | no | `boolean` | A textarea per locale rather than an input. |
@@ -184,6 +193,10 @@ Kind: interface.
 
 Kind: callable.
 
+An ordered list of localized strings, each row a `LocalizedStringField`: one value per
+language, with the active locale switchable in place. A translation UI built out of plain
+repeaters loses which language a row belongs to the moment rows reorder.
+
 ```text
 ({ locales, value, onValueChange, placeholder, strings, emptyState, maxItems, sortable, multiline, requiredLocales, disabled, invalid, className, "aria-label": ariaLabel, }: LocalizedStringRepeaterProps) => import("react").JSX.Element
 ```
@@ -201,7 +214,7 @@ Kind: interface.
 | `strings` | no | `Partial<RepeaterStrings>` | Overrides this list's own copy — the add control and each row's remove. |
 | `emptyState` | no | `React.ReactNode` |  |
 | `maxItems` | no | `number` |  |
-| `sortable` | no | `boolean` |  |
+| `sortable` | no | `boolean` | Adds the drag handle and arrow-key reordering. |
 | `multiline` | no | `boolean` |  |
 | `requiredLocales` | no | `string[]` |  |
 | `disabled` | no | `boolean` |  |
@@ -237,6 +250,10 @@ Kind: interface.
 
 Kind: callable.
 
+A repeating row of several fields, described once as data rather than assembled per row
+— contacts, line items, addresses. It reads and writes the array it is given and imports
+no form library, so any can drive it.
+
 ```text
 ({ value, onValueChange, fields, name, emptyState, maxItems, sortable, disabled, invalid, renderField, strings, className, }: ObjectRepeaterProps) => import("react").JSX.Element
 ```
@@ -260,16 +277,16 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `value` | yes | `ObjectRow[]` |  |
+| `value` | yes | `ObjectRow[]` | The rows, one object per row, keyed by field name. |
 | `onValueChange` | yes | `(value: ObjectRow[]) => void` |  |
-| `fields` | yes | `ObjectFieldDef[]` |  |
+| `fields` | yes | `ObjectFieldDef[]` | The fields every row carries, described once as data rather than assembled per row. |
 | `name` | no | `string` | Prefixes the generated field paths (`items.2.email`) to match a form library. Naming only. |
 | `emptyState` | no | `ReactNode` |  |
 | `maxItems` | no | `number` |  |
-| `sortable` | no | `boolean` |  |
+| `sortable` | no | `boolean` | Adds the drag handle and arrow-key reordering. |
 | `disabled` | no | `boolean` |  |
 | `invalid` | no | `boolean` |  |
-| `renderField` | no | `(field: ObjectFieldDef, context: ObjectRepeaterFieldContext) => ReactNode` | Replaces one field's control, keeping the row and array behaviour. |
+| `renderField` | no | `(field: ObjectFieldDef, context: ObjectRepeaterFieldContext) => ReactNode` | Replaces one field's control, keeping the row and array behaviour — how a caller<br>connects individual fields to a form library. |
 | `strings` | no | `Partial<ObjectRepeaterStrings>` |  |
 | `className` | no | `string` |  |
 
@@ -295,6 +312,10 @@ Record<string, string>
 
 Kind: callable.
 
+The chrome every list-style field shares: rows with an optional drag handle and remove
+control, an empty state, and an add button. It never owns the array — you pass `items`
+and the handlers, which keeps it usable with a form library or with plain state.
+
 ```text
 ({ items, getKey, children, onAdd, onRemove, onMove, rowVariant, strings, emptyState, showAdd, maxItems, disabled, className, }: RepeaterProps<T>) => import("react").JSX.Element
 ```
@@ -305,16 +326,16 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `items` | yes | `T[]` |  |
-| `getKey` | yes | `(item: T, index: number) => string` | Stable key for a row. An index is a poor key while rows reorder. |
-| `children` | yes | `(item: T, context: RepeaterRowContext) => ReactNode` |  |
-| `onAdd` | no | `() => void` |  |
-| `onRemove` | no | `(index: number) => void` |  |
-| `onMove` | no | `(from: number, to: number) => void` | Enables reordering. Without it, no handle is rendered. |
+| `items` | yes | `T[]` | The rows. The repeater renders what it is given and nothing else. |
+| `getKey` | yes | `(item: T, index: number) => string` | Stable identity per row. An index alone would re-key every row after a reorder and<br>lose focus. |
+| `children` | yes | `(item: T, context: RepeaterRowContext) => ReactNode` | Renders one row. `context` carries the row's `index` and whether it is `dragging`. |
+| `onAdd` | no | `() => void` | Supplying it renders the add button. |
+| `onRemove` | no | `(index: number) => void` | Supplying it renders each row's remove button. |
+| `onMove` | no | `(from: number, to: number) => void` | Supplying it enables reordering and renders the drag handle; without it, no handle is<br>rendered. The handle is the drag source, not the row. |
 | `rowVariant` | no | `"inline" \| "card"` | `card` wraps each row in a bordered surface, for multi-field rows. |
-| `strings` | no | `Partial<RepeaterStrings>` | Overrides this list's own copy — the add control and each row's remove. |
-| `emptyState` | no | `ReactNode` |  |
-| `showAdd` | no | `boolean` | Hides the add button, for a list with a fixed set of rows. |
+| `strings` | no | `Partial<RepeaterStrings>` | Overrides this list's own copy — the add control and each row's remove. `remove` is a<br>function of the row index: every remove button in a list saying the same thing is a<br>column of controls a screen reader cannot tell apart. |
+| `emptyState` | no | `ReactNode` | Shown in place of the rows when `items` is empty. Replaces `strings.emptyState`. |
+| `showAdd` | no | `boolean` | Hides the add button while keeping the rows — for a list at its cap, a fixed set of<br>rows, or one whose entries come from elsewhere. |
 | `maxItems` | no | `number` | Caps the list. The add button disables at the limit. |
 | `disabled` | no | `boolean` |  |
 | `className` | no | `string` |  |
@@ -344,6 +365,8 @@ Kind: interface.
 
 Kind: callable.
 
+An ordered list of plain strings — alternate names, allowed domains, recipients.
+
 ```text
 ({ value, onValueChange, placeholder, strings, emptyState, maxItems, sortable, disabled, invalid, className, "aria-label": ariaLabel, }: StringRepeaterProps) => import("react").JSX.Element
 ```
@@ -360,7 +383,7 @@ Kind: interface.
 | `strings` | no | `Partial<RepeaterStrings>` | Overrides this list's own copy — the add control and each row's remove. |
 | `emptyState` | no | `React.ReactNode` |  |
 | `maxItems` | no | `number` |  |
-| `sortable` | no | `boolean` |  |
+| `sortable` | no | `boolean` | Adds the drag handle and arrow-key reordering. |
 | `disabled` | no | `boolean` |  |
 | `invalid` | no | `boolean` |  |
 | `className` | no | `string` |  |
@@ -373,41 +396,164 @@ Preview route: Repeater — `/repeater`
 ### Repeater
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Repeater
-  items={contacts}
-  getKey={(contact) => contact.id}
-  onAdd={() => setContacts([...contacts, blank()])}
-  onRemove={(index) => setContacts(contacts.filter((_, i) => i !== index))}
-  onMove={move}
-  rowVariant="card"
->
-  {(contact, { index }) => (
-    <Stack direction="horizontal" gap="md">
-      <Input value={contact.name} onChange={…} aria-label="Name" />
-      <Input value={contact.email} onChange={…} aria-label="Email" />
-    </Stack>
-  )}
-</Repeater>
+import { useState } from "react"
+
+import { Input } from "themelia-ui/base/text-inputs"
+import { FormField } from "themelia-ui/base/forms"
+import { Repeater } from "themelia-ui/base/repeaters"
+import { Stack } from "themelia-ui/base/structure"
+
+
+type Contact = { id: string; name: string; email: string }
+
+export default function RepeaterExample() {
+	const [contacts, setContacts] = useState<Contact[]>([
+		{ id: "a", name: "Jamie Moreau", email: "jamie@acme.com" },
+		{ id: "b", name: "Rin Fujita", email: "rin@acme.com" },
+	])
+
+	const move = (from: number, to: number) =>
+		setContacts((current) => {
+			if (to < 0 || to >= current.length) return current
+			const next = [...current]
+			next.splice(to, 0, ...next.splice(from, 1))
+			return next
+		})
+
+	return (
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
+			<FormField htmlFor={false} label="Contacts" helperText="Drag a handle, or focus it and press ↑ / ↓.">
+				<Repeater
+					items={contacts}
+					getKey={(contact) => contact.id}
+					rowVariant="card"
+					strings={{ add: "Add contact" }}
+					onAdd={() =>
+						setContacts((current) => [
+							...current,
+							{ id: String(current.length + 1), name: "", email: "" },
+						])
+					}
+					onRemove={(index) => setContacts((current) => current.filter((_, i) => i !== index))}
+					onMove={move}
+				>
+					{(contact, { index }) => (
+						<Stack direction="horizontal" gap="md" style={{ width: "100%" }}>
+							<Input
+								value={contact.name}
+								aria-label="Name"
+								placeholder="Name"
+								onChange={(event) =>
+									setContacts((current) =>
+										current.map((row, i) =>
+											i === index ? { ...row, name: event.target.value } : row,
+										),
+									)
+								}
+							/>
+							<Input
+								value={contact.email}
+								aria-label="Email"
+								placeholder="name@example.com"
+								onChange={(event) =>
+									setContacts((current) =>
+										current.map((row, i) =>
+											i === index ? { ...row, email: event.target.value } : row,
+										),
+									)
+								}
+							/>
+						</Stack>
+					)}
+				</Repeater>
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### StringRepeater
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<StringRepeater value={domains} onValueChange={setDomains} sortable />
+import { useState } from "react"
+
+import { FormField } from "themelia-ui/base/forms"
+import { StringRepeater } from "themelia-ui/base/repeaters"
+import { Stack } from "themelia-ui/base/structure"
+
+
+export default function StringRepeaterExample() {
+	const [domains, setDomains] = useState(["acme.com", "acme.dev"])
+
+	return (
+		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField htmlFor={false} label="Allowed domains" helperText="Drag the handle, or focus it and press ↑ / ↓.">
+				<StringRepeater
+					value={domains}
+					onValueChange={setDomains}
+					placeholder="example.com"
+					sortable
+					aria-label="Domain"
+				/>
+			</FormField>
+			<FormField htmlFor={false} label="Empty" helperText="With a cap of three.">
+				<StringRepeater value={[]} onValueChange={() => {}} maxItems={3} />
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### KeyValueEditor
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<KeyValueEditor value={headers} onValueChange={setHeaders} sortable />
+import { useState } from "react"
+
+import { FormField } from "themelia-ui/base/forms"
+import { KeyValueEditor, type KeyValuePair } from "themelia-ui/base/repeaters"
+import { Stack } from "themelia-ui/base/structure"
+
+
+export default function KeyValue() {
+	const [headers, setHeaders] = useState<KeyValuePair[]>([
+		{ key: "X-Api-Version", value: "2026-01" },
+		{ key: "X-Trace", value: "on" },
+	])
+
+	return (
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
+			<FormField htmlFor={false} label="Request headers" helperText="Try entering the same key twice.">
+				<KeyValueEditor value={headers} onValueChange={setHeaders} sortable />
+			</FormField>
+		</Stack>
+	)
+}
 ```
 
 ### LocalizedStringField
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<LocalizedStringField
-  locales={[{ value: "en", label: "English" }, { value: "nl", label: "Nederlands" }]}
-  value={name}
-  onValueChange={setName}
-/>
+import { useState } from "react"
+
+import { FormField } from "themelia-ui/base/forms"
+import { LocalizedStringField, type LocalizedValue } from "themelia-ui/base/repeaters"
+import { Stack } from "themelia-ui/base/structure"
+
+
+const LOCALES = [
+	{ value: "en", label: "English" },
+	{ value: "nl", label: "Nederlands" },
+]
+
+export default function Localized() {
+	const [name, setName] = useState<LocalizedValue>({ en: "Invoice", nl: "Factuur" })
+
+	return (
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+			<FormField htmlFor={false} label="Display name" helperText="Switch locale — the value follows.">
+				<LocalizedStringField locales={LOCALES} value={name} onValueChange={setName} />
+			</FormField>
+		</Stack>
+	)
+}
 ```

package/docs/generated/components/base--resizable.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/resizable.css"
 
 ## Composition
 
-This family has no component-family dependencies.
+This module depends on no other module.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -31,6 +31,9 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+The grip between two panels: a real `role="separator"`. It is focusable and takes arrow
+keys, so the split is adjustable without a pointer.
+
 ```text
 ({ withHandle, className, ...props }: ResizableHandleProps) => import("react").JSX.Element
 ```
@@ -43,12 +46,14 @@ Extends: `ResizablePrimitive.SeparatorProps`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `withHandle` | no | `boolean` | Draws a grip on the line, for a split with no other cue that it moves. Defaults to false. |
+| `withHandle` | no | `boolean` | Draws a grip on the line, for a split with no other cue that it moves. The hit area is<br>wider than the 1px rule either way. |
 
 ### `ResizablePanel`
 
 Kind: callable.
 
+A panel inside a `ResizablePanelGroup`.
+
 ```text
 ({ className, ...props }: ResizablePanelProps) => import("react").JSX.Element
 ```
@@ -57,6 +62,10 @@ Kind: callable.
 
 Kind: callable.
 
+The split. `orientation` is its axis. Own the persistence: keep the layout in your state
+with `onLayoutChanged` and hand it back through `defaultLayout`, so a reader who widened a
+panel finds it wide next time.
+
 ```text
 ({ className, ...props }: ResizablePanelGroupProps) => import("react").JSX.Element
 ```
@@ -65,7 +74,7 @@ Kind: callable.
 
 Kind: interface.
 
-Extends: `ResizablePrimitive.GroupProps`.
+Extends: `ResizablePrimitive.GroupProps`, `Pick<ResizablePrimitive.GroupProps, "orientation">`.
 
 No own members are present in the normalized public snapshot.
 
@@ -84,9 +93,34 @@ Preview route: Resizable panels — `/resizable`
 ### Resizable
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ResizablePanelGroup orientation="horizontal" defaultLayout={savedLayout} onLayoutChanged={saveLayout}>
-  <ResizablePanel defaultSize="65%">…</ResizablePanel>
-  <ResizableHandle withHandle />
-  <ResizablePanel defaultSize="35%">…</ResizablePanel>
-</ResizablePanelGroup>
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "themelia-ui/base/resizable"
+import { Text } from "themelia-ui/base/typography"
+
+const FRAME: React.CSSProperties = {
+	width: "100%",
+	height: "12rem",
+	border: "1px solid var(--border)",
+	borderRadius: "var(--radius)",
+	overflow: "hidden",
+}
+
+export default function Resizable() {
+	return (
+		<div style={FRAME}>
+			<ResizablePanelGroup orientation="horizontal">
+				<ResizablePanel defaultSize="65%">
+					<div style={{ padding: "var(--space-lg)" }}>
+						<Text size="sm" type="secondary">The document</Text>
+					</div>
+				</ResizablePanel>
+				<ResizableHandle withHandle />
+				<ResizablePanel defaultSize="35%">
+					<div style={{ padding: "var(--space-lg)" }}>
+						<Text size="sm" type="secondary">The inspector</Text>
+					</div>
+				</ResizablePanel>
+			</ResizablePanelGroup>
+		</div>
+	)
+}
 ```