themelia-react-ui 2.0.3 → 2.0.5

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

@@ -0,0 +1,55 @@
+---
+name: themelia-design
+description: Use when designing or redesigning a Themelia view from real records, or when a screen works but reads poorly; reads the data for what matters, ranks information, chooses encodings and emphasis, and critiques rendered screens with a scored rubric. Not for component APIs or theme tokens.
+---
+
+# Themelia design
+
+Correct owners and passing checks make a view valid, not clear. This skill adds
+the designer's part: what the view shows, what the eye reaches first, and
+whether the rendered result lets the user decide quickly. Use
+**themelia-composition** for owner selection, surfaces and inset ownership,
+**themelia-components** for installed APIs and **themelia-tokenization** for
+themes and density.
+
+## Work in this order
+
+1. **Read the data.** Read a typical, a large, an exceptional and an empty
+   record, then write the data brief: the decision, three facts that matter, the
+   anomaly, and states to show or omit. See
+   [data reading](../../consumer-skill/references/data-reading.md).
+2. **Write the view spec.** Rank information as must, should, could and omit;
+   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
+   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.
+4. **Build one representative subject**, then the rest of the view.
+5. **Render and critique.** Screenshot 390×844 and 1440×900 in light and dark
+   with the opened, error and accepted states the task touches. Run the census
+   and score the [critique rubric](../../consumer-skill/references/critique-rubric.md).
+6. **Fix and repeat** at most three rounds, then report scores, decisions and
+   what stayed unverified.
+
+## Taste, briefly
+
+[View craft](../../consumer-skill/references/view-craft.md) holds the detail:
+
+- One focal point per view and per region.
+- 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
+  matters, a table for comparable rows, a list for rows that differ.
+- Label only ambiguous values; omit zero and not-applicable counters.
+- Gaps grow outward; few edges; one frame per independent subject.
+- Most improvements remove something. Never add decoration, colours, tokens or
+  anatomy overrides to make a view look designed.
+
+## Delegate to the designer agent
+
+For a whole view or a redesign, run the
+[themelia-ui-designer agent](../../consumer-skill/agents/themelia-ui-designer.md):
+`design` mode builds and self-critiques; `review` mode, in a fresh agent, gives
+an independent read-only score.

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

@@ -0,0 +1,12 @@
+---
+name: themelia-forms
+description: Compatibility route for older Themelia form-skill instructions; use themelia-components for exact bindings and themelia-composition for complete edit/create workflows.
+---
+
+# Themelia forms compatibility route
+
+Use [themelia-components](../themelia-components/SKILL.md) to inspect actual value/event, callback, ref and controlled-state contracts. Use [themelia-composition](../themelia-composition/SKILL.md) for complete edit pages and overlay workflows.
+
+The full [RHF workflows](../../consumer-skill/references/rhf-workflows.md), [typed bindings](../../consumer-skill/examples/rhf-bindings.tsx), [edit page](../../consumer-skill/examples/rhf-edit-page.tsx) and [overlay form](../../consumer-skill/examples/rhf-overlay-form.tsx) remain shared resources. Validation, dirty state, arrays, async transport, failure drafts, accepted-value reset and focus restoration retain their contracts.
+
+This package path is retained for existing instructions. Install the complete current bundle through [installation](../../consumer-skill/references/installation.md); separately installed skills are not replaced automatically.

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

@@ -0,0 +1,15 @@
+---
+name: themelia-foundation
+description: Compatibility route for older Themelia instructions naming themelia-foundation; use the current components, tokenization, composition and design capabilities for new work.
+---
+
+# Themelia foundation compatibility route
+
+The canonical capability split is now:
+
+- [themelia-components](../themelia-components/SKILL.md): installed setup, owner discovery, exact API inspection and framework integration.
+- [themelia-tokenization](../themelia-tokenization/SKILL.md): CSS/theme setup, semantic roots, typography and scoped themes.
+- [themelia-composition](../themelia-composition/SKILL.md): shell/route ownership, screen hierarchy and delivery.
+- [themelia-design](../themelia-design/SKILL.md): data briefs, view specs and rubric-scored critique of rendered views.
+
+Follow the matching capability. [Installation](../../consumer-skill/references/installation.md) explains the complete current bundle. This package path is retained for existing instructions; separately installed skills are not replaced automatically.

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

