admin-ui-starter-kit 0.4.2 → 0.4.4

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

@@ -1,12 +1,14 @@
 ---
 id: ui/menus
 title: "UI · Menus"
-description: "DropdownMenu, ContextMenu, Command palette."
+description: "DropdownMenu, Menubar, NavigationMenu, ContextMenu, and Command palette."
 layer: ui
 family: "Overlays"
 sourcePath: src/components/ui
 examples:
   - DropdownMenuExample
+  - MenubarExample
+  - NavigationMenuExample
   - ContextMenuRightClick
   - CommandPalette
 imports:
@@ -14,18 +16,20 @@ imports:
   - @/components/ui/command
   - @/components/ui/context-menu
   - @/components/ui/dropdown-menu
+  - @/components/ui/menubar
+  - @/components/ui/navigation-menu
 tags:
   - ui
   - overlays
   - menus
   - dropdownmenu
-  - contextmenu
-  - command
+  - menubar
+  - navigationmenu
 ---
 
 # UI · Menus
 
-DropdownMenu, ContextMenu, Command palette.
+DropdownMenu, Menubar, NavigationMenu, ContextMenu, and Command palette.
 
 **Layer:** `ui`
 **Source:** `src/components/ui`
@@ -33,7 +37,7 @@ DropdownMenu, ContextMenu, Command palette.
 ## Examples
 
 ```tsx
-import { Edit, Trash2, Copy } from 'lucide-react';
+import { Copy, Edit, ExternalLink, Trash2 } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import {
 	DropdownMenu,
@@ -59,21 +63,97 @@ import {
 	CommandItem,
 	CommandList,
 } from '@/components/ui/command';
+import {
+	Menubar,
+	MenubarContent,
+	MenubarItem,
+	MenubarMenu,
+	MenubarSeparator,
+	MenubarTrigger,
+} from '@/components/ui/menubar';
+import {
+	NavigationMenu,
+	NavigationMenuContent,
+	NavigationMenuItem,
+	NavigationMenuLink,
+	NavigationMenuList,
+	NavigationMenuTrigger,
+} from '@/components/ui/navigation-menu';
 
 export function DropdownMenuExample() {
 	return (
 		<>
 			<DropdownMenu>
-								<DropdownMenuTrigger render={(p) => <Button variant="outline" {...p}>Open menu</Button>} />
-								<DropdownMenuContent>
-									<DropdownMenuLabel>Actions</DropdownMenuLabel>
-									<DropdownMenuSeparator />
-									<DropdownMenuItem><Edit className="size-3.5" /> Edit</DropdownMenuItem>
-									<DropdownMenuItem><Copy className="size-3.5" /> Duplicate</DropdownMenuItem>
-									<DropdownMenuSeparator />
-									<DropdownMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</DropdownMenuItem>
-								</DropdownMenuContent>
-							</DropdownMenu>
+				<DropdownMenuTrigger render={(p) => <Button variant="outline" {...p}>Open menu</Button>} />
+				<DropdownMenuContent>
+					<DropdownMenuLabel>Actions</DropdownMenuLabel>
+					<DropdownMenuSeparator />
+					<DropdownMenuItem><Edit className="size-3.5" /> Edit</DropdownMenuItem>
+					<DropdownMenuItem><Copy className="size-3.5" /> Duplicate</DropdownMenuItem>
+					<DropdownMenuSeparator />
+					<DropdownMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
+		</>
+	);
+}
+
+export function MenubarExample() {
+	return (
+		<>
+			<Menubar>
+				<MenubarMenu>
+					<MenubarTrigger>File</MenubarTrigger>
+					<MenubarContent>
+						<MenubarItem>New workspace</MenubarItem>
+						<MenubarItem>Import data</MenubarItem>
+						<MenubarSeparator />
+						<MenubarItem variant="destructive">Archive</MenubarItem>
+					</MenubarContent>
+				</MenubarMenu>
+				<MenubarMenu>
+					<MenubarTrigger>View</MenubarTrigger>
+					<MenubarContent>
+						<MenubarItem>Compact rows</MenubarItem>
+						<MenubarItem>Show filters</MenubarItem>
+					</MenubarContent>
+				</MenubarMenu>
+			</Menubar>
+		</>
+	);
+}
+
+export function NavigationMenuExample() {
+	return (
+		<>
+			<NavigationMenu>
+				<NavigationMenuList>
+					<NavigationMenuItem>
+						<NavigationMenuTrigger>Operations</NavigationMenuTrigger>
+						<NavigationMenuContent>
+							<div className="grid w-[360px] gap-1">
+								<NavigationMenuLink href="#orders">
+									<ExternalLink className="size-4" />
+									<div>
+										<div className="font-medium">Orders</div>
+										<div className="text-xs text-muted-foreground">Review active fulfillment queues.</div>
+									</div>
+								</NavigationMenuLink>
+								<NavigationMenuLink href="#inventory">
+									<ExternalLink className="size-4" />
+									<div>
+										<div className="font-medium">Inventory</div>
+										<div className="text-xs text-muted-foreground">Monitor low-stock and replenishment signals.</div>
+									</div>
+								</NavigationMenuLink>
+							</div>
+						</NavigationMenuContent>
+					</NavigationMenuItem>
+					<NavigationMenuItem>
+						<NavigationMenuLink href="#reports">Reports</NavigationMenuLink>
+					</NavigationMenuItem>
+				</NavigationMenuList>
+			</NavigationMenu>
 		</>
 	);
 }
@@ -82,20 +162,20 @@ export function ContextMenuRightClick() {
 	return (
 		<>
 			<ContextMenu>
-								<ContextMenuTrigger>
-									<div className="flex h-24 w-full items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
-										Right-click here
-									</div>
-								</ContextMenuTrigger>
-								<ContextMenuContent>
-									<ContextMenuLabel>File</ContextMenuLabel>
-									<ContextMenuSeparator />
-									<ContextMenuItem><Edit className="size-3.5" /> Rename</ContextMenuItem>
-									<ContextMenuItem><Copy className="size-3.5" /> Copy</ContextMenuItem>
-									<ContextMenuSeparator />
-									<ContextMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</ContextMenuItem>
-								</ContextMenuContent>
-							</ContextMenu>
+				<ContextMenuTrigger>
+					<div className="flex h-24 w-full items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground">
+						Right-click here
+					</div>
+				</ContextMenuTrigger>
+				<ContextMenuContent>
+					<ContextMenuLabel>File</ContextMenuLabel>
+					<ContextMenuSeparator />
+					<ContextMenuItem><Edit className="size-3.5" /> Rename</ContextMenuItem>
+					<ContextMenuItem><Copy className="size-3.5" /> Copy</ContextMenuItem>
+					<ContextMenuSeparator />
+					<ContextMenuItem variant="destructive"><Trash2 className="size-3.5" /> Delete</ContextMenuItem>
+				</ContextMenuContent>
+			</ContextMenu>
 		</>
 	);
 }
@@ -104,20 +184,20 @@ export function CommandPalette() {
 	return (
 		<>
 			<Command className="rounded-md border border-border">
-								<CommandInput placeholder="Type a command…" />
-								<CommandList>
-									<CommandEmpty>No results.</CommandEmpty>
-									<CommandGroup heading="Actions">
-										<CommandItem>Create order</CommandItem>
-										<CommandItem>Add customer</CommandItem>
-										<CommandItem>Generate invoice</CommandItem>
-									</CommandGroup>
-									<CommandGroup heading="Navigation">
-										<CommandItem>Go to Orders</CommandItem>
-										<CommandItem>Go to Settings</CommandItem>
-									</CommandGroup>
-								</CommandList>
-							</Command>
+				<CommandInput placeholder="Type a command…" />
+				<CommandList>
+					<CommandEmpty>No results.</CommandEmpty>
+					<CommandGroup heading="Actions">
+						<CommandItem>Create order</CommandItem>
+						<CommandItem>Add customer</CommandItem>
+						<CommandItem>Generate invoice</CommandItem>
+					</CommandGroup>
+					<CommandGroup heading="Navigation">
+						<CommandItem>Go to Orders</CommandItem>
+						<CommandItem>Go to Settings</CommandItem>
+					</CommandGroup>
+				</CommandList>
+			</Command>
 		</>
 	);
 }
@@ -126,6 +206,8 @@ export function CommandPalette() {
 ## Example exports
 
 - `DropdownMenuExample`
+- `MenubarExample`
+- `NavigationMenuExample`
 - `ContextMenuRightClick`
 - `CommandPalette`
 

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

@@ -1,20 +1,24 @@
 ---
 id: ui/overlays
 title: "UI · Overlays"
-description: "Dialog, Sheet, Popover, Tooltip, HoverCard."
+description: "Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, and HoverCard."
 layer: ui
 family: "Overlays"
 sourcePath: src/components/ui
 examples:
   - DialogExample
+  - AlertDialogExample
   - SheetExample
+  - DrawerExample
   - PopoverExample
   - TooltipExample
   - HoverCardExample
 imports:
   - @/components/base/sheet
+  - @/components/ui/alert-dialog
   - @/components/ui/button
   - @/components/ui/dialog
+  - @/components/ui/drawer
   - @/components/ui/hover-card
   - @/components/ui/popover
   - @/components/ui/tooltip
@@ -22,14 +26,14 @@ tags:
   - ui
   - overlays
   - dialog
+  - alertdialog
   - sheet
-  - popover
-  - tooltip
+  - drawer
 ---
 
 # UI · Overlays
 
-Dialog, Sheet, Popover, Tooltip, HoverCard.
+Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, and HoverCard.
 
 **Layer:** `ui`
 **Source:** `src/components/ui`
@@ -38,8 +42,29 @@ Dialog, Sheet, Popover, Tooltip, HoverCard.
 
 ```tsx
 import { useState } from 'react';
