admin-ui-starter-kit 0.4.2 → 0.4.4

package/.agents/skills/admin-ui-consumer-migration/SKILL.md

@@ -20,6 +20,8 @@ When available in the installed package or repo, read these before editing:
 3. `INTEGRATION.md` — install, provider, exact import, and framework wiring.
 4. `.agents/skills/component-library-rules/references/components/INDEX.json` —
    searchable component index.
+5. `.agents/skills/admin-ui-consumer-migration/references/actions-service.md` —
+   shared action registry, overlay, form, and lifecycle wiring guide.
 
 Do not bulk-load every component doc. Use the index, then read only the matching
 component file.
@@ -141,6 +143,7 @@ Review the diff before deleting local folders.
 | Comments | `admin-ui-starter-kit/features/comments` |
 | Media picker / product gallery field | `admin-ui-starter-kit/features/media-library` |
 | Dialogs/drawers | `admin-ui-starter-kit/features/overlays` |
+| Shared action lifecycle across page/table/card/command/overlay surfaces | `admin-ui-starter-kit/services/actions` |
 | Metrics/charts | `admin-ui-starter-kit/composed/analytics` |
 | Page/header/sidebar | `admin-ui-starter-kit/layout/page`, `/header`, `/sidebar` |
 
@@ -151,6 +154,13 @@ stack, a click target, or trailing actions. Use `MetadataList` only for
 label/value facts describing one entity. Use `FormField` /
 `ControlledFormField` for every editable label + control + hint/error row.
 
+Use `services/actions` only when one action definition must appear in multiple
+surfaces and share state: page actions, table-row menus, card menus, command
+palette entries, and overlay confirmation/form flows. Keep one-off dialog state
+local with `features/overlays`. Read
+`references/actions-service.md` before migrating repeated action menus or
+framework-bound action wrappers.
+
 Typography should come from `admin-ui-starter-kit/typography`: `Text`,
 `Heading`, `Label`, and `TextLink`. Do not keep local `text-xs`,
 `text-muted-foreground`, or `font-semibold` spans when a package typography

package/.agents/skills/admin-ui-consumer-migration/references/actions-service.md

