themelia-ui 2.0.1 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/timeline.css"
 
 ## Composition
 
-This family composes `base/display`, `base/typography`.
+This module composes `base/display`, `base/typography`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -39,6 +39,9 @@ StepperStrings
 
 Kind: callable.
 
+A numbered sequence the reader is partway through: a marker per step — a numeral that
+becomes a tick — connectors, and a label with an optional hint.
+
 ```text
 ({ steps, variant, onStepClick, strings, className, ...props }: StepperProps) => import("react").JSX.Element
 ```
@@ -51,10 +54,10 @@ Extends: `Omit<ComponentProps<"ol">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `steps` | yes | `StepperStep[]` |  |
-| `variant` | no | `StepperVariant` | Which drawing. Defaults to `bar`. |
+| `steps` | yes | `StepperStep[]` | The steps, in order. Rendered as an `<ol>`, because the order is the meaning. |
+| `variant` | no | `StepperVariant` | Which drawing. `bar`: labels under ringed markers in equal columns, with the connector<br>through the marker row. `trail`: labels beside filled markers and a rule taking the<br>rest of the row; below `lg` the labels are visually hidden and only the markers show. |
 | `onStepClick` | no | `(id: string, index: number) => void` | Makes each step a button: completed steps and the current one are reachable, upcoming<br>ones disabled. Without it the steps are plain list items. |
-| `strings` | no | `Partial<StepperStrings>` |  |
+| `strings` | no | `Partial<StepperStrings>` | Overrides this stepper's own copy: `position(index, total)` names what the numeral<br>counts, and `completed` and `current` are said with those steps. |
 
 ### `StepperStatus`
 
@@ -71,13 +74,15 @@ Where a step stands: a position, not an outcome (a failed step is a Timeline ent
 
 Kind: interface.
 
+One step of a `Stepper`.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `id` | yes | `string` | Stable identity for the step, handed back to `onStepClick`. |
-| `label` | yes | `ReactNode` |  |
+| `label` | yes | `ReactNode` | What the step is called. |
 | `hint` | no | `ReactNode` | A second, quieter line under the label. |
-| `status` | no | `StepperStatus` | Where the step stands. Defaults to `upcoming`. |
-| `accessibleName` | no | `string` | The step's whole accessible name, replacing its announced position, label, hint and<br>state. `aria-current` still marks the current step. |
+| `status` | no | `StepperStatus` | Where the step stands. `completed` is the canonical spelling; `complete` is accepted as<br>the same state and normalised, so the DOM only ever says `completed`. @default "upcoming" |
+| `accessibleName` | no | `string` | The step's whole accessible name, worded by the caller. It replaces the announced<br>position, label, hint and state rather than joining them; `aria-current` still marks<br>the current step. |
 
 ### `StepperStrings`
 
@@ -107,6 +112,8 @@ markers show.
 
 Kind: callable.
 
+An ordered run of events on one rail — changelogs, milestones, an order's progress.
+
 ```text
 ({ items, className, ...props }: TimelineProps) => import("react").JSX.Element
 ```
@@ -115,15 +122,17 @@ Kind: callable.
 
 Kind: interface.
 
+One entry of a `Timeline`. Everything an entry needs travels in the item.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `id` | yes | `string` | Stable identity for the row. |
-| `title` | yes | `ReactNode` |  |
+| `title` | yes | `ReactNode` | What happened. |
 | `description` | no | `ReactNode` | Supporting copy under the title. |
-| `timestamp` | no | `ReactNode` | Already formatted — the kit's date primitives decide the format, not this. |
-| `trailing` | no | `ReactNode` | The title row's trailing lane when it holds something other than a time; replaces `timestamp`. |
+| `timestamp` | no | `ReactNode` | Already formatted — the kit's date primitives decide the format, not this component. |
+| `trailing` | no | `ReactNode` | The title row's trailing lane when what belongs there is not a time — an amount, a<br>count. It replaces `timestamp` rather than joining it: there is one lane. |
 | `icon` | no | `LucideIcon` | Decorative glyph inside the dot. |
-| `status` | no | `TimelineStatus` |  |
+| `status` | no | `TimelineStatus` | Colours the dot, and the connector that runs from it to the next entry. `progress` and<br>`completed` are not the same thing: a step you walked past is a position, so it takes<br>the same primary tone as the step you are on and a sequence reads as one journey in one<br>colour; `completed` is an outcome, a milestone that landed. A bare `progress` dot is<br>hollow where `current` is solid, because on a rail with no glyphs the card still has to<br>say where the thing is. @default "neutral" |
 | `children` | no | `ReactNode` | Anything the entry carries below its description — a card, a diff, an action row. |
 
 ### `TimelineProps`
@@ -134,7 +143,7 @@ Extends: `Omit<ComponentProps<"ol">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `items` | yes | `TimelineItem[]` |  |
+| `items` | yes | `TimelineItem[]` | The entries, in the order they should be read. Rendered as an `<ol>`, because these<br>have an order and a screen reader should say so. |
 
 ### `TimelineStatus`
 
