themelia-ui 2.0.0 → 3.0.0

package/docs/generated/components/features--actions.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/actions.css"
 
 ## Composition
 
-This family composes `features/overlays`.
+This module composes `features/overlays`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -59,6 +59,9 @@ Kind: interface.
 
 Kind: interface.
 
+One action, defined once and read from every surface: what it is called, where it appears, how
+it asks, and what it runs.
+
 Extends: `Omit<ActionPresentation, 'visible' | 'disabled'>`.
 
 | member | required | type | description / documented default |
@@ -75,11 +78,11 @@ Extends: `Omit<ActionPresentation, 'visible' | 'disabled'>`.
 | `disabled` | no | `ActionPredicate<TPayload>` |  |
 | `permission` | no | `ActionPermission` |  |
 | `roles` | no | `ActionRoles` |  |
-| `modality` | no | `'none' \| ActionModalityConfig<TPayload, TValues, TResult>` |  |
-| `request` | no | `ActionRequestConfig<TPayload, TValues>` |  |
+| `modality` | no | `'none' \| ActionModalityConfig<TPayload, TValues, TResult>` | How the action asks. The outlet renders it; no surface needs its own dialog. `"none"`, or no<br>modality, runs the action at once. |
+| `request` | no | `ActionRequestConfig<TPayload, TValues>` | A declarative request, run by `requestRunner` — for apps whose actions are mostly HTTP. |
 | `requestRunner` | no | `ActionRequestRunner<TResult>` |  |
 | `run` | no | `BivariantCallback<[ context: ActionRunContext<TPayload, TValues> ], TResult \| Promise<TResult>>` |  |