@@ -0,0 +1,236 @@
+# Actions Service Consumer Guide
+
+Use `admin-ui-starter-kit/services/actions` when a consuming app has repeated
+actions that need one shared lifecycle across several surfaces.
+
+Good fit:
+
+- the same action appears in a page header and row menu,
+- a command palette action should open the same confirmation dialog as a card
+  menu action,
+- loading, field errors, success/failure, and overlay state must stay consistent,
+- toast or telemetry should be centralized at the app shell.
+
+Poor fit:
+
+- one local dialog used by one button,
+- route links that do not mutate or require lifecycle state,
+- actions whose behavior is easier to keep directly beside a form.
+
+For poor fits, use `features/overlays`, `Button`, `PageActions`, or app-owned
+state directly.
+
+## App Shell
+
+Mount one provider and one outlet. The outlet is the only place that renders
+action-owned overlays.
+
+```tsx
+import {
+	ActionOverlayOutlet,
+	ActionProvider,
+	type ActionFeedbackHandlers,
+} from 'admin-ui-starter-kit/services/actions';
+
+const feedback: ActionFeedbackHandlers = {
+	onSuccess: (event) => {
+		if (event.message) toast.success(event.message);
+	},
+	onError: (event) => {
+		if (event.message) toast.error(event.message);
+		reportError(event.error, { actionId: event.actionId, scope: event.scope });
+	},
+};
+
+export function AppRoot() {
+	return (
+		<ActionProvider feedback={feedback}>
+			<App />
+			<ActionOverlayOutlet />
+		</ActionProvider>
+	);
+}
+```
+
+Do not put router, query, toast, telemetry, or i18n packages inside a package
+wrapper. They stay in the consuming app and enter through callbacks.
+
+## Page Scope
+
+Register definitions once per scope. Do not register one action array per row.
+
+```tsx
+import {
+	ActionScope,
+	useActionSurface,
+	type ActionDefinition,
+} from 'admin-ui-starter-kit/services/actions';
+import { PageActions } from 'admin-ui-starter-kit/layout/page';
+
+const customerActions: ActionDefinition<Customer>[] = [
+	{
+		id: 'customer.archive',
+		label: 'Archive customer',
+		surfaces: ['page', 'table-row', 'command'],
+		disabled: ({ payload }) => payload?.locked === true,
+		modality: {
+			type: 'alert',
+			tone: 'warning',
+			title: ({ payload }) => `Archive ${payload?.name}?`,
+			confirmLabel: 'Archive',
+		},
+		run: ({ payload, signal }) => api.customers.archive(payload.id, { signal }),
+		successMessage: ({ payload }) => `${payload?.name} archived`,
+		errorMessage: 'Could not archive customer',
+		onAfterMutate: () => queryClient.invalidateQueries({ queryKey: ['customers'] }),
+	},
+];
+
+function CustomerPage({ customer }: { customer: Customer }) {
+	return (
+		<ActionScope scope={`customer:${customer.id}`} actions={customerActions}>
+			<CustomerHeader customer={customer} />
+			<CustomerTable rows={[customer]} />
+		</ActionScope>
+	);
+}
+
+function CustomerHeader({ customer }: { customer: Customer }) {
+	const actions = useActionSurface<Customer>({ surface: 'page', payload: customer });
+
+	return (
+		<PageActions
+			actions={actions.map((action) => ({
+				id: action.id,
+				label: action.label,
+				icon: action.icon,
+				disabled: action.disabled || action.isRunning,
+				onClick: () => action.open(),
+			}))}
+		/>
+	);
+}
+```
+
+For row menus, call `useActionSurface({ surface: 'table-row', payload: row })`
+from the row component and map the returned actions into the existing menu
+component.
+
+## Modality And Overlay Parity
+
+Use action modality for reusable modal workflows. A delete confirmation opened
+from a row menu, page header, command palette, or search result should be one
+action definition with `modality`, not four local dialogs.
+
+`ActionOverlayOutlet` renders action-owned `alert`, `dialog`, and `drawer`
+flows through the package `features/overlays` components. That means consumers
+keep the same focus handling, backdrop behavior, confirm/cancel labels, loading
+state, field errors, and lifecycle feedback as direct overlay usage.
+
+Action modality supports the overlay controls needed for parity:
+
+- visual intent: `tone`, `showIcon`, `emphasis`;
+- geometry: `size`, `drawerDirection`;
+- footer and forms: `formId`, `render`, `footer`, `showCancel`,
+  `showConfirm`, `showFooter`, `confirmStyle`;
+- accessibility and behavior: `alertMessage`, `visuallyHideHeader`,
+  `className`, `contentClassName`, `initialFocusRef`, `closeOnEscape`,
+  `closeOnBackdropClick`, `closeOnSuccess`.
+
+Keep one-off modals on `features/overlays` when there is no shared lifecycle.
+Do not create a second app-level modal registry beside the package action
+service unless the app has a truly separate domain runtime.
+
+## Forms
+
+Action overlays can host forms without owning a form library.
+
+```tsx
+import { FormField, Input } from 'admin-ui-starter-kit/base/forms';
+
+const renameCustomer: ActionDefinition<Customer, { name: string }, Customer> = {
+	id: 'customer.rename',
+	label: 'Rename customer',
+	modality: {
+		type: 'dialog',
+		title: ({ payload }) => `Rename ${payload?.name}`,
+		formId: 'rename-customer-form',
+		render: ({ getFormProps, errors, isRunning }) => (
+			<form
+				{...getFormProps({
+					resolveValues: (formData) => ({
+						name: String(formData.get('name') ?? ''),
+					}),
+				})}
+				className="grid gap-4"
+			>
+				<FormField label="Name" error={errors.name}>
+					<Input name="name" disabled={isRunning} />
+				</FormField>
+			</form>
+		),
+	},
+	run: ({ payload, values, signal }) =>
+		api.customers.rename(payload.id, values.name, { signal }),
+};
+```
+
+For `react-hook-form`, keep the RHF setup in the app:
+
+```tsx
+import { ControlledFormField, Input } from 'admin-ui-starter-kit/base/forms';
+
+render: ({ submit, errors, isRunning }) => (
+	<form id="rename-customer-form" onSubmit={form.handleSubmit((values) => submit(values))}>
+		<ControlledFormField name="name" control={form.control} error={errors.name}>
+			{(field, _error, invalid) => (
+				<Input {...field} disabled={isRunning} invalid={invalid} />
+			)}
+		</ControlledFormField>
+	</form>
+)
+```
+
+## State And Feedback
+
+Resolved actions expose:
+
+- `status`: `idle`, `running`, `succeeded`, or `failed`.
+- `isIdle`, `isRunning`, `isSuccess`, `isError`.
+- `errors`: field errors from thrown errors shaped like `{ errors: { field } }`.
+- `error`: the raw thrown error.
+- `result`: the last successful result.
+- `runState`, `startedAt`, and `completedAt`.
+
+Use those fields to disable menu items, show spinners, render inline errors, or
+keep a dialog open after a failed submit.
+
+Provider `feedback` centralizes toasts and telemetry; per-action lifecycle
+callbacks handle local cache invalidation or page-specific follow-up.
+
+## Metadata
+
+Use metadata for non-rendering context:
+
+```tsx
+const actions = useActionSurface<Customer>({
+	surface: 'table-row',
+	payload: row,
+	metadata: { tableId: 'customers', rowIndex },
+});
+```
+
+Metadata merges from action definition, hook call, and individual
+`open`/`execute` calls. Later values win.
+
+## Migration Rules
+
+- Replace copied local action registries only when the package service can own
+  lifecycle state without importing app code.
+- Keep route helpers, Inertia router calls, React Query clients, translations,
+  permissions, and API clients in the app.
+- Do not create local package mirrors such as `@/ui/actions`.
+- Keep definitions stable with `useMemo` or module-level constants when they
+  are declared inside React components.
+- Keep one-off modals on `features/overlays`; the action provider is not a
+  replacement for local state.

