themelia-react-ui 2.0.5 → 3.0.0

package/docs/consumer-skills/themelia-composition/SKILL.md

@@ -9,9 +9,13 @@ Start with the user's decision, representative records, related entities and edi
 
 Before JSX, settle task, reading priority, action scope and inset owners. Read [screen decisions](../../consumer-skill/references/screen-decisions.md) for new screens/repairs. Optional props are capabilities, not reasons to add navigation, cards or commands.
 
+## Cover the view first
+
+Name an owner per region, reaching for a feature, then a block, then layout and base owners, then an app-owned subject. A simple view has no custom region; a domain view is about 70% owners. [Building views](../../consumer-skill/references/building-views.md) has the need → owner map, plan format and custom-part rules; the [catalogue](../../consumer-skill/references/catalogue.md) lists every component. Build custom subjects the way [templates](../../../templates/README.md) and recipes are built.
+
 ## Let the data shape the subject
 
-Discover task-specific owners before choosing custom markup: product options, variant editing and attached media have different owners from generic controls. Compare their data/state/render seams; use a fitting owner or its parts. Custom JSX shapes additional relationships without requiring an API gap. Read [capability comparison and domain coverage](../../consumer-skill/references/custom-composition.md). More data and a new component name do not establish better composition.
+Discover task-specific owners before choosing custom markup: product options, variant editing and attached media have different owners from generic controls. Compare their data/state/render seams; use a fitting owner or its parts. Custom JSX shapes additional relationships without requiring an API gap. Read [capability comparison and domain coverage](../../consumer-skill/references/custom-composition.md).
 
 ## Choose the seam
 
@@ -23,9 +27,9 @@ Use the [mapper](../../consumer-skill/references/composition-mapping.md) with --
 
 ## Assign geometry once
 
-Page narrow centers one-column forms/details at 48rem; aside infers xl/80rem. Explicit TwoColumnLayout needs Page maxWidth="xl". Collections default to lg/64rem. Settings use Page → SettingsShell → FormSection.
+Page narrow centers one-column forms/details at 48rem; aside infers xl/80rem. Explicit TwoColumnLayout needs Page maxWidth="xl". Collections default to lg/64rem. Settings use Page → AsideNavShell → FormSection.
 
-Explicit maxWidth wins, then narrow, then aside width. Page owns h1, commands, lifecycle, gutters and subject gaps. AuthShell owns auth; Container/Section own sites. Header actions defaultContent preserves responsive commands. Loading precedes error then empty; supply copy/onRetry. Resource shells are migration APIs.
+Explicit maxWidth wins, then narrow, then aside width. Page owns h1, commands, lifecycle, gutters and subject gaps. AuthShell owns auth; Container/Section own sites. Header actions defaultContent preserves responsive commands. Loading precedes error then empty; supply copy/onRetry.
 
 Stack/Grid/AdaptiveGrid own peer relationships; Card owns frame/insets. Card flat removes chrome, not padding; use none under an existing inset owner. Blocks stay card-free unless their purpose is a card. Tailwind owns app-specific tracks/queries/overflow; read [domain structures](../../consumer-skill/references/domain-structures.md).
 

package/docs/consumer-skills/themelia-design/SKILL.md

@@ -22,7 +22,11 @@ themes and density.
    name the focal point; sketch 390 and 1440 wireframes in text; choose an
    encoding per fact. See [view spec](../../consumer-skill/references/view-spec.md)
    and [screen decisions](../../consumer-skill/references/screen-decisions.md).
-3. **Find owners.** Map regions to owners with the finder, mapper and inspector
+3. **Find owners.** Write the coverage plan from
+   [building views](../../consumer-skill/references/building-views.md): one owner per region, reaching
+   for a feature, then a block, then base and layout owners, and marking only
+   the product-specific subject as custom. Scan the
+   [catalogue](../../consumer-skill/references/catalogue.md), then use the finder, mapper and inspector
    described in [discovery](../../consumer-skill/references/discovery.md);
    [archetypes](../../consumer-skill/references/screen-archetypes.md) and
    [metrics](../../consumer-skill/references/analytics.md) give starting points.
@@ -38,6 +42,8 @@ themes and density.
 [View craft](../../consumer-skill/references/view-craft.md) holds the detail:
 
 - One focal point per view and per region.
+- Good design here is choosing and arranging owners, not drawing. A view
+  that looks off usually has hand-written markup where an owner exists.
 - One solid primary command per surface; at most three text levels per region;
   tones only for status that changes the action.
 - Encode by the fact's shape: a figure with its baseline, a trend where shape