@@ -155,56 +164,160 @@ Preview route: Timeline — `/timeline`
 ### An order's progress
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Timeline
-  items={[
-    { id: "placed", title: "Order placed", timestamp: "14 Aug, 09:12", icon: CheckIcon, status: "completed" },
-    { id: "transit", title: "In transit", timestamp: "16 Aug, 06:02", icon: TruckIcon, status: "current" },
-    { id: "delivered", title: "Delivered", timestamp: "Expected 18 Aug", status: "pending" },
-  ]}
-/>
+import { CheckIcon, CreditCardIcon, PackageIcon, TruckIcon } from "lucide-react"
+
+import { Timeline, type TimelineItem } from "themelia-ui/base/timeline"
+
+const ORDER: TimelineItem[] = [
+	{
+		id: "placed",
+		title: "Order placed",
+		description: "Eight items, paid in full.",
+		timestamp: "14 Aug, 09:12",
+		icon: CheckIcon,
+		status: "completed",
+	},
+	{
+		id: "paid",
+		title: "Payment captured",
+		description: "Visa ending 4417.",
+		timestamp: "14 Aug, 09:12",
+		icon: CreditCardIcon,
+		status: "completed",
+	},
+	{
+		id: "packed",
+		title: "Packed",
+		timestamp: "15 Aug, 11:40",
+		icon: PackageIcon,
+		status: "completed",
+	},
+	{
+		id: "transit",
+		title: "In transit",
+		description: "Left the Rotterdam depot.",
+		timestamp: "16 Aug, 06:02",
+		icon: TruckIcon,
+		status: "current",
+	},
+	{
+		id: "delivered",
+		title: "Delivered",
+		timestamp: "Expected 18 Aug",
+		status: "pending",
+	},
+]
+
+export default function TimelineDefault() {
+	return (
+		<Timeline items={ORDER} />
+	)
+}
 ```
 
 ### Statuses
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Timeline items={[{ id: "1", title: "Packed", status: "completed" }]} />
+import { CircleDotIcon } from "lucide-react"
+
+import { Timeline, type TimelineItem } from "themelia-ui/base/timeline"
+
+const STATUSES: TimelineItem[] = [
+	{ id: "completed", title: "completed", description: "It happened, and it went as intended.", status: "completed" },
+	{ id: "current", title: "current", description: "Where the thing is right now.", icon: CircleDotIcon, status: "current" },
+	{ id: "warning", title: "warning", description: "It happened, but it needs a look.", status: "warning" },
+	{ id: "destructive", title: "destructive", description: "It failed. Never \"error\" — the kit has one word for this.", status: "destructive" },
+	{ id: "pending", title: "pending", description: "It has not happened yet, so the dot is unfilled.", status: "pending" },
+	{ id: "neutral", title: "neutral", description: "It happened and carries no judgement. The default.", status: "neutral" },
+]
+
+export default function TimelineStatuses() {
+	return (
+		<Timeline items={STATUSES} />
+	)
+}
 ```
 
 ### Entries that carry more than a line
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Timeline
-  items={[
-    {
-      id: "refund",
-      title: "Refund issued",
-      status: "warning",
-      children: <Badge tone="warning">Partial</Badge>,
-    },
-  ]}
-/>
+import { UndoIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Stack } from "themelia-ui/base/structure"
+import { Timeline, type TimelineItem } from "themelia-ui/base/timeline"
+
+const WITH_CONTENT: TimelineItem[] = [
+	{
+		id: "refund",
+		title: "Refund issued",
+		timestamp: "17 Aug, 14:20",
+		icon: UndoIcon,
+		status: "warning",
+		children: (
+			<Stack direction="horizontal" gap="sm">
+				<Badge tone="warning">Partial</Badge>
+				<Badge tone="neutral">€ 42.00</Badge>
+			</Stack>
+		),
+	},
+	{
+		id: "note",
+		title: "Note added",
+		timestamp: "17 Aug, 14:26",
+		status: "neutral",
+		// A sentence is a description; `children` is for blocks, and pays a block's gap.
+		description: "Customer reported one damaged item on arrival.",
+	},
+]
+
+export default function TimelineContent() {
+	return (
+		<Timeline items={WITH_CONTENT} />
+	)
+}
 ```
 
-### Props
+### Stepper
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Stepper
-  steps={[
-    { id: "account", label: "Account", hint: "Who you are", status: "completed" },
-    { id: "shipping", label: "Shipping", status: "current" },
-    { id: "review", label: "Review", status: "upcoming" },
-  ]}
-/>
-
-<Stepper variant="trail" steps={steps} />
+import { Stack } from "themelia-ui/base/structure"
+import { Stepper } from "themelia-ui/base/timeline"
+
+import { WIZARD } from "./data"
+
+export default function StepperDefault() {
+	return (
+		<Stack gap="2xl">
+			<Stepper steps={WIZARD} />
+			<Stepper variant="trail" steps={WIZARD} />
+		</Stack>
+	)
+}
 ```
 
 ### Going back a step
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Stepper
-  variant="trail"
-  steps={steps}
-  onStepClick={(id, index) => setCurrent(index)}
-/>
+import { useState } from "react"
+
+import { Stepper } from "themelia-ui/base/timeline"
+
+import { WIZARD } from "./data"
+
+/* The caller owns the position; a press on a finished step makes it current again. */
+function PressableTrail() {
+	const [current, setCurrent] = useState(2)
+	const steps = WIZARD.map((step, index) => ({
+		...step,
+		status: index < current ? ("completed" as const) : index === current ? ("current" as const) : ("upcoming" as const),
+	}))
+	return <Stepper variant="trail" steps={steps} onStepClick={(_, index) => setCurrent(index)} />
+}
+
+export default function StepperPressable() {
+	return (
+		<PressableTrail />
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/toaster.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,8 +31,11 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-A store with its own queue and timers, for a second, isolated Toaster (a host app and an
-embedded widget). Most apps use the default `toastStore`.
+An independent queue with its own timers and its own bound `toast()`, for a second,
+isolated Toaster — a host application and an embedded widget. With only the module-level
+queue, one for the whole realm, two Toasters on a page would render the same toasts, and
+`pauseAll` would walk a timer map neither owned. The singleton stays the default, because
+`toast("Saved")` working with no wiring is the point of it.
 
 ```text
 () => ToastStore
@@ -66,10 +69,12 @@ ToastFn
 
 Kind: interface.
 
+A button on a toast's pill.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `label` | yes | `string` |  |
-| `onClick` | yes | `() => void` |  |
+| `label` | yes | `string` | The button's text. |
+| `onClick` | yes | `() => void` | Runs on press, before the toast is dismissed. |
 
 ### `Toaster`
 
@@ -88,14 +93,14 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `position` | no | `ToastPosition` |  |
-| `duration` | no | `number` | Default lifetime in ms. A toast with its own `duration` still wins. |
-| `visibleToasts` | no | `number` | Maximum toasts on screen. Older ones are dropped from the render, not the store. |
-| `closeButton` | no | `boolean` |  |
+| `position` | no | `ToastPosition` | One of six: top or bottom, crossed with start, center, or end. Bottom stacks grow<br>upward so the newest is nearest the edge. `UIProvider` defaults can change it. @default "bottom-end" |
+| `duration` | no | `number` | Default lifetime in ms. A toast with its own `duration` still wins. `UIProvider`<br>defaults can change it. @default 4000 |
+| `visibleToasts` | no | `number` | Maximum toasts on screen — a cap on the render, not the store: older ones are dropped<br>from the render, and a capped toast still runs its timer and `onDismiss`. `UIProvider`<br>defaults can change it. @default 3 |
+| `closeButton` | no | `boolean` | Shows each toast's dismiss control. `UIProvider` defaults can change it. @default true |
 | `strings` | no | `Partial<ToasterStrings>` | Overrides this region's own copy — its name, and each toast's dismiss. |
 | `className` | no | `string` |  |
-| `store` | no | `ToastStore` | The queue this Toaster renders. Defaults to the singleton `toast()` writes to; pass a<br>`createToastStore()` instance for independent Toasters (a host app and an embedded widget). |
-| `container` | no | `UIPortalContainer` | Where the toast region renders. Defaults to the nearest `UIPortalHost`, else<br>`document.body`, so scoped density and theme apply. |
+| `store` | no | `ToastStore` | The queue this Toaster renders, dismisses and pauses. Defaults to the singleton<br>`toast()` writes to; pass a `createToastStore()` instance to isolate it — a host app and<br>an embedded widget. |
+| `container` | no | `UIPortalContainer` | Where the toast region renders. Defaults to the nearest `UIPortalHost`, else<br>`document.body` — so toasts raised inside a scoped region are drawn with that region's<br>density and theme. |
 
 ### `ToasterStrings`
 
@@ -110,14 +115,16 @@ Kind: interface.
 
 Kind: interface.
 
+What a toast carries beyond its title, passed as `toast(title, options)`.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `id` | no | `string` |  |
-| `description` | no | `ReactNode` |  |
+| `id` | no | `string` | Reusing an on-screen id updates that toast in place rather than stacking a second one. |
+| `description` | no | `ReactNode` | A second line under the title. |
 | `icon` | no | `ReactNode` | Replaces the status glyph. |
-| `duration` | no | `number` | Milliseconds before auto-dismissal. `Infinity` pins it open. |
-| `action` | no | `ToastAction` |  |
-| `cancel` | no | `ToastAction` |  |
+| `duration` | no | `number` | Lifetime in milliseconds before auto-dismissal. `Infinity` pins it open. Falls back to<br>the Toaster's `duration`. |
+| `action` | no | `ToastAction` | A button on the pill — the undo for something that already happened. It dismisses the<br>toast after running. |
+| `cancel` | no | `ToastAction` | A second, quieter button on the pill. Dismisses the toast after running. |
 | `onDismiss` | no | `(id: string) => void` | Called after the toast leaves, whichever way it left. |
 
 ### `ToastPosition`
@@ -175,26 +182,123 @@ Preview route: Toast — `/toast`
 ### Statuses
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-toast.success("Invoice sent")
-toast.error("Could not reach the server")
-toast.loading("Uploading…", { id: "upload" })
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { toast } from "themelia-ui/base/toaster"
+
+export default function ToastStatuses() {
+	return (
+		<Stack direction="horizontal" gap="sm" wrap>
+			<Button buttonStyle="outline" tone="neutral" onClick={() => toast("Draft saved")}>
+				Neutral
+			</Button>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() => toast.success("Invoice sent", { description: "Northwind Traders · $1,299.50" })}
+			>
+				Success
+			</Button>
+			<Button buttonStyle="outline" tone="neutral" onClick={() => toast.info("Two seats left on this plan")}>
+				Info
+			</Button>
+			<Button buttonStyle="outline" tone="neutral" onClick={() => toast.warning("Your card expires next month")}>
+				Warning
+			</Button>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() => toast.error("Could not reach the server", { description: "Retrying in 30 seconds." })}
+			>
+				Error
+			</Button>
+		</Stack>
+	)
+}
 ```
 
 ### Actions
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-toast("Invoice deleted", {
-  action: { label: "Undo", onClick: restore },
-  duration: 8000,
-})
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { toast } from "themelia-ui/base/toaster"
+
+export default function ToastActions() {
+	return (
+		<Stack direction="horizontal" gap="sm" wrap>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() =>
+					toast("Invoice deleted", {
+						description: "INV-4420 · Initech",
+						duration: 8000,
+						action: { label: "Undo", onClick: () => toast.success("Invoice restored") },
+					})
+				}
+			>
+				With undo
+			</Button>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() =>
+					toast.warning("Discard unsaved changes?", {
+						duration: Number.POSITIVE_INFINITY,
+						action: { label: "Discard", onClick: () => toast("Changes discarded") },
+						cancel: { label: "Keep", onClick: () => {} },
+					})
+				}
+			>
+				Pinned, two actions
+			</Button>
+		</Stack>
+	)
+}
 ```
 
 ### Promise
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-toast.promise(saveInvoice(), {
-  loading: "Saving…",
-  success: (invoice) => `Saved ${invoice.id}`,
-  error: "Could not save",
-})
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { toast } from "themelia-ui/base/toaster"
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export default function ToastPromise() {
+	return (
+		<Stack direction="horizontal" gap="sm" wrap>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() =>
+					void toast.promise(wait(1800), {
+						loading: "Saving invoice…",
+						success: "Invoice saved",
+						error: "Could not save",
+					})
+				}
+			>
+				Resolves
+			</Button>
+			<Button
+				buttonStyle="outline"
+				tone="neutral"
+				onClick={() =>
+					void toast
+						.promise(wait(1800).then(() => Promise.reject(new Error("timeout"))), {
+							loading: "Saving invoice…",
+							success: "Invoice saved",
+							error: (error) => `Could not save: ${(error as Error).message}`,
+						})
+						.catch(() => {})
+				}
+			>
+				Rejects
+			</Button>
+		</Stack>
+	)
+}
 ```

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