package/.agents/skills/component-library-rules/SKILL.md

@@ -11,7 +11,7 @@ This is a reusable component library. Code lives in many projects via this packa
 
 ## Goal & target distribution
 
-This codebase is on a path to becoming a **standalone, publishable npm package** that re-exports shadcn primitives, the `base/` wrappers, and the `composed/`/`features/` layers — centralized so every consuming app upgrades from one place.
+This codebase is on a path to becoming a **standalone, publishable npm package** that keeps shadcn primitives as an internal source layer and publicly re-exports the `base/` wrappers plus the `composed/`/`features/` layers — centralized so every consuming app upgrades from one place.
 
 That goal drives every other rule:
 - Components must be **framework-agnostic** by default (Inertia, Next.js, plain Vite, Remix, …).
@@ -129,6 +129,11 @@ The bare `@/components/ui/<primitive>` path is allowed **only** for base wrapper
 
 Touching shadcn primitives directly breaks the abstraction layer and means the next shadcn upgrade overwrites your work.
 
+Raw shadcn primitives are not public package subpaths. Do not document
+`admin-ui-starter-kit/ui/<primitive>` imports unless the package export map is
+intentionally changed in the same work; today consumers use the matching
+`base/`, `layout/`, `composed/`, or `features/` entrypoint.
+
 **Package-owned non-shadcn "primitives".** A few units of UI in this library are large, package-owned, opinionated implementations (Mapbox/Leaflet adapter, Google Places autocomplete) that are **not** shadcn primitives. They live in `src/components/base/` directly (e.g. `base/map/map.tsx`, `base/map/place-autocomplete.tsx`), not in `ui/`. They follow the same framework-agnostic / token-driven / strings-overridable rules as everything else in `base/`. Don't recreate them in `ui/` — `ui/` is shadcn-only.
 
 ## 2. The component layer order is sacred
@@ -780,6 +785,7 @@ Published package imports use exact subpaths, not broad aggregates:
 - ❌ `admin-ui-starter-kit/base`
 - ❌ `admin-ui-starter-kit/composed`
 - ❌ `admin-ui-starter-kit/features`
+- ❌ `admin-ui-starter-kit/ui/tabs`
 - ❌ `admin-ui-starter-kit/base/display/metadata/metadata-list`
 
 The root package entrypoint (`admin-ui-starter-kit`) must stay optional-peer-free:

package/.agents/skills/component-library-rules/references/base-wrapper.md

@@ -2,6 +2,20 @@
 
 Open this when adding a new wrapper around an `@/components/ui/<primitive>` shadcn component.
 