+import {
+	AlertDialog,
+	AlertDialogAction,
+	AlertDialogCancel,
+	AlertDialogContent,
+	AlertDialogDescription,
+	AlertDialogFooter,
+	AlertDialogHeader,
+	AlertDialogTitle,
+	AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
 import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+import {
+	Drawer,
+	DrawerClose,
+	DrawerContent,
+	DrawerDescription,
+	DrawerFooter,
+	DrawerHeader,
+	DrawerTitle,
+	DrawerTrigger,
+} from '@/components/ui/drawer';
 import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger } from '@/components/base/sheet';
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
@@ -51,18 +76,42 @@ export function DialogExample() {
 	return (
 		<>
 			<Dialog open={open} onOpenChange={setOpen}>
-									<DialogTrigger render={(p) => <Button {...p}>Open dialog</Button>} />
-									<DialogContent>
-										<DialogHeader>
-											<DialogTitle>Confirm action</DialogTitle>
-											<DialogDescription>This is a controlled dialog.</DialogDescription>
-										</DialogHeader>
-										<DialogFooter>
-											<Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
-											<Button onClick={() => setOpen(false)}>Confirm</Button>
-										</DialogFooter>
-									</DialogContent>
-								</Dialog>
+				<DialogTrigger render={(p) => <Button {...p}>Open dialog</Button>} />
+				<DialogContent>
+					<DialogHeader>
+						<DialogTitle>Confirm action</DialogTitle>
+						<DialogDescription>This is a controlled dialog.</DialogDescription>
+					</DialogHeader>
+					<DialogFooter>
+						<Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+						<Button onClick={() => setOpen(false)}>Confirm</Button>
+					</DialogFooter>
+				</DialogContent>
+			</Dialog>
+		</>
+	);
+}
+
+export function AlertDialogExample() {
+	const [open, setOpen] = useState(false);
+
+	return (
+		<>
+			<AlertDialog open={open} onOpenChange={setOpen}>
+				<AlertDialogTrigger render={(p) => <Button variant="outline" {...p}>Open alert dialog</Button>} />
+				<AlertDialogContent>
+					<AlertDialogHeader>
+						<AlertDialogTitle>Archive workspace?</AlertDialogTitle>
+						<AlertDialogDescription>
+							This action removes the workspace from active views.
+						</AlertDialogDescription>
+					</AlertDialogHeader>
+					<AlertDialogFooter>
+						<AlertDialogCancel>Cancel</AlertDialogCancel>
+						<AlertDialogAction onClick={() => setOpen(false)}>Archive</AlertDialogAction>
+					</AlertDialogFooter>
+				</AlertDialogContent>
+			</AlertDialog>
 		</>
 	);
 }
