themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/patterns--analytics.md

@@ -20,7 +20,7 @@ import "themelia-ui/patterns/analytics.css"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install recharts
@@ -28,7 +28,7 @@ npm install recharts
 
 ## Composition
 
-This family composes `base/badge`, `base/buttons`, `base/cards`, `base/chart`, `base/display`, `base/feedback`, `base/skeleton`, `base/tooltip`, `base/typography`.
+This module composes `base/badge`, `base/buttons`, `base/cards`, `base/chart`, `base/display`, `base/feedback`, `base/skeleton`, `base/tooltip`, `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.
@@ -237,12 +237,15 @@ Kind: interface.
 
 Kind: interface.
 
+One figure, for every metric surface: formatted once, and moved between surfaces by
+changing the component alone.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `id` | yes | `string` | Stable identity, for list keys. |
 | `label` | yes | `string` |  |
 | `value` | yes | `number \| string \| null` | `null` renders the empty marker rather than collapsing the tile. |
-| `valueType` | no | `MetricValueType` |  |
+| `valueType` | no | `MetricValueType` | How `formatMetricValue` renders the figure. Currency shows the code rather than the<br>symbol, because an admin screen routinely shows several at once and "$" does not say<br>which dollar. |
 | `currency` | no | `string` | ISO 4217, for `valueType: "currency"`. |
 | `change` | no | `MetricChange` |  |
 | `sparkline` | no | `readonly number[]` | Points for the tile's sparkline, in chronological order. |
@@ -278,6 +281,11 @@ Which way the figure moved against its baseline.
 
 Kind: callable.
 
+The one metric on a page allowed to shout. Its ramps come from the categorical chart
+palette, never the state tokens — a hero reports no success and no warning, and painting it
+`--success` would repaint it whenever a consumer retunes the colour that means things went
+right.
+
 ```text
 ({ title, value, change, data, theme, subtitle, className, ...props }: MetricGradientProps) => import("react").JSX.Element
 ```
@@ -336,7 +344,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 | `metrics` | yes | `MetricData[]` |  |
 | `variant` | no | `Extract<MetricVariant, "card" \| "compact" \| "bordered" \| "accent" \| "colored">` | Forwarded to every cell. |
 | `tone` | no | `MetricTone` |  |
-| `columns` | no | `MetricGridColumns` |  |
+| `columns` | no | `MetricGridColumns` | `auto` picks the break points from the cell count. |
 | `showSparklines` | no | `boolean` |  |
 | `showChanges` | no | `boolean` |  |
 | `showIcons` | no | `boolean` |  |
@@ -346,6 +354,11 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 Kind: callable.
 
+Six dense cells, each pairing a figure with a different sketch — deliberately not six
+sparklines, because when every cell draws the same shape a reader scanning the block has
+nothing to tell them apart by except the label. One accent across the whole block: the
+SHAPE is the differentiator, and a hue per cell adds a second, weaker one.
+
 ```text
 ({ cells, className, ...props }: MetricMicroGridProps) => import("react").JSX.Element
 ```
@@ -379,21 +392,25 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `data` | yes | `MetricData` |  |
-| `variant` | no | `MetricVariant` |  |
-| `tone` | no | `MetricTone` | Tints the `bordered` and `colored` variants. |
-| `showSparkline` | no | `boolean` |  |
-| `showChange` | no | `boolean` |  |
-| `showIcon` | no | `boolean` |  |
-| `loading` | no | `boolean` |  |
-| `error` | no | `boolean` |  |
+| `data` | yes | `MetricData` | The figure and what surrounds it: id, label, value, and optionally valueType, currency,<br>change, sparkline, icon, subtitle, footer, trend. One shape for every metric surface. |
+| `variant` | no | `MetricVariant` | Structural only — every variant reads the same data. |
+| `tone` | no | `MetricTone` | Tints the `bordered` and `colored` variants. The kit's vocabulary, so never `danger` or<br>`default`. |
+| `showSparkline` | no | `boolean` | Draws the sparkline. Off drops a part the surrounding surface already states. |
+| `showChange` | no | `boolean` | Draws the change chip. Off drops a part the surrounding surface already states. |
+| `showIcon` | no | `boolean` | Draws the icon. Off drops a part the surrounding surface already states. |
+| `loading` | no | `boolean` | Renders the variant's skeleton, which reserves the resolved tile's height so a grid does<br>not jump when data lands. |
+| `error` | no | `boolean` | Renders the error state in place of the figure. |
 | `strings` | no | `Partial<AnalyticsStrings>` | Overrides this block's own copy. |
-| `progress` | no | `number` | `colored` only — 0–100. |
+| `progress` | no | `number` | `colored` only — 0–100, driving the segmented bar. |
 
 ### `MetricSkeleton`
 
 Kind: callable.
 
+The placeholder a Metric shows while its figure is in flight, per variant — a single
+generic block would be the wrong height for five of the seven, and the reflow that causes
+is the thing a skeleton exists to avoid.
+
 ```text
 ({ variant, className, ...props }: MetricSkeletonProps) => import("react").JSX.Element
 ```
@@ -433,6 +450,11 @@ down is good.
 
 Kind: callable.
 
+The delta beside a figure. Direction and tone are separate props on purpose: the direction
+in `change` is a fact about the number, `trend` is a judgement about it, and for churn,
+refunds or latency the two disagree. A chip that could only derive its colour from the
+arrow would paint a rising error rate green.
+
 ```text
 ({ change, trend, variant, className, ...props }: MetricTrendChipProps) => import("react").JSX.Element
 ```
@@ -551,64 +573,185 @@ Preview route: Analytics — `/analytics`
 ### Metric bar
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetricBar
-  metrics={metrics}
-  period={{ label: "Last 30 days", value: "30d" }}
-  footerText="Updated 10 minutes ago"
-/>
+import { MetricBar } from "themelia-ui/patterns/analytics"
+
+import { METRICS } from "./data"
+
+export default function AnalyticsBar() {
+	return (
+		<MetricBar
+			metrics={METRICS}
+			period={{ label: "Last 30 days", value: "30d" }}
+			footerText="Updated 10 minutes ago"
+		/>
+	)
+}
 ```
 
 ### Metric grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetricGrid metrics={metrics} variant="card" />
