themelia-ui 3.0.0 → 3.2.0

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

@@ -8,14 +8,13 @@ Rendering a Recharts chart that must inherit the kit's tokens, legend and toolti
 
 - **Use when:** Rendering a Recharts chart that must inherit the kit's tokens, legend and tooltip chrome.
 - **Avoid when:** The number is a single figure with a trend, or the chart needs a titled card frame.
-- **Consider instead:** `patterns/analytics`
+- **Consider instead:** `blocks/analytics`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { ChartContainer } from "themelia-ui/base/chart"
-import "themelia-ui/base/chart.css"
 ```
 
 ## Optional peers
@@ -28,7 +27,7 @@ npm install recharts
 
 ## 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.
@@ -191,12 +190,49 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 
 ## Preview recipes
 
-Preview route: Chart — `/chart`
+Preview route: Analytics — `/analytics`
+
+### Compose your own
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { ArrowUpIcon, CreditCardIcon } from "lucide-react"
+
+import { Badge } from "themelia-ui/base/badge"
+import { Card } from "themelia-ui/base/cards"
+import { Sparkline } from "themelia-ui/base/chart"
+import { IconBadge } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, Text } from "themelia-ui/base/typography"
+import { Money } from "themelia-ui/primitives"
+
+export default function AnalyticsBlueprint() {
+	return (
+		<Card style={{ maxWidth: "20rem" }}>
+			<Stack gap="sm">
+				<Stack direction="horizontal" align="center" gap="sm">
+					<IconBadge icon={CreditCardIcon} tone="primary" />
+					<DisplayLabel>Revenue</DisplayLabel>
+				</Stack>
+				<Stack direction="horizontal" align="center" justify="between" gap="sm">
+					<Money amount={48200} currency="EUR" size="xl" weight="semibold" />
+					<Badge tone="success">
+						<ArrowUpIcon />
+						12.4%
+					</Badge>
+				</Stack>
+				<Sparkline data={[18, 22, 19, 27, 24, 31, 29, 38]} tone="success" label="Revenue rising over eight weeks" />
+				<Text size="xs" type="secondary">
+					Net of refunds, this quarter
+				</Text>
+			</Stack>
+		</Card>
+	)
+}
+```
 
 ### Chart
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import type { CSSProperties } from "react"
 import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts"
 
 import { Card } from "themelia-ui/base/cards"