@@ -71,15 +120,39 @@ export function SheetExample() {
 	return (
 		<>
 			<Sheet>
-									<SheetTrigger render={(p) => <Button variant="outline" {...p}>Open sheet</Button>} />
-									<SheetContent>
-										<SheetHeader>
-											<SheetTitle>Sheet title</SheetTitle>
-											<SheetDescription>Side-anchored panel.</SheetDescription>
-										</SheetHeader>
-										<div className="px-4 py-2 text-sm">Sheet body content.</div>
-									</SheetContent>
-								</Sheet>
+				<SheetTrigger render={(p) => <Button variant="outline" {...p}>Open sheet</Button>} />
+				<SheetContent>
+					<SheetHeader>
+						<SheetTitle>Sheet title</SheetTitle>
+						<SheetDescription>Side-anchored panel.</SheetDescription>
+					</SheetHeader>
+					<div className="px-4 py-2 text-sm">Sheet body content.</div>
+				</SheetContent>
+			</Sheet>
+		</>
+	);
+}
+
+export function DrawerExample() {
+	return (
+		<>
+			<Drawer direction="right">
+				<DrawerTrigger asChild>
+					<Button variant="outline">Open drawer</Button>
+				</DrawerTrigger>
+				<DrawerContent>
+					<DrawerHeader>
+						<DrawerTitle>Drawer title</DrawerTitle>
+						<DrawerDescription>Vaul-powered side panel.</DrawerDescription>
+					</DrawerHeader>
+					<div className="px-4 py-2 text-sm">Drawer body content.</div>
+					<DrawerFooter>
+						<DrawerClose asChild>
+							<Button variant="outline">Close</Button>
+						</DrawerClose>
+					</DrawerFooter>
+				</DrawerContent>
+			</Drawer>
 		</>
 	);
 }
