admin-ui-starter-kit 0.4.4 → 0.5.0

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

@@ -133,19 +133,23 @@ Review the diff before deleting local folders.
 | Icon/avatar/title row | `admin-ui-starter-kit/base/item` |
 | Label/value metadata | `admin-ui-starter-kit/base/display/metadata` |
 | Form rows | `admin-ui-starter-kit/base/forms` |
+| Form workflow chrome | `FormSection`, `FormActionsBar`, `ErrorSummary`, `DirtyStateBanner`, `SubmitStateButton` from `admin-ui-starter-kit/base/forms` |
 | Schema-driven settings/config forms | `admin-ui-starter-kit/features/schema-form` |
 | Generated read-only slug | `SlugField` from `admin-ui-starter-kit/base/forms` |
 | Password with reveal button | `PasswordInput` from `admin-ui-starter-kit/base/forms` |
-| Searchable selects | `admin-ui-starter-kit/base/combobox` |
+| Searchable selects / async resource pickers | `EnhancedCombobox`, `EnhancedComboboxMultiple`, `AsyncResourceCombobox` from `admin-ui-starter-kit/base/combobox` |
 | Date pickers | `admin-ui-starter-kit/base/date-pickers` |
-| Tables | `admin-ui-starter-kit/base/table` |
-| Filters | `admin-ui-starter-kit/features/filters` |
+| Tables / index cells | `DataTable`, `ResourceCell`, `StatusClusterCell`, `DateMetaCell` from `admin-ui-starter-kit/base/table` |
+| Data-view chrome | `admin-ui-starter-kit/base/data-view` |
+| Filters / filter URL state | `FilterProvider`, `FilterLayout`, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` from `admin-ui-starter-kit/features/filters` |
 | 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` |