@@ -226,7 +262,7 @@ const CONFIG = {
 export default function Chart() {
 	return (
 		/* Two columns, with the third chart spanning both. */
-		<Grid columns={{ base: 1, md: 2 }} gap="lg" style={{ width: "100%" }}>
+		<Grid columns={{ base: 1, md: 2 }} style={{ width: "100%" }}>
 			<Card surface="bordered" title="Revenue vs expenses" description="Bars, with a legend.">
 				<ChartContainer config={CONFIG} label="Monthly revenue and expenses, January to June">
 					<BarChart data={REVENUE}>
@@ -257,7 +293,7 @@ export default function Chart() {
 			<GridCell span="full">
 				<Card surface="bordered" title="Cumulative" description="An area, with the line indicator.">
 					{/* A wide aspect: 16:9 across the page would be half a screen tall. */}
-					<ChartContainer config={CONFIG} label="Cumulative revenue and expenses, January to June" style={{ "--chart-aspect": "48 / 9" } as CSSProperties}>
+					<ChartContainer config={CONFIG} label="Cumulative revenue and expenses, January to June" style={{ aspectRatio: "48 / 9" }}>
 						<AreaChart data={REVENUE}>
 							<CartesianGrid vertical={false} />
 							{/* A point scale again — see the note on the line chart's axis. */}
@@ -292,7 +328,7 @@ const SPARK_FLAT = [11, 12, 11, 13, 12, 12, 13, 12]
 
 export default function ChartSparkline() {
 	return (
-		<Grid columns={3} gap="xl">
+		<Grid columns={3}>
 			<GridCell>
 				<Sparkline data={SPARK_UP} tone="success" label="Revenue, trending up" />
 			</GridCell>

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

@@ -15,7 +15,6 @@ The user picks from a known, closed set — checkbox, radio, switch or select.
 
 ```tsx fragment — import-only example
 import { CardCheckboxGroup } from "themelia-ui/base/choice-inputs"
-import "themelia-ui/base/choice-inputs.css"
 ```
 
 ## Composition
@@ -110,8 +109,8 @@ Extends: `Omit<React.ComponentProps<"input">, "type" | "size">`, `Pick<React.Com
 
 Kind: type.
 
-Column cap for card groups. There is no `size` prop: geometry follows `--density-scale`
-(styles/FACTORS.md).
+Column cap for card groups. There is no `size` prop: spacing follows the density a scope
+sets.
 
 ```text
 1 | 2 | 3 | 4
@@ -632,7 +631,7 @@ export default function PillRadio() {
 	const [view, setView] = useState<string | null>("grid")
 
 	return (
-		<Stack gap="lg" align="start">
+		<Stack align="start">
 			<PillRadioGroup name="view" options={VIEWS} value={view} onValueChange={setView} allowClear />
 			<PillRadioGroup
 				name="range"
@@ -649,7 +648,7 @@ export default function PillRadio() {
 }
 ```
 
-### Type can override the master factor
+### Type has its own factor
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { Button } from "themelia-ui/base/buttons"
@@ -660,11 +659,11 @@ import { UIProvider } from "themelia-ui/ui-provider"
 
 export default function TypeFactor() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<Stack gap="sm">
 				<Text type="secondary" size="xs">typography.scale 0.875 — type shrinks, control geometry holds</Text>
 				<UIProvider config={{ typography: { scale: 0.875 } }}>
-					<Stack direction="horizontal" gap="md" align="center" wrap>
+					<Stack direction="horizontal" gap="sm" align="center" wrap>
 						<Text>Body copy at this factor.</Text>
 						<Button>Save</Button>
 						<Checkbox label="Check" defaultChecked />
@@ -674,7 +673,7 @@ export default function TypeFactor() {
 			<Stack gap="sm">
 				<Text type="secondary" size="xs">scale 0.875 + typography.scale 1 — geometry shrinks, type holds</Text>
 				<UIProvider config={{ scale: 0.875, typography: { scale: 1 } }}>
-					<Stack direction="horizontal" gap="md" align="center" wrap>
+					<Stack direction="horizontal" gap="sm" align="center" wrap>
 						<Text>Body copy at this factor.</Text>
 						<Button>Save</Button>
 						<Checkbox label="Check" defaultChecked />
@@ -710,7 +709,7 @@ export default function SelectExample() {
 	const [country, setCountry] = useState<string | undefined>("nl")
 
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Billing country">
 				<Select options={COUNTRIES} value={country} onValueChange={setCountry} allowClear />
 			</FormField>
@@ -761,7 +760,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function ToggleRows() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<SwitchCard
 				label="Two-factor authentication"
 				icon={ShieldIcon}
@@ -775,7 +774,7 @@ export default function ToggleRows() {
 				icon={RocketIcon}
 				description="Turn on features that are still changing."
 			/>
-			<Stack gap="2xs">
+			<Stack gap="sm">
 				<ToggleField label="Email notifications" description="A daily digest, sent at 09:00." defaultValue />
 				<ToggleField label="Product updates" description="Occasional release notes." />
 				<ToggleField

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

@@ -15,7 +15,6 @@ Composing a filtered single- or multi-select from its parts, with options alread
 
 ```tsx fragment — import-only example
 import { ComboboxArrow } from "themelia-ui/base/combobox"
-import "themelia-ui/base/combobox.css"
 ```
 
 ## Composition
@@ -367,7 +366,7 @@ function SingleCombobox({ id }: { id?: string }) {
 
 export default function ComboboxField() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Plain input, for comparison">
 				<Input placeholder="A regular text field" />
 			</FormField>
@@ -463,7 +462,7 @@ function GroupedCombobox({ id }: { id?: string }) {
 
 export default function ComboboxSelect() {
 	return (
-		<Stack gap="lg" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Country from the list">
 				<SelectLikeCombobox />
 			</FormField>
@@ -538,7 +537,7 @@ function MultiCombobox({ id }: { id?: string }) {
 
 export default function ComboboxMultiple() {
 	return (
-		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack gap="sm" style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Ships to" helperText="Type to filter, Backspace to remove the last chip.">
 				<MultiCombobox />
 			</FormField>

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

@@ -15,12 +15,11 @@ A keyboard-first palette lists commands across groups, usually behind a shortcut
 
 ```tsx fragment — import-only example
 import { Command } from "themelia-ui/base/command"
-import "themelia-ui/base/command.css"
 ```
 
 ## Composition
 
-This module composes `base/dialog`, `base/input-group`, `base/overlay`.
+This module composes `base/dialog`, `base/input-group`, `base/overlay`, `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.
@@ -31,7 +30,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-The command palette's root: filtering, keyboard navigation and the rows' shared state.
+The command palette's root: filtering, keyboard navigation and the rows' shared state. It
+sets the rows' type; a group heading and a shortcut take the small step.
 
 ```text
 ({ className, ...props }: CommandProps) => React.JSX.Element
@@ -73,7 +73,7 @@ Kind: callable.
 A captioned block of rows.
 
 ```text
-({ className, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Group> & Pick<React.ComponentProps<typeof CommandPrimitive.Group>, "heading">) => React.JSX.Element
+({ className, ref, heading, ...props }: React.ComponentProps<typeof CommandPrimitive.Group> & Pick<React.ComponentProps<typeof CommandPrimitive.Group>, "heading">) => React.JSX.Element
 ```
 
 ### `CommandInput`
@@ -218,8 +218,8 @@ export default function CommandDialogExample() {
 	}, [])
 
 	return (
-		<Stack direction="horizontal" gap="lg" align="center">
-			<Button buttonStyle="outline" tone="neutral" onClick={() => setOpen(true)}>
+		<Stack direction="horizontal" align="center">
+			<Button appearance="outline" tone="neutral" onClick={() => setOpen(true)}>
 				Open palette
 			</Button>
 			<Text size="sm" type="secondary">or press ⌘K</Text>

package/docs/generated/components/base--context-menu.md

@@ -15,12 +15,11 @@ The trigger is a right-click on a region that has its own actions.
 
 ```tsx fragment — import-only example
 import { ContextMenu } from "themelia-ui/base/context-menu"
-import "themelia-ui/base/context-menu.css"
 ```
 
 ## Composition
 
-This module composes `base/dropdown-menu`.
+This module composes `base/dropdown-menu`, `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.

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

@@ -15,7 +15,6 @@ A value exists to be copied — an id, key, or reference — and needs copy feed
 
 ```tsx fragment — import-only example
 import { Copyable } from "themelia-ui/base/copyable"
-import "themelia-ui/base/copyable.css"
 ```
 
 ## Composition
@@ -125,14 +124,14 @@ import { Email, MonoValue } from "themelia-ui/primitives"
 export default function CopyableExample() {
 	return (
 		<Card surface="bordered" style={{ maxWidth: "26rem", width: "100%" }}>
-			<Stack gap="md">
-				<Stack gap="2xs">
+			<Stack gap="sm">
+				<Stack gap="sm">
 					<Text size="xs" type="secondary">
 						API key
 					</Text>
 					<Copyable value="key_live_9f2c4b1e77a0d3f8b6c5a41d0e73b28c9f4610d7" mono truncate />
 				</Stack>
-				<Stack gap="2xs">
+				<Stack gap="sm">
 					<Text size="xs" type="secondary">
 						Billing contact
 					</Text>
@@ -141,7 +140,7 @@ export default function CopyableExample() {
 						displayValue={<Email value="jane@northwind.example" />}
 					/>
 				</Stack>
-				<Stack gap="2xs">
+				<Stack gap="sm">
 					<Text size="xs" type="secondary">
 						Workspace id
 					</Text>
@@ -170,7 +169,7 @@ function ShareLink() {
 
 	return (
 		<Button
-			buttonStyle="outline"
+			appearance="outline"
 			tone="neutral"
 			onClick={() => void copy(url)}
 		>
@@ -181,7 +180,7 @@ function ShareLink() {
 
 export default function UseCopyToClipboard() {
 	return (
-		<Stack direction="horizontal">
+		<Stack gap="sm" direction="horizontal">
 			<ShareLink />
 		</Stack>
 	)

package/docs/generated/components/base--date-pickers.md

@@ -15,7 +15,6 @@ The user picks a date, range, month or time from a calendar surface.
 
 ```tsx fragment — import-only example
 import { Calendar } from "themelia-ui/base/date-pickers"
-import "themelia-ui/base/date-pickers.css"
 ```
 
 ## Composition
@@ -449,12 +448,12 @@ const MARCH = new Date("2026-03-01T00:00:00")
 
 export default function CalendarLocale() {
 	return (
-		<Stack direction="horizontal" gap="2xl" wrap align="start">
-			<Stack gap="xs" align="start">
+		<Stack direction="horizontal" wrap align="start">
+			<Stack gap="sm" align="start">
 				<Text size="xs" type="secondary">built-in, Monday first</Text>
 				<Calendar mode="single" month={MARCH} />
 			</Stack>
-			<Stack gap="xs" align="start">
+			<Stack gap="sm" align="start">
 				<Text size="xs" type="secondary">dates: {"{ locale: de, weekStartsOn: 0 }"}</Text>
 				<UIProvider config={{ dates: { locale: de, weekStartsOn: 0 } }}>
 					<Calendar mode="single" month={MARCH} />
@@ -486,7 +485,7 @@ export default function DatePickerExample() {
 	const presets = useMemo(() => createRangePresets({ weekStartsOn }), [weekStartsOn])
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
 			<FormField label="Due date">
 				<DatePicker value={day} onValueChange={(next) => setDay(next as Date)} clearable />
 			</FormField>
@@ -538,7 +537,7 @@ export default function DatePickerModes() {
 	const [month, setMonth] = useState<MonthYearValue | undefined>(undefined)
 
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="start">
+		<Stack direction="horizontal" wrap align="start">
 			<SingleDatePicker value={day} onValueChange={setDay} />
 			<RangeDatePicker value={range} onValueChange={setRange} />
 			<MultipleDatePicker value={days} onValueChange={setDays} />
@@ -565,7 +564,7 @@ export default function Time() {
 	const [instant, setInstant] = useState<string | undefined>("2026-03-12T09:30:00.000Z")
 
 	return (
-		<Stack gap="xl" style={{ maxWidth: "34rem", width: "100%" }}>
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
 			<FormField label="Start time">
 				<TimePicker value={time} onValueChange={setTime} minuteStep={15} />
 			</FormField>

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

@@ -15,7 +15,6 @@ Documenting or extending the dialog anatomy itself inside base.
 
 ```tsx fragment — import-only example
 import { DialogContent } from "themelia-ui/base/dialog"
-import "themelia-ui/base/dialog.css"
 ```
 
 ## Composition
@@ -69,9 +68,9 @@ import { Input } from "themelia-ui/base/text-inputs"
 
 export default function Dialog() {
 	return (
-		<Stack direction="horizontal">
+		<Stack gap="sm" direction="horizontal">
 			<Overlay>
-				<OverlayTrigger render={<Button tone="neutral" buttonStyle="outline" />}>
+				<OverlayTrigger render={<Button tone="neutral" appearance="outline" />}>
 					Open dialog
 				</OverlayTrigger>
 				<DialogContent>
@@ -85,7 +84,7 @@ export default function Dialog() {
 						</FormField>
 					</OverlayBody>
 					<OverlayFooter>
-						<OverlayClose render={<Button tone="neutral" buttonStyle="outline" />}>
+						<OverlayClose render={<Button tone="neutral" appearance="outline" />}>
 							Cancel
 						</OverlayClose>
 						<OverlayClose render={<Button />}>
@@ -112,9 +111,9 @@ import { UIProvider } from "themelia-ui/ui-provider"
 
 export default function OverlayBackdrop() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack direction="horizontal" wrap align="center">
 			<Overlay>
-				<OverlayTrigger render={<Button tone="neutral" buttonStyle="outline" />}>
+				<OverlayTrigger render={<Button tone="neutral" appearance="outline" />}>
 					Default scrim
 				</OverlayTrigger>
 				<DialogContent>
@@ -127,7 +126,7 @@ export default function OverlayBackdrop() {
 
 			<UIProvider config={{ overlay: { backdropBlur: 4 } }}>
 				<Overlay>
-					<OverlayTrigger render={<Button tone="neutral" buttonStyle="outline" />}>
+					<OverlayTrigger render={<Button tone="neutral" appearance="outline" />}>
 						Blurred scrim
 					</OverlayTrigger>
 					<DialogContent>

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

@@ -62,7 +62,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function DirectionSlot() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<DirectionProvider direction="rtl">
 				<div dir="rtl">
 					<ContentBlock surface="card" title="اتجاه من اليمين إلى اليسار">