@@ -88,11 +161,11 @@ export function PopoverExample() {
 	return (
 		<>
 			<Popover>
-									<PopoverTrigger render={(p) => <Button variant="outline" {...p}>Open popover</Button>} />
-									<PopoverContent className="w-64 text-sm">
-										Popover content with arbitrary children.
-									</PopoverContent>
-								</Popover>
+				<PopoverTrigger render={(p) => <Button variant="outline" {...p}>Open popover</Button>} />
+				<PopoverContent className="w-64 text-sm">
+					Popover content with arbitrary children.
+				</PopoverContent>
+			</Popover>
 		</>
 	);
 }
@@ -101,11 +174,11 @@ export function TooltipExample() {
 	return (
 		<>
 			<Row>
-									<Tooltip>
-										<TooltipTrigger render={(p) => <Button variant="outline" {...p}>Hover me</Button>} />
-										<TooltipContent>Hello, I'm a tooltip.</TooltipContent>
-									</Tooltip>
-								</Row>
+				<Tooltip>
+					<TooltipTrigger render={(p) => <Button variant="outline" {...p}>Hover me</Button>} />
+					<TooltipContent>Hello, I'm a tooltip.</TooltipContent>
+				</Tooltip>
+			</Row>
 		</>
 	);
 }
@@ -114,13 +187,13 @@ export function HoverCardExample() {
 	return (
 		<>
 			<HoverCard>
-									<HoverCardTrigger render={(p) => <Button variant="link" {...p}>@maria</Button>} />
-									<HoverCardContent className="w-64 text-sm">
-										<div className="font-medium">Sarah Smitha</div>
-										<div className="text-muted-foreground">Account Manager</div>
-										<div className="mt-2 text-xs text-muted-foreground">Joined Jan 2023.</div>
-									</HoverCardContent>
-								</HoverCard>
+				<HoverCardTrigger render={(p) => <Button variant="link" {...p}>@maria</Button>} />
+				<HoverCardContent className="w-64 text-sm">
+					<div className="font-medium">Sarah Smitha</div>
+					<div className="text-muted-foreground">Account Manager</div>
+					<div className="mt-2 text-xs text-muted-foreground">Joined Jan 2023.</div>
+				</HoverCardContent>
+			</HoverCard>
 		</>
 	);
 }