+## Adding an internal shadcn primitive
+
+Install the raw primitive with:
+
+```bash
+npx shadcn@latest add <primitive>
+```
+
+The generated file lands in `src/components/ui/<primitive>.tsx`. Treat that
+file as shadcn-managed output: do not restyle it to match the library voice,
+and do not expose it as `admin-ui-starter-kit/ui/<primitive>`. Consumers get a
+public API only after you add or update a `base/`, `layout/`, `composed/`, or
+`features/` wrapper and wire the exact package export.
+
 ## When to wrap
 
 Wrap a shadcn primitive in `base/` when **any** of these are true:
@@ -109,7 +123,7 @@ Before adding a new wrapper, check if one exists:
 | `base/command/` | `ui/command` |
 | `base/popover/` | `ui/popover` |
 | `base/popover-menu/` | `popover` + `command` |
-| `base/navigation/` | `ui/dropdown-menu`, `ui/breadcrumb`, segmented `ui/tabs`, `ui/sidebar` |
+| `base/navigation/` | `ui/dropdown-menu`, `ui/breadcrumb`, segmented `ui/tabs` |
 | `base/forms/` | `ui/input`, `ui/select`, `ui/textarea`, `ui/checkbox`, `ui/switch`, `ui/radio-group`, `ui/slider` |
 | `base/date-pickers/` | `ui/calendar` |
 | `base/toaster/` | `ui/sonner` |
@@ -117,11 +131,17 @@ Before adding a new wrapper, check if one exists:
 | `base/table/` | `ui/table` |
 | `base/event-calendar/` | `ui/calendar` (richer compositions) |
 | `base/map/` | `ui/map` |
+| `base/carousel/` | `ui/carousel` |
+| `base/sheet/` | `ui/sheet` |
+| `base/sidebar/` | `ui/sidebar` |
 
 Currently NOT wrapped (consider adding when you encounter inlined usage in 2+ places):
-- `ui/sheet` — only `layout/sidebar` reaches into it
-- `ui/sidebar` — only `layout/sidebar` reaches into it
-- `ui/hover-card`, `ui/context-menu`, `ui/collapsible` — only used by other wrappers internally
+- `ui/alert-dialog`, `ui/drawer` — prefer `features/overlays` for the public API.
+- `ui/aspect-ratio`, `ui/direction`, `ui/field`, `ui/input-otp`, `ui/kbd`,
+  `ui/label`, `ui/menubar`, `ui/native-select`, `ui/navigation-menu`,
+  `ui/resizable` — installed as internal shadcn primitives; add a wrapper
+  before using them from non-`ui` layers.
+- `ui/hover-card`, `ui/context-menu`, `ui/collapsible` — only used by other wrappers internally.
 
 ## Don'ts
 

package/.agents/skills/component-library-rules/references/components/INDEX.json

@@ -89,9 +89,10 @@
   {"id":"ui/collapsible","title":"UI · Collapsible","description":"Headless show/hide region.","layer":"ui","family":"Layout","tags":["ui","layout","collapsible","headless","show","hide","region"],"sourcePath":"src/components/ui/collapsible","publicImport":"","examples":["Default"],"doc":"./ui__collapsible.md"},
   {"id":"ui/empty-item","title":"UI · Empty + Item","description":"Empty state and Item list-row primitives.","layer":"ui","family":"Data display","tags":["ui","data","display","empty","item","state","list"],"sourcePath":"src/components/ui","publicImport":"","examples":["EmptyState","ItemsList"],"doc":"./ui__empty-item.md"},
   {"id":"ui/input-group","title":"UI · Input group","description":"Input with leading / trailing add-ons.","layer":"ui","family":"Forms","tags":["ui","forms","input-group","input","group","leading","trailing"],"sourcePath":"src/components/ui/input-group","publicImport":"","examples":["LeadingIcon","TrailingAddon","StackedEmailPassword"],"doc":"./ui__input-group.md"},
