admin-ui-starter-kit 0.5.0 → 0.6.1

package/.agents/skills/component-library-rules/references/components/docs__showcase.md

@@ -0,0 +1,197 @@
+---
+id: docs/showcase
+title: "Showcase"
+description: "How to use this preview app as the package map, design review surface, and release verification aid."
+layer: docs
+family: "Start here"
+sourcePath: src/preview
+examples:
+  - ShowcaseWorkflow
+  - SearchTargets
+  - RouteShortcuts
+  - InteractionChecks
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/base/display
+  - @/components/typography
+tags:
+  - docs
+  - start
+  - here
+  - preview
+  - showcase
+  - how
+  - app
+  - package
+---
+
+# Showcase
+
+How to use this preview app as the package map, design review surface, and release verification aid.
+
+**Layer:** `docs`
+**Source:** `src/preview`
+
+## Workflow
+
+<Example name="ShowcaseWorkflow" source={examplesSource} layout="flush">
+	<Examples.ShowcaseWorkflow />
+</Example>
+
+## Search
+
+The sidebar search is global. It should find docs pages, package layers,
+component families, route ids, and token surfaces. The CSS variables page also
+has its own variable-level search table for token names, utilities, scopes, and
+purposes.
+
+<Example name="SearchTargets" source={examplesSource} layout="flush">
+	<Examples.SearchTargets />
+</Example>
+
+## Shortcuts
+
+<Example name="RouteShortcuts" source={examplesSource} layout="center">
+	<Examples.RouteShortcuts />
+</Example>
+
+## Examples
+
+```tsx
+import {
+	CheckCircle2,
+	Code2,
+	Eye,
+	FileSearch,
+	MousePointer2,
+	PanelsTopLeft } from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { IconBadge,
+} from '@/components/base/display';
+import { Text } from '@/components/typography';
+
+const WORKFLOW = [
+	{
+		icon: PanelsTopLeft,
+		title: 'Browse',
+		description: 'Use the sidebar groups for docs, base, layouts, composed surfaces, and features.',
+		tone: 'primary',
+	},
+	{
+		icon: Eye,
+		title: 'Inspect',
+		description: 'Each MDX page shows live examples, source paths, and the owning layer.',
+		tone: 'info',
+	},
+	{
+		icon: Code2,
+		title: 'Copy',
+		description: 'Example code uses real components and public import paths.',
+		tone: 'success',
+	},
+	{
+		icon: CheckCircle2,
+		title: 'Verify',
+		description: 'Use browser, a11y, visual, exports, docs, and package smoke gates before release.',
+		tone: 'warning',
+	},
+] as const;
+
+export function ShowcaseWorkflow() {
+	return (
+		<div className="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+			{WORKFLOW.map((item) => (
+				<SmartCard key={item.title} surface="framed" padding="default" className="h-full">
+					<div className="space-y-3">
+						<IconBadge icon={item.icon} tone={item.tone} shape="square" />
+						<div>
+							<Text weight="semibold">{item.title}</Text>
+							<Text size="xs" type="secondary" className="mt-1">
+								{item.description}
+							</Text>
+						</div>
+					</div>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function SearchTargets() {
+	return (
+		<SmartCard
+			title="Searchable route index"
+			description="The sidebar search scans labels, ids, families, sections, scope labels, and route notes."
+			icon={<IconBadge icon={FileSearch} tone="info" shape="square" size="default" />}
+		>
+			<div className="flex flex-wrap gap-2">
+				<Badge variant="secondary">css variables</Badge>
+				<Badge variant="secondary">services/actions</Badge>
+				<Badge variant="secondary">hooks reference</Badge>
+				<Badge variant="secondary">global search</Badge>
+				<Badge variant="secondary">base/forms</Badge>
+				<Badge variant="secondary">layout/sidebar</Badge>
+				<Badge variant="secondary">features/filters</Badge>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function RouteShortcuts() {
+	return (
+		<div className="flex flex-wrap gap-2">
+			<Button href="#/docs/installation" size="default">
+				Installation
+			</Button>
+			<Button href="#/base/css-variables" size="default" buttonStyle="outline">
+				CSS variables
+			</Button>
+			<Button href="#/docs/refinement-guide" size="default" buttonStyle="outline">
+				Refinement guide
+			</Button>
+			<Button href="#/features/global-search" size="default" buttonStyle="outline">
+				Global search
+			</Button>
+			<Button href="#/layout/sidebar" size="default" buttonStyle="outline">
+				Sidebar
+			</Button>
+		</div>
+	);
+}
+
+export function InteractionChecks() {
+	return (
+		<SmartCard surface="framed" padding="default">
+			<div className="grid gap-3 md:grid-cols-[auto_minmax(0,1fr)]">
+				<IconBadge icon={MousePointer2} tone="primary" shape="square" />
+				<div className="space-y-2">
+					<Text weight="semibold">Treat examples as functional previews</Text>
+					<Text size="xs" type="secondary">
+						Interactive examples should exercise callbacks, async states, selection, validation, overlays, and controlled/uncontrolled behavior instead of rendering static mocks.
+					</Text>
+					<div className="flex flex-wrap gap-2">
+						<Badge variant="secondary">Callbacks</Badge>
+						<Badge variant="secondary">Loading</Badge>
+						<Badge variant="secondary">Errors</Badge>
+						<Badge variant="secondary">Keyboard</Badge>
+						<Badge variant="secondary">Responsive</Badge>
+					</div>
+				</div>
+			</div>
+		</SmartCard>
+	);
+}
+```
+
+## Example exports
+
+- `ShowcaseWorkflow`
+- `SearchTargets`
+- `RouteShortcuts`
+- `InteractionChecks`
+