@@ -129,7 +202,9 @@ export function HoverCardExample() {
 ## Example exports
 
 - `DialogExample`
+- `AlertDialogExample`
 - `SheetExample`
+- `DrawerExample`
 - `PopoverExample`
 - `TooltipExample`
 - `HoverCardExample`

package/AGENTS.md

@@ -13,9 +13,9 @@ good or bad. Fixes propagate everywhere; mistakes do too.
 
 The architectural goals — and the reason every rule below exists — are:
 
-1. **Centralized**: shadcn primitives, typography, base wrappers,
-   composed surfaces, and feature shells all ship from one place.
-   Consumers upgrade once.
+1. **Centralized**: shadcn primitives live internally, while typography,
+   base wrappers, composed surfaces, and feature shells ship as the
+   public package surface. Consumers upgrade once.
 2. **Framework-agnostic**: Inertia, Tanstack Router, RR7, Next.js, plain
    Vite, anywhere. Routing, i18n, and data fetching arrive via callbacks
    and props at each call site. **The library never imports any framework
@@ -106,7 +106,10 @@ Hard rules (full detail in the skill):
   data / i18n at the call site via direct props
   (`onSubmit`, `onSelect`, `fetcher`, `strings`, …).
 - Direct imports from `@/components/ui/*` are allowed **only** inside
-  the matching `base/` wrapper. Anywhere else, use the wrapper.
+  the matching `base/` wrapper. Anywhere else, use the wrapper. Raw
+  `src/components/ui/*` files are not public package entrypoints;
+  consumers use `admin-ui-starter-kit/base/<family>`,
+  `admin-ui-starter-kit/features/<feature>`, etc.
 - Published package imports are exact subpaths. The root entrypoint
   exports only optional-peer-free utilities/provider; `base`,
   `composed`, and `features` aggregate entrypoints are intentionally

package/CHANGELOG.md

@@ -6,6 +6,30 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.4] — 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.
+
+### 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.
+
 ## [0.1.3] — 2026-05-22
 
 ### Added
@@ -98,6 +122,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.4...HEAD
+[0.4.4]: https://github.com/nicolasvlachos/admin-ui-starter-kit/compare/v0.1.3...v0.4.4
 [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,45 @@ 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:
+
+```tsx
+import {
+	ActionOverlayOutlet,
+	ActionProvider,
+	ActionScope,
+	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`,
+	},
+];
+
+<ActionProvider feedback={{ onSuccess: (event) => event.message && toast.success(event.message) }}>
+	<ActionScope scope={`customer:${customer.id}`} actions={customerActions}>
+		<CustomerPage />
+	</ActionScope>
+	<ActionOverlayOutlet />
+</ActionProvider>;
+```
+
+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