+| Selected-resource cards | `ResourceSelectorCard` from `admin-ui-starter-kit/composed/data-display` |
+| Settings/action/token surfaces | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` from `admin-ui-starter-kit/composed/admin` |
+| Page/header/sidebar/resource/settings chrome | `admin-ui-starter-kit/layout/page`, `/header`, `/sidebar`, `/resource`, `/settings` |
 
 ## Selection rules
 
@@ -154,6 +158,20 @@ 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 `ResourceIndexShell` / `ResourceShowShell` / `TabbedResourceShell` for
+admin index and show pages before keeping local `h-[calc(...)]`, sticky header,
+or show-page card scaffolding. Use `SettingsShell` / `AsideNavShell` for
+settings sections with left navigation. Always pass app routing through
+`renderLink`.
+
+Use `DataTable` selection-toolbar props and exported table cells for /users
+style index pages. Keep URL/search/sort state in the app, and use the filters
+query helpers only to transform plain query records before routing.
+
+Use `AsyncResourceCombobox` plus `ResourceSelectorCard` for "pick a resource"
+flows. The package owns selector/card UI state; the app owns the dialog,
+fetcher, route generation, permissions, and mutation side effects.
+
 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
@@ -161,6 +179,10 @@ local with `features/overlays`. Read
 `references/actions-service.md` before migrating repeated action menus or
 framework-bound action wrappers.
 
+Read `references/package-gap-surfaces.md` before keeping local index-page,
+settings-page, token-manager, resource-picker, or show-page glue in a consumer
+app. Those patterns now have package-owned neutral surfaces.
+
 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

@@ -30,11 +30,36 @@ import {
 	ActionOverlayOutlet,
 	ActionProvider,
 	type ActionFeedbackHandlers,
+	type ActionRequestRunner,
+	type ActionRuntimeGlue,
 } from 'admin-ui-starter-kit/services/actions';
 
+const requestRunner: ActionRequestRunner = async (request) => {
+	if (request.target?.type === 'named') {
+		return appVisit(appRoute(request.target.name, request.target.params), {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	if (request.target?.type === 'url') {
+		return appHttp(request.target.url, {
+			...request.options,
+			method: request.method,
+			data: request.data,
+			headers: request.headers,
+		});
+	}
+
+	throw new Error('Action request target is missing.');
+};
+
 const feedback: ActionFeedbackHandlers = {
 	onSuccess: (event) => {
 		if (event.message) toast.success(event.message);
+		queryClient.invalidateQueries({ queryKey: [event.actionId] });
 	},
 	onError: (event) => {
 		if (event.message) toast.error(event.message);
@@ -42,9 +67,21 @@ const feedback: ActionFeedbackHandlers = {
 	},
 };
 
+const runtime: ActionRuntimeGlue = {
+	requestRunner,
+	feedback,
+	guards: {
+		can: (permission) => auth.can(permission),
+		hasAnyRole: (roles) => auth.hasAnyRole(roles),
+	},
+	parseErrors: (error) => parseBackendActionError(error),
+	onOverlayOpenChange: (open) => polling.setPaused(open),
+	onRunningChange: (running) => activity.setBusy(running),
+};
+
 export function AppRoot() {
 	return (
-		<ActionProvider feedback={feedback}>
+		<ActionProvider runtime={runtime}>
 			<App />
 			<ActionOverlayOutlet />
 		</ActionProvider>
@@ -55,6 +92,25 @@ export function AppRoot() {
 Do not put router, query, toast, telemetry, or i18n packages inside a package
 wrapper. They stay in the consuming app and enter through callbacks.
 
+For serious migrations, prefer `ActionRuntimeGlue` over app-local package
+mirrors. Keep visit/router libraries, cache invalidation, toast systems, auth
+services, backend error parsing, and polling control in the consuming app. The
+package receives them only through `runtime` callbacks.
+
+Provider contract:
+
+| Prop | Consumer responsibility |
+| --- | --- |
+| `feedback` | Toasts, telemetry, global success/error handling. |
+| `requestRunner` | Execute normalized `request` definitions through the app transport. |
+| `guards` | Permission and role checks for `permission` and `roles`. |
+| `parseErrors` | Normalize backend validation/errors into `{ fieldErrors, message }`. |
+| `onOverlayOpenChange` | Pause polling or background refresh while action overlays are open. |
+| `onRunningChange` | Track whether any action is running. |
+
+Per-action `run`, `requestRunner`, and `parseErrors` override provider-level
+defaults when a workflow needs special handling.
+
 ## Page Scope
 
 Register definitions once per scope. Do not register one action array per row.
@@ -116,6 +172,98 @@ For row menus, call `useActionSurface({ surface: 'table-row', payload: row })`
 from the row component and map the returned actions into the existing menu
 component.
 
+Use `toPageAction`, `toMenuAction`, `toTableAction`, and `toCommandAction` to
+map resolved package actions into package-owned surfaces without rebuilding the
+same glue in every app.
+
+## Local Actions
+
+Use `useLocalAction(definition, options)` when migrating an existing page-owned
+action hook. It keeps the definition local to the component but still uses the
+package lifecycle, guards, overlays, provider feedback, and request runner.
+
+```tsx
+const action = useLocalAction<Booking, { note: string }, Booking>({
+	id: 'booking.confirm',
+	label: 'Confirm booking',
+	modality: {
+		type: 'dialog',
+		title: ({ payload }) => `Confirm ${payload?.reference}`,
+		formId: 'confirm-booking-form',
+		render: ({ getFormProps, isRunning }) => (
+			<form {...getFormProps()} id="confirm-booking-form">
+				<textarea name="note" disabled={isRunning} />
+			</form>
+		),
+	},
+	request: {
+		method: 'post',
+		target: ({ payload }) => ({
+			type: 'named',
+			name: 'bookings.confirm',
+			params: payload?.id,
+		}),
+		data: ({ values }) => values,
+	},
+}, { payload: booking });
+```
+
+Prefer `ActionScope` + `useActionSurface` once multiple surfaces need the same
+definition.
+
+## Requests, Guards, And Errors
+
+Use `run` for bespoke behavior. Use `request` when actions repeat the same
+route/request boilerplate and a provider adapter can execute it.
+
+```tsx
+const archiveBooking: ActionDefinition<Booking, undefined, Booking> = {
+	id: 'booking.archive',
+	label: 'Archive booking',
+	permission: ['bookings.archive', 'bookings.manage'],
+	roles: ['admin', 'ops'],
+	request: {
+		method: 'post',
+		target: ({ payload }) => ({
+			type: 'named',
+			name: 'bookings.archive',
+			params: payload?.id,
+		}),
+		options: { preserveScroll: true },
+	},
+	successMessage: ({ payload }) => `${payload?.reference} archived`,
+};
+```
+
+`permission` arrays require every permission through `guards.can`. `roles`
+passes the full role list to `guards.hasAnyRole`. If a definition declares a
+permission or role and the matching guard is missing, the action is hidden.
+
+Normalize backend errors once at the provider for server validation:
+
+```tsx
+<ActionProvider
+	parseErrors={(error) => {
+		const response = error as {
+			errors?: Record<string, string | string[]>;
+			message?: string;
+		};
+
+		return {
+			fieldErrors: response.errors,
+			message: response.message ?? 'Action failed.',
+		};
+	}}
+>
+	<App />
+	<ActionOverlayOutlet />
+</ActionProvider>
+```
+
+Parsed `fieldErrors` land on `action.errors` and overlay render contexts.
+Parsed messages are used by failed lifecycle feedback unless the action defines
+an explicit `errorMessage`.
+
 ## Modality And Overlay Parity
 
 Use action modality for reusable modal workflows. A delete confirmation opened
@@ -227,8 +375,11 @@ Metadata merges from action definition, hook call, and individual
 
 - 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,
+- Keep route helpers, visit/router calls, cache/query clients, translations,
   permissions, and API clients in the app.
+- Do not request or add new package exports named after a framework, router,
+  query library, toast library, or i18n package. Use `ActionRuntimeGlue` and
+  app-owned adapters instead.
 - 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.

package/.agents/skills/admin-ui-consumer-migration/references/package-gap-surfaces.md

@@ -0,0 +1,52 @@
+# Package Surfaces For Admin Index/Show Pages
+
+Use this when a consumer page has local glue around `/users`, settings, tokens,
+or resource selectors.
+
+## Index Pages
+
+- Use `ResourceIndexShell` from `admin-ui-starter-kit/layout/resource` for the
+  page header, actions, toolbar, empty/loading/error slots, and content rhythm.
+- Use `DataTable` from `admin-ui-starter-kit/base/table` for row selection,
+  selection toolbar, sticky toolbar/header, max body height, and row actions.
+- Use `ResourceCell`, `StatusClusterCell`, and `DateMetaCell` for common user
+  and resource index columns.
+- Keep query state, route generation, sorting persistence, and data fetching in
+  the app.
+
+## Filters And URL State
+
+- Use `FilterProvider` / `FilterLayout` for UI state.
+- Use `parseFiltersFromQuery`, `serializeFiltersToQuery`, and
+  `mergeFilterQuery` to convert between `ActiveFilter[]` and plain query
+  records.
+- The helpers do not navigate. The app passes the resulting record to Inertia,
+  Next, React Router, TanStack Router, or plain `history` code.
+
+## Resource Pickers
+
+- Use `AsyncResourceCombobox` for remote searchable resource options.
+- Use `ResourceSelectorCard` for the selected resource summary.
+- Keep picker dialogs, fetch wrappers, permissions, routing, and mutations in
+  the app.
+
+## Show And Settings Pages
+
+- Use `ResourceShowShell` or `TabbedResourceShell` for resource detail pages.
+- Use `ResourceHeader` / `PersonHeader` for avatar/icon, title, badges,
+  metadata, and actions.
+- Use `ResourceDetailsSection` when a card is mostly metadata plus optional
+  body/help/action content.
+- Use `SettingsShell` / `AsideNavShell` for settings pages with left nav.
+  Always wire links through `renderLink`.
+
+## Action Surfaces
+
+- Use `ActionList` / `ActionRow` for settings rows and security panels.
+- Use `SensitiveActionCard` for delete/revoke/disable panels.
+- Use `CopyableSecretAlert` for one-time token or password values.
+- Use `ApiTokenManager` for neutral token CRUD UI. Persistence, confirmation,
+  backend validation, translations, and permissions remain app-owned callbacks.
+
+Use `services/actions` only when the same action definition needs shared
+loading/error/overlay/toast lifecycle across several package surfaces.

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

@@ -6,25 +6,25 @@
   {"id":"base/cards","title":"Cards (SmartCard)","description":"The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.","layer":"base","family":"Foundations","tags":["base","foundations","cards","smartcard","composed","card","primitive"],"sourcePath":"src/components/base/cards","publicImport":"admin-ui-starter-kit/base/cards","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.md"},
   {"id":"base/carousel","title":"Carousel","description":"Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","carousel","embla","backed","keyboard","orientation"],"sourcePath":"src/components/base/carousel","publicImport":"admin-ui-starter-kit/base/carousel","examples":["ProductCarousel","InsideControlsCarousel","GalleryCarousel","ProductGridGallery","TopNavigationCarousel","ResponsiveCarousel","VerticalCarousel","LocalizedControls"],"doc":"./base__carousel.md"},
   {"id":"base/chart","title":"Chart","description":"Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces.","layer":"base","family":"Display","tags":["base","display","chart","token","aware","recharts","helpers"],"sourcePath":"src/components/base/display/chart","publicImport":"admin-ui-starter-kit/base/display/chart","examples":["BarChartCard","AreaChartCard","LineChartCard","DonutChartCard","RadialChartCard","MixedSeriesChartCard"],"doc":"./base__chart.md"},
-  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","SizeSm","SizeMd","SizeLg","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.md"},
+  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncResourceCustomerPicker","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","SizeSm","SizeMd","SizeLg","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.md"},
   {"id":"base/copyable","title":"Copyable","description":"Click-to-copy inline span with hover affordance and toast feedback.","layer":"base","family":"Display","tags":["base","display","copyable","click","copy","inline","span"],"sourcePath":"src/components/base/copyable","publicImport":"admin-ui-starter-kit/base/copyable","examples":["Default","Mono","MonoTruncate","CustomDisplayValue","CustomToastMessage","RealisticOrderRow","CustomerListWithCopyableEmails"],"doc":"./base__copyable.md"},
   {"id":"base/currency","title":"Currency","description":"MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.","layer":"base","family":"Display","tags":["base","display","currency","moneydisplay","currencypairpreview","locale","aware"],"sourcePath":"src/components/base/currency","publicImport":"admin-ui-starter-kit/base/currency","examples":["Default","Sizes","MultipleCurrencies","EmptyState","PairStackedEmphasisVariants","PairInlineEmphasisVariants","PairMinimalVariant","CurrencyPairPreviewExample","ProviderConfigDualPricing","RealisticOrdersList"],"doc":"./base__currency.md"},
   {"id":"base/date-pickers","title":"Date pickers","description":"DatePicker (single / range / multiple) and MonthYearPicker — popover-based, locale-aware, with optional year dropdown and time input.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","date-pickers","date","pickers","datepicker","single"],"sourcePath":"src/components/base/date-pickers","publicImport":"admin-ui-starter-kit/base/date-pickers","examples":["Default","ModeSingle","ModeRange","ModeMultiple","WithYearDropdown","ButtonStyles","MonthYearPickerExample","DateRangePickerLegacy","WithTimeInput","RealisticDateFilter"],"doc":"./base__date-pickers.md"},
   {"id":"base/display","title":"Display","description":"The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern.","layer":"base","family":"Display","tags":["base","display","layer","avatar","iconbadge","inlinestat"],"sourcePath":"src/components/base/display","publicImport":"admin-ui-starter-kit/base/display","examples":["NotificationBannerVariants","AvatarSizes","StackedAvatarsExample","IconBadgeTones","IconBadgeShapes","IconBadgeSizes","InlineStatLayouts","SeparatorExample","TooltipExample","BooleanIndicatorExample","ShowIfExample","ThrottleAlertExample","VisuallyHiddenExample","PlaceholderPatternExample","AlertExample","ProgressExample","SkeletonExample","CollapsibleExample","DialogExample","DateBlockExample","MoneyDisplayExample","QRCodeExample","RealisticUserCard"],"doc":"./base__display.md"},
   {"id":"base/empty-state","title":"Empty state","description":"Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.","layer":"base","family":"Display","tags":["base","display","empty-state","empty","state","adaptive","zero"],"sourcePath":"src/components/base/display/empty-state","publicImport":"admin-ui-starter-kit/base/display","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./base__empty-state.md"},
   {"id":"base/event-calendar","title":"Event calendar","description":"Month view with categories, filtering, navigation rules, custom event rendering, and three day-heading variants.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","event-calendar","event","calendar","month","view"],"sourcePath":"src/components/base/event-calendar","publicImport":"admin-ui-starter-kit/base/event-calendar","examples":["Default","RangeModeMonthYearCompactMonthYearJump","NavigationLimitsDisabledDates","FilterEventRenderEventCustomEventRendering","DayHeadingVariantTinted","DayHeadingVariantBordered","DayHeadingVariantAccent","WithCustomStringsBG"],"doc":"./base__event-calendar.md"},
-  {"id":"base/forms","title":"Forms","description":"The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","full","form","scope","formfield"],"sourcePath":"src/components/base/forms","publicImport":"admin-ui-starter-kit/base/forms","examples":["BasicField","WithError","WithHelperText","InputBasic","InputWithIcons","PasswordInputExample","SlugFieldExample","InputWithAddons","InputClearableLoading","InputCharacterCount","TextareaExample","DecimalInputExample","PercentageInputExample","CurrencyInputExample","MoneyInputExample","WeightInputExample","DimensionsInputExample","SelectExample","RichSelectExample","RoundingModeSelectExample","SwitchExample","CheckboxExample","ToggleFieldExample","SwitchCardExample","PillRadioGroupExample","ListRadioGroupExample","CardRadioGroupExample","CardCheckboxGroupExample","DateTimeInputExample","TimePickerExample","SliderExample","TagsInputExample","PhoneInputExample","CoordinatesInputExample","StringRepeaterExample","ObjectRepeaterExample","KeyValueEditorExample","ListExample","LocalizedStringFieldExample","LocalizedObjectFieldExample","LocalizedStringRepeaterExample","AvatarUploadExample","DropzoneExample","WholeForm"],"doc":"./base__forms.md"},
+  {"id":"base/forms","title":"Forms","description":"The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","full","form","scope","formfield"],"sourcePath":"src/components/base/forms","publicImport":"admin-ui-starter-kit/base/forms","examples":["BasicField","WithError","WithHelperText","WorkflowChrome","InputBasic","InputWithIcons","PasswordInputExample","SlugFieldExample","InputWithAddons","InputClearableLoading","InputCharacterCount","TextareaExample","DecimalInputExample","PercentageInputExample","CurrencyInputExample","MoneyInputExample","WeightInputExample","DimensionsInputExample","SelectExample","RichSelectExample","RoundingModeSelectExample","SwitchExample","CheckboxExample","ToggleFieldExample","SwitchCardExample","PillRadioGroupExample","ListRadioGroupExample","CardRadioGroupExample","CardCheckboxGroupExample","DateTimeInputExample","TimePickerExample","SliderExample","TagsInputExample","PhoneInputExample","CoordinatesInputExample","StringRepeaterExample","ObjectRepeaterExample","KeyValueEditorExample","ListExample","LocalizedStringFieldExample","LocalizedObjectFieldExample","LocalizedStringRepeaterExample","AvatarUploadExample","DropzoneExample","WholeForm"],"doc":"./base__forms.md"},
   {"id":"base/frame","title":"Frame","description":"Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.","layer":"base","family":"Foundations","tags":["base","foundations","frame","grouped","panel","primitive","related"],"sourcePath":"src/components/base/frame","publicImport":"admin-ui-starter-kit/base/frame","examples":["DefaultFrame","StackedPanels","InverseFrame","DenseFitPanel","FrameVariantMatrix"],"doc":"./base__frame.md"},
   {"id":"base/item","title":"Item","description":"Canonical row primitive — icon/avatar/image media, title + description content, optional actions. Use ItemGroup to compose lists.","layer":"base","family":"Foundations","tags":["base","foundations","item","canonical","row","primitive","icon"],"sourcePath":"src/components/base/item","publicImport":"admin-ui-starter-kit/base/item","examples":["Basic","Variants","PolymorphicLink"],"doc":"./base__item.md"},
   {"id":"base/map","title":"Map","description":"Leaflet-backed map primitives — Map shell, MapTileLayer, MapMarker, MapPopup. Always wrap in a fixed-height container.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","map","leaflet","backed","primitives","shell"],"sourcePath":"src/components/base/map","publicImport":"admin-ui-starter-kit/base/map","examples":["Default","MultipleMarkers","TighterZoom","CompactSize"],"doc":"./base__map.md"},
   {"id":"base/metadata-list","title":"Metadata list","description":"Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.","layer":"base","family":"","tags":["base","metadata","list","flexible","label","value"],"sourcePath":"src/components/base/display/metadata","publicImport":"admin-ui-starter-kit/base/display/metadata","examples":["APISurface","Vertical2ColumnNoIcons","VerticalSingleColumnNoIcons","RowsTwoColumnWithHairlines","RowsReceiptStyle","RowsWithIconsTooltips","SectionedMultiCard","Dense4ColumnOverview","Example3ColumnWithIcons","HorizontalPillSummary","WithTitleSeparator","EmptyStateFallbacksCustomRenderers"],"doc":"./base__metadata-list.md"},
   {"id":"base/navigation","title":"Navigation","description":"The navigation primitives — PageHeader, Breadcrumbs, ActionMenu, LanguageSwitcher, SectionNav, SideNav, AsideNavigationMenu, TabNavigationMenu, NavigationTabs, OverflowTabBar.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","primitives","pageheader","breadcrumbs","actionmenu"],"sourcePath":"src/components/base/navigation","publicImport":"admin-ui-starter-kit/base/navigation","examples":["PageHeaderExample","SectionNavSticky","BreadcrumbsSizes","ActionMenuExample","LanguageSwitcherButtons","LanguageSwitcherInline","AsideNavigationMenuExample","TabNavigationMenuExample","NavigationTabsRound","SideNavCollapsibleGroups","OverflowTabBarResponsiveWithMoreMenu"],"doc":"./base__navigation.md"},
   {"id":"base/spinner","title":"Spinner","description":"Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.","layer":"base","family":"","tags":["base","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/base/spinner","publicImport":"admin-ui-starter-kit/base/spinner","examples":["Default","Variants","WithLabel","CustomColour","SectionPlaceholder"],"doc":"./base__spinner.md"},
-  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefaultSizeXsCompact","SizeSm","SizeBase","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","SizeSmGlassExplicitCellTextScaling","WithSortingRowActions","PaginationExample","RealisticOrdersTable","CellRenderers","WithRowSelection","WithColumnVisibility","WithCustomToolbar","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
+  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefaultSizeXsCompact","SizeSm","SizeBase","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","SizeSmGlassExplicitCellTextScaling","WithSortingRowActions","PaginationExample","RealisticOrdersTable","CellRenderers","IndexTableCells","WithRowSelection","WithColumnVisibility","WithCustomToolbar","DataViewChrome","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
   {"id":"base/typography","title":"Typography","description":"Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.","layer":"base","family":"Foundations","tags":["base","foundations","typography","heading","text","label","textlink"],"sourcePath":"src/components/typography","publicImport":"admin-ui-starter-kit/typography","examples":["HeadingTags","HeadingWithSubHeading","TextSizes","TextTypes","TextWeights","TextLineHeights","TextAlignment","TextContentAndHTML","TextTags","LabelExample","TextLinkVariants","TextLinkSizes","HighLightExample","UnderlineExample","DangerousHTMLExample","RealisticArticle"],"doc":"./base__typography.md"},
   {"id":"base/upload-tray","title":"Upload tray","description":"Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","fields","upload","tray","drag","drop"],"sourcePath":"src/components/base/forms/fields","publicImport":"admin-ui-starter-kit/base/forms","examples":["Default","EmptyDropzoneOnly","MixedItemStates","LiveSimulatedUpload","LocalisedFrench"],"doc":"./base__upload-tray.md"},
   {"id":"common/brand","title":"Common · Brand","description":"Inline Logo + AppLogo variants used by the preview shell.","layer":"common","family":"Branding","tags":["common","branding","_brand","brand","inline","logo","applogo"],"sourcePath":"src/preview/_brand","publicImport":"","examples":["LogoExample","AppLogoSizes","AppLogoVariants"],"doc":"./common__brand.md"},
-  {"id":"composed/admin","title":"Composed · Admin","description":"Team list, permissions, conversations, settings, inventory.","layer":"composed","family":"Admin","tags":["composed","admin","team","list","permissions","conversations"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel"],"doc":"./composed__admin.md"},
+  {"id":"composed/admin","title":"Composed · Admin","description":"Team list, permissions, conversations, settings, inventory.","layer":"composed","family":"Admin","tags":["composed","admin","team","list","permissions","conversations"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel","ActionSurfaces","TokenManager"],"doc":"./composed__admin.md"},
   {"id":"composed/ai","title":"Composed · AI","description":"Summary block + classification panel.","layer":"composed","family":"AI","tags":["composed","ai","summary","block","classification","panel"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AISummary","AIClassification"],"doc":"./composed__ai.md"},
   {"id":"composed/ai-elements","title":"Composed · AI (elements)","description":"Standalone surfaces ported from elements.ai-sdk.dev: shimmer, code-block, agent, package-info, reasoning, chain-of-thought, sources, inline-citation, task, artifact, file-tree, confirmation, attachment.","layer":"composed","family":"AI","tags":["composed","ai","elements","standalone","surfaces","ported"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["Counter","AiShimmerExample","AiAgentExample","AiCodeBlockExample","AiAttachmentExample","AiInlineCitationExample","AiSourcesExample","AiReasoningExample","AiChainOfThoughtExample","AiTaskExample","AiArtifactExample","AiFileTreeExample","AiPackageInfoExample","AiConfirmationExample"],"doc":"./composed__ai-elements.md"},
   {"id":"composed/ai-new","title":"Composed · AI (extras)","description":"Confidence dial, prompt suggestions, token usage card, message bubble, tool call, citation, feedback.","layer":"composed","family":"AI","tags":["composed","ai","extras","confidence","dial","prompt"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AiConfidenceCardExample","AiPromptSuggestionsExample","AiTokenUsageCardExample","AiMessageBubbleExample","AiToolCallExample","AiCitationExample","AiFeedbackExample"],"doc":"./composed__ai-new.md"},
@@ -45,6 +45,7 @@
   {"id":"composed/navigation","title":"Composed · Navigation & boards","description":"Kanban, tab switcher, time ruler, vendor performance, experience activity.","layer":"composed","family":"Navigation","tags":["composed","navigation","boards","kanban","tab","switcher"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["KanbanMicroBoardExample","TabSwitcherCardExample","TimeDistributionRulerExample","VendorPerformance","ExperienceActivity"],"doc":"./composed__navigation.md"},
   {"id":"composed/navigation-extras","title":"Composed · Navigation (extras)","description":"BreadcrumbProgress wizard + CategoryNavCard sidebar.","layer":"composed","family":"Navigation","tags":["composed","navigation","extras","breadcrumbprogress","wizard","categorynavcard"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["BreadcrumbProgressExample","CategoryNavCardExample"],"doc":"./composed__navigation-extras.md"},
   {"id":"composed/onboarding-checklist","title":"Composed · Onboarding · Checklist","description":"Step-list accordion with completed / in-progress / pending status indicators. Auto-opens the next non-completed step. Strings + status ARIA fully overridable. Composes base/accordion.","layer":"composed","family":"Onboarding","tags":["composed","onboarding","checklist","step","list","accordion"],"sourcePath":"src/components/composed/onboarding","publicImport":"admin-ui-starter-kit/composed/onboarding","examples":["BorderedDefaultPointOfSaleOnboarding","CardVariantWorkspaceSetupControlled","FlatVariantMinimal"],"doc":"./composed__onboarding-checklist.md"},
+  {"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","tags":["composed","data","display","resource-selector-card.tsx","resource","selector","card","selected"],"sourcePath":"src/components/composed/data-display/resource-selector-card.tsx","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["SelectedResource","EmptyResource"],"doc":"./composed__resource-selector-card.md"},
   {"id":"composed/timelines","title":"Composed · Timelines","description":"Read-only tracking timelines — steps, order, payment, activity stream, release changelog, project milestones. For interactive activity (segments, mass-config, resource registry, callbacks) see Features → Activity feed.","layer":"composed","family":"Timelines","tags":["composed","timelines","read","only","tracking","steps"],"sourcePath":"src/components/composed/timelines","publicImport":"admin-ui-starter-kit/composed/timelines","examples":["StepsVertical","StepsHorizontalExample","OrderTimeline","PaymentTimeline","ActivityStreamReadOnlyTracking","Changelog","Milestones"],"doc":"./composed__timelines.md"},
   {"id":"composed/vendor-profile","title":"Composed · Vendor profile","description":"VendorProfileCard with metrics, stats and actions.","layer":"composed","family":"Cards","tags":["composed","cards","vendor-profile","vendor","profile","vendorprofilecard","metrics"],"sourcePath":"src/components/composed/cards/vendor-profile","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithEverything","Minimal"],"doc":"./composed__vendor-profile.md"},
   {"id":"features/activities","title":"Features · Activity feed","description":"Interactive activity feed — generic, framework-agnostic, with headline segments, callbacks (actor / resource / action), strings, slots, mass event configuration, and a save/restore resource registry. For read-only tracking timelines (order, payment, changelog, milestones) see Composed → Timelines.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","activity","feed","interactive","generic"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["DefaultFeed","CompactFeed","RichFeed","EventConfiguration","CustomRows","ResourceRegistry"],"doc":"./features__activities.md"},
@@ -53,7 +54,7 @@
   {"id":"features/comments","title":"Features · Comments","description":"Generic, framework-agnostic comments with rich-text composer (TipTap-backed), inline resource references (mentions, links, badges), attachment uploads with progress, and reactions. Every callback / registry flows as a direct prop — no provider.","layer":"features","family":"Collaboration","tags":["features","collaboration","comments","generic","framework","agnostic","rich"],"sourcePath":"src/components/features/comments","publicImport":"admin-ui-starter-kit/features/comments","examples":["APISurface","CommentsExample","ReadOnly","EmptyStateCustomStrings","CustomReferenceRendering"],"doc":"./features__comments.md"},
   {"id":"features/enhanced-activities","title":"Features · Enhanced activities","description":"Shopify-style unified surface: domain events and comments under one chronological timeline. Comments render as note activities with MentionContent-powered user, booking, and order chips. Composer at the top uses the same TipTap-backed editor with the live mention trigger flow.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","enhanced","shopify","style","unified"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["APISurface","ActivityTimelineComposer","CompactDensity"],"doc":"./features__enhanced-activities.md"},
   {"id":"features/event-log","title":"Features · Event log","description":"Unified, mentions-aware mixed-source log: comments + audit events + system messages + custom kinds under one chronological surface. Inline `@user` / `#booking` / `$order` triggers work in the composer; resource chips render with tone-driven Badge variants in every entry kind.","layer":"features","family":"Collaboration","tags":["features","collaboration","event-log","event","log","unified","mentions"],"sourcePath":"src/components/features/event-log","publicImport":"admin-ui-starter-kit/features/event-log","examples":["APISurface","CommentsEventsUnderOneLog","ReadOnlyTimelineNoComposer"],"doc":"./features__event-log.md"},