+import { MetricGrid } from "themelia-ui/patterns/analytics"
+
+import { METRICS } from "./data"
+
+export default function AnalyticsGrid() {
+	return (
+		<MetricGrid metrics={METRICS} variant="card" />
+	)
+}
 ```
 
 ### Seven variants, one shape
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Metric data={revenue} variant="bordered" />
+import { Stack } from "themelia-ui/base/structure"
+import { Metric, MetricGrid } from "themelia-ui/patterns/analytics"
+
+import { CHURN, FULFILMENT, ORDERS, REVENUE } from "./data"
+
+export default function AnalyticsVariants() {
+	return (
+		<Stack gap="xl">
+			<MetricGrid metrics={[REVENUE, CHURN]} variant="bordered" columns={2} />
+			<MetricGrid metrics={[ORDERS, FULFILMENT]} variant="compact" columns={2} />
+			<MetricGrid metrics={[REVENUE, CHURN]} variant="accent" columns={2} />
+			<Metric data={ORDERS} variant="colored" tone="primary" progress={62} />
+			<Metric data={REVENUE} variant="minimal" />
+		</Stack>
+	)
+}
 ```
 
 ### Comparison
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetricComparison
-  current={{ id: "c", label: "Revenue", value: 48200, valueType: "currency", currency: "EUR" }}
-  previous={{ id: "p", label: "Revenue", value: 42900, valueType: "currency", currency: "EUR" }}
-  currentPeriod="Aug 2026"
-  previousPeriod="Jul 2026"
-/>
+import { MetricComparison } from "themelia-ui/patterns/analytics"
+
+export default function AnalyticsComparison() {
+	return (
+		<MetricComparison
+			current={{ id: "c", label: "Revenue", value: 48_200, valueType: "currency", currency: "EUR" }}
+			previous={{ id: "p", label: "Revenue", value: 42_900, valueType: "currency", currency: "EUR" }}
+			currentPeriod="Aug 2026"
+			previousPeriod="Jul 2026"
+		/>
+	)
+}
 ```
 
 ### Gradient hero
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetricGradient title="Sessions" value="18,204" data={points} theme="ocean" />
+import { MetricGradient } from "themelia-ui/patterns/analytics"
+
+import { SERIES } from "./data"
+
+const HERO = SERIES.map((point) => ({ label: point.month, value: point.sessions }))
+
+export default function AnalyticsHero() {
+	return (
+		<MetricGradient
+			title="Sessions this quarter"
+			value="18,204"
+			subtitle="Across every channel"
+			change={{ value: "9.2%", direction: "up" }}
+			data={HERO}
+			theme="ocean"
+		/>
+	)
+}
 ```
 
 ### Micro grid
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MetricMicroGrid cells={cells} />
+import { MetricMicroGrid } from "themelia-ui/patterns/analytics"
+
+const MICRO = [
+	{ label: "Sessions", value: "18.2k", data: [4, 9, 6, 12, 10, 17] },
+	{ label: "Signups", value: "412", data: [2, 5, 4, 8, 7, 11] },
+	{ label: "Activation", value: "63%", data: [3, 6, 5, 9, 8, 12] },
+	{ label: "Seats used", value: "84 / 120", data: [84, 120] },
+	{ label: "Retention", value: "91%", data: [6, 7, 7, 9, 10, 12] },
+	{ label: "Plan mix", value: "3 tiers", data: [5, 3, 2] },
+]
+
+export default function AnalyticsMicro() {
+	return (
+		<MetricMicroGrid cells={MICRO} />
+	)
+}
 ```
 
 ### Chart card
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ChartCard title="Sessions" config={config} surface="bordered">
-  <AreaChart data={series}>…</AreaChart>
-</ChartCard>
+import { Area, AreaChart, CartesianGrid, XAxis } from "recharts"
+
+import type { ChartConfig } from "themelia-ui/base/chart"
+import { ChartCard } from "themelia-ui/patterns/analytics"
+
+import { SERIES } from "./data"
+
+const CHART_CONFIG = {
+	sessions: { label: "Sessions", color: "var(--chart-1)" },
+} satisfies ChartConfig
+
+export default function AnalyticsChartCard() {
+	return (
+		<ChartCard
+			title="Sessions"
+			description="Six months, all channels."
+			config={CHART_CONFIG}
+			surface="bordered"
+		>
+			<AreaChart data={SERIES}>
+				<CartesianGrid vertical={false} />
+				<XAxis dataKey="month" tickLine={false} axisLine={false} />
+				<Area dataKey="sessions" type="monotone" stroke="var(--color-sessions)" fill="var(--color-sessions)" fillOpacity={0.2} />
+			</AreaChart>
+		</ChartCard>
+	)
+}
 ```
 
 ### Activity heatmap
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ActivityHeatmap data={days} />
+import {
+	ActivityHeatmap, type ActivityHeatmapDay, type ActivityLevel,
+} from "themelia-ui/patterns/analytics"
+
+/* A fixed, cyclic pattern, not random data, for stable visual baselines. */
+const HEATMAP: ActivityHeatmapDay[] = Array.from({ length: 182 }, (_, index) => {
+	const date = new Date("2026-03-02T00:00:00")
+	date.setDate(date.getDate() + index)
+	const weekday = date.getDay()
+	const level = (weekday === 0 || weekday === 6 ? index % 2 : (index % 5) + 1) as ActivityLevel
+	return { date: date.toISOString().slice(0, 10), level: Math.min(level, 4) as ActivityLevel }
+})
+
+export default function AnalyticsHeatmap() {
+	return (
+		<ActivityHeatmap data={HEATMAP} />
+	)
+}
 ```
 
 ### Time ruler
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<TimeRuler hours={hours} currentHour={14} />
+import { TimeRuler } from "themelia-ui/patterns/analytics"
+
+const HOURS = [
+	0, 0, 0, 0, 1, 2, 5, 9, 14, 18, 22, 25,
+	24, 19, 21, 23, 20, 16, 12, 9, 6, 4, 2, 1,
+]
+
+export default function AnalyticsRuler() {
+	return (
+		<TimeRuler hours={HOURS} currentHour={14} />
+	)
+}
 ```