@@ -20,7 +20,7 @@ import "themelia-ui/base/toggle.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,11 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
+A control that stays engaged, reported with `aria-pressed`: `pressed` and
+`defaultPressed` hold its state, controlled and uncontrolled, and `onPressedChange` fires
+with the next one. Inside a `ToggleGroup`, `value` names the toggle, and the group reads it
+into its own value; outside a group it is unused.
+
 ```text
 ({ variant, className, ...props }: ToggleProps) => import("react").JSX.Element
 ```
@@ -39,8 +44,10 @@ Kind: callable.
 
 Kind: callable.
 
-A set of `Toggle`s (each given a `value`) sharing one value. `multiple` makes it a
-checkbox set rather than one-at-a-time.
+A set of `Toggle`s (each given a `value`) sharing one value. `multiple` allows several at
+once rather than one: a view switch is one, text styles are several. The value is always
+an array, even when only one may be pressed, so switching `multiple` does not change its
+shape.
 
 ```text
 ({ attached, className, ...props }: ToggleGroupProps) => import("react").JSX.Element
@@ -50,21 +57,21 @@ checkbox set rather than one-at-a-time.
 
 Kind: interface.
 
-Extends: `ToggleGroupPrimitive.Props`.
+Extends: `ToggleGroupPrimitive.Props`, `Pick<ToggleGroupPrimitive.Props, "multiple" | "value" | "onValueChange">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `attached` | no | `boolean` | Joins the toggles into one framed control. Defaults to true. |
+| `attached` | no | `boolean` | Joins the toggles into one framed control with internal rules. Off leaves them as<br>separate buttons in a row. |
 
 ### `ToggleProps`
 
 Kind: interface.
 
