themelia-ui 3.0.0 → 3.2.0

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

@@ -15,7 +15,6 @@ Presenting label/key and value facts, a collapsible region, a keyboard hint or a
 
 ```tsx fragment — import-only example
 import { BooleanIndicator } from "themelia-ui/base/display"
-import "themelia-ui/base/display.css"
 ```
 
 ## Composition
@@ -208,8 +207,8 @@ MetadataListStrings
 
 Kind: callable.
 
-A glyph in a tinted medallion. Its size comes from `--icon-badge-size`, so a caller
-needing a smaller mark re-points the token instead of redrawing the badge.
+A glyph in a tinted medallion. `tone` coordinates fill and glyph; `shape` chooses
+rounded or circular geometry. Internal sizing variables are not consumer overrides.
 
 ```text
 ({ icon, children, tone, shape, solid, bordered, className, ...props }: IconBadgeProps) => import("react").JSX.Element
@@ -242,8 +241,10 @@ Kind: type.
 
 Kind: type.
 
+A medallion's tones: the kit's tone union, without secondary.
+
 ```text
-"neutral" | "primary" | "success" | "warning" | "destructive" | "info"
+Extract<SemanticTone, "neutral" | "primary" | "success" | "warning" | "destructive" | "info">
 ```
 
 ### `InlineStat`
@@ -307,7 +308,7 @@ are pressed in turn rather than together.
 Kind: type.
 
 ```text
-DescriptorBase & ValueFallback & DisplayOverride & { kind: "badge"; value: DisplayValue; badgeTone?: BadgeProps["tone"]; badgeVariant?: BadgeProps["variant"]; }
+DescriptorBase & ValueFallback & DisplayOverride & { kind: "badge"; value: DisplayValue; badgeTone?: BadgeProps["tone"]; badgeAppearance?: BadgeProps["appearance"]; }
 ```
 
 ### `MetadataColumns`
@@ -342,16 +343,6 @@ Kind: type.
 DescriptorBase & ValueFallback & { kind: "date"; value: DateValueInput; pattern?: string; }
 ```
 
-### `MetadataDensity`
-
-Kind: type.
-
-`compact` tightens the rhythm for a dense panel.
-
-```text
-"default" | "compact"
-```
-
 ### `MetadataEmptyValueDescriptor`
 
 Kind: type.
@@ -404,7 +395,7 @@ when the list is empty, so a caller can render it unconditionally.
 **Alternatives:** Item, FormField.
 
 ```text
-({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings, }: MetadataListProps) => import("react").JSX.Element | null
+({ items, columns, size, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings, }: MetadataListProps) => import("react").JSX.Element | null
 ```
 
 ### `MetadataListItem`
