themelia-ui 3.0.0 → 3.2.0

package/docs/generated/components/primitives.md

@@ -15,7 +15,6 @@ Displaying or formatting exactly one read-only value — currency/money, date, e
 
 ```tsx fragment — import-only example
 import { Address } from "themelia-ui/primitives"
-import "themelia-ui/primitives.css"
 ```
 
 ## Composition
@@ -1102,7 +1101,119 @@ Extract<TextProps["type"], "inherit" | "main" | "secondary">
 
 ## Preview recipes
 
-Preview route: Form field — `/form-field`
+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 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} />
+	)
+}
+```
+
+### 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>
+	)
+}
+```
 
 ### Scale
 
@@ -1110,29 +1221,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>
 	)
@@ -1151,9 +1262,9 @@ import { DE, UK, US } from "./data"
 export default function AddressExample() {
 	return (
 		// Captioned with the country code you pass; the name is the address's last line.
-		<Grid columns={{ base: 1, md: 3 }} gap="xl">
+		<Grid columns={{ base: 1, md: 3 }}>
 			{[["GB", UK], ["US", US], ["DE", DE]].map(([label, value]) => (
-				<Stack key={label as string} gap="2xs">
+				<Stack key={label as string} gap="sm">
 					<Text size="xs" type="secondary">country: "{label as string}"</Text>
 					<Address value={value as typeof UK} />
 				</Stack>
@@ -1173,7 +1284,7 @@ import { DE, UK, US } from "./data"
 
 export default function AddressInline() {
 	return (
-		<Stack gap="xs">
+		<Stack gap="sm">
 			<Address value={UK} format="inline" />
 			<Address value={US} format="inline" />
 			<Address value={DE} format="inline" />
@@ -1190,7 +1301,7 @@ import { Address } from "themelia-ui/primitives"
 
 export default function AddressPartial() {
 	return (
-		<Grid columns={{ base: 1, md: 3 }} gap="xl">
+		<Grid columns={{ base: 1, md: 3 }}>
 			<Address value={{ line1: "221B Baker Street", city: "London" }} />
 			<Address value={{ city: "London", postalCode: "NW1 6XE" }} />
 			<Address value={null} />
@@ -1600,7 +1711,7 @@ import { UIProvider } from "themelia-ui/ui-provider"
 
 export default function MoneyProviderExample() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<UIProvider
 				config={{
 					formatting: { locale: "de-DE" },

package/docs/generated/components/theming.md

@@ -30,8 +30,8 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: callable.
 
-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.
+The two shadows from one intensity: the default theme's geometry, with every layer's ink
+scaled so 0.8 reproduces it exactly.
 
 ```text
 ({ intensity }: ThemeElevationRecipe) => ThemeOverrides
@@ -112,6 +112,14 @@ need not import a React feature; `features/theme-tweaker` re-exports them.
 "light" | "dark"
 ```
 
+### `ThemeName`
+
+Kind: type.
+
+```text
+keyof typeof themes
+```
+
 ### `ThemeOverrides`
 
 Kind: type.
@@ -131,6 +139,29 @@ Kind: interface.
 | `primary` | yes | `string` |  |
 | `mode` | no | `ThemeMode` |  |
 
+### `ThemePreset`
+
+Kind: interface.
+
+A ready-made theme: the name a picker shows, one line on what it is for, and the provider
+config it sets. The config reaches past colour: radii, shadows and border weight (`theme`),
+spacing (`density`), type (`typography`), motion, and how components draw themselves
+(`defaults`). Pass `config` to `UIProvider`, or spread it under settings of your own.
+
+| member | required | type | description / documented default |
+| --- | :-: | --- | --- |
+| `label` | yes | `string` |  |
+| `description` | yes | `string` |  |
+| `config` | yes | `UIConfig` |  |
+
+### `themes`
+
+Kind: const.
+
+```text
+{ soft: ThemePreset; sharp: ThemePreset; dense: ThemePreset; editorial: ThemePreset; }
+```
+
 ### `ThemeTypeScaleRecipe`
 
 Kind: interface.
@@ -150,5 +181,117 @@ Kind: type.
 
 ## Preview recipes
 
-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.
+Preview route: Themes — `/themes`
+
+### Four styles
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Switch } from "themelia-ui/base/choice-inputs"
+import { MetadataList } from "themelia-ui/base/display"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { themes, type ThemeName } from "themelia-ui/theming"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+/* Each theme on a region of its own: the nested provider sets its colours, corners, spacing, type and card style there. */
+export default function ThemeGallery() {
+	return (
+		<div style={{ display: "grid", gap: "1.5rem", gridTemplateColumns: "repeat(auto-fit, minmax(18rem, 1fr))", width: "100%" }}>
+			{(Object.keys(themes) as ThemeName[]).map((name) => {
+				const theme = themes[name]
+				return (
+					<UIProvider key={name} config={theme.config}>
+						<Card title={theme.label} description={theme.description}>
+							<Stack gap="sm">
+								<FormField label="Event">
+									<Input defaultValue="Autumn gala" />
+								</FormField>
+								<MetadataList
+									layout="rows"
+									items={[
+										{ label: "Guests", value: "120" },
+										{ label: "Deposit", value: "€2,400 paid" },
+									]}
+								/>
+								<Switch defaultChecked aria-label={`Send reminders, ${theme.label}`} />
+								<Stack direction="horizontal" gap="sm" align="center">
+									<Button>Publish</Button>
+									<Button tone="neutral" appearance="outline">Preview</Button>
+									<Badge tone="primary">Draft</Badge>
+								</Stack>
+							</Stack>
+						</Card>
+					</UIProvider>
+				)
+			})}
+		</div>
+	)
+}
+```
+
+### Switching themes
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { themes, type ThemePreset } from "themelia-ui/theming"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+/* A theme of your own: start from one and change what you need. Here, Sharp with a rose accent and more room. */
+const brand: ThemePreset = {
+	label: "Brand",
+	description: "Sharp's square corners, a rose accent and room to breathe.",
+	config: {
+		...themes.sharp.config,
+		density: "comfortable",
+		theme: {
+			...themes.sharp.config.theme,
+			colors: {
+				...themes.sharp.config.theme?.colors,
+				primary: "light-dark(oklch(0.5 0.19 15), oklch(0.76 0.13 15))",
+				"primary-foreground": "light-dark(oklch(0.985 0 0), oklch(0.2 0.05 15))",
+				ring: "light-dark(oklch(0.56 0.17 15), oklch(0.7 0.12 15))",
+			},
+		},
+	},
+}
+
+const CHOICES: Record<string, ThemePreset | undefined> = { default: undefined, ...themes, brand }
+
+/* Switching a theme is switching which config the provider is handed: the region repaints in place. */
+export default function SwitchThemes() {
+	const [choice, setChoice] = useState("soft")
+
+	return (
+		<Stack style={{ width: "100%", maxWidth: "38rem" }}>
+			<PillRadioGroup
+				aria-label="Theme for this example"
+				name="switch-theme"
+				value={choice}
+				onValueChange={(value) => { if (value) setChoice(value) }}
+				options={Object.entries(CHOICES).map(([value, theme]) => ({ value, label: theme?.label ?? "Default" }))}
+			/>
+			<UIProvider config={CHOICES[choice]?.config ?? {}}>
+				<Card title="Invite your team" description="Teammates see the same projects and saved views.">
+					<Stack gap="sm">
+						<Input aria-label="Email address" placeholder="name@example.com" />
+						<Stack direction="horizontal" gap="sm">
+							<Button>Send invite</Button>
+							<Button tone="neutral" appearance="ghost">Copy link</Button>
+						</Stack>
+					</Stack>
+				</Card>
+			</UIProvider>
+		</Stack>
+	)
+}
+```