-  {"id":"features/filters","title":"Filters","description":"Composable filter system. Search + multi-select stay always visible; the rest collapse behind a Filters button. Provider-driven so it works with any data source.","layer":"features","family":"Search & filter","tags":["features","search","filter","filters","composable","system","multi","select"],"sourcePath":"src/components/features/filters","publicImport":"admin-ui-starter-kit/features/filters","examples":["Default"],"doc":"./features__filters.md"},
+  {"id":"features/filters","title":"Filters","description":"Composable filter system. Search + multi-select stay always visible; the rest collapse behind a Filters button. Provider-driven so it works with any data source.","layer":"features","family":"Search & filter","tags":["features","search","filter","filters","composable","system","multi","select"],"sourcePath":"src/components/features/filters","publicImport":"admin-ui-starter-kit/features/filters","examples":["Default","QueryStateHelpers"],"doc":"./features__filters.md"},
   {"id":"features/global-search","title":"GlobalSearch","description":"Async search palette with slots, render-props, and a headless useGlobalSearch hook.","layer":"features","family":"Search & filter","tags":["features","search","filter","global-search","globalsearch","async","palette","slots"],"sourcePath":"src/components/features/global-search","publicImport":"admin-ui-starter-kit/features/global-search","examples":["Default","IdleSuggestions","PopulatedResults","LoadingState","EmptyState"],"doc":"./features__global-search.md"},
   {"id":"features/kanban","title":"Features · Kanban","description":"Drag-and-drop board, generic in T. Pass `itemActions` (static array or per-item factory) for the ⋮ menu, `onItemClick` for whole-card click. Headless via `useKanban`; slots: KanbanBoard / KanbanColumn / KanbanColumnContent / KanbanItem / KanbanItemHandle / KanbanItemActions / KanbanOverlay.","layer":"features","family":"Boards","tags":["features","boards","kanban","drag","drop","board","generic"],"sourcePath":"src/components/features/kanban","publicImport":"admin-ui-starter-kit/features/kanban","examples":["RoadmapBoardWithActionsOnItemClick"],"doc":"./features__kanban.md"},
   {"id":"features/media-library","title":"Features · Media Library","description":"Framework-agnostic media picker for admin product, CMS, and campaign flows. Provides an embeddable library surface, a Dialog-backed picker wrapper, upload staging, details editing, controlled selection, async fetching, slots, render hooks, and headless state through useMediaLibrary.","layer":"features","family":"Assets","tags":["features","assets","media-library","media","library","framework","agnostic"],"sourcePath":"src/components/features/media-library","publicImport":"admin-ui-starter-kit/features/media-library","examples":["EmbeddedLibrary","ProductMediaDialog","ResourceGalleryList","ExternalResourceGallery","ConfirmOnSelectDialog","AsyncFetcherLibrary","EmptyAndErrorStates","HeadlessSelection"],"doc":"./features__media-library.md"},