package/docs/generated/components/patterns--onboarding.md

@@ -20,7 +20,7 @@ import "themelia-ui/patterns/onboarding.css"
 
 ## Composition
 
-This family composes `base/accordion`, `base/display`, `base/feedback`, `base/typography`.
+This module composes `base/accordion`, `base/display`, `base/feedback`, `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.
@@ -43,11 +43,11 @@ Extends: `Omit<ComponentProps<"div">, "children" | "onChange" | "defaultValue">`
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `steps` | yes | `ChecklistStep[]` |  |
+| `steps` | yes | `ChecklistStep[]` | id, status, title, and optionally badge, content, disabled. |
 | `defaultExpanded` | no | `string[]` | Uncontrolled starting state. Defaults to the first unfinished step. |
-| `expanded` | no | `string[]` | Controlled. |
-| `onExpandedChange` | no | `(expanded: string[]) => void` |  |
-| `onStepOpen` | no | `(id: string) => void` | Fires when a step opens — for analytics, not for state. |
+| `expanded` | no | `string[]` | The open steps, controlled. Uncontrolled, the checklist opens the first unfinished<br>step. |
+| `onExpandedChange` | no | `(expanded: string[]) => void` | Reports the open steps when a reader opens or closes one. |
+| `onStepOpen` | no | `(id: string) => void` | Fires on the transition into open — for analytics, not for state. |
 | `multiple` | no | `boolean` |  |
 | `surface` | no | `AccordionSurface` |  |
 | `strings` | no | `Partial<ChecklistStrings>` |  |
@@ -102,9 +102,36 @@ Preview route: Timelines, onboarding & admin — `/blocks-admin`
 ### Onboarding checklist
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Checklist
-  steps={[
-    { id: "3", status: "inProgress", title: "Connect a data source", content: <Form /> },
-  ]}
-/>
+import { Badge } from "themelia-ui/base/badge"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Checklist } from "themelia-ui/patterns/onboarding"
+
+export default function BlocksChecklist() {
+	return (
+		<Checklist
+			steps={[
+				{ id: "1", status: "completed", title: "Create your workspace", content: <Text type="secondary">Named and provisioned in eu-west-1.</Text> },
+				{ id: "2", status: "completed", title: "Invite your team", content: <Text type="secondary">Four people accepted.</Text> },
+				{
+					id: "3",
+					status: "inProgress",
+					title: "Connect a data source",
+					badge: <Badge tone="warning">Required</Badge>,
+					content: (
+						<Stack gap="md">
+							<Text type="secondary">Pick where your data lives. You can add more later.</Text>
+							<Stack direction="horizontal" gap="sm" wrap>
+								<Button tone="primary">Connect Postgres</Button>
+								<Button tone="secondary" buttonStyle="outline">Upload a CSV</Button>
+							</Stack>
+						</Stack>
+					),
+				},
+				{ id: "4", status: "pending", title: "Publish your first dashboard", content: <Text type="secondary">Start from a template.</Text> },
+			]}
+		/>
+	)
+}
 ```