@@ -461,6 +452,16 @@ DescriptorBase & ValueFallback & DisplayOverride & { kind: "mono"; value: Displa
 
 Kind: type.
 
+### `MetadataSize`
+
+Kind: type.
+
+`sm` tightens the rhythm for a dense panel.
+
+```text
+"default" | "sm"
+```
+
 ### `MetadataTextValueDescriptor`
 
 Kind: type.
@@ -571,7 +572,7 @@ Extends: `SeparatorPrimitive.Props`, `Pick<SeparatorPrimitive.Props, "aria-hidde
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `variant` | no | `SeparatorVariant` | How the rule is drawn. Structural, not semantic — a dashed rule is the same divider,<br>drawn as provisional. |
-| `thickness` | no | `string \| number` | The rule's thickness: a CSS length, or a number in pixels. Overrides<br>`--separator-thickness` for this rule, e.g. a seam between panels. |
+| `thickness` | no | `string \| number` | The rule's thickness: a CSS length, or a number in pixels. Overrides the hairline for<br>this rule, e.g. a seam between panels. |
 | `label` | no | `React.ReactNode` | Text set into a gap in the rule — "OR", "More options". Horizontal only. It drops the<br>separator role, because the rule is then decoration around real text. |
 
 ### `SeparatorVariant`
@@ -607,7 +608,186 @@ Extends: `React.ComponentProps<"span">`.
 
 ## Preview recipes
 
-Preview route: Collapsible — `/collapsible`
+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>
+	)
+}
+```
+
+### Compose your own checklist
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { CheckIcon, CircleIcon } from "lucide-react"
+
+import { Accordion } from "themelia-ui/base/accordion"
+import { Button } from "themelia-ui/base/buttons"
+import { IconBadge } from "themelia-ui/base/display"
+import { Progress } from "themelia-ui/base/feedback"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+
+export default function ChecklistBlueprint() {
+	return (
+		<Stack style={{ maxWidth: "34rem", width: "100%" }}>
+			<Progress value={1} max={3} label="1 of 3 steps complete" />
+			<Accordion
+				media="medallion"
+				defaultValue={["invite"]}
+				items={[
+					{
+						value: "profile",
+						title: "Complete your profile",
+						icon: <IconBadge icon={CheckIcon} tone="success" shape="circle" />,
+						content: <Text type="secondary">Name, avatar and time zone are set.</Text>,
+					},
+					{
+						value: "invite",
+						title: "Invite your team",
+						icon: <IconBadge icon={CircleIcon} shape="circle" />,
+						content: (
+							<Stack gap="sm" align="start">
+								<Text type="secondary">Teammates see the same projects and saved views.</Text>
+								<Button>Send invites</Button>
+							</Stack>
+						),
+					},
+					{
+						value: "connect",
+						title: "Connect a data source",
+						icon: <IconBadge icon={CircleIcon} shape="circle" />,
+						content: <Text type="secondary">Postgres, a CSV upload or the REST API.</Text>,
+					},
+				]}
+			/>
+		</Stack>
+	)
+}
+```
+
+### 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>
+	)
+}
+```
+
+### 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>
+	)
+}
+```
 
 ### Collapsible
 
@@ -625,7 +805,7 @@ export default function CollapsibleExample() {
 				</Text>
 			</CollapsibleTrigger>
 			<CollapsibleContent>
-				<Stack gap="sm" style={{ paddingTop: "var(--space-md)" }}>
+				<Stack gap="sm" style={{ paddingTop: "var(--gap-sm)" }}>
 					<Text type="secondary" size="sm">
 						Content that expands to its natural height.
 					</Text>
@@ -650,7 +830,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function ContentBlockSurfaces() {
 	return (
-		<Grid columns={{ base: 1, sm: 2 }} gap="lg">
+		<Grid columns={{ base: 1, sm: 2 }}>
 			{(["plain", "bordered", "muted", "card"] as const).map((surface) => (
 				<GridCell key={surface}>
 					<ContentBlock
@@ -684,7 +864,7 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function ContentBlockFlush() {
 	return (
-		<Grid columns={2} gap="lg">
+		<Grid columns={2}>
 			<GridCell>
 				<ContentBlock surface="card" flush>
 					<ItemGroup ruled>
@@ -692,7 +872,7 @@ export default function ContentBlockFlush() {
 							{ name: "Production", value: "sk_live_••••0b3d" },
 							{ name: "Staging", value: "sk_test_••••a771" },
 						].map((row) => (
-							<Item key={row.name} style={{ paddingInline: "var(--space-xl)" }}>
+							<Item key={row.name} style={{ paddingInline: "var(--padding)" }}>
 								<ItemMedia>
 									<IconBadge icon={KeyRoundIcon} />
 								</ItemMedia>
@@ -737,14 +917,14 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function ContentBlockHeader() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<ContentBlock
 				surface="card"
 				icon={<TruckIcon aria-hidden="true" />}
 				title="Shipment"
 				titleSuffix={<Badge tone="info">In transit</Badge>}
 				headerEnd={
-					<Button tone="neutral" buttonStyle="ghost">
+					<Button tone="neutral" appearance="ghost">
 						Track
 					</Button>
 				}
@@ -770,15 +950,15 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function IconBadgeExample() {
 	return (
-		<Stack gap="xl">
-			<Stack direction="horizontal" gap="lg" wrap align="center">
+		<Stack>
+			<Stack direction="horizontal" wrap align="center">
 				{(["neutral", "primary", "success", "warning", "destructive", "info"] as const).map(
 					(tone) => (
 						<IconBadge key={tone} icon={CreditCardIcon} tone={tone} />
 					),
 				)}
 			</Stack>
-			<Stack direction="horizontal" gap="lg" wrap align="center">
+			<Stack direction="horizontal" wrap align="center">
 				{(["neutral", "primary", "success", "warning", "destructive", "info"] as const).map(
 					(tone) => (
 						<IconBadge key={tone} icon={CreditCardIcon} tone={tone} shape="circle" solid />
@@ -813,7 +993,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="اتجاه من اليمين إلى اليسار">
@@ -844,7 +1024,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function DateBlockExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="start">
+		<Stack direction="horizontal" wrap align="start">
 			<DateBlock date="2026-08-16" />
 			<DateBlock date="2026-12-31" />
 			<DateBlock date="2027-01-04" showYear />
@@ -862,7 +1042,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function DateBlockParts() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="start">
+		<Stack direction="horizontal" wrap align="start">
 			<DateBlock date="2026-09-02" showWeekday={false} />
 			<DateBlock date="2026-09-02" showMonth={false} />
 			<DateBlock date="2026-09-02" showYear />
@@ -921,8 +1101,8 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function DateBlockUnboxed() {
 	return (
-		<Stack gap="lg">
-			<Stack direction="horizontal" gap="xl" wrap align="start">
+		<Stack>
+			<Stack direction="horizontal" wrap align="start">
 				<DateBlock date="2026-08-27" boxed={false} />
 				<DateBlock date="2026-08-27" boxed={false} showWeekday={false} />
 			</Stack>
@@ -944,22 +1124,22 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function InlineStatExample() {
 	return (
-		<Stack gap="xl">
+		<Stack>
 			<Card style={{ maxWidth: "24rem" }}>
 				<CardContent>
-					<Stack gap="md">
+					<Stack gap="sm">
 						<InlineStat label="Subtotal" value="€ 1,240.00" mono />
 						<InlineStat label="Shipping" value="€ 18.50" mono />
 						<InlineStat label="Discount" value={null} mono />
 					</Stack>
 				</CardContent>
 			</Card>
-			<Stack direction="horizontal" gap="2xl" wrap>
+			<Stack direction="horizontal" wrap>
 				<InlineStat layout="inline" label="Region" value="eu-west-1" mono />
 				<InlineStat layout="inline" label="Plan" value="Team" />
 				<InlineStat layout="inline" label="Seats" value="12" mono />
 			</Stack>
-			<Stack direction="horizontal" gap="2xl" wrap>
+			<Stack direction="horizontal" wrap>
 				<InlineStat layout="stacked" label="Open invoices" value="14" mono />
 				<InlineStat layout="stacked" label="Overdue" value="3" mono />
 				<InlineStat layout="stacked" label="Collected" value="€ 48,200.00" mono />
@@ -979,7 +1159,7 @@ import { Text } from "themelia-ui/base/typography"
 export default function KbdExample() {
 	return (
 		<Stack gap="sm">
-			<Stack direction="horizontal" gap="md" align="center">
+			<Stack direction="horizontal" gap="sm" align="center">
 				<Text size="sm" type="secondary">Open the palette with</Text>
 				<Kbd>⌘K</Kbd>
 				<Text size="sm" type="secondary">or</Text>
@@ -987,7 +1167,7 @@ export default function KbdExample() {
 				<Text size="sm" type="secondary">· close with</Text>
 				<Kbd>Esc</Kbd>
 			</Stack>
-			<Stack direction="horizontal" gap="md" align="center">
+			<Stack direction="horizontal" gap="sm" align="center">
 				<Text size="sm" type="secondary">Go to the inbox with</Text>
 				{/* A sequence: G, then I. The wider gap between caps says "in turn". */}
 				<KbdGroup>
@@ -1043,24 +1223,24 @@ const SUMMARY: MetadataInlineListItem[] = [
 
 export default function MetadataInline() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<MetadataList layout="inline" itemSeparator items={SUMMARY} />
-			<MetadataList layout="inline" itemSeparator="—" density="compact" items={SUMMARY} />
+			<MetadataList layout="inline" itemSeparator="—" size="sm" items={SUMMARY} />
 		</Stack>
 	)
 }
 ```
 