package/.agents/skills/component-library-rules/references/components/features__activities.md

@@ -483,98 +483,97 @@ export function CustomRows() {
 }
 
 export function ResourceRegistry() {
-	const [registry, setRegistry] =
-	        useState<Record<string, ActivityResourceConfig>>(RESOURCE_SEED);
+	const [registry, setRegistry] = useState<Record<string, ActivityResourceConfig>>(RESOURCE_SEED);
 	const [, setLastEvent] = useState<string>('—');
 	const recordEvent = (msg: string) => setLastEvent(msg);
 	return (
-		<>
+		<div className="max-h-[42rem] overflow-auto pr-2">
 			<Text type="secondary" className="mb-3">
-			                    Edit a resource entry — every row referencing that key updates immediately and the registry change is broadcast through onResourcesChange (wire to localStorage / API).
-			                </Text>
-			                <div className="grid gap-4 lg:grid-cols-[2fr_1fr]">
-			                    <ActivityFeed
-			                        activities={RICH_ACTIVITIES}
-			                        density="rich"
-			                        currentUserId="u-12"
-			                        resources={registry}
-			                        onResourcesChange={setRegistry}
-			                        onResourceClick={(ref, cfg) =>
-			                            recordEvent(
-			                                `Registry click → ${ref.key} (${cfg?.label ?? 'untagged'})`,
-			                            )
-			                        }
-			                    />
-			                    <div className="rounded-lg border border-border bg-card p-4">
-			                        <Text weight="semibold" className="mb-3">
-			                            Registered resources
-			                        </Text>
-			                        <div className="space-y-3">
-			                            {Object.entries(registry).map(([key, cfg]) => (
-			                                <div
-			                                    key={key}
-			                                    className="space-y-1 rounded-md border border-border/60 px-3 py-2"
-			                                >
-			                                    <Text size="xs" type="secondary" className="tabular-nums">
-			                                        {key}
-			                                    </Text>
-			                                    <Text weight="medium">
-			                                        {cfg.label}
-			                                    </Text>
-			                                    <div className="flex flex-wrap gap-2">
-			                                        <Button
-			                                            size="xs"
-			                                            variant="secondary"
-			                                            buttonStyle="outline"
-			                                            onClick={() =>
-			                                                setRegistry((r) => ({
-			                                                    ...r,
-			                                                    [key]: {
-			                                                        ...r[key],
-			                                                        badge: {
-			                                                            label: 'Updated',
-			                                                            tone: 'warning',
-			                                                        },
-			                                                    },
-			                                                }))
-			                                            }
-			                                        >
-			                                            Mark updated
-			                                        </Button>
-			                                        <Button
-			                                            size="xs"
-			                                            variant="secondary"
-			                                            buttonStyle="ghost"
-			                                            onClick={() =>
-			                                                setRegistry((r) => {
-			                                                    const next = { ...r };
-			                                                    delete next[key];
-			                                                    return next;
-			                                                })
-			                                            }
-			                                        >
-			                                            Untag
-			                                        </Button>
-			                                    </div>
-			                                </div>
-			                            ))}
-			                            {Object.keys(registry).length === 0 && (
-			                                <Text size="xs" type="secondary">
-			                                    Registry empty — every reference now renders as a plain key.
-			                                </Text>
-			                            )}
-			                            <Button
-			                                size="xs"
-			                                variant="primary"
-			                                buttonStyle="solid"
-			                                onClick={() => setRegistry(RESOURCE_SEED)}
-			                            >
-			                                Restore seed
-			                            </Button>
-			                        </div>
-			                    </div>
-			                </div>
-		</>
+				Edit a resource entry — every row referencing that key updates immediately and the registry change is broadcast through onResourcesChange (wire to localStorage / API).
+			</Text>
+			<div className="grid gap-4 lg:grid-cols-[2fr_1fr]">
+				<ActivityFeed
+					activities={RICH_ACTIVITIES}
+					density="rich"
+					currentUserId="u-12"
+					resources={registry}
+					onResourcesChange={setRegistry}
+					onResourceClick={(ref, cfg) =>
+						recordEvent(
+							`Registry click → ${ref.key} (${cfg?.label ?? 'untagged'})`,
+						)
+					}
+				/>
+				<div className="rounded-lg border border-border bg-card p-4">
+					<Text weight="semibold" className="mb-3">
+						Registered resources
+					</Text>
+					<div className="space-y-3">
+						{Object.entries(registry).map(([key, cfg]) => (
+							<div
+								key={key}
+								className="space-y-1 rounded-md border border-border/60 px-3 py-2"
+							>
+								<Text size="xs" type="secondary" className="tabular-nums">
+									{key}
+								</Text>
+								<Text weight="medium">
+									{cfg.label}
+								</Text>
+								<div className="flex flex-wrap gap-2">
+									<Button
+										size="small"
+										variant="secondary"
+										buttonStyle="outline"
+										onClick={() =>
+											setRegistry((r) => ({
+												...r,
+												[key]: {
+													...r[key],
+													badge: {
+														label: 'Updated',
+														tone: 'warning',
+													},
+												},
+											}))
+										}
+									>
+										Mark updated
+									</Button>
+									<Button
+										size="small"
+										variant="secondary"
+										buttonStyle="ghost"
+										onClick={() =>
+											setRegistry((r) => {
+												const next = { ...r };
+												delete next[key];
+												return next;
+											})
+										}
+									>
+										Untag
+									</Button>
+								</div>
+							</div>
+						))}
+						{Object.keys(registry).length === 0 && (
+							<Text size="xs" type="secondary">
+								Registry empty — every reference now renders as a plain key.
+							</Text>
+						)}
+						<Button
+							size="small"
+							variant="primary"
+							buttonStyle="solid"
+							onClick={() => setRegistry(RESOURCE_SEED)}
+						>
+							Restore seed
+						</Button>
+					</div>
+				</div>
+			</div>
+		</div>
 	);
 }
 ```

package/.agents/skills/component-library-rules/references/components/features__ai-chat.md

@@ -403,7 +403,7 @@ export function Default() {
 	}, []);
 
 	return (
-		<div className="h-[640px]">
+		<div className="h-160">
 			<AiChat
 				agent={AGENT}
 				messages={messages}
@@ -460,7 +460,7 @@ export function Streaming() {
 		},
 	];
 	return (
-		<div className="h-[420px]">
+		<div className="h-105">
 			<AiChat
 				agent={AGENT}
 				messages={messages}
@@ -480,7 +480,7 @@ export function Streaming() {
 export function Empty() {
 	const [input, setInput] = useState('');
 	return (
-		<div className="h-[420px]">
+		<div className="h-105">
 			<AiChat
 				agent={AGENT}
 				messages={[]}
@@ -511,7 +511,7 @@ export function WithSlots() {
 		{ id: 'q2', label: 'Draft refund email to customer #2941', status: 'queued' },
 	]);
 	return (
-		<div className="h-[520px]">
+		<div className="h-130">
 			<AiChat
 				messages={SEED_MESSAGES.slice(0, 2)}
 				inputValue={input}
@@ -524,7 +524,7 @@ export function WithSlots() {
 					header: (
 						<div className="flex items-center justify-between border-b border-border bg-card px-4 py-2.5">
 							<Text weight="semibold">Atlas · workspace assistant</Text>
-							<Button buttonStyle="ghost" size="xs">
+							<Button buttonStyle="ghost" size="small">
 								Settings
 							</Button>
 						</div>
@@ -556,13 +556,13 @@ export function Headless() {
 	});
 
 	return (
-		<div className="flex h-[520px] flex-col overflow-hidden rounded-xl border border-border bg-background">
+		<div className="flex h-130 flex-col overflow-hidden rounded-xl border border-border bg-background">
 			<div className="flex items-center justify-between border-b border-border px-4 py-2">
 				<Text weight="semibold">Custom shell — built from partials</Text>
 				{!isAtBottom && (
 					<Button
 						buttonStyle="ghost"
-						size="xs"
+						size="small"
 						onClick={() => scrollToBottom()}
 					>
 						Jump to latest

package/.agents/skills/component-library-rules/references/components/features__data-view.md

@@ -0,0 +1,175 @@
+---
+id: features/data-view
+title: "Features · Data view"
+description: "Controlled data-view chrome for tables, filters, saved views, and pagination. Consumers own fetching, query state, table data, and persistence."
+layer: features
+family: "Tables"
+sourcePath: src/components/features/data-view
+examples:
+  - CustomerDataView
+  - EmptyCustomerDataView
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/forms
+  - @/components/base/table
+  - @/components/composed/data-display
+  - @/components/features/data-view
+  - @/components/typography
+publicImport: admin-ui-starter-kit/features/data-view
+tags:
+  - features
+  - tables
+  - data-view
+  - data
+  - view
+  - controlled
+  - chrome
+---
+
+# Features · Data view
+
+Controlled data-view chrome for tables, filters, saved views, and pagination. Consumers own fetching, query state, table data, and persistence.
+
+**Layer:** `features`
+**Source:** `src/components/features/data-view`
+**Consumer import:** `admin-ui-starter-kit/features/data-view`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/data-view`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+import { type ColumnDef } from '@tanstack/react-table';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { EmptyState } from '@/components/composed/data-display';
+import { Input } from '@/components/base/forms';
+import { DataTable } from '@/components/base/table';
+import {
+	DataViewPagination,
+	DataViewShell,
+	DataViewToolbar,
+	SavedViewTabs,
+} from '@/components/features/data-view';
+import { Text } from '@/components/typography';
+
+type Customer = {
+	id: string;
+	name: string;
+	plan: string;
+	region: string;
+	spend: string;
+};
+
+const customers: Customer[] = [
+	{ id: 'CUS-1042', name: 'Sarah Smitha', plan: 'Scale', region: 'US', spend: '2,450 USD' },
+	{ id: 'CUS-1188', name: 'Daniel Smith', plan: 'Pro', region: 'EU', spend: '970 USD' },
+	{ id: 'CUS-1201', name: 'Emma Garcia', plan: 'Enterprise', region: 'APAC', spend: '8,220 USD' },
+	{ id: 'CUS-1284', name: 'Nadia Kowalski', plan: 'Starter', region: 'EU', spend: '320 USD' },
+];
+
+const columns: ColumnDef<Customer>[] = [
+	{
+		accessorKey: 'name',
+		header: 'Customer',
+		cell: ({ row }) => (
+			<div className="grid gap-0.5">
+				<Text tag="span" size="inherit" weight="semibold">{row.original.name}</Text>
+				<Text tag="span" size="xs" type="secondary" className="font-mono">{row.original.id}</Text>
+			</div>
+		),
+	},
+	{
+		accessorKey: 'plan',
+		header: 'Plan',
+		cell: ({ row }) => <Badge variant="secondary">{row.original.plan}</Badge>,
+	},
+	{
+		accessorKey: 'region',
+		header: 'Region',
+	},
+	{
+		accessorKey: 'spend',
+		header: 'Spend',
+		meta: { align: 'end' },
+	},
+];
+
+export function CustomerDataView() {
+	const [view, setView] = useState('all');
+
+	return (
+		<DataViewShell
+			header={
+				<div className="grid gap-1">
+					<Text weight="semibold">Customers</Text>
+					<Text size="xs" type="secondary">
+						Controlled feature chrome around consumer-owned table state.
+					</Text>
+				</div>
+			}
+			toolbar={
+				<DataViewToolbar
+					search={<Input aria-label="Search customers" placeholder="Search customers..." className="w-60" />}
+					filters={<Badge variant="secondary">Region: all</Badge>}
+					views={
+						<SavedViewTabs
+							value={view}
+							onValueChange={setView}
+							views={[
+								{ id: 'all', label: 'All', count: 128 },
+								{ id: 'high-value', label: 'High value', count: 18 },
+								{ id: 'at-risk', label: 'At risk', count: 7 },
+							]}
+						/>
+					}
+					actions={<Button variant="secondary">Export</Button>}
+				/>
+			}
+			footer={
+				<DataViewPagination
+					page={2}
+					pageCount={6}
+					total="128 customers"
+					onPageChange={() => {}}
+				/>
+			}
+		>
+			<DataTable<Customer> columns={columns} data={customers} surface="flat" />
+		</DataViewShell>
+	);
+}
+
+export function EmptyCustomerDataView() {
+	return (
+		<DataViewShell
+			toolbar={
+				<DataViewToolbar
+					search={<Input aria-label="Search archived customers" placeholder="Search archived customers..." className="w-64" />}
+					actions={<Button variant="secondary">Clear filters</Button>}
+				/>
+			}
+			isEmpty
+			empty={
+				<EmptyState
+					title="No archived customers"
+					description="This view will populate when customers match the current filters."
+					actions={<Button variant="secondary">Reset view</Button>}
+				/>
+			}
+		/>
+	);
+}
+```
+
+## Example exports
+
+- `CustomerDataView`
+- `EmptyCustomerDataView`
+