package/docs/consumer-skills/themelia-tokenization/SKILL.md

@@ -5,7 +5,7 @@ description: Build consistent domain structures with Themelia base/layout compon
 
 # Themelia tokenization
 
-Use mostly public base components and layout blocks. When a domain needs a particular structure, compose their content with semantic JSX and token-backed Tailwind on app-owned elements. **themelia-components** verifies APIs; **themelia-composition** decides hierarchy; **themelia-design** judges the rendered view. Read [domain structures](../../consumer-skill/references/domain-structures.md) and its executable allocation example; the [design contract](../../consumer-skill/references/design-contract.md) owns shared roles.
+Use mostly public base components and layout blocks; [building views](../../consumer-skill/references/building-views.md) maps needs to owners and the [catalogue](../../consumer-skill/references/catalogue.md) lists them all. When a domain needs a particular structure, compose their content with semantic JSX and token-backed Tailwind on app-owned elements. **themelia-components** verifies APIs; **themelia-composition** decides hierarchy; **themelia-design** judges the rendered view. Read [domain structures](../../consumer-skill/references/domain-structures.md) and its executable allocation example; the [design contract](../../consumer-skill/references/design-contract.md) owns shared roles.
 
 ## Inspect before applying
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "themelia-react-ui",
-  "version": "2.0.5",
+  "version": "3.0.0",
   "description": "A composable React UI library for modern admin applications, built on Base UI and Tailwind with shadcn-compatible themes, shared design tokens, reusable layouts, blocks and workflows.",
   "publishConfig": {
     "access": "public",
@@ -29,6 +29,7 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
+    "MIGRATION.md",
     "docs/consumer-skill",
     "docs/consumer-skills",
     "templates",
@@ -193,10 +194,6 @@
       "types": "./dist/components/base/repeaters/index.d.ts",
       "import": "./dist/base/repeaters.js"
     },
-    "./base/sheet": {
-      "types": "./dist/components/base/sheet/index.d.ts",
-      "import": "./dist/base/sheet.js"
-    },
     "./base/sidebar": {
       "types": "./dist/components/base/sidebar/index.d.ts",
       "import": "./dist/base/sidebar.js"
@@ -337,10 +334,6 @@
       "types": "./dist/components/features/suggestions/index.d.ts",
       "import": "./dist/features/suggestions.js"
     },
-    "./features/sync": {
-      "types": "./dist/components/features/sync/index.d.ts",
-      "import": "./dist/features/sync.js"
-    },
     "./features/table": {
       "types": "./dist/components/features/table/index.d.ts",
       "import": "./dist/features/table.js"
@@ -449,6 +442,10 @@
     "./blocks/analytics/usage-card": {
       "types": "./dist/components/blocks/analytics/usage-card/index.d.ts",
       "import": "./dist/blocks/analytics/usage-card.js"
+    },
+    "./blocks/analytics/charts": {
+      "types": "./dist/components/blocks/analytics/charts/index.d.ts",
+      "import": "./dist/blocks/analytics/charts.js"
     }
   },
   "scripts": {
@@ -457,12 +454,13 @@
     "build:preview": "node scripts/generate-utilities.mjs && vite build --config vite.preview.config.ts",
     "preview": "vite preview --config vite.preview.config.ts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "node scripts/run-unit.mjs",
     "test:watch": "vitest",
     "test:browser": "npm run build:preview && node scripts/run-browser.mjs",
+    "test:browser:quick": "npm run build:preview && node scripts/run-browser.mjs --quick",
     "check:package": "node scripts/check-package.mjs",
-    "check": "npm run check:contract && npm run check:preview && npm run check:docs && npm run lint && npm run check:design-lint && npm run typecheck && npm test && npm run build && npm run check:skill && npm run check:maps && npm run check:package && npm run build:preview",
-    "check:contract": "node --test scripts/test-runtime-ownership.mjs scripts/test-primitive-geometry.mjs scripts/test-source-entrypoints.mjs scripts/test-utility-vocabulary.mjs scripts/test-theme-contrast.mjs scripts/test-theme-modes.mjs && node scripts/check-contract.mjs",
+    "check": "node scripts/run-gate.mjs full",
+    "check:contract": "node --test scripts/test-runtime-ownership.mjs scripts/test-primitive-geometry.mjs scripts/test-source-entrypoints.mjs scripts/test-utility-vocabulary.mjs scripts/test-example-utilities.mjs scripts/test-theme-contrast.mjs scripts/test-theme-modes.mjs && node scripts/check-contract.mjs",
     "lint": "node scripts/generate-utilities.mjs && oxlint src/components src/lib src/preview docs/consumer-skill/examples templates --deny-warnings",
     "check:design-lint": "node scripts/generate-utilities.mjs && node scripts/check-design-lint.mjs",
     "check:preview": "node scripts/check-preview.mjs",
@@ -475,7 +473,7 @@
     "check:docs": "node --test scripts/test-public-docs.mjs && node scripts/refresh-prop-docs.mjs --check",
     "collect:browser": "npm run build:preview && node scripts/run-browser.mjs --collectors",
     "check:all": "npm run check && node scripts/run-browser.mjs",
-    "check:quick": "npm run check:contract && npm run lint && npm run check:design-lint && npm run typecheck && npm test && npm run build",
+    "check:quick": "node scripts/run-gate.mjs quick",
     "check:maps": "node scripts/test-client-boundaries.mjs --built",
     "build:docs": "node scripts/build-static-docs.mjs",
     "check:static-docs": "node scripts/check-static-docs.mjs",
@@ -521,6 +519,7 @@
     "hast-util-sanitize": "^5.0.2",
     "hast-util-to-html": "^9.0.5",
     "react-resizable-panels": "^4.11.2",
+    "style-to-js": "^1.1.21",
     "tailwind-merge": "^3.5.0",
     "zustand": "^5.0.12"
   },