@@ -76,8 +77,8 @@
   {"id":"layout/layout-app-shell","title":"Layout · App shell","description":"Standalone header-first shell with a 70px+ topbar and a sidebar/content body grid.","layer":"layout","family":"Shells","tags":["layout","shells","app-shell","app","shell","standalone","header"],"sourcePath":"src/components/layout/app-shell","publicImport":"admin-ui-starter-kit/layout/app-shell","examples":["DarkHeaderLeftSidebar","LightHeaderRightSidebar"],"doc":"./layout__layout-app-shell.md"},
   {"id":"layout/layout-auth","title":"Layout · Auth shell","description":"Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages.","layer":"layout","family":"Shells","tags":["layout","shells","auth","shell","framework","neutral","card"],"sourcePath":"src/components/layout/auth","publicImport":"admin-ui-starter-kit/layout/auth","examples":["CenteredCardAuth","LocalizedPatternCardAuth","ProviderMatrixAuth","ResetPasswordAuth","SplitAuthShell","RightSplitAuthShell","FrameworkLinkContract"],"doc":"./layout__layout-auth.md"},
   {"id":"layout/layout-containers","title":"Layout · Containers","description":"Container and Section primitives for page structure, width clamps, padding density, and semantic wrappers.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","containers","container","section","primitives","page"],"sourcePath":"src/components/layout/containers","publicImport":"admin-ui-starter-kit/layout/containers","examples":["NarrowContainer","WideContainer","BareContainer","SectionRhythm"],"doc":"./layout__layout-containers.md"},
