admin-ui-starter-kit 0.4.3 → 0.4.5

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,377 @@
+# 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.
+
+For serious migrations, prefer the package adapters over app-local action
+wrappers:
+
+```tsx
+import {
+	ActionOverlayOutlet,
+	ActionProvider,
+	createInertiaActionRunner,
+	createReactQueryActionFeedback,
+} from 'admin-ui-starter-kit/services/actions';
+
+<ActionProvider
+	requestRunner={createInertiaActionRunner({
+		router,
+		route,
+		defaults: { preserveScroll: true },
+	})}
+	feedback={createReactQueryActionFeedback({
+		queryClient,
+		invalidate: (event) => ({ queryKey: [event.actionId] }),
+		feedback: {
+			onError: (event) => event.message && toast.error(event.message),
+		},
+	})}
+	guards={{
+		can: (permission) => auth.can(permission),
+		hasAnyRole: (roles) => auth.hasAnyRole(roles),
+	}}
+	parseErrors={(error) => parseLaravelErrors(error)}
+	onOverlayOpenChange={(open) => polling.setPaused(open)}
+	onRunningChange={(running) => activity.setBusy(running)}
+>
+	<App />
+	<ActionOverlayOutlet />
+</ActionProvider>
+```
+
+These helpers are dependency-free. They accept router-like and query-client-like
+objects, so the package stays framework-neutral.
+
+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.
+
+```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.
+
+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',
+		route: 'bookings.confirm',
+		params: ({ payload }) => 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',
+		route: 'bookings.archive',
+		params: ({ payload }) => 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 Laravel/Inertia-style
+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
+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/CHANGELOG.md

@@ -6,6 +6,41 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.5] — 2026-06-20
+
+### Added
+
+- **Action modality / overlay parity** — reusable actions can now drive
+  package `Dialog`, `Drawer`, and `AlertDialog` flows through
+  `ActionOverlayOutlet` without losing overlay controls. `ActionModalityConfig`
+  now supports alert messages, custom footer composition, hidden headers,
+  focus refs, escape/backdrop behavior, content classes, confirm style, icon /
+  emphasis controls, and drawer footer visibility.
+- **Action migration APIs** — added `useLocalAction` for incremental
+  page-owned action migration, provider-level guards, provider/action error
+  parsing, request runner support, overlay/running state callbacks, typed action
+  factories, and surface mapping helpers.
+- **Dependency-free action adapters** — added HTTP, Inertia-like, and React
+  Query-like helpers that accept router/query-client objects without importing
+  framework packages into the library.
+
+### Fixed
+
+- `Drawer` and `AlertDialog` now honor `visuallyHideHeader` consistently while
+  keeping accessible names and descriptions intact.
+- `AlertDialog` now supports `alertMessage`, matching dialog/drawer emphasis
+  messaging and action-owned confirmation flows.
+
+### Documentation
+
+- Documented the recommended modality pattern: use
+  `services/actions` + `ActionOverlayOutlet` for reusable modal workflows, and
+  reserve `features/overlays` for one-off local state.
+- Expanded package-facing action docs across `README.md`, `INTEGRATION.md`,
+  the service README, and the consumer migration skill with provider contracts,
+  request runners, guards, error parsing, local actions, and migration choice
+  points.
+
 ## [0.1.3] — 2026-05-22
 
 ### Added
@@ -98,6 +133,7 @@ Initial public release.
 - **What this is not:** a marketing-site UI kit. Built for admin panels
   and SaaS dashboards.
 
-[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.4.5...HEAD
+[0.4.5]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.5
 [0.1.3]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.0...v0.1.3
 [0.1.0]: https://github.com/nicolasvlachos/admin-ui-starter-kit/releases/tag/v0.1.0

package/COMPONENT_SELECTION.md

@@ -42,6 +42,7 @@ or documented here, treat it as private.
 | Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
 | Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
 | Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
+| Shared action lifecycle across page/table/card/command/overlay surfaces | actions service | `admin-ui-starter-kit/services/actions` |
 
 ## Decision tree
 
@@ -64,7 +65,15 @@ or documented here, treat it as private.
    Use `layout`. Keep routing, active-link state, auth requests, and app
    translations in the app.
 
-6. Does it hardcode backend, auth, routing, app translations, or product
+6. Does the same action need to appear across multiple surfaces and share
+   loading, errors, overlay state, and toast feedback?
+   Use `services/actions`. Register typed actions from the page or feature,
+   then map `useActionSurface(...)` results into `PageActions`, table row
+   menus, card menus, or command palette rows. Use action modality for shared
+   alert/dialog/drawer flows, including form actions. Keep local one-off
+   dialogs in `features/overlays`.
+
+7. Does it hardcode backend, auth, routing, app translations, or product
    branding?
    Keep it in the app. Wrap package components only where the wrapper binds
    app-specific behaviour.

package/INTEGRATION.md

@@ -49,6 +49,7 @@ import { MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library'
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
 import { PageHeader } from 'admin-ui-starter-kit/layout/page';
+import { ActionProvider, ActionOverlayOutlet } from 'admin-ui-starter-kit/services/actions';
 ```
 
 Do not import `admin-ui-starter-kit/base`,