package/docs/generated/components/patterns--timelines.md

@@ -20,7 +20,7 @@ import "themelia-ui/patterns/timelines.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/feedback`, `base/timeline`, `base/typography`.
+This module composes `base/badge`, `base/feedback`, `base/timeline`, `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.
@@ -79,7 +79,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `entries` | yes | `ChangelogEntry[]` |  |
+| `entries` | yes | `ChangelogEntry[]` | id, kind, title, and optionally description, version, timestamp, author. `kind` is<br>added \| removed \| modified \| fixed. |
 | `strings` | no | `Partial<ChangelogStrings>` |  |
 
 ### `defaultChangelogStrings`
@@ -156,7 +156,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `milestones` | yes | `Milestone[]` |  |
+| `milestones` | yes | `Milestone[]` | `status` is completed \| inProgress \| upcoming \| blocked. `progress` is drawn only while<br>the milestone is in flight. |
 | `strings` | no | `Partial<MilestonesStrings>` |  |
 
 ### `Step`
@@ -203,7 +203,7 @@ Extends: `Omit<ComponentProps<"div">, "children">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `steps` | yes | `Step[]` |  |
+| `steps` | yes | `Step[]` | `status` is completed \| current \| upcoming. The vertical form also takes per-step<br>`content`. |
 | `strings` | no | `Partial<StepsStrings>` |  |
 
 ### `StepsStrings`