-  {"id":"layout/layout-header","title":"Layout · Header","description":"Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.","layer":"layout","family":"Shells","tags":["layout","shells","header","topbar","breadcrumbs","command"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppHeaderComposition","HeaderPartials","CustomNotificationRenderer"],"doc":"./layout__layout-header.md"},
-  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","header","partials","actions"],"sourcePath":"src/components/layout/page","publicImport":"admin-ui-starter-kit/layout/page","examples":["ProductionPageShell","ComposablePartials"],"doc":"./layout__layout-page.md"},
+  {"id":"layout/layout-header","title":"Layout · Header","description":"Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.","layer":"layout","family":"Shells","tags":["layout","shells","header","topbar","breadcrumbs","command"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppHeaderComposition","HeaderPartials","HeaderToolPrimitives","CustomNotificationRenderer"],"doc":"./layout__layout-header.md"},
+  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","header","partials"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["ProductionPageShell","ComposablePartials","ResourceShells","TabbedResourceDetails","SettingsShellExample"],"doc":"./layout__layout-page.md"},
   {"id":"layout/layout-sidebar","title":"Layout · Sidebar","description":"Full app sidebar assembly plus reusable navigation, workspace, and footer item partials.","layer":"layout","family":"Shells","tags":["layout","shells","sidebar","full","app","assembly"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppSidebarShell","NavigationPartials","CustomRowRenderer"],"doc":"./layout__layout-sidebar.md"},
   {"id":"layout/layout-users","title":"Layout · Users & avatars","description":"User identity surfaces used by layout headers, sidebars, menus, avatar groups, and status badges.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","users","avatars","user","identity"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AvatarStates","HeaderUserMenuExample","SidebarUserMenu","CustomTriggerCustomContent"],"doc":"./layout__layout-users.md"},
   {"id":"layout/layout-workspace","title":"Layout · Workspace","description":"Nested record workspace shell with header, workflow navigation, scroll-owned body, and optional right rail.","layer":"layout","family":"Shells","tags":["layout","shells","workspace","nested","record","shell","header"],"sourcePath":"src/components/layout/workspace","publicImport":"admin-ui-starter-kit/layout/workspace","examples":["ProductRecordWorkspaceShell","WorkspaceWithoutRail"],"doc":"./layout__layout-workspace.md"},

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

@@ -58,6 +58,7 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [Composed · Navigation & boards](./composed__navigation.md) — Kanban, tab switcher, time ruler, vendor performance, experience activity.
 - [Composed · Navigation (extras)](./composed__navigation-extras.md) — BreadcrumbProgress wizard + CategoryNavCard sidebar.
 - [Composed · Onboarding · Checklist](./composed__onboarding-checklist.md) — Step-list accordion with completed / in-progress / pending status indicators. Auto-opens the next non-completed step. Strings + status ARIA fully overridable. Composes base/accordion.
+- [Composed · Resource selector card](./composed__resource-selector-card.md) — Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing.
 - [Composed · Timelines](./composed__timelines.md) — Read-only tracking timelines — steps, order, payment, activity stream, release changelog, project milestones. For interactive activity (segments, mass-config, resource registry, callbacks) see Features → Activity feed.
 - [Composed · Vendor profile](./composed__vendor-profile.md) — VendorProfileCard with metrics, stats and actions.
 

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

@@ -16,6 +16,7 @@ examples:
   - MultipleGrouped
   - GroupedTeamByRole
   - AsyncCustomers
+  - AsyncResourceCustomerPicker
   - AsyncDebouncedSearch
   - AsyncWithLoadMore
   - CustomItemRendering
@@ -139,6 +140,10 @@ message.
 	<Examples.AsyncCustomers />
 </Example>
 
+<Example name="AsyncResourceCustomerPicker" source={examplesSource}>
+	<Examples.AsyncResourceCustomerPicker />
+</Example>
+
 <Example name="AsyncDebouncedSearch" source={examplesSource}>
 	<Examples.AsyncDebouncedSearch />
 </Example>
@@ -200,7 +205,7 @@ message.
 ```tsx
 import { useEffect, useMemo, useState } from 'react';
 import { useForm } from 'react-hook-form';
-import { EnhancedCombobox, EnhancedComboboxMultiple } from '@/components/base/combobox';
+import { AsyncResourceCombobox, EnhancedCombobox, EnhancedComboboxMultiple } from '@/components/base/combobox';
 import { ControlledFormField } from '@/components/base/forms';
 import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Badge } from '@/components/base/badge';
@@ -504,6 +509,36 @@ export function AsyncCustomers() {
 	);
 }
 
+export function AsyncResourceCustomerPicker() {
+	const [selected, setSelected] = useState<typeof MOCK_CUSTOMERS[number] | null>(null);
+
+	return (
+		<div className="flex flex-col gap-2 w-80">
+			<AsyncResourceCombobox
+				fetcher={async ({ query }) => {
+					const data = await mockListCustomers();
+					const q = query.toLowerCase().trim();
+					return q
+						? data.filter((customer) =>
+							customer.name.toLowerCase().includes(q) ||
+							customer.email.toLowerCase().includes(q))
+						: data;
+				}}
+				value={selected}
+				onValueChange={setSelected}
+				getKey={(customer) => customer.id}
+				getLabel={(customer) => customer.name}
+				getDescription={(customer) => customer.email}
+				getMeta={(customer) => `${customer.city}, ${customer.country}`}
+				strings={{ placeholder: 'Search customer resources…' }}
+			/>
+			<Text size="xs" type="secondary">
+				selected: {selected?.name ?? '—'}
+			</Text>
+		</div>
+	);
+}
+
 export function AsyncDebouncedSearch() {
 	const [search, setSearch] = useState('');
 	const [results, setResults] = useState<typeof MOCK_TEAM>([]);
@@ -891,6 +926,7 @@ export function FormFieldIntegration() {
 - `MultipleGrouped`
 - `GroupedTeamByRole`
 - `AsyncCustomers`
+- `AsyncResourceCustomerPicker`
 - `AsyncDebouncedSearch`
 - `AsyncWithLoadMore`
 - `CustomItemRendering`

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

@@ -9,6 +9,7 @@ examples:
   - BasicField
   - WithError
   - WithHelperText
+  - WorkflowChrome
   - InputBasic
   - InputWithIcons
   - PasswordInputExample
@@ -106,6 +107,10 @@ to the inner field to flip the destructive border + ring.
 	<Examples.WithHelperText />
 </Example>
 
+<Example name="WorkflowChrome" source={examplesSource}>
+	<Examples.WorkflowChrome />
+</Example>
+
 ## Consumer usage
 
 Consumers import the form row wrappers and field primitives from the exact
@@ -369,7 +374,15 @@ import { useState } from 'react';
 import { useForm, FormProvider } from 'react-hook-form';
 import { Mail, Search, Lock, Star, Zap, Box, Globe, Shield } from 'lucide-react';
 
-import { FormField, ControlledFormField } from '@/components/base/forms';
+import {
+	ControlledFormField,
+	DirtyStateBanner,
+	ErrorSummary,
+	FormActionsBar,
+	FormField,
+	FormSection,
+	SubmitStateButton,
+} from '@/components/base/forms';
 import {
 	Input,
 	Textarea,
@@ -443,6 +456,47 @@ export function WithHelperText() {
 	);
 }
 
+export function WorkflowChrome() {
+	return (
+		<div className="grid gap-3">
+			<FormSection
+				title="Publishing"
+				description="Section chrome, validation summary, dirty state, and submit state stay reusable across form libraries."
+				actions={<Button variant="secondary" size="sm">Reset</Button>}
+			>
+				<div className="grid gap-3 sm:grid-cols-2">
+					<FormField label="Display title" required>
+						<Input defaultValue="Summer collection" />
+					</FormField>
+					<FormField label="Status">
+						<Select
+							defaultValue="draft"
+							options={[
+								{ value: 'draft', label: 'Draft' },
+								{ value: 'published', label: 'Published' },
+							]}
+						/>
+					</FormField>
+				</div>
+			</FormSection>
+			<ErrorSummary
+				title="Fix publishing errors"
+				description="Two fields need attention before this can publish."
+				errors={['Display title is required', 'Publish date must be in the future']}
+			/>
+			<DirtyStateBanner
+				title="Unsaved changes"
+				description="Save or discard before leaving this workflow."
+				actions={<Button variant="secondary" size="sm">Discard</Button>}
+			/>
+			<FormActionsBar
+				leading={<span className="text-xs text-muted-foreground">Last saved 2 minutes ago</span>}
+				trailing={<SubmitStateButton isDirty>Save changes</SubmitStateButton>}
+			/>
+		</div>
+	);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Text inputs
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1178,6 +1232,7 @@ export function WholeForm() {
 - `BasicField`
 - `WithError`
 - `WithHelperText`
+- `WorkflowChrome`
 - `InputBasic`
 - `InputWithIcons`
 - `PasswordInputExample`