themelia-ui 3.0.0 → 3.2.0

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

@@ -15,7 +15,6 @@ Writing table markup directly, with rows you control and no sorting or selection
 
 ```tsx fragment — import-only example
 import { Table } from "themelia-ui/base/table"
-import "themelia-ui/base/table.css"
 ```
 
 ## Composition
@@ -202,7 +201,66 @@ Kind: interface.
 
 ## Preview recipes
 
-Preview route: Table — `/table`
+Preview route: Timelines, onboarding & admin — `/blocks-admin`
+
+### Compose your own permissions
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { CheckIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { VisuallyHidden } from "themelia-ui/base/display"
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "themelia-ui/base/table"
+import { Text } from "themelia-ui/base/typography"
+
+const ROLES = ["Owner", "Editor", "Viewer"] as const
+const PERMISSIONS: { name: string; granted: readonly boolean[] }[] = [
+	{ name: "Edit projects", granted: [true, true, false] },
+	{ name: "Manage billing", granted: [true, false, false] },
+	{ name: "Export data", granted: [true, true, true] },
+]
+
+export default function RolesBlueprint() {
+	return (
+		<Table>
+			<TableHeader>
+				<TableRow>
+					<TableHead>Permission</TableHead>
+					{ROLES.map((role) => (
+						<TableHead key={role} align="center">
+							{role}
+						</TableHead>
+					))}
+				</TableRow>
+			</TableHeader>
+			<TableBody>
+				{PERMISSIONS.map((permission) => (
+					<TableRow key={permission.name}>
+						<TableCell>{permission.name}</TableCell>
+						{permission.granted.map((granted, index) => (
+							<TableCell key={ROLES[index]} align="center">
+								{granted ? (
+									<Badge tone="success">
+										<CheckIcon aria-hidden />
+										<VisuallyHidden>Granted</VisuallyHidden>
+									</Badge>
+								) : (
+									<>
+										<Text tag="span" type="secondary" aria-hidden>
+											—
+										</Text>
+										<VisuallyHidden>Not granted</VisuallyHidden>
+									</>
+								)}
+							</TableCell>
+						))}
+					</TableRow>
+				))}
+			</TableBody>
+		</Table>
+	)
+}
+```
 
 ### Sortable columns
 
@@ -298,7 +356,7 @@ import styles from "./table-empty.module.css"
 
 export default function TableEmptyExample() {
 	return (
-		<Stack gap="xl" style={{ width: "100%" }}>
+		<Stack style={{ width: "100%" }}>
 			<Table>
 				<TableHeader>
 					<TableRow>

package/docs/generated/components/base--text-inputs.md

@@ -15,12 +15,11 @@ Free text is typed — plain, multiline, password, search or slug.
 
 ```tsx fragment — import-only example
 import { FieldShell } from "themelia-ui/base/text-inputs"
-import "themelia-ui/base/text-inputs.css"
 ```
 
 ## Composition
 
-This module depends on no other module.
+This module composes `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.
@@ -339,29 +338,29 @@ Preview route: Form field — `/form-field`
 import { Stack } from "themelia-ui/base/structure"
 import { Input, NativeSelect } from "themelia-ui/base/text-inputs"
 import { MonoValue } from "themelia-ui/primitives"
-import { Scope } from "themelia-ui/ui-provider"
+import { UIScope } from "themelia-ui/ui-provider"
 
 export default function FormsScale() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
-			{[1, 0.875, 1.125].map((scale) => (
-				<Scope key={scale} vars={{ "--density-scale": scale }}>
-					<Stack direction="horizontal" gap="md" align="center" justify="start">
+		<Stack style={{ width: "100%" }}>
+			{(["compact", "default", "comfortable"] as const).map((density) => (
+				<UIScope key={density} config={{ density }}>
+					<Stack direction="horizontal" gap="sm" align="center" justify="start">
 						{/* Widths on the wrappers: Input's style lands on the inner control, not its frame. */}
-						<MonoValue size="xs" style={{ width: "3.5rem", flexShrink: 0, fontSize: "0.75rem" }}>
-							{scale}
+						<MonoValue size="xs" style={{ width: "6rem", flexShrink: 0 }}>
+							{density}
 						</MonoValue>
 						{/* Named even in a geometry demo: a placeholder is not a label. */}
 						<div style={{ width: "12rem", flexShrink: 0 }}>
-							<Input placeholder="Field" aria-label={`Example field at density ${scale}`} />
+							<Input placeholder="Field" aria-label={`Example field at ${density} density`} />
 						</div>
 						<div style={{ width: "9rem", flexShrink: 0 }}>
-							<NativeSelect defaultValue="a" aria-label={`Example select at density ${scale}`}>
+							<NativeSelect defaultValue="a" aria-label={`Example select at ${density} density`}>
 								<option value="a">Option</option>
 							</NativeSelect>
 						</div>
 					</Stack>
-				</Scope>
+				</UIScope>
 			))}
 		</Stack>
 	)
@@ -378,7 +377,7 @@ import { Input, NativeSelect, Textarea } from "themelia-ui/base/text-inputs"
 
 export default function SharedSurface() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Input">
 				<Input placeholder="Northwind Traders" />
 			</FormField>
@@ -412,7 +411,7 @@ import { UIProvider } from "themelia-ui/ui-provider"
 export default function IphoneInputZoom() {
 	return (
 		<UIProvider config={{ forms: { preventIPhoneZoom: true } }}>
-			<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+			<Stack gap="sm" style={{ maxWidth: "26rem", width: "100%" }}>
 				<FormField label="Enabled on iPhones"><Input placeholder="16px minimum on iPhone" /></FormField>
 				<FormField label="iPhone textarea"><Textarea /></FormField>
 				<FormField label="iPhone native select"><NativeSelect><option>First option</option></NativeSelect></FormField>
@@ -436,7 +435,7 @@ import { Input, NativeSelect } from "themelia-ui/base/text-inputs"
 
 export default function States() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Default" helperText="The supporting line.">
 				<Input placeholder="name@example.com" />
 			</FormField>
@@ -471,7 +470,7 @@ export default function Affordances() {
 	const [search, setSearch] = useState("shipping")
 
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Search" helperText="Clear appears once there is a value.">
 				<SearchInput
 					value={search}
@@ -513,7 +512,7 @@ function SlugFieldDemo() {
 	const [title, setTitle] = useState("Northwind Traders — Q4 Report & Notes")
 
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Title">
 				<Input value={title} onChange={(event) => setTitle(event.target.value)} />
 			</FormField>
@@ -541,7 +540,7 @@ import { Textarea } from "themelia-ui/base/text-inputs"
 
 export default function TextareaExample() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Notes" helperText="Plain multi-line text.">
 				<Textarea rows={4} placeholder="Anything worth recording." />
 			</FormField>

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

@@ -8,14 +8,13 @@ Composing a generic vertical sequence of dated entries.
 
 - **Use when:** Composing a generic vertical sequence of dated entries.
 - **Avoid when:** The sequence is a changelog, milestones or a step tracker.
-- **Consider instead:** `patterns/timelines`, `features/activities`
+- **Consider instead:** `blocks/timelines`, `features/activities`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { Stepper } from "themelia-ui/base/timeline"
-import "themelia-ui/base/timeline.css"
 ```
 
 ## Composition
@@ -159,7 +158,49 @@ takes the primary tone of `current`; `completed` is an outcome (a milestone that
 
 ## Preview recipes
 
-Preview route: Timeline — `/timeline`
+Preview route: Timelines, onboarding & admin — `/blocks-admin`
+
+### Compose your own timeline
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { RocketIcon, WrenchIcon } 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"
+import { MonoValue } from "themelia-ui/primitives"
+
+const RELEASES: TimelineItem[] = [
+	{
+		id: "3.1.0",
+		title: "Saved views",
+		timestamp: <MonoValue size="xs" type="secondary">v3.1.0</MonoValue>,
+		icon: RocketIcon,
+		status: "success",
+		description: "Filters and columns can be saved and shared with the team.",
+		children: (
+			<Stack direction="horizontal" gap="sm">
+				<Badge tone="success">Added</Badge>
+				<Badge tone="neutral">Tables</Badge>
+			</Stack>
+		),
+	},
+	{
+		id: "3.0.2",
+		title: "Faster exports",
+		timestamp: <MonoValue size="xs" type="secondary">v3.0.2</MonoValue>,
+		icon: WrenchIcon,
+		status: "neutral",
+		description: "Large exports stream instead of waiting for the whole file.",
+	},
+]
+
+export default function ChangelogBlueprint() {
+	return (
+		<Timeline items={RELEASES} />
+	)
+}
+```
 
 ### An order's progress
 
@@ -288,7 +329,7 @@ import { WIZARD } from "./data"
 
 export default function StepperDefault() {
 	return (
-		<Stack gap="2xl">
+		<Stack>
 			<Stepper steps={WIZARD} />
 			<Stepper variant="trail" steps={WIZARD} />
 		</Stack>

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

@@ -15,12 +15,11 @@ A message is transient, non-blocking, and reports the outcome of an action.
 
 ```tsx fragment — import-only example
 import { Toaster } from "themelia-ui/base/toaster"
-import "themelia-ui/base/toaster.css"
 ```
 
 ## Composition
 
-This module depends on no other module.
+This module composes `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.
@@ -177,7 +176,39 @@ One queue of toasts, its timers, and the `toast()` bound to it.
 
 ## Preview recipes
 
-Preview route: Toast — `/toast`
+Preview route: Cart, checkout & billing — `/blocks-commerce`
+
+### Compose your own
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { toast } from "themelia-ui/base/toaster"
+import { Money } from "themelia-ui/primitives"
+
+export default function CartSummaryBlueprint() {
+	return (
+		<Card title="Order summary" description="3 items" style={{ maxWidth: "24rem" }}>
+			<Stack>
+				<MetadataList
+					layout="rows"
+					items={[
+						{ label: "Subtotal", value: <Money amount={258} currency="EUR" /> },
+						{ label: "Shipping", value: <Money amount={4.8} currency="EUR" /> },
+						{ label: "Tax", value: <Money amount={51.6} currency="EUR" /> },
+						{ label: "Total", value: <Money amount={314.4} currency="EUR" weight="semibold" /> },
+					]}
+				/>
+				<Button onClick={() => toast("Checkout requested", { description: "Preview callback — connect this action to your application." })}>
+					Check out
+				</Button>
+			</Stack>
+		</Card>
+	)
+}
+```
 
 ### Statuses
 
@@ -189,24 +220,24 @@ 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")}>
+			<Button appearance="outline" tone="neutral" onClick={() => toast("Draft saved")}>
 				Neutral
 			</Button>
 			<Button
-				buttonStyle="outline"
+				appearance="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")}>
+			<Button appearance="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")}>
+			<Button appearance="outline" tone="neutral" onClick={() => toast.warning("Your card expires next month")}>
 				Warning
 			</Button>
 			<Button
-				buttonStyle="outline"
+				appearance="outline"
 				tone="neutral"
 				onClick={() => toast.error("Could not reach the server", { description: "Retrying in 30 seconds." })}
 			>
@@ -228,7 +259,7 @@ export default function ToastActions() {
 	return (
 		<Stack direction="horizontal" gap="sm" wrap>
 			<Button
-				buttonStyle="outline"
+				appearance="outline"
 				tone="neutral"
 				onClick={() =>
 					toast("Invoice deleted", {
@@ -241,7 +272,7 @@ export default function ToastActions() {
 				With undo
 			</Button>
 			<Button
-				buttonStyle="outline"
+				appearance="outline"
 				tone="neutral"
 				onClick={() =>
 					toast.warning("Discard unsaved changes?", {
@@ -271,7 +302,7 @@ export default function ToastPromise() {
 	return (
 		<Stack direction="horizontal" gap="sm" wrap>
 			<Button
-				buttonStyle="outline"
+				appearance="outline"
 				tone="neutral"
 				onClick={() =>
 					void toast.promise(wait(1800), {
@@ -284,7 +315,7 @@ export default function ToastPromise() {
 				Resolves
 			</Button>
 			<Button
-				buttonStyle="outline"
+				appearance="outline"
 				tone="neutral"
 				onClick={() =>
 					void toast

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

@@ -15,12 +15,11 @@ A control holds a pressed state, alone or as one of a mutually exclusive group.
 
 ```tsx fragment — import-only example
 import { Toggle } from "themelia-ui/base/toggle"
-import "themelia-ui/base/toggle.css"
 ```
 
 ## Composition
 
-This module depends on no other module.
+This module composes `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.
@@ -37,7 +36,7 @@ with the next one. Inside a `ToggleGroup`, `value` names the toggle, and the gro
 into its own value; outside a group it is unused.
 
 ```text
-({ variant, className, ...props }: ToggleProps) => import("react").JSX.Element
+({ appearance, className, ...props }: ToggleProps) => import("react").JSX.Element
 ```
 
 ### `ToggleGroup`
@@ -71,7 +70,7 @@ Extends: `TogglePrimitive.Props`, `Pick<TogglePrimitive.Props, "pressed" | "defa
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `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. |
+| `appearance` | 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
 
@@ -91,11 +90,11 @@ export default function ToggleExample() {
 	const [bold, setBold] = useState(false)
 
 	return (
-		<Stack direction="horizontal" gap="lg" align="center">
+		<Stack direction="horizontal" align="center">
 			<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
 				<BoldIcon />
 			</Toggle>
-			<Toggle variant="outline" aria-label="Italic">
+			<Toggle appearance="outline" aria-label="Italic">
 				<ItalicIcon />
 			</Toggle>
 			<Toggle disabled aria-label="Underline">
@@ -124,8 +123,8 @@ export default function ToggleGroupExample() {
 	const [align, setAlign] = useState("left")
 
 	return (
-		<Stack gap="xl">
-			<Stack gap="xs" align="start">
+		<Stack>
+			<Stack gap="sm" 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>
@@ -134,7 +133,7 @@ export default function ToggleGroupExample() {
 				</ToggleGroup>
 			</Stack>
 
-			<Stack gap="xs" align="start">
+			<Stack gap="sm" align="start">
 				<Text size="xs" type="secondary">one at a time</Text>
 				<ToggleGroup
 					value={[align]}
@@ -146,11 +145,11 @@ export default function ToggleGroupExample() {
 				</ToggleGroup>
 			</Stack>
 
-			<Stack gap="xs" align="start">
+			<Stack gap="sm" 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>
+					<Toggle value="a" appearance="outline">Day</Toggle>
+					<Toggle value="b" appearance="outline">Week</Toggle>
 				</ToggleGroup>
 			</Stack>
 		</Stack>

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

@@ -15,12 +15,11 @@ A persistent group of related actions or controls needs one tab stop and arrow-k
 
 ```tsx fragment — import-only example
 import { Toolbar } from "themelia-ui/base/toolbar"
-import "themelia-ui/base/toolbar.css"
 ```
 
 ## Composition
 
-This module composes `base/buttons`.
+This module composes `base/buttons`, `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.
@@ -45,17 +44,17 @@ names the set.
 Kind: callable.
 
 A toolbar item rendered through the kit Button: Base UI owns the navigation behaviour, the
-Button its look. It takes `tone`, `buttonStyle`, `iconOnly`, `loading` and `render`.
+Button its look. It takes `tone`, `appearance`, `iconOnly`, `loading` and `render`.
 
 ```text
-({ render, tone, buttonStyle, iconOnly, loading, fullWidth, className, ...props }: ToolbarButtonProps) => React.JSX.Element
+({ render, tone, appearance, iconOnly, loading, fullWidth, className, ...props }: ToolbarButtonProps) => React.JSX.Element
 ```
 
 ### `ToolbarButtonProps`
 
 Kind: interface.
 
-Extends: `Omit<ToolbarPrimitive.Button.Props, "render">`, `Pick<ButtonProps, "tone" | "buttonStyle" | "iconOnly" | "loading" | "fullWidth">`.
+Extends: `Omit<ToolbarPrimitive.Button.Props, "render">`, `Pick<ButtonProps, "tone" | "appearance" | "iconOnly" | "loading" | "fullWidth">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -157,7 +156,7 @@ import {
 
 export default function ToolbarExample() {
 	return (
-		<Stack direction="horizontal">
+		<Stack gap="sm" direction="horizontal">
 			<Toolbar aria-label="Formatting">
 				<ToolbarGroup>
 					<ToolbarButton iconOnly aria-label="Bold">
@@ -177,7 +176,7 @@ export default function ToolbarExample() {
 					</ToolbarButton>
 				</ToolbarGroup>
 				<ToolbarSeparator />
-				<ToolbarInput aria-label="Font size" defaultValue="14" inputMode="numeric" style={{ width: "calc(4rem * var(--scale))" }} />
+				<ToolbarInput aria-label="Font size" defaultValue="14" inputMode="numeric" style={{ width: "4rem" }} />
 				<ToolbarLink
 					href="#/toolbar"
 					onClick={(event) => {
@@ -203,7 +202,7 @@ import { Toolbar, ToolbarButton } from "themelia-ui/base/toolbar"
 
 export default function ToolbarOrientation() {
 	return (
-		<Stack direction="horizontal" gap="xl" align="start">
+		<Stack direction="horizontal" align="start">
 			<Toolbar aria-label="History" orientation="vertical">
 				<ToolbarButton iconOnly aria-label="Undo">
 					<Undo2Icon />

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

@@ -15,12 +15,11 @@ A short, non-essential hint labels a control on hover or focus.
 
 ```tsx fragment — import-only example
 import { Tooltip } from "themelia-ui/base/tooltip"
-import "themelia-ui/base/tooltip.css"
 ```
 
 ## Composition
 
-This module depends on no other module.
+This module composes `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.
@@ -82,22 +81,22 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "themelia-ui/base/toolti
 
 export default function TooltipExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" align="center" wrap>
+		<Stack direction="horizontal" align="center" wrap>
 			<Tooltip>
-				<TooltipTrigger render={<Button buttonStyle="outline" tone="neutral" />}>
+				<TooltipTrigger render={<Button appearance="outline" tone="neutral" />}>
 					Hover or focus
 				</TooltipTrigger>
 				<TooltipContent>Charged on the first of the month.</TooltipContent>
 			</Tooltip>
 
 			<Tooltip>
-				<TooltipTrigger render={<Button buttonStyle="ghost" tone="neutral" iconOnly aria-label="About billing" />}>
+				<TooltipTrigger render={<Button appearance="ghost" tone="neutral" iconOnly aria-label="About billing" />}>
 					<InfoIcon />
 				</TooltipTrigger>
 				<TooltipContent>An icon-only control still needs a name of its own.</TooltipContent>
 			</Tooltip>
 
-			<TooltipButton tooltip="TooltipButton wires the two together" buttonStyle="outline" tone="neutral">
+			<TooltipButton tooltip="TooltipButton wires the two together" appearance="outline" tone="neutral">
 				TooltipButton
 			</TooltipButton>
 		</Stack>