@@ -0,0 +1,42 @@
+---
+name: themelia-tokenization
+description: Build consistent domain structures with Themelia base/layout components, semantic JSX and token-backed Tailwind; also theme shared spacing, density, typography, colors and portals. Not library maintenance.
+---
+
+# 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.
+
+## Inspect before applying
+
+Resolve installed identity and active CSS through [installation](../../consumer-skill/references/installation.md). Shipped component CSS and app-authored Tailwind compilation are separate setup paths. Override after package styles or inside ThemeScope.
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs gap-space-xl
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs --space-scale
+```
+
+Read overrideRoot and exact spelling. Roots are settings; derived --spacing-*, --radius-* and --container-* aliases are not. Do not read those aliases in scoped calc expressions. The lookup does not index semantic colors; follow its stylesheet/theme reads.
+
+## Compose without drift
+
+Public props/parts own controls, rows, text and surfaces. Stack/Grid/AdaptiveGrid own routine sibling layout. Tailwind owns specialized tracks, parent queries, alignment, overflow and drawing on app markup. A valid token on the wrong owner still drifts: do not repad a public panel/menu or redraw its states. Use fitting domain owners; custom JSX shapes additional relationships.
+
+| Relationship | Public gap / shipped default |
+| --- | --- |
+| Title + description | dense / normal: 2 / 4px |
+| Compact affordances | xs: 4px |
+| Commands | md: 8px |
+| Related fields/content | xl: 16px |
+| Independent subjects/columns | 2xl: 24px |
+| Major page regions | 3xl: 32px |
+
+Page owns gutters, Card owns insets, structures own peer gaps. Card flat removes paint, not its md inset (24px). Use padding none when an ancestor owns that room; align flat/painted peer content edges. A block inside adds no second Card/inset. Read [semantic roles](../../consumer-skill/references/design-contract.md#semantic-roles), not a screenshot's measurements.
+
+Use Heading/Text props for copy roles and primitives for Money/Date/Number/contact/missing values. Semantic tag is separate from visual size. Rich trigger/slot labels can override inherited typography: preserve the owner's label scale, reserving larger headings for the actual subject. Density does not shrink primary content into metadata.
+
+Pair shadcn surfaces/foregrounds. Badges are neutral for categories/counts; status tones communicate status. Numbers use UI sans/tabular figures; MonoValue is for codes. Existing action/control, row, surface, icon/avatar and shell roots cover geometry. --space-scale changes gaps/insets; --density-scale changes controls/rows. First repair duplicated padding and priorities before proposing mobile root changes. Use [theme boundaries](../../consumer-skill/references/theming.md); avoid private recipes, local focus scales, raw palettes and per-component tokens.
+
+## Verify the effect
+
+Vary spacing/density independently. Inspect both themes, narrow/wide parents, text hierarchy, adjoining heights, corners and clipping. Open a real menu/picker/overlay in the scoped theme and verify portal inheritance. Run app checks and [review](../../consumer-skill/references/review.md), execute keyboard/focus and relevant invalid/disabled states, and report source, inspected appearance and behavior separately. No Themelia theme-publishing CLI exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "themelia-react-ui",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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",
@@ -30,6 +30,8 @@
     "README.md",
     "CHANGELOG.md",
     "docs/consumer-skill",
+    "docs/consumer-skills",
+    "templates",
     "THIRD_PARTY_NOTICES.md"
   ],
   "sideEffects": [
@@ -477,7 +479,7 @@
     "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",
-    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-evals.mjs scripts/test-button-codemod.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
+    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-inspection.mjs scripts/test-consumer-mapper.mjs scripts/test-composition-metadata.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-evals.mjs scripts/test-button-codemod.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
     "check:release": "npm run check:all && npm run check:agent && npm run build:docs && npm run check:static-docs"
   },
   "peerDependencies": {

package/templates/README.md

@@ -0,0 +1,39 @@
+# Admin composition examples
+
+These shipped, copyable application blueprints demonstrate `themelia-react-ui` through its public imports. Open `/?page=templates` after `npm run dev` for the shared shell, or use the individual catalogue pages under Templates. They ship in `node_modules/themelia-react-ui/templates/` as source assets, not additional npm entrypoints. Copy and adapt them into the application.
+
+The examples use local, in-memory records. A reload resets them. Connect your app's data loading, persistence, authorization, notification delivery and navigation at the shown callbacks; no backend or authentication service is included. Publishing settings and permissions here describe sample state, not server enforcement.
+
+For production create/edit workflows, adapt the [RHF edit page](../docs/consumer-skill/examples/rhf-edit-page.tsx) and [RHF overlay form](../docs/consumer-skill/examples/rhf-overlay-form.tsx) to these domain screens. Replace their local draft state with RHF values, validation, arrays and dirty tracking, and await the app's complete transport before accepting a saved baseline. The [forms workflow guide](../docs/consumer-skill/references/rhf-workflows.md) supplies typed control bindings and Inertia/TanStack integration seams.
+
+| 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 |
+| [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 |
+| [user-permissions-template.tsx](user-permissions-template.tsx) | `UserPermissionsTemplate` | FormField, DirtyStateBanner, role-based Page save and confirmed suspend commands, role presets and editable permission groups with a saved/discard baseline |
+| [analytics-operations-template.tsx](analytics-operations-template.tsx) | `AnalyticsOperationsTemplate` | Numeric MetricBar KPIs, MetricComparison, ActivityHeatmap, UsageCard and an app-owned operations list |
+
+For layout selection, read the [owner map](../docs/consumer-skill/references/composition.md#structure-and-spacing) and [typed layout-block recipe](../docs/consumer-skill/examples/layout-blocks.tsx). Use horizontal Stack for rows, Grid/GridCell for prescribed columns and spans, AdaptiveGrid for parent-driven equal tiles, and TwoColumnLayout for a main/support split.
+
+## 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.
+- 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
+  collapse. A destructive command is a `destructive: true` secondary action that
+  opens ConfirmDialog. Put subject commands in Card's header. Status/count badges use `titleSuffix`;
+  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.
+- 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.
+
+## Checks
+
+`npm run typecheck`, `npm run lint` and `npm run check:design-lint` include `templates/`. `npm run check:package` also typechecks these sources against the installed tarball, from the installed tarball, alongside the shipped consumer-skill recipes. `node docs/consumer-skill/scripts/check-composition.mjs templates` is a supplementary static review; unresolved dynamic spreads still need source and interaction review.
+
+`tests/browser/templates.spec.ts` covers Card boundaries at desktop/mobile widths in both themes, mobile navigation and contact/credit submission. The dated verification report records the images actually inspected and the checks executed. Static checks and screenshots do not establish backend integration.

package/templates/admin-shell-template.tsx

@@ -0,0 +1,382 @@
+import { useState, type ReactNode } from 'react';
+import {
+	BarChart3,
+	Package,
+	Settings,
+	ShoppingBag,
+	Store,
+	Users,
+} from 'lucide-react';
+
+import { IconBadge } from 'themelia-react-ui/base/display';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { useSidebar } from 'themelia-react-ui/base/sidebar';
+import {
+	type BreadcrumbItem,
+	type LayoutLinkRenderProps,
+	type WorkspaceLink,
+} from 'themelia-react-ui/layout';
+import { AppLayout, type AppLayoutVariant } from 'themelia-react-ui/layout/app-shell';
+import {
+	HeaderBreadcrumbs,
+	HeaderNotifications,
+	HeaderUserMenu,
+	type HeaderNotification,
+	type HeaderUserMenuProps,
+} from 'themelia-react-ui/layout/header';
+import {
+	AppSidebar,
+	LayoutSidebarProvider,
+	SidebarNavigationUser,
+	type AppSidebarProps,
+} from 'themelia-react-ui/layout/sidebar';
+import { Text } from 'themelia-react-ui/typography';
+import {
+	UIProvider,
+	type ComponentScale,
+	type UIConfig,
+} from 'themelia-react-ui/ui-provider';
+
+import { AnalyticsOperationsTemplate } from './analytics-operations-template';
+import { CustomersAdminTemplate } from './customers-template';
+import { OrdersAdminTemplate } from './orders-template';
+import { ProductsAdminTemplate } from './products-template';
+import { UserPermissionsTemplate } from './user-permissions-template';
+
+export type AdminTemplateId =
+	| 'orders'
+	| 'products'
+	| 'customers'
+	| 'user-permissions'
+	| 'analytics';
+
+interface TemplateRouteMeta {
+	id: AdminTemplateId;
+	label: string;
+	url: string;
+	breadcrumbs: BreadcrumbItem[];
+}
+
+const TEMPLATE_ROUTES: Record<AdminTemplateId, TemplateRouteMeta> = {
+	analytics: {
+		id: 'analytics',
+		label: 'Overview',
+		url: '/admin/overview',
+		breadcrumbs: [{ label: 'Store overview' }],
+	},
+	orders: {
+		id: 'orders',
+		label: 'Orders',
+		url: '/admin/orders',
+		breadcrumbs: [
+			{ label: 'Orders', href: '/admin/orders' },
+			{ label: '#1042' },
+		],
+	},
+	products: {
+		id: 'products',
+		label: 'Products',
+		url: '/admin/products',
+		breadcrumbs: [
+			{ label: 'Products', href: '/admin/products' },
+			{ label: 'Merino Wool Crewneck Sweater' },
+		],
+	},
+	customers: {
+		id: 'customers',
+		label: 'Customers',
+		url: '/admin/customers',
+		breadcrumbs: [
+			{ label: 'Customers', href: '/admin/customers' },
+			{ label: 'Elena Rostova' },
+		],
+	},
+	'user-permissions': {
+		id: 'user-permissions',
+		label: 'Settings',
+		url: '/admin/settings',
+		breadcrumbs: [
+			{ label: 'Settings', href: '/admin/settings' },
+			{ label: 'Staff & permissions' },
+		],
+	},
+};
+
+const SIDEBAR_ICON_MAP: NonNullable<AppSidebarProps['iconMap']> = {
+	analytics: BarChart3,
+	orders: ShoppingBag,
+	products: Package,
+	customers: Users,
+	settings: Settings,
+};
+
+const NAVIGATION_GROUPS: NonNullable<AppSidebarProps['navigationGroups']> = {
+	Store: [
+		{
+			label: 'Overview',
+			href: '/admin/overview',
+			icon: 'analytics',
+		},
+		{
+			label: 'Orders',
+			href: '/admin/orders',
+			icon: 'orders',
+			badge: '3',
+		},
+		{
+			label: 'Products',
+			href: '/admin/products',
+			icon: 'products',
+		},
+		{
+			label: 'Customers',
+			href: '/admin/customers',
+			icon: 'customers',
+		},
+	],
+	Settings: [
+		{
+			label: 'Staff & permissions',
+			href: '/admin/settings',
+			icon: 'settings',
+		},
+	],
+};
+
+const WORKSPACE_LINKS: WorkspaceLink[] = [
+	{
+		label: 'Oak & Loom — US Online Store',
+		url: '/admin/overview',
+	},
+];
+
+const CURRENT_USER: NonNullable<HeaderUserMenuProps['user']> = {
+	name: 'Maya Lin',
+	email: 'maya.lin@oakandloom.com',
+	role: 'Store Operations Lead',
+};
+
+const INITIAL_NOTIFICATIONS: HeaderNotification[] = [
+	{
+		id: 'notif-1',
+		title: 'Order #1042 shipped via UPS Ground',
+		description: 'Tracking 1Z999AA10123456784 scanned at Brooklyn hub.',
+		time: '12m ago',
+		tone: 'info',
+		read: false,
+	},
+	{
+		id: 'notif-2',
+		title: 'Low stock alert · Midnight Navy / Large',
+		description: '6 units remaining at Brooklyn Warehouse.',
+		time: '1h ago',
+		tone: 'warning',
+		read: false,
+	},
+	{
+		id: 'notif-3',
+		title: 'Daily Stripe payout deposited',
+		description: '6,420.50 USD settled to operating account.',
+		time: '3h ago',
+		tone: 'success',
+		read: true,
+	},
+];
+
+export const adminStarterUIDefaults: UIConfig = {
+	density: { defaultScale: 'md' },
+	card: {
+		defaultSurface: 'card',
+	},
+	formatting: { locale: 'en-US' },
+	money: { defaultCurrency: 'USD' },
+};
+
+export interface AdminStarterShellProps {
+	defaultTemplate?: AdminTemplateId;
+	activeTemplate?: AdminTemplateId;
+	onTemplateChange?: (template: AdminTemplateId) => void;
+	defaultShellVariant?: AppLayoutVariant;
+	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) => {
+		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;
+		const route = Object.values(TEMPLATE_ROUTES).find((item) => item.url === href);
+		if (route) { event.preventDefault(); onNavigate(route.id); setOpenMobile(false); }
+	}}>{children}</a>;
+}
+
+function TemplateUserMenu({ sidebar = false, onNavigate }: { sidebar?: boolean; onNavigate: (id: AdminTemplateId) => void }) {
+	const { setOpenMobile } = useSidebar();
+	const openSettings = () => { onNavigate('user-permissions'); setOpenMobile(false); };
+	return sidebar ? <SidebarNavigationUser user={CURRENT_USER} onSettings={openSettings} /> : <HeaderUserMenu user={CURRENT_USER} onSettings={openSettings} />;
+}
+
+export function AdminStarterShell({
+	defaultTemplate = 'orders',
+	activeTemplate: controlledTemplate,
+	onTemplateChange,
+	defaultShellVariant = 'inset',
+	children,
+}: AdminStarterShellProps) {
+	const [internalTemplate, setInternalTemplate] = useState<AdminTemplateId>(defaultTemplate);
+	const [notifications, setNotifications] =
+		useState<HeaderNotification[]>(INITIAL_NOTIFICATIONS);
+
+	const activeTemplate = controlledTemplate ?? internalTemplate;
+	const activeMeta = TEMPLATE_ROUTES[activeTemplate];
+
+	const selectTemplate = (next: AdminTemplateId) => {
+		if (controlledTemplate === undefined) {
+			setInternalTemplate(next);
+		}
+		onTemplateChange?.(next);
+	};
+
+	const renderLink = (props: LayoutLinkRenderProps) => <TemplateLink {...props} onNavigate={selectTemplate} />;
+
+	const brandLogo = (
+		<Stack direction="horizontal" align="center" gap="sm" wrap={false}>
+			<IconBadge icon={Store} tone="primary" shape="square" />
+			<Stack gap="none" className="min-w-0">
+				<Text weight="semibold" size="sm" className="truncate">
+					Oak & Loom
+				</Text>
+				<Text size="xs" type="secondary" className="truncate">
+					Online Store
+				</Text>
+			</Stack>
+		</Stack>
+	);
+
+	const sidebarNode = (
+		<AppSidebar
+			className="h-full"
+			logo={brandLogo}
+			collapsedLogo={<IconBadge icon={Store} tone="primary" shape="square" />}
+			workspaceLinks={WORKSPACE_LINKS}
+			navigationGroups={NAVIGATION_GROUPS}
+			iconMap={SIDEBAR_ICON_MAP}
+			currentUrl={activeMeta.url}
+			renderLink={renderLink}
+			searchable
+			slots={{
+				footer: (
+					<TemplateUserMenu sidebar onNavigate={selectTemplate} />
+				),
+			}}
+		/>
+	);
+
+	const breadcrumbsNode = (
+		<HeaderBreadcrumbs
+			homeBreadcrumb={{ label: 'Oak & Loom', href: '/admin/overview' }}
+			breadcrumbs={activeMeta.breadcrumbs}
+			renderLink={renderLink}
+		/>
+	);
+
+	const trailingToolsNode = (
+		<Stack direction="horizontal" align="center" gap="sm" wrap={false}>
+			<HeaderNotifications
+				notifications={notifications}
+				onMarkAllRead={() =>
+					setNotifications((current) =>
+						current.map((item) => ({ ...item, read: true })),
+					)
+				}
+			/>
+			<TemplateUserMenu onNavigate={selectTemplate} />
+		</Stack>
+	);
+
+	const activePageNode =
+		children ??
+		(activeTemplate === 'orders' ? (
+			<OrdersAdminTemplate />
+		) : activeTemplate === 'products' ? (
+			<ProductsAdminTemplate />
+		) : activeTemplate === 'customers' ? (
+			<CustomersAdminTemplate />
+		) : activeTemplate === 'user-permissions' ? (
+			<UserPermissionsTemplate />
+		) : (
+			<AnalyticsOperationsTemplate />
+		));
+
+	return (
+		<LayoutSidebarProvider adaptTo="container" className="h-full min-h-0">
+			{defaultShellVariant === 'sidebar' || defaultShellVariant === 'inset' ? (
+				<AppLayout
+					variant={defaultShellVariant}
+					className="h-full min-h-0"
+					sidebar={sidebarNode}
+					slots={{
+						toolbarStart: breadcrumbsNode,
+						toolbarEnd: trailingToolsNode,
+					}}
+				>
+					{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 }}>
+					{activePageNode}
+				</AppLayout>
+			) : (
+				<AppLayout
+					variant={defaultShellVariant}
+					className="h-full min-h-0"
+					logo={brandLogo}
+					sidebar={sidebarNode}
+					slots={{
+						headerStart: breadcrumbsNode,
+						headerEnd: trailingToolsNode,
+					}}
+				>
+					{activePageNode}
+				</AppLayout>
+			)}
+		</LayoutSidebarProvider>
+	);
+}
+
+export interface AdminTemplatesShowcaseProps extends AdminStarterShellProps {
+	defaultDensity?: ComponentScale;
+}
+
+export function AdminTemplatesShowcase({ defaultDensity = 'md', ...props }: AdminTemplatesShowcaseProps) {
+	return (
+		<UIProvider config={{ ...adminStarterUIDefaults, density: { defaultScale: defaultDensity } }}>
+			<AdminStarterShell {...props} />
+		</UIProvider>
+	);
+}
+
+export function OrdersTemplatePreview() {
+	return <OrdersAdminTemplate />;
+}
+
+export function ProductsTemplatePreview() {
+	return <ProductsAdminTemplate />;
+}
+
+export function CustomersTemplatePreview() {
+	return <CustomersAdminTemplate />;
+}
+
+export function UserPermissionsTemplatePreview() {
+	return <UserPermissionsTemplate />;
+}
+
+export function AnalyticsOperationsTemplatePreview() {
+	return <AnalyticsOperationsTemplate />;
+}
+
+export default AdminTemplatesShowcase;