-### density
+### size
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 import { MetadataList } from "themelia-ui/base/display"
 
 import { FACTS } from "./data"
 
-export default function MetadataDensity() {
+export default function MetadataSize() {
 	return (
-		<MetadataList density="compact" columns={2} items={FACTS.slice(0, 4)} title="Invoice" titleSeparator />
+		<MetadataList size="sm" columns={2} items={FACTS.slice(0, 4)} title="Invoice" titleSeparator />
 	)
 }
 ```
@@ -1077,13 +1257,13 @@ const SCROLL_FRAME = {
 	maxHeight: "9rem",
 	border: "var(--border-width) solid var(--border)",
 	borderRadius: "var(--radius)",
-	padding: "var(--surface-y) var(--surface-x)",
+	padding: "var(--padding)",
 } as const
 
 export default function ScrollAreaExample() {
 	return (
 		<ScrollArea style={SCROLL_FRAME}>
-			<Stack gap="xs">
+			<Stack gap="sm">
 				{Array.from({ length: 12 }, (_, index) => (
 					<Text key={index} size="sm" type="secondary">
 						Scrollable line {index + 1}
@@ -1103,7 +1283,7 @@ import { Stack } from "themelia-ui/base/structure"
 
 export default function BooleanIndicatorExample() {
 	return (
-		<Stack direction="horizontal" gap="xl">
+		<Stack direction="horizontal">
 			<BooleanIndicator value strings={{ true: "Active", false: "Paused" }} />
 			<BooleanIndicator value={false} strings={{ true: "Active", false: "Paused" }} />
 		</Stack>
@@ -1136,10 +1316,10 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function SeparatorExample() {
 	return (
-		<Stack gap="lg" style={{ width: "100%" }}>
+		<Stack style={{ width: "100%" }}>
 			<Separator />
 			<Separator label="OR" />
-			<Stack direction="horizontal" gap="md" align="center" style={{ height: "1.5rem" }}>
+			<Stack direction="horizontal" gap="sm" align="center" style={{ height: "1.5rem" }}>
 				<Text size="sm">Left</Text>
 				<Separator orientation="vertical" />
 				<Text size="sm">Right</Text>
@@ -1159,24 +1339,24 @@ import { Text } from "themelia-ui/base/typography"
 
 export default function SeparatorVariants() {
 	return (
-		<Stack gap="xl" style={{ maxWidth: "26rem", width: "100%" }}>
-			<Stack gap="xs">
+		<Stack style={{ maxWidth: "26rem", width: "100%" }}>
+			<Stack gap="sm">
 				<Text size="xs" type="secondary">solid</Text>
 				<Separator />
 			</Stack>
-			<Stack gap="xs">
+			<Stack gap="sm">
 				<Text size="xs" type="secondary">dashed</Text>
 				<Separator variant="dashed" />
 			</Stack>
-			<Stack gap="xs">
+			<Stack gap="sm">
 				<Text size="xs" type="secondary">dotted</Text>
 				<Separator variant="dotted" />
 			</Stack>
-			<Stack gap="xs">
+			<Stack gap="sm">
 				<Text size="xs" type="secondary">thickness=&#123;2&#125;</Text>
 				<Separator thickness={2} />
 			</Stack>
-			<Stack direction="horizontal" gap="lg" style={{ height: "3rem" }}>
+			<Stack direction="horizontal" style={{ height: "3rem" }}>
 				<Text size="sm">Vertical</Text>
 				<Separator orientation="vertical" variant="dashed" />
 				<Text size="sm">rules</Text>

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

@@ -15,12 +15,11 @@ Composing a menu anatomy — submenus, radio and checkbox items — from its par
 
 ```tsx fragment — import-only example
 import { DropdownMenu } from "themelia-ui/base/dropdown-menu"
-import "themelia-ui/base/dropdown-menu.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.
@@ -220,9 +219,9 @@ export default function DropdownMenuExample() {
 	const [sort, setSort] = useState("date")
 
 	return (
-		<Stack direction="horizontal" gap="lg">
+		<Stack direction="horizontal">
 			<DropdownMenu>
-				<DropdownMenuTrigger render={<Button buttonStyle="outline" tone="neutral" />}>
+				<DropdownMenuTrigger render={<Button appearance="outline" tone="neutral" />}>
 					Options <ChevronDownIcon />
 				</DropdownMenuTrigger>
 				<DropdownMenuContent>
@@ -268,9 +267,9 @@ import { UIProvider } from "themelia-ui/ui-provider"
 
 export default function DropdownScheme() {
 	return (
-		<Stack direction="horizontal" gap="lg">
+		<Stack direction="horizontal">
 			<DropdownMenu>
-				<DropdownMenuTrigger render={<Button buttonStyle="outline" tone="neutral" />}>
+				<DropdownMenuTrigger render={<Button appearance="outline" tone="neutral" />}>
 					Default <ChevronDownIcon />
 				</DropdownMenuTrigger>
 				<DropdownMenuContent>
@@ -280,7 +279,7 @@ export default function DropdownScheme() {
 			</DropdownMenu>
 			<UIProvider config={{ overlay: { darkMenus: false } }}>
 				<DropdownMenu>
-					<DropdownMenuTrigger render={<Button buttonStyle="outline" tone="neutral" />}>
+					<DropdownMenuTrigger render={<Button appearance="outline" tone="neutral" />}>
 						Follows the page <ChevronDownIcon />
 					</DropdownMenuTrigger>
 					<DropdownMenuContent>