package/templates/README.md

@@ -8,7 +8,7 @@ For production create/edit workflows, adapt the [RHF edit page](../docs/consumer
 
 | File | Export | Composition demonstrated |
 | --- | --- | --- |
-| [admin-shell-template.tsx](admin-shell-template.tsx) | `AdminStarterShell`, `AdminTemplatesShowcase` | UIProvider defaults, all five AppLayout presets, AppSidebar, workspace context, breadcrumbs, notifications and account/settings menus |
+| [admin-shell-template.tsx](admin-shell-template.tsx) | `AdminStarterShell`, `AdminTemplatesShowcase` | UIProvider defaults, all five AppLayout presets with a skip link, AppSidebar, NavigationTabs route links for the stacked preset, workspace context, breadcrumbs, notifications derived from each item's `read` flag and account/settings menus |
 | [orders-template.tsx](orders-template.tsx) | `OrdersAdminTemplate` | Page with a fulfillment primary command, TwoColumnLayout, Card, lifecycle-grouped Item rows, MetadataList, Money, AddressCard, PaymentMethod, ActivityLog and refund/tracking/note dialogs |
 | [products-template.tsx](products-template.tsx) | `ProductsAdminTemplate` | ProductVariantsManager, ProductVariantDetails/Editor, SeoListingCard, publishing/organization forms and variant duplication |
 | [customers-template.tsx](customers-template.tsx) | `CustomersAdminTemplate` | MetricBar, DataTable order history, MetadataList, AddressCard, ActivityLog, contact drafts and validated store-credit submission |
@@ -20,7 +20,7 @@ For layout selection, read the [owner map](../docs/consumer-skill/references/com
 ## Boundaries to preserve when adapting
 
 - `AdminTemplatesShowcase` supplies UIProvider defaults; embedded preview pages inherit the catalogue's provider. `AdminStarterShell` inherits the application's provider. `defaultDensity` belongs to the standalone showcase.
-- Page owns gutters and the default resource measure, TwoColumnLayout owns the main/aside split, and Stack/Grid own peer gaps. These record and overview routes keep the default measure; only a wide directory or comparison opts into `maxWidth="full"`. Ordinary Cards retain the default padding. Compact control density does not shrink Cards. Peer Card stacks use `gap="2xl"`, matching Page and TwoColumnLayout’s 24px default rhythm in both axes; copy and form groups keep their own gaps.
+- Page owns gutters and the default resource measure, TwoColumnLayout owns the main/aside split, and Stack/Grid own peer gaps. Inside a Page the split uses `adaptTo="container"`, so it follows the page's own width beside a docked sidebar instead of the viewport. In the stacked shell the contained measure owns the inline gutter and each Page keeps its defaults. These record and overview routes keep the default measure; only a wide directory or comparison opts into `maxWidth="full"`. Ordinary Cards retain the default padding. Compact control density does not shrink Cards. Peer Card stacks use `gap="2xl"`, matching Page and TwoColumnLayout’s 24px default rhythm in both axes; copy and form groups keep their own gaps.
 - A headed address, payment, SEO or variants panel uses its own `surface="card"`. It delegates to Card's aligned header/body anatomy and inherits provider separators. Do not wrap it in an untitled padded Card. Omitted surface keeps these blocks unframed for embedding; an embedded header does not inherit an unintended Card separator.
 - Put page commands in Page's header as `primaryAction` (one) and ordered
   `secondaryActions`; the header owns their treatment, overflow and narrow-width
@@ -29,6 +29,7 @@ For layout selection, read the [owner map](../docs/consumer-skill/references/com
   a status shown in the page header is not repeated in a card or fact list. Spacing separates a card's header, body and footer; a body separator is appropriate only between distinct body sections.
 - Metrics use numeric values and formatting hints. Context such as “12 orders” belongs in a subtitle; it is not a directional trend. The analytics period changes the KPI strip; comparisons, heatmap and quota data are separately described monthly/current snapshots.
 - Overlay edits start from a snapshot and update committed display state only on Save. Native forms use `formId` so required fields and submission ownership are preserved. App persistence should use the overlay's async contract with pending/error/retry handling before committing; do not bind a draft editor directly to committed record data.
+- Ids for unsaved rows come from a local counter (`useId` plus a ref). `crypto.randomUUID()` exists only in secure contexts and throws on a LAN dev server; let the server assign the real id on save.
 - Local sidebar navigation preserves native link modifiers and closes the mobile drawer. Replace the local route map with your router adapter and record-aware destinations. Sample records across these pages are independent; a customer route is not an order's customer resolver.
 - Choose the component that fits the subject. A lifecycle-specific order item group can use Item; editable permission groups can use ToggleField. Do not replace them with an unrelated block merely to increase the component count.
 

package/templates/admin-shell-template.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from 'react';
+import { useState, type MouseEvent, type ReactNode } from 'react';
 import {
 	BarChart3,
 	Package,
@@ -9,8 +9,8 @@ import {
 } from 'lucide-react';
 
 import { IconBadge } from 'themelia-react-ui/base/display';
+import { NavigationTabs, type NavigationTabItem } from 'themelia-react-ui/base/navigation';
 import { Stack } from 'themelia-react-ui/base/structure';
-import { useSidebar } from 'themelia-react-ui/base/sidebar';
 import {
 	type BreadcrumbItem,
 	type LayoutLinkRenderProps,
@@ -28,6 +28,7 @@ import {
 	AppSidebar,
 	LayoutSidebarProvider,
 	SidebarNavigationUser,
+	useLayoutSidebar,
 	type AppSidebarProps,
 } from 'themelia-react-ui/layout/sidebar';
 import { Text } from 'themelia-react-ui/typography';
@@ -102,6 +103,20 @@ const TEMPLATE_ROUTES: Record<AdminTemplateId, TemplateRouteMeta> = {
 	},
 };
 
+/** The same destinations as the sidebar, in its order, as route tabs for the stacked shell's header. */
+const STACKED_NAVIGATION: NavigationTabItem[] = (['analytics', 'orders', 'products', 'customers', 'user-permissions'] as const).map((id) => ({
+	id,
+	title: TEMPLATE_ROUTES[id].label,
+	href: TEMPLATE_ROUTES[id].url,
+}));
+
+/** A plain primary click is the app's to route; a modified one opens the real destination in the browser. */
+function isPlainClick(event: MouseEvent<HTMLAnchorElement>) {
+	return !event.defaultPrevented && event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+}
+
+const SKIP_TO_CONTENT_LABEL = 'Skip to content';
+
 const SIDEBAR_ICON_MAP: NonNullable<AppSidebarProps['iconMap']> = {
 	analytics: BarChart3,
 	orders: ShoppingBag,
@@ -200,19 +215,19 @@ export interface AdminStarterShellProps {
 	children?: ReactNode;
 }
 
-function TemplateLink({ href, children, active, disabled, external, target, rel, onClick, onNavigate, ...props }: LayoutLinkRenderProps & { onNavigate: (id: AdminTemplateId) => void }) {
-	const { setOpenMobile } = useSidebar();
-	return <a {...props} href={disabled ? undefined : href} target={target ?? (external ? '_blank' : undefined)} rel={rel ?? (external ? 'noopener noreferrer' : undefined)} aria-current={active ? 'page' : undefined} aria-disabled={disabled || undefined} onClick={(event) => {
+/** The router seam: a real app renders its router's Link here. Navigation owners pass `aria-current` ready to spread. */
+function TemplateLink({ href, children, active: _active, disabled, external, target, rel, onClick, onNavigate, ...props }: LayoutLinkRenderProps & { onNavigate: (id: AdminTemplateId) => void }) {
+	return <a {...props} href={disabled ? undefined : href} target={target ?? (external ? '_blank' : undefined)} rel={rel ?? (external ? 'noopener noreferrer' : undefined)} aria-disabled={disabled || undefined} onClick={(event) => {
 		onClick?.(event);
 		if (disabled) { event.preventDefault(); return; }
-		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || external || (target && target !== '_self')) return;
+		if (!isPlainClick(event) || external || (target && target !== '_self')) return;
 		const route = Object.values(TEMPLATE_ROUTES).find((item) => item.url === href);
-		if (route) { event.preventDefault(); onNavigate(route.id); setOpenMobile(false); }
+		if (route) { event.preventDefault(); onNavigate(route.id); }
 	}}>{children}</a>;
 }
 
 function TemplateUserMenu({ sidebar = false, onNavigate }: { sidebar?: boolean; onNavigate: (id: AdminTemplateId) => void }) {
-	const { setOpenMobile } = useSidebar();
+	const { setOpenMobile } = useLayoutSidebar();
 	const openSettings = () => { onNavigate('user-permissions'); setOpenMobile(false); };
 	return sidebar ? <SidebarNavigationUser user={CURRENT_USER} onSettings={openSettings} /> : <HeaderUserMenu user={CURRENT_USER} onSettings={openSettings} />;
 }
@@ -283,6 +298,7 @@ export function AdminStarterShell({
 
 	const trailingToolsNode = (
 		<Stack direction="horizontal" align="center" gap="sm" wrap={false}>
+			{/* The unread badge and "Mark all as read" follow each notification's `read` flag. */}
 			<HeaderNotifications
 				notifications={notifications}
 				onMarkAllRead={() =>
@@ -315,6 +331,7 @@ export function AdminStarterShell({
 				<AppLayout
 					variant={defaultShellVariant}
 					className="h-full min-h-0"
+					skipToContentLabel={SKIP_TO_CONTENT_LABEL}
 					sidebar={sidebarNode}
 					slots={{
 						toolbarStart: breadcrumbsNode,
@@ -324,15 +341,37 @@ export function AdminStarterShell({
 					{activePageNode}
 				</AppLayout>
 			) : defaultShellVariant === 'stacked' ? (
-				<AppLayout variant="stacked" className="h-full min-h-0" logo={brandLogo}
-					nav={<Stack direction="horizontal" gap="lg">{Object.values(TEMPLATE_ROUTES).map((route) => <TemplateLink key={route.id} href={route.url} active={route.id === activeTemplate} onNavigate={selectTemplate}>{route.label}</TemplateLink>)}</Stack>}
-					slots={{ headerEnd: trailingToolsNode }}>
+				// The stacked shell's contained measure owns the page gutter, so each
+				// route Page keeps its defaults. Its navigation is route tabs: real
+				// links that bring their own landmark, so the shell's region is a div.
+				<AppLayout
+					variant="stacked"
+					className="h-full min-h-0"
+					skipToContentLabel={SKIP_TO_CONTENT_LABEL}
+					logo={brandLogo}
+					navAs="div"
+					nav={
+						<NavigationTabs
+							items={STACKED_NAVIGATION}
+							currentPath={activeMeta.url}
+							strings={{ tabsAria: 'Primary navigation' }}
+							onSelect={(item, event) => {
+								const route = Object.values(TEMPLATE_ROUTES).find((candidate) => candidate.url === item.href);
+								if (!route || !isPlainClick(event)) return;
+								event.preventDefault();
+								selectTemplate(route.id);
+							}}
+						/>
+					}
+					slots={{ headerEnd: trailingToolsNode }}
+				>
 					{activePageNode}
 				</AppLayout>
 			) : (
 				<AppLayout
 					variant={defaultShellVariant}
 					className="h-full min-h-0"
+					skipToContentLabel={SKIP_TO_CONTENT_LABEL}
 					logo={brandLogo}
 					sidebar={sidebarNode}
 					slots={{

package/templates/analytics-operations-template.tsx

@@ -18,14 +18,8 @@ import {
 	ItemTitle,
 } from 'themelia-react-ui/base/item';
 import { Grid, Stack } from 'themelia-react-ui/base/structure';
-import {
-	ActivityHeatmap,
-	MetricBar,
-	MetricComparison,
-	UsageCard,
-	type ActivityHeatmapDay,
-	type MetricData,
-} from 'themelia-react-ui/blocks/analytics';
+import { ActivityHeatmap, MetricComparison, UsageCard, type ActivityHeatmapDay, type MetricData } from 'themelia-react-ui/blocks/analytics';
+import { MetricBar } from 'themelia-react-ui/blocks/analytics/charts';
 import { MetadataList } from 'themelia-react-ui/base/metadata-list';
 import { ActivityLog, type ActivityLogEntry } from 'themelia-react-ui/features/activities';
 import { TwoColumnLayout } from 'themelia-react-ui/layout/containers';
@@ -199,27 +193,29 @@ export function AnalyticsOperationsTemplate({
 			header={{
 				title: 'Store overview',
 				description: 'Sales KPIs for the selected period, with monthly comparisons and a current operations snapshot.',
-				titleBadges: [{ label: 'Live', tone: 'success' }],
-				// A period choice is a control, not a command, so it stays in `actions`.
-				actions: (
-					<Select
-						aria-label="Reporting period"
-						options={[
-							{ value: '7d', label: 'Last 7 days' },
-							{ value: '30d', label: 'Last 30 days' },
-						]}
-						value={period}
-						onValueChange={(value) => {
-							if (value === '7d' || value === '30d') setPeriod(value);
-						}}
-					/>
-				),
+				slots: { titleSuffix: <Badge tone="success">Live</Badge> },
 			}}
+			// A period choice is a control, not a command, so it sits in the page toolbar.
+			toolbar={
+				<Select
+					className="w-auto"
+					aria-label="Reporting period"
+					options={[
+						{ value: '7d', label: 'Last 7 days' },
+						{ value: '30d', label: 'Last 30 days' },
+					]}
+					value={period}
+					onValueChange={(value) => {
+						if (value === '7d' || value === '30d') setPeriod(value);
+					}}
+				/>
+			}
 		>
 			<Stack gap="2xl">
 				<MetricBar metrics={kpiMetrics} />
 
 				<TwoColumnLayout
+					adaptTo="container"
 					stickyAside
 					main={
 						<Stack gap="2xl">
@@ -364,7 +360,7 @@ export function AnalyticsOperationsTemplate({
 								title="Recent activity"
 								description="Latest carrier pickups, payouts, and catalog updates."
 							>
-								<ActivityLog bare entries={STORE_ACTIVITY} itemSpacing="compact" />
+								<ActivityLog title={false} entries={STORE_ACTIVITY} itemSpacing="compact" />
 							</Card>
 						</Stack>
 					}

package/templates/customers-template.tsx

@@ -16,7 +16,7 @@ import { DecimalInput } from 'themelia-react-ui/base/forms-numeric';
 import { Grid, Stack } from 'themelia-react-ui/base/structure';
 import { Input, Textarea } from 'themelia-react-ui/base/text-inputs';
 import { PhoneInput, TagsInput } from 'themelia-react-ui/base/value-inputs';
-import { MetricBar, type MetricData } from 'themelia-react-ui/blocks/analytics';
+import { MetricBar, type MetricData } from 'themelia-react-ui/blocks/analytics/charts';
 import { AddressCard } from 'themelia-react-ui/blocks/commerce';
 import { MetadataList } from 'themelia-react-ui/base/metadata-list';
 import { ActivityLog, type ActivityLogEntry } from 'themelia-react-ui/features/activities';
@@ -25,7 +25,7 @@ import { DataTable } from 'themelia-react-ui/features/table';
 import { TwoColumnLayout } from 'themelia-react-ui/layout/containers';
 import { Page } from 'themelia-react-ui/layout/page';
 import { Date as DateValue, Money, useMoneyFormatter } from 'themelia-react-ui/primitives';
-import { Text } from 'themelia-react-ui/typography';
+import { Heading, Text } from 'themelia-react-ui/typography';
 
 interface CustomerOrderSummary {
 	id: string;
@@ -279,28 +279,31 @@ export function CustomersAdminTemplate() {
 				<MetricBar metrics={customerMetrics} />
 
 				<TwoColumnLayout
+					adaptTo="container"
 					stickyAside
 					main={
 						<Stack gap="2xl">
-							<Card
-								title="Orders placed"
-								titleSuffix={<Badge tone="neutral">{CUSTOMER_ORDERS.length}</Badge>}
-								description="Orders placed across Online Store and SoHo POS."
-							>
-								<DataTable<CustomerOrderSummary>
-									columns={orderColumns}
-									data={CUSTOMER_ORDERS}
-									surface="flat"
-									enableSorting
-									getRowId={(order) => order.id}
-								/>
-							</Card>
+							<DataTable<CustomerOrderSummary>
+								columns={orderColumns}
+								data={CUSTOMER_ORDERS}
+								topbarContent={
+									<Stack gap="dense">
+										<Stack direction="horizontal" align="center" gap="md" wrap>
+											<Heading tag="h2" size="base" className="text-inherit">Orders placed</Heading>
+											<Badge tone="neutral">{CUSTOMER_ORDERS.length}</Badge>
+										</Stack>
+										<Text size="xs" type="secondary">Orders placed across Online Store and SoHo POS.</Text>
+									</Stack>
+								}
+								enableSorting
+								getRowId={(order) => order.id}
+							/>
 
 							<Card
 								title="Timeline"
 								description="Order history, address changes, and store credit adjustments."
 							>
-								<ActivityLog bare entries={activityEntries} itemSpacing="compact" />
+								<ActivityLog title={false} entries={activityEntries} itemSpacing="compact" />
 							</Card>
 						</Stack>
 					}
@@ -361,13 +364,15 @@ export function CustomersAdminTemplate() {
 							<AddressCard
 								surface="card"
 								kind="shipping"
-								name={customerName}
-								line1="214 Mercer Street"
-								line2="Apt 4B"
-								city="New York, NY"
-								postalCode="10012"
-								country="United States"
-								phone="+1 (212) 555-0192"
+								address={{
+									name: customerName,
+									line1: '214 Mercer Street',
+									line2: 'Apt 4B',
+									city: 'New York, NY',
+									postalCode: '10012',
+									country: 'United States',
+									phone: '+1 (212) 555-0192',
+								}}
 								default
 							/>
 
@@ -418,7 +423,7 @@ export function CustomersAdminTemplate() {
 			>
 				<form id={contactFormId} onSubmit={(event) => { event.preventDefault(); saveContact(); }}>
 				<Stack gap="xl">
-					<FormSection title="Contact information">
+					<FormSection title="Contact information" surface="flat" padding="none">
 						<Grid columns={{ base: 1, sm: 2 }} gap="lg">
 							<FormField label="Full name" required>
 								<Input
@@ -477,7 +482,7 @@ export function CustomersAdminTemplate() {
 				formId={creditFormId}
 			>
 				<form id={creditFormId} onSubmit={(event) => { event.preventDefault(); handleIssueStoreCredit(); }}>
-				<FormSection title="Store credit adjustment">
+				<FormSection title="Store credit adjustment" surface="flat" padding="none">
 					<FormField
 						label="Credit amount (USD)"
 						required

package/templates/index.ts

@@ -18,12 +18,6 @@ export { ProductsAdminTemplate } from './products-template';
 
 export { CustomersAdminTemplate } from './customers-template';
 
-export {
-	UserPermissionsTemplate,
-	UserPermissionsTemplate as UserPermissionsAdminTemplate,
-} from './user-permissions-template';
+export { UserPermissionsTemplate } from './user-permissions-template';
 
-export {
-	AnalyticsOperationsTemplate,
-	AnalyticsOperationsTemplate as AnalyticsOperationsAdminTemplate,
-} from './analytics-operations-template';
+export { AnalyticsOperationsTemplate } from './analytics-operations-template';

package/templates/orders-template.tsx

@@ -443,16 +443,15 @@ export function OrdersAdminTemplate() {
 			header={{
 				title: 'Order #1042',
 				description: 'October 14, 2026 at 2:14 pm · Online Store',
-				titleBadges: [
-					{
-						label: totalRefundedAmount > 0 ? 'Partially refunded' : 'Paid',
-						tone: totalRefundedAmount > 0 ? 'warning' : 'success',
-					},
-					{
-						label: unfulfilledUnitCount > 0 ? 'Partially fulfilled' : 'Fulfilled',
-						tone: unfulfilledUnitCount > 0 ? 'info' : 'success',
-					},
-				],
+				slots: {
+					// Payment and fulfilment status sit directly after the title.
+					titleSuffix: (
+						<Stack direction="horizontal" gap="sm" wrap>
+							<Badge tone={totalRefundedAmount > 0 ? 'warning' : 'success'}>{totalRefundedAmount > 0 ? 'Partially refunded' : 'Paid'}</Badge>
+							<Badge tone={unfulfilledUnitCount > 0 ? 'info' : 'success'}>{unfulfilledUnitCount > 0 ? 'Partially fulfilled' : 'Fulfilled'}</Badge>
+						</Stack>
+					),
+				},
 				// Fulfillment is the order's next step, so it is the route's one primary command
 				// while physical items remain unfulfilled.
 				primaryAction: {
@@ -464,6 +463,7 @@ export function OrdersAdminTemplate() {
 			}}
 		>
 			<TwoColumnLayout
+				adaptTo="container"
 				stickyAside
 				main={
 					<Stack gap="2xl">
@@ -838,7 +838,7 @@ export function OrdersAdminTemplate() {
 
 						{/* Order Timeline */}
 						<Card title="Timeline">
-							<ActivityLog bare entries={timeline} itemSpacing="compact" />
+							<ActivityLog title={false} entries={timeline} itemSpacing="compact" />
 						</Card>
 					</Stack>
 				}
@@ -888,25 +888,29 @@ export function OrdersAdminTemplate() {
 							surface="card"
 							kind="shipping"
 							default
-							name="Ava Bennett"
-							line1="214 Mercer Street"
-							line2="Apt 4B"
-							city="New York, NY"
-							postalCode="10012"
-							country="United States"
-							phone="+1 (212) 555-0148"
+							address={{
+								name: 'Ava Bennett',
+								line1: '214 Mercer Street',
+								line2: 'Apt 4B',
+								city: 'New York, NY',
+								postalCode: '10012',
+								country: 'United States',
+								phone: '+1 (212) 555-0148',
+							}}
 						/>
 
 						{/* Billing Address Card */}
 						<AddressCard
 							surface="card"
 							kind="billing"
-							name="Ava Bennett"
-							line1="214 Mercer Street"
-							line2="Apt 4B"
-							city="New York, NY"
-							postalCode="10012"
-							country="United States"
+							address={{
+								name: 'Ava Bennett',
+								line1: '214 Mercer Street',
+								line2: 'Apt 4B',
+								city: 'New York, NY',
+								postalCode: '10012',
+								country: 'United States',
+							}}
 						/>
 
 						{/* Payment Method Card */}

package/templates/products-template.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { useId, useMemo, useRef, useState } from 'react';
 
 import { Badge } from 'themelia-react-ui/base/badge';
 import { Card } from 'themelia-react-ui/base/cards';
@@ -315,8 +315,17 @@ export function ProductsAdminTemplate() {
 		variantDrawer.show();
 	};
 
+	// Local ids for unsaved variants. `crypto.randomUUID()` exists only in secure
+	// contexts, so it throws on a LAN dev server; the server assigns the real id on save.
+	const variantIdPrefix = useId();
+	const variantIdCount = useRef(0);
+	const createVariantId = () => {
+		variantIdCount.current += 1;
+		return `${variantIdPrefix}new-variant-${variantIdCount.current}`;
+	};
+
 	const duplicateVariant = (variant: ProductVariantRow) => {
-		const copy = { ...variant, id: crypto.randomUUID(), sku: `${String(variant.sku ?? 'MWC')}-COPY` };
+		const copy = { ...variant, id: createVariantId(), sku: `${String(variant.sku ?? 'MWC')}-COPY` };
 		setVariantState((current) => [...current, copy]);
 		return copy;
 	};
@@ -368,7 +377,7 @@ export function ProductsAdminTemplate() {
 					productDirty ? 'Unsaved product changes' : savedRevision !== null
 						? `Saved revision #${savedRevision} · Updated just now`
 						: `Men’s Knitwear · ${variantState.length} variants (${totalInventory} in stock)`,
-				titleBadges: [{ label: productStatus, tone: statusBadgeTone }],
+				slots: { titleSuffix: <Badge tone={statusBadgeTone}>{productStatus}</Badge> },
 				primaryAction: {
 					label: 'Save product',
 					disabled: !productDirty,
@@ -378,6 +387,7 @@ export function ProductsAdminTemplate() {
 			}}
 		>
 			<TwoColumnLayout
+				adaptTo="container"
 				stickyAside
 				main={
 					<Stack gap="2xl">
@@ -453,7 +463,7 @@ export function ProductsAdminTemplate() {
 								setVariantState((current) => [
 									...current,
 									{
-										id: crypto.randomUUID(),
+										id: createVariantId(),
 										name: 'Heather Gray / Large',
 										sku: `MWC-GRY-L-${nextIndex}`,
 										price: '145.00',