admin-ui-starter-kit 0.4.4 → 0.5.0

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

@@ -16,13 +16,18 @@ examples:
   - PaginationExample
   - RealisticOrdersTable
   - CellRenderers
+  - IndexTableCells
   - WithRowSelection
   - WithColumnVisibility
   - WithCustomToolbar
+  - DataViewChrome
   - StickyHeaderAndFirstColumn
   - EmptyState
 imports:
   - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/data-view
+  - @/components/base/forms
   - @/components/base/table
   - @/components/base/table/pagination
   - @/components/typography
@@ -98,14 +103,19 @@ canonical Laravel-paginator shape.
 
 ## Cell renderers
 
-`StatusCell`, `DateCell`, `CurrencyCell`, and `AvatarCell` are reusable
-column-cell renderers exported from `base/table`. Compose them inside your
-column `cell` function to keep the table look consistent.
+`StatusCell`, `StatusClusterCell`, `DateCell`, `DateMetaCell`,
+`CurrencyCell`, `AvatarCell`, and `ResourceCell` are reusable column-cell
+renderers exported from `base/table`. Compose them inside your column `cell`
+function to keep index tables consistent.
 
 <Example name="CellRenderers" source={examplesSource}>
 	<Examples.CellRenderers />
 </Example>
 
+<Example name="IndexTableCells" source={examplesSource}>
+	<Examples.IndexTableCells />
+</Example>
+
 ## Selection
 
 <Example name="WithRowSelection" source={examplesSource}>
@@ -122,6 +132,10 @@ column `cell` function to keep the table look consistent.
 	<Examples.WithCustomToolbar />
 </Example>
 
+<Example name="DataViewChrome" source={examplesSource}>
+	<Examples.DataViewChrome />
+</Example>
+
 ## Sticky
 
 <Example name="StickyHeaderAndFirstColumn" source={examplesSource}>
@@ -155,13 +169,24 @@ import { Edit, Trash2, ShoppingBag, CheckCircle2, Clock, XCircle, Truck } from '
 import {
 	DataTable,
 	StatusCell,
+	StatusClusterCell,
 	DateCell,
+	DateMetaCell,
 	CurrencyCell,
 	AvatarCell,
+	ResourceCell,
 	type StatusCellEntry,
 } from '@/components/base/table';
+import {
+	DataViewPagination,
+	DataViewShell,
+	DataViewToolbar,
+	SavedViewTabs,
+} from '@/components/base/data-view';
 import { Pagination } from '@/components/base/table/pagination';
 import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { Input } from '@/components/base/forms';
 import { Text } from '@/components/typography';
 import { MOCK_ORDERS, MOCK_CUSTOMERS } from '@/preview/_mocks';
 
@@ -433,6 +458,79 @@ export function CellRenderers() {
 	return <DataTable<CellDemoRow> columns={cellDemoColumns} data={cellDemoData} />;
 }
 
+type IndexUserRow = {
+	id: string;
+	name: string;
+	email: string;
+	role: string;
+	createdAt: string;
+	statuses: Array<'active' | 'verified' | 'twoFactor'>;
+};
+
+const indexUserData: IndexUserRow[] = [
+	{ id: 'USR-001', name: 'Sarah Smitha', email: 'sarah@example.com', role: 'Owner', createdAt: '2026-05-14', statuses: ['active', 'verified', 'twoFactor'] },
+	{ id: 'USR-002', name: 'Daniel Smith', email: 'daniel@example.com', role: 'Admin', createdAt: '2026-05-22', statuses: ['active', 'verified'] },
+	{ id: 'USR-003', name: 'Emma Garcia', email: 'emma@example.com', role: 'Support', createdAt: '2026-06-02', statuses: ['active'] },
+];
+
+const indexUserColumns: ColumnDef<IndexUserRow>[] = [
+	{
+		accessorKey: 'name',
+		header: 'User',
+		cell: ({ row }) => (
+			<ResourceCell
+				title={row.original.name}
+				subtitle={row.original.email}
+				metadata={[{ label: 'Role', value: row.original.role }]}
+				href={`#/users/${row.original.id}`}
+			/>
+		),
+	},
+	{
+		id: 'status',
+		header: 'Status',
+		cell: ({ row }) => (
+			<StatusClusterCell
+				items={[
+					{ id: 'active', label: 'Active', variant: 'success', hidden: !row.original.statuses.includes('active') },
+					{ id: 'verified', label: 'Verified', variant: 'info', hidden: !row.original.statuses.includes('verified') },
+					{ id: 'twoFactor', label: '2FA', variant: 'secondary', hidden: !row.original.statuses.includes('twoFactor') },
+				]}
+			/>
+		),
+	},
+	{
+		accessorKey: 'createdAt',
+		header: 'Created',
+		cell: ({ getValue }) => (
+			<DateMetaCell value={getValue() as string} secondary="Synced today" />
+		),
+	},
+];
+
+export function IndexTableCells() {
+	return (
+		<DataTable<IndexUserRow>
+			columns={indexUserColumns}
+			data={indexUserData}
+			enableRowSelection
+			getRowId={(row) => row.id}
+			rowActionsMenuLabel={(row) => `Actions for ${row.name}`}
+			rowActions={() => [
+				{ id: 'open', label: 'Open', onClick: () => {} },
+				{ id: 'disable', label: 'Disable', variant: 'destructive', onClick: () => {} },
+			]}
+			bulkActions={({ selectedRowCount }) => (
+				<Button variant="secondary" disabled={selectedRowCount === 0}>
+					Bulk update
+				</Button>
+			)}
+			maxBodyHeight={320}
+			stickyToolbar
+		/>
+	);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Row selection (with checkbox column)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -491,6 +589,48 @@ export function WithCustomToolbar() {
 	);
 }
 
