themelia-ui 2.0.0 → 3.0.0

package/docs/generated/components/features--theme-tweaker.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/theme-tweaker.css"
 
 ## Composition
 
-This family composes `base/accordion`, `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/item`, `base/navigation`, `base/overlay`, `base/structure`, `base/text-inputs`, `base/typography`, `base/value-inputs`, `features/overlays`.
+This module composes `base/accordion`, `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/item`, `base/navigation`, `base/overlay`, `base/structure`, `base/text-inputs`, `base/typography`, `base/value-inputs`, `features/overlays`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -119,7 +119,8 @@ UIConfigSettingsStrings
 
 Kind: callable.
 
-The whole shadow ladder from one intensity.
+The whole shadow ladder from one intensity: the default theme's geometry and
+`--shadow-ink`, with every layer's ink scaled so 0.8 reproduces it exactly.
 
 ```text
 ({ intensity }: ThemeElevationRecipe) => ThemeOverrides
@@ -221,7 +222,7 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `intensity` | yes | `number` | 0 is flat, 1 is pronounced. |
+| `intensity` | yes | `number` | 0 is flat, 1 is pronounced; 0.8 reproduces the default theme. |
 
 ### `ThemeExportArtifact`
 
@@ -393,9 +394,9 @@ Extends: `Omit<HTMLAttributes<HTMLDivElement>, "children" | "defaultValue" | "on
 | `onModeChange` | no | `(mode: ThemeMode) => void` |  |
 | `fields` | no | `readonly ThemeTweakerField[]` | The catalog of editable variables. Defaults to the kit's whole public surface. |
 | `target` | no | `ThemeTweakerTarget` | `self` themes only the editor and its preview; `document` themes the whole app while<br>mounted, so portaled menus and dialogs inherit the edit too. |
-| `apply` | no | `boolean` |  |
+| `apply` | no | `boolean` | Writes the edited theme onto the target. Set `false` when the application owns theme<br>application, as with useAppliedTheme at its root. |
 | `manageModeClass` | no | `boolean` | Manages `.light` / `.dark` on a non-self target. Off when a theme manager owns it. |
-| `preview` | no | `ReactNode \| false` | `false` hides it; a node replaces the built-in one. |
+| `preview` | no | `ReactNode \| false` | The sample the edit is shown on. `false` hides it, so the editor edits the actual app<br>without a sample preview; a node replaces the built-in one. |
 | `fileName` | no | `string` |  |
 | `config` | no | `UIConfig` |  |
 | `defaultConfig` | no | `UIConfig` |  |
@@ -532,6 +533,10 @@ Kind: type.
 
 Kind: callable.
 
+The provider settings editor — the non-CSS half of a theme, which ThemeTweaker includes under
+Provider. Connect its controlled `config` to your root UIProvider to update mounted
+consumers.
+
 ```text
 ({ config, onChange, strings, className, }: UIConfigSettingsProps) => import("react").JSX.Element
 ```
@@ -569,6 +574,10 @@ Kind: interface.
 
 Kind: callable.
 
+Writes an edited theme onto a live element and removes it on cleanup. Keep it mounted with
+`target: "document"` and `apply: true` to apply document-wide values; set
+`manageModeClass: false` when UIProvider owns the colour scheme.
+
 ```text
 ({ apply, manageModeClass, selfRef, target, theme, }: UseAppliedThemeOptions) => void
 ```