-  {"id":"ui/inputs","title":"UI · Inputs","description":"Input, Textarea, Select primitives.","layer":"ui","family":"Forms","tags":["ui","forms","inputs","input","textarea","select"],"sourcePath":"src/components/ui","publicImport":"","examples":["InputExample","TextareaExample","SelectExample"],"doc":"./ui__inputs.md"},
-  {"id":"ui/menus","title":"UI · Menus","description":"DropdownMenu, ContextMenu, Command palette.","layer":"ui","family":"Overlays","tags":["ui","overlays","menus","dropdownmenu","contextmenu","command"],"sourcePath":"src/components/ui","publicImport":"","examples":["DropdownMenuExample","ContextMenuRightClick","CommandPalette"],"doc":"./ui__menus.md"},
-  {"id":"ui/overlays","title":"UI · Overlays","description":"Dialog, Sheet, Popover, Tooltip, HoverCard.","layer":"ui","family":"Overlays","tags":["ui","overlays","dialog","sheet","popover","tooltip"],"sourcePath":"src/components/ui","publicImport":"","examples":["DialogExample","SheetExample","PopoverExample","TooltipExample","HoverCardExample"],"doc":"./ui__overlays.md"},
+  {"id":"ui/inputs","title":"UI · Inputs","description":"Input, Textarea, Select, NativeSelect, InputOTP, Field, and Kbd primitives.","layer":"ui","family":"Forms","tags":["ui","forms","inputs","input","textarea","select"],"sourcePath":"src/components/ui","publicImport":"","examples":["InputExample","TextareaExample","SelectExample","NativeSelectExample","InputOTPExample","FieldExample","KbdExample"],"doc":"./ui__inputs.md"},
+  {"id":"ui/layout-primitives","title":"UI · Layout primitives","description":"AspectRatio and Resizable primitives.","layer":"ui","family":"Layout","tags":["ui","layout","primitives","aspectratio","resizable"],"sourcePath":"src/components/ui","publicImport":"","examples":["AspectRatioExample","ResizableExample"],"doc":"./ui__layout-primitives.md"},
+  {"id":"ui/menus","title":"UI · Menus","description":"DropdownMenu, Menubar, NavigationMenu, ContextMenu, and Command palette.","layer":"ui","family":"Overlays","tags":["ui","overlays","menus","dropdownmenu","menubar","navigationmenu"],"sourcePath":"src/components/ui","publicImport":"","examples":["DropdownMenuExample","MenubarExample","NavigationMenuExample","ContextMenuRightClick","CommandPalette"],"doc":"./ui__menus.md"},
+  {"id":"ui/overlays","title":"UI · Overlays","description":"Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, and HoverCard.","layer":"ui","family":"Overlays","tags":["ui","overlays","dialog","alertdialog","sheet","drawer"],"sourcePath":"src/components/ui","publicImport":"","examples":["DialogExample","AlertDialogExample","SheetExample","DrawerExample","PopoverExample","TooltipExample","HoverCardExample"],"doc":"./ui__overlays.md"},
   {"id":"ui/pagination","title":"UI · Pagination","description":"Manual composition of pagination controls.","layer":"ui","family":"Navigation","tags":["ui","navigation","pagination","manual","composition","controls"],"sourcePath":"src/components/ui/pagination","publicImport":"","examples":["Default"],"doc":"./ui__pagination.md"},
   {"id":"ui/progress","title":"UI · Progress","description":"Linear progress bar at varying values.","layer":"ui","family":"Data display","tags":["ui","data","display","progress","linear","bar","varying","values"],"sourcePath":"src/components/ui/progress","publicImport":"","examples":["Values"],"doc":"./ui__progress.md"},
   {"id":"ui/scroll-area","title":"UI · Scroll area","description":"Custom-styled scroll viewport.","layer":"ui","family":"Layout","tags":["ui","layout","scroll-area","scroll","area","custom","styled"],"sourcePath":"src/components/ui/scroll-area","publicImport":"","examples":["Vertical","Horizontal"],"doc":"./ui__scroll-area.md"},

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

@@ -111,9 +111,10 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [UI · Collapsible](./ui__collapsible.md) — Headless show/hide region.
 - [UI · Empty + Item](./ui__empty-item.md) — Empty state and Item list-row primitives.
 - [UI · Input group](./ui__input-group.md) — Input with leading / trailing add-ons.
-- [UI · Inputs](./ui__inputs.md) — Input, Textarea, Select primitives.
-- [UI · Menus](./ui__menus.md) — DropdownMenu, ContextMenu, Command palette.
-- [UI · Overlays](./ui__overlays.md) — Dialog, Sheet, Popover, Tooltip, HoverCard.
+- [UI · Inputs](./ui__inputs.md) — Input, Textarea, Select, NativeSelect, InputOTP, Field, and Kbd primitives.
+- [UI · Layout primitives](./ui__layout-primitives.md) — AspectRatio and Resizable primitives.
+- [UI · Menus](./ui__menus.md) — DropdownMenu, Menubar, NavigationMenu, ContextMenu, and Command palette.
+- [UI · Overlays](./ui__overlays.md) — Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, and HoverCard.
 - [UI · Pagination](./ui__pagination.md) — Manual composition of pagination controls.
 - [UI · Progress](./ui__progress.md) — Linear progress bar at varying values.
 - [UI · Scroll area](./ui__scroll-area.md) — Custom-styled scroll viewport.

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

