themelia-ui 1.0.0

package/.agents/skills/themelia-ui/references/components/features--actions.md

@@ -0,0 +1,882 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `features/actions`
+
+The same operation runs from a table row, a card menu and the command palette, and all three must get one confirm, one loading state and one error path.
+
+## Selection
+
+- **Use when:** The same operation runs from a table row, a card menu and the command palette, and all three must get one confirm, one loading state and one error path.
+- **Avoid when:** One surface owns the action and nothing else invokes it — a registry then adds indirection for a single caller.
+- **Consider instead:** `features/overlays`, `base/action-menu`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { ActionHttpError } from "themelia-ui/features/actions"
+import "themelia-ui/features/actions.css"
+```
+
+## Composition
+
+This family composes `base/alert-dialog`, `base/buttons`, `base/dialog`, `base/feedback`, `base/sheet`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `ACTION_GLOBAL_SCOPE`
+
+Kind: const.
+
+```text
+unknown
+```
+
+### `ActionButtonStyle`
+
+Kind: type.
+
+### `ActionContext`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `actionId` | yes | `string` |
+| `scope` | yes | `string` |
+| `surface` | no | `ActionSurface` |
+| `payload` | yes | `TPayload \| undefined` |
+| `metadata` | no | `ActionMetadata` |
+
+### `ActionDefinition`
+
+Kind: interface.
+
+Extends: `Omit<ActionPresentation, 'visible' | 'disabled'>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | yes | `string` |
+| `label` | yes | `ReactNode` |
+| `searchLabel` | no | `string` |
+| `icon` | no | `ComponentType<{ className?: string; }>` |
+| `surfaces` | no | `readonly ActionSurface[]` |
+| `group` | no | `string` |
+| `placement` | no | `ActionPlacement` |
+| `order` | no | `number` |
+| `visible` | no | `ActionPredicate<TPayload>` |
+| `disabled` | no | `ActionPredicate<TPayload>` |
+| `permission` | no | `ActionPermission` |
+| `roles` | no | `ActionRoles` |
+| `modality` | no | `'none' \| ActionModalityConfig<TPayload, TValues, TResult>` |
+| `request` | no | `ActionRequestConfig<TPayload, TValues>` |
+| `requestRunner` | no | `ActionRequestRunner<TResult>` |
+| `run` | no | `BivariantCallback<[ context: ActionRunContext<TPayload, TValues> ], TResult \| Promise<TResult>>` |
+| `parseErrors` | no | `ActionErrorParser` |
+| `successMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `errorMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `onStart` | no | `BivariantCallback<[ event: ActionLifecycleEvent<TPayload, TValues, TResult> ], void>` |
+| `onAfterMutate` | no | `BivariantCallback<[ event: ActionLifecycleEvent<TPayload, TValues, TResult> ], void>` |
+| `onError` | no | `BivariantCallback<[ event: ActionLifecycleEvent<TPayload, TValues, TResult> ], void>` |
+| `onSettled` | no | `BivariantCallback<[ event: ActionLifecycleEvent<TPayload, TValues, TResult> ], void>` |
+| `metadata` | no | `ActionMetadata` |
+
+### `ActionDrawerDirection`
+
+Kind: type.
+
+```text
+'left' | 'right' | 'top' | 'bottom'
+```
+
+### `ActionEntry`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `key` | yes | `string` |
+| `registration` | yes | `ActionRegistration` |
+| `action` | yes | `ActionDefinition` |
+
+### `ActionErrorParseContext`
+
+Kind: interface.
+
+Extends: `ActionRunContext<TPayload, TValues>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `error` | yes | `unknown` |
+
+### `ActionErrorParser`
+
+Kind: type.
+
+```text
+BivariantCallback<[ error: unknown, context: ActionErrorParseContext ], ParsedActionError | ActionFieldErrors | string | null | undefined>
+```
+
+### `ActionFeedbackHandlers`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `onStart` | no | `(event: ActionLifecycleEvent) => void` |
+| `onSuccess` | no | `(event: ActionLifecycleEvent) => void` |
+| `onError` | no | `(event: ActionLifecycleEvent) => void` |
+| `onSettled` | no | `(event: ActionLifecycleEvent) => void` |
+
+### `ActionFieldErrors`
+
+Kind: type.
+
+```text
+Record<string, string | string[]>
+```
+
+### `ActionFormProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | no | `string` |
+| `onSubmit` | yes | `FormEventHandler<HTMLFormElement>` |
+
+### `ActionFormSubmitOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `resolveValues` | no | `(formData: FormData, event: FormEvent<HTMLFormElement>) => TValues \| Promise<TValues>` |
+
+### `ActionGuardContext`
+
+Kind: interface.
+
+Extends: `ActionContext<TPayload>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `action` | yes | `ActionDefinition` |
+
+### `ActionGuards`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `can` | no | `(permission: string, context: ActionGuardContext) => boolean` |
+| `hasAnyRole` | no | `(roles: readonly string[], context: ActionGuardContext) => boolean` |
+
+### `ActionHttpError`
+
+Kind: class.
+
+### `ActionHttpErrorOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `status` | yes | `number` |
+| `statusText` | yes | `string` |
+| `body` | yes | `unknown` |
+| `response` | yes | `Response` |
+
+### `ActionLifecycleEvent`
+
+Kind: interface.
+
+Extends: `ActionMessageContext<TPayload, TValues, TResult>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `type` | yes | `ActionLifecycleType` |
+| `key` | yes | `string` |
+| `status` | yes | `ActionStatus` |
+| `runState` | yes | `ActionRunState` |
+| `message` | no | `string` |
+
+### `ActionLifecycleType`
+
+Kind: type.
+
+```text
+'started' | 'succeeded' | 'failed' | 'settled'
+```
+
+### `ActionMessage`
+
+Kind: type.
+
+```text
+string | BivariantCallback<[ context: ActionMessageContext<TPayload, TValues, TResult> ], string | null | undefined>
+```
+
+### `ActionMessageContext`
+
+Kind: interface.
+
+Extends: `ActionContext<TPayload>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `action` | yes | `ActionDefinition` |
+| `values` | yes | `TValues \| undefined` |
+| `status` | no | `ActionStatus` |
+| `errors` | no | `ActionFieldErrors` |
+| `result` | no | `TResult` |
+| `error` | no | `unknown` |
+
+### `ActionMetadata`
+
+Kind: type.
+
+```text
+Record<string, unknown>
+```
+
+### `ActionModalityConfig`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `type` | yes | `ActionModalityType` |
+| `title` | yes | `ActionMessage<TPayload, TValues, TResult>` |
+| `description` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `confirmLabel` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `cancelLabel` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `tone` | no | `ActionTone` |
+| `size` | no | `ActionOverlaySize` |
+| `drawerDirection` | no | `ActionDrawerDirection` |
+| `formId` | no | `string` |
+| `showCancel` | no | `boolean` |
+| `showConfirm` | no | `boolean` |
+| `showIcon` | no | `boolean` |
+| `emphasis` | no | `boolean` |
+| `showFooter` | no | `boolean` |
+| `visuallyHideHeader` | no | `boolean` |
+| `className` | no | `string` |
+| `contentClassName` | no | `string` |
+| `initialFocusRef` | no | `RefObject<HTMLElement>` |
+| `closeOnEscape` | no | `boolean` |
+| `closeOnSuccess` | no | `boolean` |
+| `closeOnBackdropClick` | no | `boolean` |
+| `confirmStyle` | no | `Extract<ActionButtonStyle, 'solid' \| 'outline'>` |
+| `footer` | no | `ReactNode` |
+| `alertMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |
+| `render` | no | `BivariantCallback<[ context: ActionRenderContext<TPayload, TValues> ], ReactNode>` |
+
+### `ActionModalityType`
+
+Kind: type.
+
+```text
+'alert' | 'dialog' | 'drawer'
+```
+
+### `ActionOverlayOutlet`
+
+Kind: callable.
+
+```text
+({ strings }?: ActionOverlayOutletProps) => import("react").JSX.Element | null
+```
+
+### `ActionOverlayOutletProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `strings` | no | `StringsProp<ActionOverlayStrings>` |
+
+### `ActionOverlaySize`
+
+Kind: type.
+
+```text
+'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | 'full'
+```
+
+### `ActionOverlayStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `confirm` | yes | `string` |
+| `cancel` | yes | `string` |
+
+### `ActionPermission`
+
+Kind: type.
+
+```text
+string | readonly string[]
+```
+
+### `ActionPlacement`
+
+Kind: type.
+
+```text
+'auto' | 'inline' | 'menu'
+```
+
+### `ActionPredicate`
+
+Kind: type.
+
+```text
+boolean | BivariantCallback<[context: ActionContext<TPayload>], boolean>
+```
+
+### `ActionProvider`
+
+Kind: callable.
+
+```text
+({ actions, runtime, feedback, guards, parseErrors, requestRunner, onOverlayOpenChange, onRunningChange, children, }: ActionProviderProps<TPayload, TValues, TResult>) => ReactNode
+```
+
+### `ActionProviderProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `actions` | no | `readonly ActionDefinition<TPayload, TValues, TResult>[]` |
+| `runtime` | no | `ActionRuntimeGlue` |
+| `feedback` | no | `ActionFeedbackHandlers` |
+| `guards` | no | `ActionGuards` |
+| `parseErrors` | no | `ActionErrorParser` |
+| `requestRunner` | no | `ActionRequestRunner` |
+| `onOverlayOpenChange` | no | `(open: boolean, snapshot: ActionStoreSnapshot) => void` |
+| `onRunningChange` | no | `(running: boolean, snapshot: ActionStoreSnapshot) => void` |
+| `children` | yes | `ReactNode` |
+
+### `ActionRegistration`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | yes | `string` |
+| `scope` | yes | `string` |
+| `order` | yes | `number` |
+| `actions` | yes | `readonly ActionDefinition[]` |
+
+### `ActionRegistrationOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `scope` | no | `string` |
+
+### `ActionRenderContext`
+
+Kind: interface.
+
+Extends: `ActionContext<TPayload>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `action` | yes | `ActionDefinition` |
+| `values` | yes | `TValues \| undefined` |
+| `formId` | no | `string` |
+| `status` | yes | `ActionStatus` |
+| `isIdle` | yes | `boolean` |
+| `isRunning` | yes | `boolean` |
+| `isSuccess` | yes | `boolean` |
+| `isError` | yes | `boolean` |
+| `result` | yes | `unknown` |
+| `error` | yes | `unknown` |
+| `errors` | yes | `ActionFieldErrors` |
+| `close` | yes | `() => void` |
+| `submit` | yes | `(values?: TValues) => Promise<unknown>` |
+| `getFormProps` | yes | `(options?: ActionFormSubmitOptions<TValues>) => ActionFormProps` |
+
+### `ActionRequestConfig`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `method` | yes | `ActionRequestMethod` |
+| `target` | no | `ActionRequestValue<TPayload, TValues, ActionRequestTarget>` |
+| `data` | no | `ActionRequestValue<TPayload, TValues, unknown>` |
+| `headers` | no | `ActionRequestValue<TPayload, TValues, Record<string, string>>` |
+| `options` | no | `ActionRequestValue<TPayload, TValues, Record<string, unknown>>` |
+
+### `ActionRequestMethod`
+
+Kind: type.
+
+```text
+'get' | 'post' | 'put' | 'patch' | 'delete'
+```
+
+### `ActionRequestRunner`
+
+Kind: type.
+
+```text
+BivariantCallback<[ request: ResolvedActionRequest, context: ActionRunContext ], TResult | Promise<TResult>>
+```
+
+### `ActionRequestTarget`
+
+Kind: type.
+
+```text
+{ type: 'url'; url: string; } | { type: 'named'; name: string; params?: unknown; }
+```
+
+### `ActionRequestValue`
+
+Kind: type.
+
+```text
+TValue | BivariantCallback<[ context: ActionRunContext<TPayload, TValues> ], TValue>
+```
+
+### `ActionRoles`
+
+Kind: type.
+
+```text
+string | readonly string[]
+```
+
+### `ActionRunContext`
+
+Kind: interface.
+
+Extends: `ActionContext<TPayload>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `action` | yes | `ActionDefinition` |
+| `values` | yes | `TValues \| undefined` |
+| `signal` | yes | `AbortSignal` |
+
+### `ActionRunState`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `status` | yes | `ActionStatus` |
+| `isIdle` | yes | `boolean` |
+| `isRunning` | yes | `boolean` |
+| `isSuccess` | yes | `boolean` |
+| `isError` | yes | `boolean` |
+| `error` | yes | `unknown` |
+| `errors` | yes | `ActionFieldErrors` |
+| `message` | no | `string` |
+| `result` | no | `unknown` |
+| `payload` | no | `unknown` |
+| `values` | no | `unknown` |
+| `metadata` | no | `ActionMetadata` |
+| `startedAt` | no | `number` |
+| `completedAt` | no | `number` |
+
+### `ActionRuntimeGlue`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `requestRunner` | no | `ActionRequestRunner` |
+| `parseErrors` | no | `ActionErrorParser` |
+| `guards` | no | `ActionGuards` |
+| `feedback` | no | `ActionFeedbackHandlers` |
+| `onOverlayOpenChange` | no | `(open: boolean, snapshot: ActionStoreSnapshot) => void` |
+| `onRunningChange` | no | `(running: boolean, snapshot: ActionStoreSnapshot) => void` |
+
+### `ActionScope`
+
+Kind: callable.
+
+```text
+({ scope, actions, children, }: ActionScopeProps<TPayload, TValues, TResult>) => ReactNode
+```
+
+### `ActionScopeProps`
+
+Kind: interface.
+
+Extends: `ActionRegistrationOptions`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `actions` | yes | `readonly ActionDefinition<TPayload, TValues, TResult>[]` |
+| `children` | yes | `ReactNode` |
+
+### `ActionStatus`
+
+Kind: type.
+
+```text
+'idle' | 'running' | 'succeeded' | 'failed'
+```
+
+### `ActionStore`
+
+Kind: class.
+
+### `ActionStoreSnapshot`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `version` | yes | `number` |
+| `registrations` | yes | `readonly ActionRegistration[]` |
+| `runStates` | yes | `Readonly<Record<string, ActionRunState>>` |
+| `active` | yes | `ActiveActionState \| null` |
+
+### `ActionSurface`
+
+Kind: type.
+
+```text
+'page' | 'table' | 'table-row' | 'card' | 'command' | (string & {})
+```
+
+### `ActionSurfaceOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `surface` | yes | `ActionSurface` |
+| `scope` | no | `string` |
+| `includeGlobal` | no | `boolean` |
+| `payload` | no | `TPayload` |
+| `metadata` | no | `ActionMetadata` |
+
+### `ActionTone`
+
+Kind: type.
+
+```text
+SemanticTone
+```
+
+### `ActiveActionState`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `key` | yes | `string` |
+| `actionId` | yes | `string` |
+| `scope` | yes | `string` |
+| `payload` | no | `unknown` |
+| `values` | no | `unknown` |
+| `metadata` | no | `ActionMetadata` |
+
+### `createActionStore`
+
+Kind: callable.
+
+```text
+() => ActionStore
+```
+
+### `createHttpActionRunner`
+
+Kind: callable.
+
+```text
+({ baseUrl, fetcher, parseResponse, }?: CreateHttpActionRunnerOptions) => ActionRequestRunner<TResult>
+```
+
+### `CreateHttpActionRunnerOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `baseUrl` | no | `string` |
+| `fetcher` | no | `typeof fetch` |
+| `parseResponse` | no | `(response: Response) => Promise<unknown>` |
+
+### `defaultActionOverlayStrings`
+
+Kind: const.
+
+```text
+ActionOverlayStrings
+```
+
+### `defineAction`
+
+Kind: callable.
+
+```text
+(definition: ActionDefinition<TPayload, TValues, TResult>) => ActionDefinition<TPayload, TValues, TResult>
+```
+
+### `defineDeleteAction`
+
+Kind: callable.
+
+```text
+(definition: Omit<ActionDefinition<TPayload, undefined, TResult>, 'modality'> & { modality: Omit<ActionModalityConfig<TPayload, undefined, TResult>, 'type' | 'tone'> & Partial<Pick<ActionModalityConfig<TPayload, undefined, TResult>, 'type' | 'tone'>>; }) => ActionDefinition<TPayload, undefined, TResult>
+```
+
+### `defineFormAction`
+
+Kind: callable.
+
+```text
+(definition: Omit<ActionDefinition<TPayload, TValues, TResult>, 'modality'> & { modality: Omit<ActionModalityConfig<TPayload, TValues, TResult>, 'type'> & Partial<Pick<ActionModalityConfig<TPayload, TValues, TResult>, 'type'>>; }) => ActionDefinition<TPayload, TValues, TResult>
+```
+
+### `defineSilentAction`
+
+Kind: callable.
+
+```text
+(definition: Omit<ActionDefinition<TPayload, TValues, TResult>, 'modality'>) => ActionDefinition<TPayload, TValues, TResult>
+```
+
+### `extractActionFieldErrors`
+
+Kind: callable.
+
+```text
+(error: unknown) => ActionFieldErrors
+```
+
+### `parseActionError`
+
+Kind: callable.
+
+```text
+(error: unknown, context: ActionErrorParseContext<TPayload, TValues>, parser?: ActionErrorParser) => ParsedActionError
+```
+
+### `ParsedActionError`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `fieldErrors` | no | `ActionFieldErrors` |
+| `message` | no | `string` |
+
+### `resolveActionMessage`
+
+Kind: callable.
+
+```text
+(message: ActionMessage<TPayload, TValues, TResult> | undefined, context: ActionMessageContext<TPayload, TValues, TResult>) => string | undefined
+```
+
+### `resolveActionRequest`
+
+Kind: callable.
+
+```text
+(request: ActionRequestConfig<TPayload, TValues>, context: ActionRunContext<TPayload, TValues>) => ResolvedActionRequest
+```
+
+### `ResolvedAction`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `key` | yes | `string` |
+| `id` | yes | `string` |
+| `scope` | yes | `string` |
+| `label` | yes | `ReactNode` |
+| `searchLabel` | yes | `string` |
+| `icon` | no | `ComponentType<{ className?: string; }>` |
+| `group` | no | `string` |
+| `placement` | yes | `ActionPlacement` |
+| `order` | yes | `number` |
+| `surface` | no | `ActionSurface` |
+| `visible` | yes | `boolean` |
+| `disabled` | yes | `boolean` |
+| `status` | yes | `ActionStatus` |
+| `isIdle` | yes | `boolean` |
+| `isRunning` | yes | `boolean` |
+| `isSuccess` | yes | `boolean` |
+| `isError` | yes | `boolean` |
+| `error` | yes | `unknown` |
+| `errors` | yes | `ActionFieldErrors` |
+| `message` | no | `string` |
+| `result` | yes | `TResult \| undefined` |
+| `runState` | yes | `ActionRunState` |
+| `payload` | yes | `TPayload \| undefined` |
+| `values` | yes | `TValues \| undefined` |
+| `metadata` | no | `ActionMetadata` |
+| `startedAt` | no | `number` |
+| `completedAt` | no | `number` |
+| `definition` | yes | `ActionDefinition<TPayload, TValues, TResult>` |
+| `open` | yes | `(payload?: TPayload, metadata?: ActionMetadata) => void` |
+| `execute` | yes | `(values?: TValues, payload?: TPayload, metadata?: ActionMetadata) => Promise<TResult \| undefined>` |
+| `close` | yes | `() => void` |
+| `submit` | yes | `(values?: TValues) => Promise<TResult \| undefined>` |
+
+### `ResolvedActionRequest`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `method` | yes | `ActionRequestMethod` |
+| `target` | no | `ActionRequestTarget` |
+| `data` | no | `unknown` |
+| `headers` | no | `Record<string, string>` |
+| `options` | no | `Record<string, unknown>` |
+
+### `toCommandAction`
+
+Kind: callable.
+
+```text
+(action: ResolvedAction<TPayload, TValues, TResult>, metadata?: ActionMetadata) => { id: string; label: string; group: string | undefined; disabled: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; onSelect: () => void; }
+```
+
+### `toMenuAction`
+
+Kind: callable.
+
+```text
+(action: ResolvedAction<TPayload, TValues, TResult>) => { label: string; onClick: () => void; disabled: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string; buttonStyle: string | undefined; }
+```
+
+### `toPageAction`
+
+Kind: callable.
+
+```text
+(action: ResolvedAction<TPayload, TValues, TResult>) => { id: string; label: import('react').ReactNode; onClick: () => void; disabled: boolean; loading: boolean; icon: import('react').ComponentType<{ className?: string; }> | undefined; tone: string | undefined; buttonStyle: string | undefined; visible: boolean; group: string | undefined; placement: ActionPlacement; }
+```
+
+### `toTableAction`
+
+Kind: callable.
+
+```text
+(action: ResolvedAction<TData>) => { id: string; label: string; onClick: (row: TData) => void; disabled: boolean; isDisabled: () => boolean; isVisible: () => boolean; icon: import('react').ReactElement<{ className?: string; }, string | import('react').JSXElementConstructor<any>> | undefined; tone: string; buttonStyle: string | undefined; }
+```
+
+### `useAction`
+
+Kind: callable.
+
+```text
+(actionId: string, options?: UseActionOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult> | null
+```
+
+### `UseActionOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `scope` | no | `string` |
+| `includeGlobal` | no | `boolean` |
+| `payload` | no | `TPayload` |
+| `metadata` | no | `ActionMetadata` |
+
+### `useActionScope`
+
+Kind: callable.
+
+```text
+() => string
+```
+
+### `useActionSnapshot`
+
+Kind: callable.
+
+```text
+() => ActionStoreSnapshot
+```
+
+### `useActionStore`
+
+Kind: callable.
+
+```text
+() => ActionStore
+```
+
+### `useActionSurface`
+
+Kind: callable.
+
+```text
+(options: ActionSurfaceOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult>[]
+```
+
+### `useActiveAction`
+
+Kind: callable.
+
+```text
+() => ResolvedAction<TPayload, TValues, TResult> | null
+```
+
+### `useLocalAction`
+
+Kind: callable.
+
+```text
+(definition: ActionDefinition<TPayload, TValues, TResult>, options?: UseLocalActionOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult> | null
+```
+
+### `UseLocalActionOptions`
+
+Kind: interface.
+
+Extends: `UseActionOptions<TPayload>`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `scope` | no | `string` |
+
+### `useRegisterActions`
+
+Kind: callable.
+
+```text
+(actions: readonly ActionDefinition<TPayload, TValues, TResult>[], options?: ActionRegistrationOptions) => void
+```
+
+## Preview recipes
+
+Preview route: Actions — `/actions`
+
+### One definition, many surfaces
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+const actions = [defineAction({
+  id: "invoice.delete",
+  label: "Delete invoice",
+  surfaces: ["page", "card"],
+  modality: { type: "alert", title: "Delete this invoice?", tone: "destructive" },
+  run: async ({ payload }) => api.delete(payload),
+})]
+
+useRegisterActions(actions, { scope: "invoice" })
+const pageActions = useActionSurface({ surface: "page", scope: "invoice", payload: id })
+```