@@ -231,26 +231,88 @@ Preview route: Timelines, onboarding & admin — `/blocks-admin`
 ### Changelog
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ChangelogTimeline
-  entries={[
-    { id: "1", kind: "added", title: "Saved views", version: "v3.4.0", timestamp: "16 Aug" },
-  ]}
-/>
+import { ChangelogTimeline, type ChangelogEntry } from "themelia-ui/patterns/timelines"
+
+const CHANGELOG: ChangelogEntry[] = [
+	{
+		id: "1",
+		kind: "added",
+		title: "Saved views on the data table",
+		description: "A view captures filters, column order and page size.",
+		version: "v3.4.0",
+		timestamp: "16 Aug",
+		author: "Alice Mercer",
+	},
+	{
+		id: "2",
+		kind: "fixed",
+		title: "Sheet no longer traps focus after a nested dialog closes",
+		version: "v3.3.2",
+		timestamp: "12 Aug",
+	},
+	{
+		id: "3",
+		kind: "modified",
+		title: "Badge tones renamed to the semantic set",
+		description: "The default and error tones are gone; use neutral and destructive.",
+		version: "v3.3.0",
+		timestamp: "4 Aug",
+	},
+	{
+		id: "4",
+		kind: "removed",
+		title: "The legacy size prop on Metric",
+		version: "v3.3.0",
+		timestamp: "4 Aug",
+	},
+]
+
+export default function BlocksChangelog() {
+	return (
+		<ChangelogTimeline entries={CHANGELOG} />
+	)
+}
 ```
 
 ### Milestones
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MilestonesTimeline
-  milestones={[
-    { id: "3", title: "Token consolidation", status: "inProgress", progress: 68 },
-  ]}
-/>
+import { MilestonesTimeline, type Milestone } from "themelia-ui/patterns/timelines"
+
+const MILESTONES: Milestone[] = [
+	{ id: "1", title: "Discovery", description: "Interviews with eight teams.", status: "completed", dueDate: "12 Jun" },
+	{ id: "2", title: "Design system audit", status: "completed", dueDate: "3 Jul" },
+	{ id: "3", title: "Token consolidation", description: "1,699 custom properties down to 479.", status: "inProgress", dueDate: "29 Aug", progress: 68 },
+	{ id: "4", title: "Consumer migration", status: "blocked", description: "Waiting on the package release." },
+	{ id: "5", title: "Deprecate the old kit", status: "upcoming", dueDate: "Q4" },
+]
+
+export default function BlocksMilestones() {
+	return (
+		<MilestonesTimeline milestones={MILESTONES} />
+	)
+}
 ```
 
 ### Steps, vertical and horizontal
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Steps steps={steps} />
-<StepsBar steps={steps} />
+import { Stack } from "themelia-ui/base/structure"
+import { Steps, StepsBar, type Step } from "themelia-ui/patterns/timelines"
+
+const STEPS: Step[] = [
+	{ id: "1", title: "Create your workspace", description: "Name it and pick a region.", status: "completed", timestamp: "Done 14 Aug" },
+	{ id: "2", title: "Invite your team", description: "Add the people who need access.", status: "completed", timestamp: "Done 15 Aug" },
+	{ id: "3", title: "Connect a data source", description: "Postgres, BigQuery, or a CSV upload.", status: "current", badge: "Required" },
+	{ id: "4", title: "Publish your first dashboard", description: "Pick a template or start empty.", status: "upcoming" },
+]
+
+export default function BlocksSteps() {
+	return (
+		<Stack gap="2xl">
+			<StepsBar steps={STEPS} />
+			<Steps steps={STEPS} />
+		</Stack>
+	)
+}
 ```