@@ -580,7 +589,33 @@ Preview route: Theme tweaker — `/theme-tweaker`
 ### Isolated theme scopes
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ThemeScope theme={createTheme({ shared: { "--radius": "0.875rem" } })}>
-  <Button>Scoped radius</Button>
-</ThemeScope>
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Grid } from "themelia-ui/base/structure"
+import { ThemeScope, createTheme } from "themelia-ui/features/theme-tweaker"
+
+/*
+ * Both radii: a container reads --radius and the controls inside it read --radius-sm, so a
+ * scope that set only one would leave half the corners as they were.
+ */
+const SQUARE_CORNERS = createTheme({ shared: { "--radius": "0.25rem", "--radius-sm": "0.125rem" } })
+
+export default function IsolatedThemeScope() {
+	return (
+		<Grid gap="lg">
+			<Card
+				title="App theme"
+				description="The corners every other region uses."
+				footerSlot={<Button>Unscoped</Button>}
+			/>
+			<ThemeScope theme={SQUARE_CORNERS}>
+				<Card
+					title="Scoped theme"
+					description="Squarer corners, in this region only."
+					footerSlot={<Button>Scoped radius</Button>}
+				/>
+			</ThemeScope>
+		</Grid>
+	)
+}
 ```

package/docs/generated/components/forms-rhf.md

@@ -19,7 +19,7 @@ import { rhfFormControl } from "themelia-ui/forms-rhf"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install react-hook-form
@@ -27,7 +27,7 @@ npm install react-hook-form
 
 ## 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.
@@ -38,8 +38,9 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-Wraps an RHF `control` in the kit's headless contract. `useField` delegates to
-`useController`, so registration, validation and dirty tracking keep working.
+Wraps a react-hook-form `control` in the kit's headless contract. `useField` delegates to
+`useController`, so registration, validation and dirty tracking keep working. Imported
+from `themelia-ui/forms-rhf`, never from `themelia-ui/forms`, which stays dependency-free.
 
 ```text
 (control: Control<TValues>) => FormControl<TValues>
@@ -47,5 +48,5 @@ Wraps an RHF `control` in the kit's headless contract. `useField` delegates to
 
 ## Preview recipes
 
-No dedicated recipe is currently attributed to this family. Use the public declarations
+No dedicated recipe is currently attributed to this module. Use the public declarations
 above and the composition guide; this absence is explicit and verification-visible.

package/docs/generated/components/forms.md

@@ -19,7 +19,7 @@ import { useFormFieldBinding } from "themelia-ui/forms"
 
 ## 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.
@@ -30,7 +30,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: interface.
 
-What a bound field hands to a control.
+What a bound field hands to a control: what `useFormFieldBinding` returns, spreadable onto
+the control.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -46,7 +47,8 @@ What a bound field hands to a control.
 
 Kind: interface.
 
-One field's state, as an adapter reports it.
+One field's state, as an adapter reports it. Everything past `value` and `setValue` is
+optional.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -60,8 +62,9 @@ One field's state, as an adapter reports it.
 
 Kind: interface.
 
-The adapter contract. `useField` is a hook, called once per bound field during render,
-so an RHF adapter can delegate to `useController`.
+The adapter contract: the one-method interface a form library satisfies to work with the
+kit's fields. `useField` is a hook, called once per bound field during render, so an RHF
+adapter can delegate to `useController`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -71,7 +74,9 @@ so an RHF adapter can delegate to `useController`.
 
 Kind: callable.
 
-Binds one field. The only API a component needs to be form-library agnostic.
+Binds one field: turns a control and a field name into the exact props a kit control
+takes — value, onValueChange, onBlur, invalid, error, disabled. The only API a component
+needs to be form-library agnostic.
 
 ```text
 ({ name, control, disabled, }: { name: Extract<keyof TValues, string> | string; control: FormControl<TValues>; disabled?: boolean; }) => FieldBinding<TValue>
@@ -81,7 +86,8 @@ Binds one field. The only API a component needs to be form-library agnostic.
 
 Kind: callable.
 
-A `FormControl` over plain React state — the zero-dependency default.
+A `FormControl` over plain React state — the zero-dependency default. Also exposes the
+current values and a reset, which a library-backed control owns itself.
 
 ```text
 (initialValues: TValues, options?: { errors?: Partial<Record<keyof TValues, string>>; }) => FormControl<TValues> & { values: TValues; reset: (next?: TValues) => void; }