+export function DataViewChrome() {
+	const [view, setView] = useState('all');
+
+	return (
+		<DataViewShell
+			header={
+				<div className="space-y-1">
+					<Text weight="semibold">Orders data view</Text>
+					<Text size="xs" type="secondary">Controlled chrome around the table; the app owns query state and data fetching.</Text>
+				</div>
+			}
+			toolbar={
+				<DataViewToolbar
+					search={<Input aria-label="Search orders" placeholder="Search orders..." className="w-56" />}
+					views={
+						<SavedViewTabs
+							value={view}
+							onValueChange={setView}
+							views={[
+								{ id: 'all', label: 'All', count: 117 },
+								{ id: 'review', label: 'Needs review', count: 8 },
+								{ id: 'drafts', label: 'Drafts', count: 16 },
+							]}
+						/>
+					}
+					actions={<Button variant="secondary">Export</Button>}
+				/>
+			}
+			footer={
+				<DataViewPagination
+					page={2}
+					pageCount={8}
+					total="117 orders"
+					onPageChange={() => {}}
+				/>
+			}
+		>
+			<DataTable<Order> columns={columns} data={data} surface="flat" />
+		</DataViewShell>
+	);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Sticky header & first column
 // ─────────────────────────────────────────────────────────────────────────────
@@ -535,9 +675,11 @@ export function EmptyState() {
 - `PaginationExample`
 - `RealisticOrdersTable`
 - `CellRenderers`
+- `IndexTableCells`
 - `WithRowSelection`
 - `WithColumnVisibility`
 - `WithCustomToolbar`
+- `DataViewChrome`
 - `StickyHeaderAndFirstColumn`
 - `EmptyState`
 

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

@@ -11,8 +11,12 @@ examples:
   - RecentConversations
   - SettingsToggles
   - InventoryLevel
+  - ActionSurfaces
+  - TokenManager
 imports:
+  - @/components/base/buttons
   - @/components/base/cards
+  - @/components/composed/admin
   - @/components/composed/admin/conversation-row
   - @/components/composed/admin/inventory-level
   - @/components/composed/admin/role-permission
@@ -50,7 +54,14 @@ import { RolePermissionCard } from '@/components/composed/admin/role-permission'
 import { RecentConversationRow } from '@/components/composed/admin/conversation-row';
 import { SettingsToggleRow } from '@/components/composed/admin/settings-toggle';
 import { InventoryLevelCard } from '@/components/composed/admin/inventory-level';
+import {
+	ActionList,
+	ApiTokenManager,
+	CopyableSecretAlert,
+	SensitiveActionCard,
+} from '@/components/composed/admin';
 import { SmartCard } from '@/components/base/cards';
+import { Button } from '@/components/base/buttons';
 
 export function TeamMembers() {
 	return (
@@ -123,6 +134,59 @@ export function InventoryLevel() {
 		</>
 	);
 }
+
+export function ActionSurfaces() {
+	return (
+		<div className="grid gap-4">
+			<ActionList
+				title="Security actions"
+				description="Rows standardize settings, security, and show-card action surfaces."
+				rows={[
+					{
+						icon: Shield,
+						title: 'Require two-factor authentication',
+						description: 'Ask all admins to enroll before their next session.',
+						primaryAction: { label: 'Require 2FA', onClick: () => {} },
+						secondaryAction: { label: 'Preview policy', variant: 'secondary', onClick: () => {} },
+					},
+					{
+						icon: MessageSquare,
+						title: 'Notify account owners',
+						description: 'Send a summary before applying the change.',
+						primaryAction: { label: 'Send notice', variant: 'secondary', onClick: () => {} },
+					},
+				]}
+			/>
+			<SensitiveActionCard
+				title="Disable workspace"
+				description="Suspends access for every member and pauses background jobs."
+				confirmation="The consumer app owns the confirmation dialog and mutation callback."
+				action={<Button variant="error" buttonStyle="outline">Disable</Button>}
+			/>
+			<CopyableSecretAlert value="sk_live_x9K2..." />
+		</div>
+	);
+}
+
+export function TokenManager() {
+	return (
+		<ApiTokenManager
+			tokens={[
+				{ id: 'prod', name: 'Production', value: 'sk_prod_123', displayValue: '••••123' },
+				{ id: 'dev', name: 'Development', value: 'sk_dev_456', displayValue: '••••456' },
+			]}
+			abilities={[
+				{ id: 'read', label: 'Read records', description: 'List and inspect resources.' },
+				{ id: 'write', label: 'Write records', description: 'Create and update resources.' },
+				{ id: 'delete', label: 'Delete records', description: 'Remove resources through callbacks.' },
+			]}
+			createdToken={{ value: 'sk_new_789', displayValue: 'sk_new_789' }}
+			onCreateToken={() => {}}
+			onRevokeToken={() => {}}
+			onRevokeAllTokens={() => {}}
+		/>
+	);
+}
 ```
 
 ## Example exports
@@ -132,4 +196,6 @@ export function InventoryLevel() {
 - `RecentConversations`
 - `SettingsToggles`
 - `InventoryLevel`
+- `ActionSurfaces`
+- `TokenManager`
 

package/.agents/skills/component-library-rules/references/components/composed__resource-selector-card.md

@@ -0,0 +1,85 @@
+---
+id: composed/resource-selector-card
+title: "Composed · Resource selector card"
+description: "Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing."
+layer: composed
+family: "Data display"
+sourcePath: src/components/composed/data-display/resource-selector-card.tsx
+examples:
+  - SelectedResource
+  - EmptyResource
+imports:
+  - @/components/composed/data-display
+publicImport: admin-ui-starter-kit/composed/data-display
+tags:
+  - composed
+  - data
+  - display
+  - resource-selector-card.tsx
+  - resource
+  - selector
+  - card
+  - selected
+---
+
+# Composed · Resource selector card
+
+Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing.
+
+**Layer:** `composed`
+**Source:** `src/components/composed/data-display/resource-selector-card.tsx`
+**Consumer import:** `admin-ui-starter-kit/composed/data-display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/data-display`.
+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 { ResourceSelectorCard } from '@/components/composed/data-display';
+
+const resources = [
+	{ id: 'usr-1', name: 'Sarah Smith', email: 'sarah@example.com', role: 'Owner' },
+	{ id: 'usr-2', name: 'Marcus Lee', email: 'marcus@example.com', role: 'Admin' },
+];
+
+export function SelectedResource() {
+	const [resource, setResource] = useState<(typeof resources)[number] | null>(resources[0]);
+
+	return (
+		<ResourceSelectorCard
+			title="Account owner"
+			description="Selected resources render through accessor props."
+			resource={resource}
+			getKey={(item) => item.id}
+			getTitle={(item) => item.name}
+			getSubtitle={(item) => item.email}
+			getMetadata={(item) => [{ label: 'Role', value: item.role }]}
+			onSelect={() => setResource(resources[1])}
+			onRemove={() => setResource(null)}
+		/>
+	);
+}
+
+export function EmptyResource() {
+	return (
+		<ResourceSelectorCard<(typeof resources)[number]>
+			title="Approver"
+			description="The consumer owns the picker dialog and passes callbacks."
+			getKey={(item) => item.id}
+			getTitle={(item) => item.name}
+			getSubtitle={(item) => item.email}
+			onSelect={() => {}}
+		/>
+	);
+}
+```
+
+## Example exports
+
+- `SelectedResource`
+- `EmptyResource`
+

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

@@ -7,8 +7,11 @@ family: "Search & filter"
 sourcePath: src/components/features/filters
 examples:
   - Default
+  - QueryStateHelpers
 imports:
+  - @/components/base/cards
   - @/components/features/filters
+  - @/components/typography
   - @/preview/_mocks
 publicImport: admin-ui-starter-kit/features/filters
 tags:
@@ -48,6 +51,13 @@ The example below mounts a search facet, a multi-select status facet, and
 an async-select customer facet wired to the in-repo mock fetcher in
 `src/preview/_mocks/fetchers.ts` (~280ms simulated delay).
 
+## URL state
+
+`parseFiltersFromQuery`, `serializeFiltersToQuery`, and `mergeFilterQuery`
+convert filter state to plain query records. They do not navigate, import a
+router, or assume a backend. Consumers pass the returned record into their
+framework-specific URL update path.
+
 ## Examples
 
 ```tsx
@@ -58,10 +68,15 @@ import {
 	type ActiveFilter,
 	type FilterConfig,
 	type FilterOption,
+	FilterOperatorEnum,
 	FilterLayout,
 	FilterProvider,
 	FilterType,
+	parseFiltersFromQuery,
+	serializeFiltersToQuery,
 } from '@/components/features/filters';
+import { SmartCard } from '@/components/base/cards';
+import { Text } from '@/components/typography';
 import { mockListCustomers } from '@/preview/_mocks';
 
 export function Default() {
@@ -121,9 +136,63 @@ export function Default() {
 		</FilterProvider>
 	);
 }
+
+export function QueryStateHelpers() {
+	const filters = useMemo<FilterConfig[]>(
+		() => [
+			{
+				key: 'q',
+				label: 'Search',
+				type: FilterType.SEARCH,
+				icon: <Search className="size-4" />,
+				displayConfig: { display: 'always' },
+				operator: FilterOperatorEnum.CONTAINS,
+			},
+			{
+				key: 'status',
+				label: 'Status',
+				type: FilterType.MULTI_SELECT,
+				icon: <BadgeCheck className="size-4" />,
+				displayConfig: { display: 'always' },
+				options: [],
+			},
+		],
+		[],
+	);
+	const parsed = parseFiltersFromQuery(filters, {
+		q: 'gift',
+		status: ['paid', 'pending'],
+		status__op: 'in',
+		page: '4',
+	});
+	const serialized = serializeFiltersToQuery(filters, parsed, {
+		page: '4',
+		sort: 'created_at',
+	});
+
+	return (
+		<SmartCard title="URL-state helpers" description="The package transforms filter state; the app decides how to navigate.">
+			<div className="grid gap-3 md:grid-cols-2">
+				<div className="grid gap-1">
+					<Text size="xs" weight="semibold">Parsed filters</Text>
+					<pre className="overflow-auto rounded-md bg-muted p-3 text-xs">
+						{JSON.stringify(parsed, null, 2)}
+					</pre>
+				</div>
+				<div className="grid gap-1">
+					<Text size="xs" weight="semibold">Serialized query</Text>
+					<pre className="overflow-auto rounded-md bg-muted p-3 text-xs">
+						{JSON.stringify(serialized, null, 2)}
+					</pre>
+				</div>
+			</div>
+		</SmartCard>
+	);
+}
 ```
 
 ## Example exports
 
 - `Default`
+- `QueryStateHelpers`
 

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

@@ -8,6 +8,7 @@ sourcePath: src/components/layout
 examples:
   - AppHeaderComposition
   - HeaderPartials
+  - HeaderToolPrimitives
   - CustomNotificationRenderer
 imports:
   - @/components/base/badge
@@ -54,8 +55,11 @@ import { Text } from '@/components/typography';
 import {
 	Header,
 	HeaderBreadcrumbs,
+	HeaderGlobalSearchTrigger,
 	HeaderNotifications,
 	HeaderSearch,
+	HeaderToolButton,
+	HeaderToolPopover,
 	HeaderUserMenu,
 	type HeaderNotification,
 } from '@/components/layout/header';
@@ -191,6 +195,36 @@ export function HeaderPartials() {
 	);
 }
 
+export function HeaderToolPrimitives() {
+	return (
+		<SmartCard padding="sm">
+			<div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_auto] lg:items-center">
+				<div className="min-w-0">
+					<Text weight="semibold">Header tools</Text>
+					<Text size="xs" type="secondary">
+						Icon tools, popovers, and global-search triggers share the same dense header contract.
+					</Text>
+				</div>
+				<div className="flex min-w-0 flex-wrap items-center gap-2">
+					<HeaderGlobalSearchTrigger
+						className="w-64"
+						strings={{ placeholder: 'Search workspace' }}
+						onOpen={() => {}}
+					/>
+					<HeaderToolButton label="Notifications" icon={Bell} badge="3" onClick={() => {}} />
+					<HeaderToolPopover label="Settings" icon={Settings} open>
+						<div className="grid gap-1 p-3">
+							<Text weight="semibold">Workspace tools</Text>
+							<Text size="xs" type="secondary">Consumer-owned content inside package popover chrome.</Text>
+							<Button variant="secondary" size="sm">Open settings</Button>
+						</div>
+					</HeaderToolPopover>
+				</div>
+			</div>
+		</SmartCard>
+	);
+}
+
 export function CustomNotificationRenderer() {
 	return (
 		<>
@@ -220,5 +254,6 @@ export function CustomNotificationRenderer() {
 
 - `AppHeaderComposition`
 - `HeaderPartials`
+- `HeaderToolPrimitives`
 - `CustomNotificationRenderer`