-| `parseErrors` | no | `ActionErrorParser` |  |
+| `parseErrors` | no | `ActionErrorParser` | Turns a failure into field errors, so a form modality can show them inline. |
 | `successMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |  |
 | `errorMessage` | no | `ActionMessage<TPayload, TValues, TResult>` |  |
 | `onStart` | no | `BivariantCallback<[ event: ActionLifecycleEvent<TPayload, TValues, TResult> ], void>` |  |
@@ -183,6 +186,10 @@ Kind: interface.
 
 Kind: class.
 
+The `Error` createHttpActionRunner throws for a failed response, carrying `status`,
+`statusText`, `body` and the `Response`, plus the body's own `errors` when it has them. What
+`parseErrors` receives for an HTTP failure.
+
 ### `ActionHttpErrorOptions`
 
 Kind: interface.
@@ -291,6 +298,9 @@ Kind: type.
 
 Kind: callable.
 
+Renders the active action's modality — alert, dialog, or drawer. Mount one inside the
+`ActionProvider`; every surface that runs an action with a `modality` then shares it.
+
 ```text
 ({ strings }?: ActionOverlayOutletProps) => import("react").JSX.Element | null
 ```
@@ -348,6 +358,8 @@ boolean | BivariantCallback<[context: ActionContext<TPayload>], boolean>
 
 Kind: callable.
 
+Owns the action registry and the run state. Mount one near the app shell.
+
 ```text
 ({ actions, runtime, feedback, guards, parseErrors, requestRunner, onOverlayOpenChange, onRunningChange, children, }: ActionProviderProps<TPayload, TValues, TResult>) => ReactNode
 ```
@@ -512,6 +524,9 @@ Kind: interface.
 
 Kind: callable.
 
+Declarative registration, for actions that belong to a subtree rather than a component.
+Registers `actions` under `scope` while mounted, and surfaces inside it resolve in that scope.
+
 ```text
 ({ scope, actions, children, }: ActionScopeProps<TPayload, TValues, TResult>) => ReactNode
 ```
@@ -629,6 +644,8 @@ ActionOverlayStrings
 
 Kind: callable.
 
+Identity helper that keeps the generics inferred.
+
 ```text
 (definition: ActionDefinition<TPayload, TValues, TResult>) => ActionDefinition<TPayload, TValues, TResult>
 ```
@@ -637,6 +654,9 @@ Kind: callable.
 
 Kind: callable.
 
+`defineAction` for a destructive action: its tone defaults to `"destructive"`, and its
+modality to a destructive `"alert"`.
+
 ```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>
 ```
@@ -645,6 +665,9 @@ Kind: callable.
 
 Kind: callable.
 
+`defineAction` for an action that asks through a form: the modality's `type` defaults to
+`"dialog"`.
+
 ```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>
 ```
@@ -653,6 +676,8 @@ Kind: callable.
 
 Kind: callable.
 
+`defineAction` for an action that runs without asking: its modality is `"none"`.
+
 ```text
 (definition: Omit<ActionDefinition<TPayload, TValues, TResult>, 'modality'>) => ActionDefinition<TPayload, TValues, TResult>
 ```
@@ -785,6 +810,9 @@ Kind: callable.
 
 Kind: callable.
 
+One action by id, when a surface is not the right shape. `null` when none is registered in
+scope or it is not visible.
+
 ```text
 (actionId: string, options?: UseActionOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult> | null
 ```
@@ -804,6 +832,8 @@ Kind: interface.
 
 Kind: callable.
 
+The nearest `ActionScope`'s id, or the global scope. For a surface resolving its own actions.
+
 ```text
 () => string
 ```
@@ -812,6 +842,9 @@ Kind: callable.
 
 Kind: callable.
 
+Subscribes to the whole store. Prefer a narrower hook — this re-renders on any registry or
+run change.
+
 ```text
 () => ActionStoreSnapshot
 ```
@@ -820,6 +853,9 @@ Kind: callable.
 
 Kind: callable.
 
+The store itself, for logic the hooks do not cover. Throws outside an `ActionProvider` rather
+than returning null.
+
 ```text
 () => ActionStore
 ```
@@ -828,6 +864,8 @@ Kind: callable.
 
 Kind: callable.
 
+The actions for one surface, already filtered by visibility, permission, and guards.
+
 ```text
 (options: ActionSurfaceOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult>[]
 ```
@@ -836,6 +874,9 @@ Kind: callable.
 
 Kind: callable.
 
+Whichever action is currently open, or `null`. The outlet reads this; a bespoke outlet would
+too.
+
 ```text
 () => ResolvedAction<TPayload, TValues, TResult> | null
 ```
@@ -844,6 +885,9 @@ Kind: callable.
 
 Kind: callable.
 
+One action registered for the lifetime of the component that declares it, for a definition no
+other surface needs.
+
 ```text
 (definition: ActionDefinition<TPayload, TValues, TResult>, options?: UseLocalActionOptions<TPayload>) => ResolvedAction<TPayload, TValues, TResult> | null
 ```
@@ -862,6 +906,9 @@ Extends: `UseActionOptions<TPayload>`.
 
 Kind: callable.
 
+Registers `actions` for as long as the calling component is mounted, under `options.scope` or
+else the nearest `ActionScope`'s.
+
 ```text
 (actions: readonly ActionDefinition<TPayload, TValues, TResult>[], options?: ActionRegistrationOptions) => void
 ```
@@ -873,14 +920,99 @@ Preview route: Action definitions — `/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 })
+import { TrashIcon } from "lucide-react"
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import {
+	ActionOverlayOutlet, ActionProvider, defineAction, useActionSurface, useRegisterActions,
+	type ActionDefinition,
+} from "themelia-ui/features/actions"
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * One action registered once, read by a page toolbar and a card's overflow menu. The store
+ * owns confirmation, loading and errors, so both agree.
+ */
+function ActionsDemo() {
+	const [deleted, setDeleted] = useState<string[]>([])
+
+	const actions: ActionDefinition[] = [
+		defineAction({
+			id: "invoice.delete",
+			label: "Delete invoice",
+			icon: TrashIcon,
+			tone: "destructive",
+			surfaces: ["page", "card"],
+			modality: {
+				type: "alert",
+				title: "Delete this invoice?",
+				description: "This cannot be undone.",
+				confirmLabel: "Delete",
+				tone: "destructive",
+				closeOnSuccess: true,
+			},
+			run: async ({ payload }) => {
+				await wait(700)
+				setDeleted((current) => [...current, String(payload ?? "INV-4417")])
+				return payload
+			},
+		}),
+	]
+
+	useRegisterActions(actions, { scope: "invoice" })
+
+	const pageActions = useActionSurface({ surface: "page", scope: "invoice", payload: "INV-4417" })
+	const cardActions = useActionSurface({ surface: "card", scope: "invoice", payload: "INV-4418" })
+
+	return (
+		<Stack gap="xl" style={{ width: "100%" }}>
+			<Stack direction="horizontal" gap="md" align="center">
+				{pageActions.map((action) => (
+					<Button
+						key={action.key}
+						tone={action.definition.tone}
+						loading={action.isRunning}
+						disabled={action.disabled}
+						onClick={() => action.open()}
+					>
+						{action.label}
+					</Button>
+				))}
+				<Text size="sm" type="secondary">
+					page surface — payload INV-4417
+				</Text>
+			</Stack>
+
+			<Card
+				surface="bordered"
+				title="Northwind Traders"
+				description="Invoice #4418 — the same action, from a card menu."
+				actions={cardActions.map((action) => ({
+					label: action.label,
+					icon: action.definition.icon,
+					tone: action.definition.tone,
+					onClick: () => action.open(),
+				}))}
+			>
+				<Text size="sm" type="secondary">
+					{deleted.length ? `Deleted: ${deleted.join(", ")}` : "Nothing deleted yet."}
+				</Text>
+			</Card>
+		</Stack>
+	)
+}
+
+export default function Actions() {
+	return (
+		<ActionProvider>
+			<ActionsDemo />
+			<ActionOverlayOutlet />
+		</ActionProvider>
+	)
+}
 ```