@@ -1,7 +1,7 @@
 ---
 id: ui/inputs
 title: "UI · Inputs"
-description: "Input, Textarea, Select primitives."
+description: "Input, Textarea, Select, NativeSelect, InputOTP, Field, and Kbd primitives."
 layer: ui
 family: "Forms"
 sourcePath: src/components/ui
@@ -9,8 +9,16 @@ examples:
   - InputExample
   - TextareaExample
   - SelectExample
+  - NativeSelectExample
+  - InputOTPExample
+  - FieldExample
+  - KbdExample
 imports:
+  - @/components/ui/field
   - @/components/ui/input
+  - @/components/ui/input-otp
+  - @/components/ui/kbd
+  - @/components/ui/native-select
   - @/components/ui/select
   - @/components/ui/textarea
 tags:
@@ -24,7 +32,7 @@ tags:
 
 # UI · Inputs
 
-Input, Textarea, Select primitives.
+Input, Textarea, Select, NativeSelect, InputOTP, Field, and Kbd primitives.
 
 **Layer:** `ui`
 **Source:** `src/components/ui`
@@ -33,7 +41,19 @@ Input, Textarea, Select primitives.
 
 ```tsx
 import { useState } from 'react';
+import {
+	Field,
+	FieldDescription,
+	FieldError,
+	FieldGroup,
+	FieldLabel,
+	FieldLegend,
+	FieldSet,
+} from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
+import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from '@/components/ui/input-otp';
+import { Kbd, KbdGroup } from '@/components/ui/kbd';
+import { NativeSelect, NativeSelectOption } from '@/components/ui/native-select';
 import { Textarea } from '@/components/ui/textarea';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Col } from '../../PreviewLayout';
@@ -43,11 +63,11 @@ export function InputExample() {
 	return (
 		<>
 			<Col>
-								<Input placeholder="Type something…" value={text} onChange={(e) => setText(e.target.value)} />
-								<Input disabled placeholder="Disabled" />
-								<Input aria-invalid placeholder="Invalid state" />
-								<Input type="email" placeholder="email@example.com" />
-							</Col>
+				<Input placeholder="Type something…" value={text} onChange={(e) => setText(e.target.value)} />
+				<Input disabled placeholder="Disabled" />
+				<Input aria-invalid placeholder="Invalid state" />
+				<Input type="email" placeholder="email@example.com" />
+			</Col>
 		</>
 	);
 }
@@ -66,17 +86,92 @@ export function SelectExample() {
 	return (
 		<>
 			<Select value={fruit} onValueChange={setFruit}>
-								<SelectTrigger className="w-48">
-									<SelectValue placeholder="Pick a fruit" />
-								</SelectTrigger>
-								<SelectContent>
-									<SelectItem value="apple">Apple</SelectItem>
-									<SelectItem value="banana">Banana</SelectItem>
-									<SelectItem value="cherry">Cherry</SelectItem>
-									<SelectItem value="date">Date</SelectItem>
-								</SelectContent>
-							</Select>
-							<div className="mt-2 text-xs text-muted-foreground">value: {fruit || '—'}</div>
+				<SelectTrigger className="w-48">
+					<SelectValue placeholder="Pick a fruit" />
+				</SelectTrigger>
+				<SelectContent>
+					<SelectItem value="apple">Apple</SelectItem>
+					<SelectItem value="banana">Banana</SelectItem>
+					<SelectItem value="cherry">Cherry</SelectItem>
+					<SelectItem value="date">Date</SelectItem>
+				</SelectContent>
+			</Select>
+			<div className="mt-2 text-xs text-muted-foreground">value: {fruit || '—'}</div>
+		</>
+	);
+}
+
+export function NativeSelectExample() {
+	const [status, setStatus] = useState('open');
+
+	return (
+		<>
+			<NativeSelect
+				aria-label="Issue status"
+				value={status}
+				onChange={(event) => setStatus(event.target.value)}
+			>
+				<NativeSelectOption value="open">Open</NativeSelectOption>
+				<NativeSelectOption value="review">In review</NativeSelectOption>
+				<NativeSelectOption value="resolved">Resolved</NativeSelectOption>
+			</NativeSelect>
+			<div className="mt-2 text-xs text-muted-foreground">value: {status}</div>
+		</>
+	);
+}
+
+export function InputOTPExample() {
+	const [code, setCode] = useState('');
+
+	return (
+		<>
+			<InputOTP maxLength={6} value={code} onChange={setCode}>
+				<InputOTPGroup>
+					<InputOTPSlot index={0} />
+					<InputOTPSlot index={1} />
+					<InputOTPSlot index={2} />
+				</InputOTPGroup>
+				<InputOTPSeparator />
+				<InputOTPGroup>
+					<InputOTPSlot index={3} />
+					<InputOTPSlot index={4} />
+					<InputOTPSlot index={5} />
+				</InputOTPGroup>
+			</InputOTP>
+			<div className="mt-2 text-xs text-muted-foreground">value: {code || 'empty'}</div>
+		</>
+	);
+}
+
+export function FieldExample() {
+	return (
+		<>
+			<FieldSet className="max-w-md">
+				<FieldLegend variant="label">Notification settings</FieldLegend>
+				<FieldGroup>
+					<Field>
+						<FieldLabel htmlFor="ui-field-email">Email</FieldLabel>
+						<Input id="ui-field-email" type="email" defaultValue="kira@example.com" />
+						<FieldDescription>Used for critical account notifications.</FieldDescription>
+					</Field>
+					<Field data-invalid="true">
+						<FieldLabel htmlFor="ui-field-backup-email">Backup email</FieldLabel>
+						<Input id="ui-field-backup-email" type="email" aria-invalid defaultValue="invalid" />
+						<FieldError>Enter a valid email address.</FieldError>
+					</Field>
+				</FieldGroup>
+			</FieldSet>
+		</>
+	);
+}
+
+export function KbdExample() {
+	return (
+		<>
+			<KbdGroup>
+				<Kbd>Ctrl</Kbd>
+				<Kbd>K</Kbd>
+			</KbdGroup>
 		</>
 	);
 }
@@ -87,4 +182,8 @@ export function SelectExample() {
 - `InputExample`
 - `TextareaExample`
 - `SelectExample`
+- `NativeSelectExample`
+- `InputOTPExample`
+- `FieldExample`
+- `KbdExample`
 

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

@@ -0,0 +1,71 @@
+---
+id: ui/layout-primitives
+title: "UI · Layout primitives"
+description: "AspectRatio and Resizable primitives."
+layer: ui
+family: "Layout"
+sourcePath: src/components/ui
+examples:
+  - AspectRatioExample
+  - ResizableExample
+imports:
+  - @/components/ui/aspect-ratio
+  - @/components/ui/resizable
+tags:
+  - ui
+  - layout
+  - primitives
+  - aspectratio
+  - resizable
+---
+
+# UI · Layout primitives
+
+AspectRatio and Resizable primitives.
+
+**Layer:** `ui`
+**Source:** `src/components/ui`
+
+## Examples
+
+```tsx
+import { AspectRatio } from '@/components/ui/aspect-ratio';
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@/components/ui/resizable';
+
+export function AspectRatioExample() {
+	return (
+		<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-md border border-border bg-muted/40">
+			<div className="flex size-full items-center justify-center text-sm text-muted-foreground">
+				16:9 content well
+			</div>
+		</AspectRatio>
+	);
+}
+
+export function ResizableExample() {
+	return (
+		<ResizablePanelGroup
+			orientation="horizontal"
+			className="min-h-40 max-w-2xl rounded-md border border-border"
+		>
+			<ResizablePanel defaultSize={35}>
+				<div className="flex h-full items-center justify-center p-4 text-sm text-muted-foreground">
+					Navigation
+				</div>
+			</ResizablePanel>
+			<ResizableHandle withHandle />
+			<ResizablePanel defaultSize={65}>
+				<div className="flex h-full items-center justify-center p-4 text-sm text-muted-foreground">
+					Workspace
+				</div>
+			</ResizablePanel>
+		</ResizablePanelGroup>
+	);
+}
+```
+
+## Example exports
+
+- `AspectRatioExample`
+- `ResizableExample`
+