-Extends: `TogglePrimitive.Props`.
+Extends: `TogglePrimitive.Props`, `Pick<TogglePrimitive.Props, "pressed" | "defaultPressed" | "onPressedChange" | "value">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `variant` | no | `"ghost" \| "outline"` | Sunk when engaged, or outlined. Match whatever sits beside it in the row. |
+| `variant` | no | `"ghost" \| "outline"` | Sunk when engaged, or outlined. Match whatever sits beside it in the row — `outline`<br>for a lone control, `ghost` inside a group. |
 
 ## Preview recipes
 
@@ -73,19 +80,80 @@ Preview route: Toggle — `/toggle`
 ### Toggle
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
-  <BoldIcon />
-</Toggle>
+import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"
+import { useState } from "react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { Toggle } from "themelia-ui/base/toggle"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ToggleExample() {
+	const [bold, setBold] = useState(false)
+
+	return (
+		<Stack direction="horizontal" gap="lg" align="center">
+			<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
+				<BoldIcon />
+			</Toggle>
+			<Toggle variant="outline" aria-label="Italic">
+				<ItalicIcon />
+			</Toggle>
+			<Toggle disabled aria-label="Underline">
+				<UnderlineIcon />
+			</Toggle>
+			<Text size="sm" type="secondary">
+				{bold ? "pressed" : "not pressed"}
+			</Text>
+		</Stack>
+	)
+}
 ```
 
 ### ToggleGroup
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-{/* several at once */}
-<ToggleGroup multiple value={marks} onValueChange={setMarks}>
-  <Toggle value="bold"><BoldIcon /></Toggle>
-</ToggleGroup>
-
-{/* one at a time */}
-<ToggleGroup value={[align]} onValueChange={([next]) => setAlign(next)}>
+import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon, BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"
+import { useState } from "react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { Toggle, ToggleGroup } from "themelia-ui/base/toggle"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ToggleGroupExample() {
+	const [marks, setMarks] = useState<string[]>(["bold"])
+	const [align, setAlign] = useState("left")
+
+	return (
+		<Stack gap="xl">
+			<Stack gap="xs" align="start">
+				<Text size="xs" type="secondary">multiple — several at once</Text>
+				<ToggleGroup multiple value={marks} onValueChange={setMarks}>
+					<Toggle value="bold" aria-label="Bold"><BoldIcon /></Toggle>
+					<Toggle value="italic" aria-label="Italic"><ItalicIcon /></Toggle>
+					<Toggle value="underline" aria-label="Underline"><UnderlineIcon /></Toggle>
+				</ToggleGroup>
+			</Stack>
+
+			<Stack gap="xs" align="start">
+				<Text size="xs" type="secondary">one at a time</Text>
+				<ToggleGroup
+					value={[align]}
+					onValueChange={(next) => setAlign(next[0] ?? align)}
+				>
+					<Toggle value="left" aria-label="Align left"><AlignLeftIcon /></Toggle>
+					<Toggle value="center" aria-label="Align centre"><AlignCenterIcon /></Toggle>
+					<Toggle value="right" aria-label="Align right"><AlignRightIcon /></Toggle>
+				</ToggleGroup>
+			</Stack>
+
+			<Stack gap="xs" align="start">
+				<Text size="xs" type="secondary">attached={"{false}"} — separate buttons</Text>
+				<ToggleGroup attached={false} multiple>
+					<Toggle value="a" variant="outline">Day</Toggle>
+					<Toggle value="b" variant="outline">Week</Toggle>
+				</ToggleGroup>
+			</Stack>
+		</Stack>
+	)
+}
 ```