@@ -102,6 +103,13 @@ Common primitive choices:
   storage, fetching, URL resolution, and framework routing in the app through
   `fetcher`, `accessors`, `onUpload`, `onItemUpdate`, `onItemDelete`, `value`,
   and `onValueChange`.
+- Use `services/actions` when the same action definition should drive multiple
+  surfaces and share lifecycle state. Mount one `ActionProvider` near the app
+  shell, mount one `ActionOverlayOutlet`, register page actions with
+  `useRegisterActions` or `<ActionScope>`, and bridge lifecycle feedback to
+  your toast/telemetry system through provider callbacks. Use the resolved
+  action state (`status`, `isRunning`, `errors`, `result`) to drive loading,
+  disabled, and validation UI.
 - Use `Text`, `Heading`, `Label`, and `TextLink` instead of local typography
   utility spans.
 
@@ -148,6 +156,91 @@ For Next.js App Router or any React Server Components setup, import these
 components from a client component file (`'use client'`). The package is
 framework-neutral, but interactive UI still runs on the client.
 
+For shared actions, keep the registry framework-neutral and put framework
+calls inside callbacks or provider adapters:
+
+```tsx
+import {
+	ActionOverlayOutlet,
+	ActionProvider,
+	ActionScope,
+	createInertiaActionRunner,
+	createReactQueryActionFeedback,
+	type ActionDefinition,
+} from 'admin-ui-starter-kit/services/actions';
+
+const customerActions: ActionDefinition<Customer>[] = [
+	{
+		id: 'customer.delete',
+		label: 'Delete customer',
+		modality: {
+			type: 'alert',
+			tone: 'destructive',
+			title: ({ payload }) => `Delete ${payload?.name}?`,
+			confirmLabel: 'Delete',
+		},
+		run: ({ payload }) => router.delete(`/customers/${payload?.id}`),
+		successMessage: ({ payload }) => `${payload?.name} deleted`,
+	},
+	{
+		id: 'customer.archive',
+		label: 'Archive customer',
+		permission: 'customers.archive',
+		roles: ['admin', 'ops'],
+		modality: {
+			type: 'alert',
+			tone: 'warning',
+			title: ({ payload }) => `Archive ${payload?.name}?`,
+			confirmLabel: 'Archive',
+		},
+		request: {
+			method: 'post',
+			route: 'customers.archive',
+			params: ({ payload }) => payload?.id,
+			options: { preserveScroll: true },
+		},
+		successMessage: ({ payload }) => `${payload?.name} archived`,
+	},
+];
+
+<ActionProvider
+	requestRunner={createInertiaActionRunner({ router, route })}
+	feedback={createReactQueryActionFeedback({
+		queryClient,
+		invalidate: (event) => ({ queryKey: [event.actionId] }),
+		feedback: {
+			onSuccess: (event) => event.message && toast.success(event.message),
+			onError: (event) => event.message && toast.error(event.message),
+		},
+	})}
+	guards={{
+		can: (permission) => auth.can(permission),
+		hasAnyRole: (roles) => auth.hasAnyRole(roles),
+	}}
+	parseErrors={(error) => parseLaravelActionError(error)}
+	onOverlayOpenChange={(open) => polling.setPaused(open)}
+	onRunningChange={(running) => activity.setBusy(running)}
+>
+	<ActionScope scope={`customer:${customer.id}`} actions={customerActions}>
+		<CustomerPage />
+	</ActionScope>
+	<ActionOverlayOutlet />
+</ActionProvider>;
+```
+
+Use `useLocalAction(definition, options)` for one page-owned action during an
+incremental migration. Use `<ActionScope>` and `useActionSurface(...)` once the
+same definition needs to appear in page actions, table row menus, command
+palette entries, cards, or action-owned overlays. `ActionOverlayOutlet` renders
+action modality through the package `features/overlays`, so reusable modal
+workflows keep the same focus, backdrop, loading, submit, and error behavior as
+direct overlay usage.
+
+For form actions, set `modality.formId` and render a form through the modality
+render prop. The context exposes `getFormProps(...)`, `submit(values)`,
+`errors`, and loading/status flags. Keep `react-hook-form`, validation schemas,
+API calls, route changes, and translations in the app.
+
 ## 5. Compose Base UI triggers with `render`
 
 Some shadcn-style primitives in this package are backed by Base UI. Dropdown