@@ -94,23 +100,71 @@ Preview route: Form binding — `/form-binding`
 ### useStateFormControl
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-const control = useStateFormControl({ email: "", workspace: "acme-corp" })
-
-function BoundInput({ name, label, control }) {
-  const field = useFormFieldBinding<string>({ name, control })
-  return (
-    <FormField label={label} error={field.error}>
-      <Input
-        value={field.value ?? ""}
-        onChange={(event) => field.onValueChange(event.target.value)}
-        onBlur={field.onBlur}
-      />
-    </FormField>
-  )
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { useFormFieldBinding, useStateFormControl } from "themelia-ui/forms"
+import { MonoValue } from "themelia-ui/primitives"
+
+
+/**
+ * A field bound through the headless contract, so the demo exercises the real seam rather
+ * than describing it. `useFormFieldBinding` returns exactly the props a control takes.
+ */
+function BoundInput({
+	name,
+	label,
+	control,
+	type,
+}: {
+	name: string
+	label: string
+	control: Parameters<typeof useFormFieldBinding<string>>[0]["control"]
+	type?: string
+}) {
+	const field = useFormFieldBinding<string>({ name, control })
+	return (
+		<FormField label={label} error={field.error}>
+			<Input
+				type={type}
+				value={field.value ?? ""}
+				onChange={(event) => field.onValueChange(event.target.value)}
+				onBlur={field.onBlur}
+				aria-invalid={field.invalid || undefined}
+			/>
+		</FormField>
+	)
+}
+
+export default function FormBindingState() {
+	const [submitted, setSubmitted] = useState<string | null>(null)
+	const control = useStateFormControl(
+		{ email: "", workspace: "acme-corp" },
+		{ errors: { email: "" } },
+	)
+
+	return (
+		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+			<BoundInput name="email" label="Email" control={control} type="email" />
+			<BoundInput name="workspace" label="Workspace" control={control} />
+			<Stack direction="horizontal" gap="sm" align="center">
+				<Button onClick={() => setSubmitted(JSON.stringify(control.values))}>
+					Submit
+				</Button>
+				<Button buttonStyle="outline" onClick={() => control.reset()}>
+					Reset
+				</Button>
+			</Stack>
+			{submitted !== null && <MonoValue>{submitted}</MonoValue>}
+		</Stack>
+	)
 }
 ```
 
-### The contract
+### rhfFormControl
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { rhfFormControl } from "themelia-ui/forms-rhf"

package/docs/generated/components/layout--app-shell.md

@@ -20,7 +20,7 @@ import "themelia-ui/layout/app-shell.css"
 
 ## Composition
 
-This family composes `base/sidebar`.
+This module composes `base/sidebar`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -47,13 +47,13 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `children` | yes | `ReactNode` |  |
 | `toolbar` | no | `ReactNode \| false` | The row above the content. `false` removes it, for a shell with no chrome at all. |
 | `toolbarEnd` | no | `ReactNode` | Rendered at the toolbar's trailing edge — a search field, an account menu. |
-| `showTrigger` | no | `boolean` | Shows the panel toggle in the toolbar. On mobile it is the only way to open it. |
-| `boundContent` | no | `boolean` | Caps the content measure so a wide monitor does not stretch prose across the page. |
-| `contained` | no | `boolean` | Bounds the shell to its parent instead of the viewport. See SidebarProvider. |
+| `showTrigger` | no | `boolean` | Shows the panel toggle, the toolbar's collapse control. On mobile it is the only way to<br>open the panel; turn it off for a shell whose navigation is opened from somewhere else. |
+| `boundContent` | no | `boolean` | Caps the content at a reading measure instead of letting it run the shell's full width,<br>so a wide monitor does not stretch prose across the page. |
+| `contained` | no | `boolean` | Bounds the shell to its parent instead of the viewport. The panel is fixed by default,<br>which is right for a shell that owns the screen and wrong everywhere else. |
 | `defaultOpen` | no | `boolean` |  |
-| `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Configure controlled state, persistence, shortcuts and translated sidebar controls. |
-| `toolbarClassName` | no | `string` |  |
-| `contentClassName` | no | `string` |  |
+| `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Passes `open`/`onOpenChange`, `persist`, `keyboardShortcut` and `strings` to the<br>shell's provider: controlled state, persistence, shortcuts and translated sidebar<br>controls. Disable persistence and shortcuts in independent embedded examples. |
+| `toolbarClassName` | no | `string` | Styles the toolbar without wrapping it. The shell owns the grid, so a wrapper around a<br>region would break the sticky rows. |
+| `contentClassName` | no | `string` | Styles the content region without wrapping it. The shell owns the grid, so a wrapper<br>around a region would break the sticky rows. |
 | `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `ruledToolbar` | no | `boolean` | `false` when the content below sits on its own plane — an inset sidebar. |
 
@@ -76,9 +76,9 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `header` | no | `ReactNode` | The header row — a mark, navigation, an account menu. |
 | `headerEnd` | no | `ReactNode` |  |
 | `contained` | no | `boolean` | Fit a parent with a definite height and scroll the content below the header. |
-| `boundContent` | no | `boolean` | Set false for tables or composed workspaces that use the full content width. |
+| `boundContent` | no | `boolean` | Caps the reading width. Set false for wide tables and composed workspaces that use the<br>full content width. |
 | `children` | yes | `ReactNode` |  |
-| `headerClassName` | no | `string` |  |
+| `headerClassName` | no | `string` | Styles the header row without wrapping it. The shell owns the grid, so a wrapper around<br>a region would break the sticky rows. |
 | `contentClassName` | no | `string` |  |
 | `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the element the content region is drawn as (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 
@@ -86,6 +86,11 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 Kind: callable.
 
+The header-first admin shell. The header spans the full width and owns the brand, the
+search and the account; the sidebar and the content share the height below it. The only
+difference from SidebarInsetLayout is where the LOGO lives — and that decides the whole
+frame, which is why it is two components rather than a boolean.
+
 ```text
 ({ children, sidebarSide, mobileSidebarMode, headerHeight, sidebarWidth, sidebarTrigger, logo, headerActions, sidebar, slots, contentRender, defaultOpen, contained, sidebarProviderProps, className, headerClassName, bodyClassName, sidebarClassName, contentClassName, style, ...props }: TopbarSidebarLayoutProps) => import("react").JSX.Element
 ```
@@ -99,19 +104,19 @@ Extends: `Omit<ComponentProps<"div">, "children" | "title">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `children` | no | `ReactNode` |  |
-| `sidebarSide` | no | `TopbarSidebarSide` |  |
-| `mobileSidebarMode` | no | `TopbarSidebarMobileMode` |  |
+| `sidebarSide` | no | `TopbarSidebarSide` | Which side the rail sits on. Match the Sidebar's own `side` to it. |
+| `mobileSidebarMode` | no | `TopbarSidebarMobileMode` | `drawer` hides the sidebar column below md and uses the Sidebar's mobile sheet, which<br>the trigger opens. `inline` stacks static navigation above the content; pair it with<br>`collapsible="none"` and `sidebarTrigger={false}`. |
 | `headerHeight` | no | `string` | Any CSS length. Falls back to the shell's own token. |
 | `sidebarWidth` | no | `string` |  |
 | `sidebarTrigger` | no | `ReactNode` | Shorthands for the matching `slots` entry, for a shell with only a few regions. |
 | `logo` | no | `ReactNode` |  |
 | `headerActions` | no | `ReactNode` |  |
-| `sidebar` | no | `ReactNode` |  |
+| `sidebar` | no | `ReactNode` | The rail: a Sidebar or AppSidebar with `icon` or `offcanvas` collapse, which becomes<br>the mobile drawer. Omit it for a full-width body. |
 | `slots` | no | `TopbarSidebarLayoutSlots` |  |
 | `contentRender` | no | `useRender.ComponentProps<"main">["render"]` | Replaces the content column's element (`<main>` by default). Pass<br>`contentRender={<div />}` when embedded in a page that owns the main landmark. |
 | `defaultOpen` | no | `boolean` | The sidebar's initial uncontrolled open state. |
-| `contained` | no | `boolean` | Fit the height of a parent instead of owning the viewport. |
-| `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Configure controlled state, persistence, shortcuts and translated sidebar controls. |
+| `contained` | no | `boolean` | Fits a parent with a definite height instead of owning the viewport. Either way the<br>sidebar and content scroll below the header. |
+| `sidebarProviderProps` | no | `Pick<SidebarProviderProps, "open" \| "onOpenChange" \| "persist" \| "keyboardShortcut" \| "strings">` | Passes `open`/`onOpenChange`, `persist`, `keyboardShortcut` and `strings` to the<br>shell's provider: controlled state, persistence, shortcuts and translated sidebar<br>controls. Disable persistence and shortcuts in independent embedded examples. |
 | `headerClassName` | no | `string` |  |
 | `bodyClassName` | no | `string` |  |
 | `sidebarClassName` | no | `string` |  |
@@ -155,24 +160,249 @@ Kind: type.
 
 Preview route: App shell — `/app-shell`
 
+### The shell
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import type { SidebarCollapsible, SidebarVariant } from "themelia-ui/base/sidebar"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { SidebarInsetLayout } from "themelia-ui/layout/app-shell"
+import { AppSidebar } from "themelia-ui/layout/sidebar"
+
+import { demoLink } from "./_demo-link"
+import { AdminContent, Brand, BrandMark } from "./_shared"
+import { FRAME, NAVIGATION, PROVIDER } from "./data"
+
+function ShellDemo({ variant, collapsible }: { variant: SidebarVariant; collapsible: SidebarCollapsible }) {
+	const [currentUrl, setCurrentUrl] = useState("/app/settings/members")
+	return <div style={FRAME}>
+		<SidebarInsetLayout contentRender={<div />} contained sidebarProviderProps={PROVIDER}
+			showTrigger={collapsible !== "none"} ruledToolbar={variant !== "inset"}
+			toolbar={<Text weight="medium">Workspace</Text>} toolbarEnd={<Badge tone="neutral">{variant}</Badge>}
+			sidebar={<AppSidebar variant={variant} collapsible={collapsible} currentUrl={currentUrl} navigationGroups={NAVIGATION}
+				liveBadges={{ invoices: 2 }} logo={<Brand />} collapsedLogo={<BrandMark />} renderLink={demoLink(setCurrentUrl)} />}
+		><AdminContent currentUrl={currentUrl} /></SidebarInsetLayout>
+	</div>
+}
+
+export default function SidebarShell() {
+	const [variant, setVariant] = useState<string | null>("sidebar")
+	const [collapsible, setCollapsible] = useState<string | null>("icon")
+
+	return (
+		<Stack gap="lg" style={{ width: "100%" }}>
+			<Stack direction="horizontal" gap="xl" wrap>
+				<Stack gap="2xs">
+					<Text size="xs" type="secondary">
+						variant
+					</Text>
+					<PillRadioGroup
+						aria-label="Sidebar surface"
+						name="sidebar-variant"
+						value={variant}
+						onValueChange={setVariant}
+						options={[
+							{ value: "sidebar", label: "sidebar" },
+							{ value: "floating", label: "floating" },
+							{ value: "inset", label: "inset" },
+						]}
+					/>
+				</Stack>
+				<Stack gap="2xs">
+					<Text size="xs" type="secondary">
+						collapsible
+					</Text>
+					<PillRadioGroup
+						aria-label="Sidebar collapse behavior"
+						name="sidebar-collapsible"
+						value={collapsible}
+						onValueChange={setCollapsible}
+						options={[
+							{ value: "icon", label: "icon" },
+							{ value: "offcanvas", label: "offcanvas" },
+							{ value: "none", label: "none" },
+						]}
+					/>
+				</Stack>
+			</Stack>
+			<ShellDemo
+				key={`${variant}-${collapsible}`}
+				variant={(variant ?? "sidebar") as SidebarVariant}
+				collapsible={(collapsible ?? "icon") as SidebarCollapsible}
+			/>
+		</Stack>
+	)
+}
+```
+
 ### TopbarSidebarLayout
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TopbarSidebarLayout
-  logo={<Brand />}
-  sidebar={<AppSidebar collapsible="icon" navigationGroups={NAVIGATION} currentUrl={url} renderLink={renderLink} />}
->
-  <InvoicePage />
-</TopbarSidebarLayout>
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { TopbarSidebarLayout } from "themelia-ui/layout/app-shell"
+import { AppSidebar } from "themelia-ui/layout/sidebar"
+
+import { demoLink } from "./_demo-link"
+import { AdminContent, Brand } from "./_shared"
+import { FRAME, NAVIGATION, PROVIDER } from "./data"
+
+function TopbarDemo() {
+	const [currentUrl, setCurrentUrl] = useState("/app/invoices")
+	const [side, setSide] = useState<string | null>("left")
+	const [query, setQuery] = useState("")
+	const sidebarSide = side === "right" ? "right" : "left"
+
+	return (
+		<Stack gap="lg" style={{ width: "100%", minWidth: 0 }}>
+			<PillRadioGroup
+				aria-label="Navigation side"
+				name="topbar-sidebar-side"
+				value={side}
+				onValueChange={setSide}
+				options={[{ value: "left", label: "Left navigation" }, { value: "right", label: "Right navigation" }]}
+			/>
+			<div style={FRAME}>
+				<TopbarSidebarLayout
+					contained
+					contentRender={<div />}
+					sidebarProviderProps={PROVIDER}
+					sidebarSide={sidebarSide}
+					logo={<Brand />}
+					headerActions={<Badge tone="neutral">Workspace</Badge>}
+					sidebar={
+						<AppSidebar
+							side={sidebarSide}
+							collapsible="icon"
+							currentUrl={currentUrl}
+							navigationGroups={NAVIGATION}
+							renderLink={demoLink(setCurrentUrl)}
+						/>
+					}
+				>
+					<Stack gap="lg">
+						{currentUrl === "/app/invoices" && (
+							<Input type="search" aria-label="Search invoices" placeholder="Search invoices…" value={query} onChange={event => setQuery(event.target.value)} />
+						)}
+						<AdminContent currentUrl={currentUrl} query={currentUrl === "/app/invoices" ? query : undefined} />
+					</Stack>
+				</TopbarSidebarLayout>
+			</div>
+		</Stack>
+	)
+}
+
+export default function TopbarSidebarLayoutExample() {
+	return (
+		<TopbarDemo />
+	)
+}
 ```
 
 ### StackedLayout
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<StackedLayout
-  header={<Nav />}
-  headerEnd={<Account />}
->
-  {children}
-</StackedLayout>
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { StackedLayout } from "themelia-ui/layout/app-shell"
+
+import { AdminContent, Brand } from "./_shared"
+import { FRAME } from "./data"
+
+function StackedDemo() {
+	const [currentUrl, setCurrentUrl] = useState("/app")
+	const destinations = [["/app", "Overview"], ["/app/invoices", "Invoices"], ["/app/settings", "Settings"]] as const
+
+	return (
+		<div style={FRAME}>
+			<StackedLayout
+				contained
+				boundContent={false}
+				contentRender={<div />}
+				header={
+					<Stack direction="horizontal" gap="md" align="center" wrap>
+						<Brand />
+						<nav aria-label="Primary navigation (stacked example)">
+							<Stack direction="horizontal" gap="xs" wrap>
+								{destinations.map(([path, label]) => (
+									<Button
+										key={path}
+										tone="neutral"
+										buttonStyle={currentUrl === path ? "solid" : "ghost"}
+										aria-current={currentUrl === path ? "page" : undefined}
+										onClick={() => setCurrentUrl(path)}
+									>{label}</Button>
+								))}
+							</Stack>
+						</nav>
+					</Stack>
+				}
+			>
+				<AdminContent currentUrl={currentUrl} />
+			</StackedLayout>
+		</div>
+	)
+}
+
+export default function StackedShell() {
+	return (
+		<StackedDemo />
+	)
+}
+```
+
+### A workspace inside a shell
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { StackedLayout } from "themelia-ui/layout/app-shell"
+import { WorkspaceLayout, WorkspaceNav } from "themelia-ui/layout/workspace"
+
+import { Brand, InvoiceContent, SettingsContent } from "./_shared"
+import { FRAME } from "./data"
+
+function WorkspaceDemo() {
+	const [section, setSection] = useState("details")
+	return (
+		<div style={FRAME}>
+			<StackedLayout contained boundContent={false} contentRender={<div />} header={<Brand />} headerEnd={<Badge tone="neutral">Settings</Badge>}>
+				<WorkspaceLayout
+					contentRender={<div />}
+					contentWidth="full"
+					sidebar={
+						<WorkspaceNav
+							aria-label="Record sections (workspace example)"
+							activeId={section}
+							onSelect={item => setSection(item.id)}
+							groups={[{ id: "settings", label: "Workspace", items: [
+								{ id: "details", label: "Details", completion: 100 },
+								{ id: "billing", label: "Billing", completion: 50 },
+							] }]}
+						/>
+					}
+				>
+					{section === "details" ? <SettingsContent /> : <InvoiceContent />}
+				</WorkspaceLayout>
+			</StackedLayout>
+		</div>
+	)
+}
+
+export default function ComposedWorkspace() {
+	return (
+		<WorkspaceDemo />
+	)
+}
 ```