admin-ui-starter-kit 0.6.4 → 0.6.6

package/dist/showcase/assets/actions-DnqxABJU.js

@@ -0,0 +1,310 @@
+import{n as e}from"./chunk-QTnfLwEv.js";import{n as t,o as n,p as r,t as i}from"./section-Cv8i4DIx.js";import{t as a}from"./arrow-right-S5k93UPM.js";import{t as o}from"./bell-CmuQlO_k.js";import{t as s}from"./box-D-wrSdOJ.js";import{t as c}from"./braces-CgCdmdAl.js";import{n as l,r as u,t as d}from"./example-eGsLGIcp.js";import{t as f}from"./route-BeXaXTk8.js";import{t as p}from"./shield-check-ClL4B_Cd.js";import{d as m,l as h,s as g}from"./index-DDZl6kOS.js";import{t as _}from"./icon-badge-eNEGgpAV.js";import{t as v}from"./smart-card-Cg6rtWH9.js";var y=h(`database-zap`,[[`ellipse`,{cx:`12`,cy:`5`,rx:`9`,ry:`3`,key:`msslwz`}],[`path`,{d:`M3 5V19A9 3 0 0 0 15 21.84`,key:`14ibmq`}],[`path`,{d:`M21 5V8`,key:`1marbg`}],[`path`,{d:`M21 12L18 17H22L19 22`,key:`zafso`}],[`path`,{d:`M3 12A9 3 0 0 0 14.59 14.87`,key:`1y4wr8`}]]),b=h(`panel-top-open`,[[`rect`,{width:`18`,height:`18`,x:`3`,y:`3`,rx:`2`,key:`afitv7`}],[`path`,{d:`M3 9h18`,key:`1pudct`}],[`path`,{d:`m15 14-3 3-3-3`,key:`g215vf`}]]),x=h(`rectangle-ellipsis`,[[`rect`,{width:`20`,height:`12`,x:`2`,y:`6`,rx:`2`,key:`9lu3g6`}],[`path`,{d:`M12 12h.01`,key:`1mp3jc`}],[`path`,{d:`M17 12h.01`,key:`1m0b6t`}],[`path`,{d:`M7 12h.01`,key:`eqddd0`}]]),S=h(`workflow`,[[`rect`,{width:`8`,height:`8`,x:`3`,y:`3`,rx:`2`,key:`by2w9f`}],[`path`,{d:`M7 11v4a2 2 0 0 0 2 2h4`,key:`xkn7yn`}],[`rect`,{width:`8`,height:`8`,x:`13`,y:`13`,rx:`2`,key:`1cgmvn`}]]),C=e({FitChecklist:()=>N,FormsAndState:()=>M,LifecycleFlow:()=>k,NextRoutes:()=>P,RuntimeGlue:()=>A,RuntimeMap:()=>O,SurfaceHelpers:()=>j}),w=m(),T=[{icon:b,title:`ActionProvider`,description:`Owns the registry, guards, request runner, parsed errors, feedback, and lifecycle state.`,tone:`primary`},{icon:s,title:`ActionScope`,description:`Registers contextual actions once for a page, resource, table, card, or command surface.`,tone:`info`},{icon:S,title:`ActionOverlayOutlet`,description:`Renders action-owned alert, dialog, and drawer flows with shared loading and error state.`,tone:`warning`},{icon:o,title:`Feedback callbacks`,description:`Lets the app wire toast, telemetry, invalidation, and polling pause behavior without package imports.`,tone:`success`}],E=[[`Define`,`ActionDefinition keeps label, surfaces, permission, request/run, modality, and messages together.`],[`Resolve`,`useAction or useActionSurface applies payload, metadata, visibility, disabled state, and current run state.`],[`Open`,`open() launches the configured overlay, or immediate actions call execute() directly.`],[`Run`,`run() or requestRunner receives values, payload, metadata, and AbortSignal.`],[`Feedback`,`onAfterMutate, onError, onSettled, provider feedback, and parsed field errors receive one lifecycle event shape.`]],D=[[`Good fit`,`One action definition needs to appear in page actions, row menus, card menus, command results, or overlays.`],[`Poor fit`,`One button opens one local dialog and the lifecycle does not need to be shared elsewhere.`],[`Rule`,`Use features/overlays directly for one-off local UI; use services/actions for repeated shared behavior.`]];function O(){return(0,w.jsx)(`div`,{className:`grid gap-3 md:grid-cols-2`,children:T.map(e=>(0,w.jsx)(v,{surface:`framed`,padding:`default`,className:`h-full`,icon:(0,w.jsx)(_,{icon:e.icon,tone:e.tone,shape:`square`}),title:e.title,description:e.description,children:(0,w.jsx)(n,{variant:`secondary`,children:`Framework neutral`})},e.title))})}function k(){return(0,w.jsx)(v,{surface:`framed`,padding:`default`,children:(0,w.jsx)(`div`,{className:`grid gap-3`,children:E.map(([e,t],n)=>(0,w.jsxs)(`div`,{className:`grid gap-3 rounded-md border bg-background px-3 py-2.5 md:grid-cols-[auto_minmax(0,1fr)] md:items-start`,children:[(0,w.jsx)(`span`,{className:`inline-flex size-7 shrink-0 items-center justify-center rounded-md bg-muted text-xs font-semibold text-foreground`,children:n+1}),(0,w.jsxs)(`div`,{children:[(0,w.jsx)(r,{weight:`semibold`,children:e}),(0,w.jsx)(r,{size:`xs`,type:`secondary`,className:`mt-1`,children:t})]})]},e))})})}function A(){return(0,w.jsxs)(`div`,{className:`grid gap-3 md:grid-cols-3`,children:[(0,w.jsx)(v,{surface:`framed`,padding:`default`,icon:(0,w.jsx)(_,{icon:f,tone:`primary`,shape:`square`}),title:`Request runner`,description:`Executes normalized url or named targets through app-owned fetch, router, or visit code.`,children:(0,w.jsx)(n,{variant:`secondary`,children:`ActionRequestRunner`})}),(0,w.jsx)(v,{surface:`framed`,padding:`default`,icon:(0,w.jsx)(_,{icon:p,tone:`success`,shape:`square`}),title:`Guards`,description:`Checks permission and role metadata without importing the app auth layer.`,children:(0,w.jsx)(n,{variant:`secondary`,children:`can / hasAnyRole`})}),(0,w.jsx)(v,{surface:`framed`,padding:`default`,icon:(0,w.jsx)(_,{icon:y,tone:`warning`,shape:`square`}),title:`Errors and feedback`,description:`Normalizes backend errors and forwards success or failure to app-owned toast and cache systems.`,children:(0,w.jsx)(n,{variant:`secondary`,children:`parseErrors / feedback`})})]})}function j(){return(0,w.jsx)(v,{title:`Map resolved actions into package surfaces`,description:`The helpers keep page actions, menus, tables, and command palettes aligned without repeating adapter glue.`,icon:(0,w.jsx)(_,{icon:g,tone:`info`,shape:`square`,size:`default`}),children:(0,w.jsxs)(`div`,{className:`flex flex-wrap gap-2`,children:[(0,w.jsx)(n,{variant:`secondary`,children:`toPageAction`}),(0,w.jsx)(n,{variant:`secondary`,children:`toMenuAction`}),(0,w.jsx)(n,{variant:`secondary`,children:`toTableAction`}),(0,w.jsx)(n,{variant:`secondary`,children:`toCommandAction`})]})})}function M(){return(0,w.jsx)(v,{surface:`framed`,padding:`default`,children:(0,w.jsxs)(`div`,{className:`grid gap-3 md:grid-cols-[auto_minmax(0,1fr)]`,children:[(0,w.jsx)(_,{icon:x,tone:`primary`,shape:`square`}),(0,w.jsxs)(`div`,{className:`space-y-3`,children:[(0,w.jsxs)(`div`,{children:[(0,w.jsx)(r,{weight:`semibold`,children:`Forms stay app-owned, but action state is shared`}),(0,w.jsx)(r,{size:`xs`,type:`secondary`,className:`mt-1`,children:`Use modality.formId and getFormProps for native forms, or call action.submit(values) from an app-owned form library. The action service owns loading, parsed field errors, result, and lifecycle callbacks.`})]}),(0,w.jsxs)(`div`,{className:`flex flex-wrap gap-2`,children:[(0,w.jsx)(n,{variant:`secondary`,children:`status`}),(0,w.jsx)(n,{variant:`secondary`,children:`isRunning`}),(0,w.jsx)(n,{variant:`secondary`,children:`errors`}),(0,w.jsx)(n,{variant:`secondary`,children:`result`}),(0,w.jsx)(n,{variant:`secondary`,children:`runState`})]})]})]})})}function N(){return(0,w.jsx)(`div`,{className:`grid gap-3 md:grid-cols-3`,children:D.map(([e,t])=>(0,w.jsxs)(v,{surface:`framed`,padding:`default`,children:[(0,w.jsx)(r,{weight:`semibold`,children:e}),(0,w.jsx)(r,{size:`xs`,type:`secondary`,className:`mt-1`,children:t})]},e))})}function P(){return(0,w.jsxs)(`div`,{className:`flex flex-wrap gap-2`,children:[(0,w.jsx)(u,{href:`#/features/overlays`,buttonStyle:`outline`,icon:a,children:`Overlays`}),(0,w.jsx)(u,{href:`#/layout/page`,buttonStyle:`outline`,icon:a,children:`Page actions`}),(0,w.jsx)(u,{href:`#/base/table`,buttonStyle:`outline`,icon:a,children:`Table actions`}),(0,w.jsx)(u,{href:`#/services/hooks`,icon:c,children:`Hooks reference`})]})}var F=`import {
+	ArrowRight,
+	Bell,
+	Box,
+	Braces,
+	ClipboardCheck,
+	DatabaseZap,
+	FormInput,
+	PanelTopOpen,
+	Route,
+	ShieldCheck,
+	Workflow,
+	} from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { IconBadge,
+} from '@/components/base/display';
+import { Text } from '@/components/typography';
+
+const runtimePieces = [
+	{
+		icon: PanelTopOpen,
+		title: 'ActionProvider',
+		description: 'Owns the registry, guards, request runner, parsed errors, feedback, and lifecycle state.',
+		tone: 'primary',
+	},
+	{
+		icon: Box,
+		title: 'ActionScope',
+		description: 'Registers contextual actions once for a page, resource, table, card, or command surface.',
+		tone: 'info',
+	},
+	{
+		icon: Workflow,
+		title: 'ActionOverlayOutlet',
+		description: 'Renders action-owned alert, dialog, and drawer flows with shared loading and error state.',
+		tone: 'warning',
+	},
+	{
+		icon: Bell,
+		title: 'Feedback callbacks',
+		description: 'Lets the app wire toast, telemetry, invalidation, and polling pause behavior without package imports.',
+		tone: 'success',
+	},
+] as const;
+
+const lifecycle = [
+	['Define', 'ActionDefinition keeps label, surfaces, permission, request/run, modality, and messages together.'],
+	['Resolve', 'useAction or useActionSurface applies payload, metadata, visibility, disabled state, and current run state.'],
+	['Open', 'open() launches the configured overlay, or immediate actions call execute() directly.'],
+	['Run', 'run() or requestRunner receives values, payload, metadata, and AbortSignal.'],
+	['Feedback', 'onAfterMutate, onError, onSettled, provider feedback, and parsed field errors receive one lifecycle event shape.'],
+] as const;
+
+const fitChecks = [
+	['Good fit', 'One action definition needs to appear in page actions, row menus, card menus, command results, or overlays.'],
+	['Poor fit', 'One button opens one local dialog and the lifecycle does not need to be shared elsewhere.'],
+	['Rule', 'Use features/overlays directly for one-off local UI; use services/actions for repeated shared behavior.'],
+] as const;
+
+export function RuntimeMap() {
+	return (
+		<div className="grid gap-3 md:grid-cols-2">
+			{runtimePieces.map((piece) => (
+				<SmartCard
+					key={piece.title}
+					surface="framed"
+					padding="default"
+					className="h-full"
+					icon={<IconBadge icon={piece.icon} tone={piece.tone} shape="square" />}
+					title={piece.title}
+					description={piece.description}
+				>
+					<Badge variant="secondary">Framework neutral</Badge>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function LifecycleFlow() {
+	return (
+		<SmartCard surface="framed" padding="default">
+			<div className="grid gap-3">
+				{lifecycle.map(([title, description], index) => (
+					<div key={title} className="grid gap-3 rounded-md border bg-background px-3 py-2.5 md:grid-cols-[auto_minmax(0,1fr)] md:items-start">
+						<span className="inline-flex size-7 shrink-0 items-center justify-center rounded-md bg-muted text-xs font-semibold text-foreground">
+							{index + 1}
+						</span>
+						<div>
+							<Text weight="semibold">{title}</Text>
+							<Text size="xs" type="secondary" className="mt-1">
+								{description}
+							</Text>
+						</div>
+					</div>
+				))}
+			</div>
+		</SmartCard>
+	);
+}
+
+export function RuntimeGlue() {
+	return (
+		<div className="grid gap-3 md:grid-cols-3">
+			<SmartCard
+				surface="framed"
+				padding="default"
+				icon={<IconBadge icon={Route} tone="primary" shape="square" />}
+				title="Request runner"
+				description="Executes normalized url or named targets through app-owned fetch, router, or visit code."
+			>
+				<Badge variant="secondary">ActionRequestRunner</Badge>
+			</SmartCard>
+			<SmartCard
+				surface="framed"
+				padding="default"
+				icon={<IconBadge icon={ShieldCheck} tone="success" shape="square" />}
+				title="Guards"
+				description="Checks permission and role metadata without importing the app auth layer."
+			>
+				<Badge variant="secondary">can / hasAnyRole</Badge>
+			</SmartCard>
+			<SmartCard
+				surface="framed"
+				padding="default"
+				icon={<IconBadge icon={DatabaseZap} tone="warning" shape="square" />}
+				title="Errors and feedback"
+				description="Normalizes backend errors and forwards success or failure to app-owned toast and cache systems."
+			>
+				<Badge variant="secondary">parseErrors / feedback</Badge>
+			</SmartCard>
+		</div>
+	);
+}
+
+export function SurfaceHelpers() {
+	return (
+		<SmartCard
+			title="Map resolved actions into package surfaces"
+			description="The helpers keep page actions, menus, tables, and command palettes aligned without repeating adapter glue."
+			icon={<IconBadge icon={ClipboardCheck} tone="info" shape="square" size="default" />}
+		>
+			<div className="flex flex-wrap gap-2">
+				<Badge variant="secondary">toPageAction</Badge>
+				<Badge variant="secondary">toMenuAction</Badge>
+				<Badge variant="secondary">toTableAction</Badge>
+				<Badge variant="secondary">toCommandAction</Badge>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function FormsAndState() {
+	return (
+		<SmartCard surface="framed" padding="default">
+			<div className="grid gap-3 md:grid-cols-[auto_minmax(0,1fr)]">
+				<IconBadge icon={FormInput} tone="primary" shape="square" />
+				<div className="space-y-3">
+					<div>
+						<Text weight="semibold">Forms stay app-owned, but action state is shared</Text>
+						<Text size="xs" type="secondary" className="mt-1">
+							Use modality.formId and getFormProps for native forms, or call action.submit(values) from an app-owned form library. The action service owns loading, parsed field errors, result, and lifecycle callbacks.
+						</Text>
+					</div>
+					<div className="flex flex-wrap gap-2">
+						<Badge variant="secondary">status</Badge>
+						<Badge variant="secondary">isRunning</Badge>
+						<Badge variant="secondary">errors</Badge>
+						<Badge variant="secondary">result</Badge>
+						<Badge variant="secondary">runState</Badge>
+					</div>
+				</div>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function FitChecklist() {
+	return (
+		<div className="grid gap-3 md:grid-cols-3">
+			{fitChecks.map(([title, description]) => (
+				<SmartCard key={title} surface="framed" padding="default">
+					<Text weight="semibold">{title}</Text>
+					<Text size="xs" type="secondary" className="mt-1">
+						{description}
+					</Text>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function NextRoutes() {
+	return (
+		<div className="flex flex-wrap gap-2">
+			<Button href="#/features/overlays" buttonStyle="outline" icon={ArrowRight}>
+				Overlays
+			</Button>
+			<Button href="#/layout/page" buttonStyle="outline" icon={ArrowRight}>
+				Page actions
+			</Button>
+			<Button href="#/base/table" buttonStyle="outline" icon={ArrowRight}>
+				Table actions
+			</Button>
+			<Button href="#/services/hooks" icon={Braces}>
+				Hooks reference
+			</Button>
+		</div>
+	);
+}
+`;function I(e){let n={code:`code`,li:`li`,p:`p`,ul:`ul`,...e.components};return C||R(`Examples`,!1),N||R(`Examples.FitChecklist`,!0),M||R(`Examples.FormsAndState`,!0),k||R(`Examples.LifecycleFlow`,!0),P||R(`Examples.NextRoutes`,!0),A||R(`Examples.RuntimeGlue`,!0),O||R(`Examples.RuntimeMap`,!0),j||R(`Examples.SurfaceHelpers`,!0),(0,w.jsxs)(t,{title:`Actions service`,description:`Framework-neutral action registry, lifecycle, overlay, request, guard, and feedback glue for shared admin actions.`,layer:`services`,status:`ready`,sourcePath:`src/services/actions`,children:[(0,w.jsxs)(i,{title:`Overview`,id:`overview`,children:[(0,w.jsxs)(n.p,{children:[(0,w.jsx)(n.code,{children:`admin-ui-starter-kit/services/actions`}),` is optional runtime glue for actions that
+must appear in more than one surface. It is not a router, query client, toast
+system, permission service, or form library. The package owns the typed action
+definition, lifecycle state, overlay outlet, and surface mapping; the consuming
+app owns behavior through callbacks.`]}),(0,w.jsx)(d,{name:`RuntimeMap`,source:F,layout:`flush`,children:(0,w.jsx)(O,{})})]}),(0,w.jsxs)(i,{title:`Public import`,id:`public-import`,children:[(0,w.jsx)(n.p,{children:`Use the exact services subpath:`}),(0,w.jsx)(l,{language:`tsx`,code:`import {
+ActionProvider,
+ActionOverlayOutlet,
+ActionScope,
+useAction,
+useActionSurface,
+useLocalAction,
+defineAction,
+defineDeleteAction,
+defineFormAction,
+defineSilentAction,
+createHttpActionRunner,
+toPageAction,
+toMenuAction,
+toTableAction,
+toCommandAction,
+type ActionDefinition,
+type ActionRuntimeGlue,
+type ResolvedAction,
+} from 'admin-ui-starter-kit/services/actions';`}),(0,w.jsxs)(n.p,{children:[`Do not import from `,(0,w.jsx)(n.code,{children:`admin-ui-starter-kit/services`}),`, `,(0,w.jsx)(n.code,{children:`dist/`}),`, or file-level paths.
+The only public services export today is `,(0,w.jsx)(n.code,{children:`admin-ui-starter-kit/services/actions`}),`.`]})]}),(0,w.jsxs)(i,{title:`Runtime boundary`,id:`runtime-boundary`,children:[(0,w.jsx)(n.p,{children:`Mount one provider near the app shell and one outlet inside it. Provider props
+are the framework adapter boundary: routing, fetch, cache invalidation, auth,
+toasts, telemetry, backend error parsing, and polling control enter through
+callbacks.`}),(0,w.jsx)(l,{language:`tsx`,code:`const runtime: ActionRuntimeGlue = {
+requestRunner: async (request, context) => appRequest(request, context),
+guards: {
+	can: (permission, context) => auth.can(permission, context),
+	hasAnyRole: (roles) => auth.hasAnyRole(roles),
+},
+parseErrors: (error) => parseBackendActionError(error),
+feedback: {
+	onSuccess: (event) => toast.success(event.message),
+	onError: (event) => reportActionError(event.error, event),
+},
+onOverlayOpenChange: (open) => polling.setPaused(open),
+onRunningChange: (running) => activity.setBusy(running),
+};
+
+export function AppRoot() {
+return (
+	<ActionProvider runtime={runtime}>
+		<App />
+		<ActionOverlayOutlet />
+	</ActionProvider>
+);
+}`}),(0,w.jsx)(d,{name:`RuntimeGlue`,source:F,layout:`flush`,children:(0,w.jsx)(A,{})})]}),(0,w.jsxs)(i,{title:`Lifecycle`,id:`lifecycle`,children:[(0,w.jsx)(n.p,{children:`Actions move through one consistent lifecycle, no matter whether the trigger is
+a page button, table row menu, card action, command result, alert dialog, dialog
+form, or drawer.`}),(0,w.jsx)(d,{name:`LifecycleFlow`,source:F,layout:`flush`,children:(0,w.jsx)(k,{})}),(0,w.jsxs)(n.p,{children:[`Each resolved action exposes `,(0,w.jsx)(n.code,{children:`status`}),`, `,(0,w.jsx)(n.code,{children:`isRunning`}),`, `,(0,w.jsx)(n.code,{children:`isError`}),`, `,(0,w.jsx)(n.code,{children:`errors`}),`,
+`,(0,w.jsx)(n.code,{children:`error`}),`, `,(0,w.jsx)(n.code,{children:`result`}),`, `,(0,w.jsx)(n.code,{children:`runState`}),`, `,(0,w.jsx)(n.code,{children:`open`}),`, `,(0,w.jsx)(n.code,{children:`execute`}),`, `,(0,w.jsx)(n.code,{children:`submit`}),`, and `,(0,w.jsx)(n.code,{children:`close`}),`.
+Lifecycle callbacks receive the same event shape through `,(0,w.jsx)(n.code,{children:`onStart`}),`,
+`,(0,w.jsx)(n.code,{children:`onAfterMutate`}),`, `,(0,w.jsx)(n.code,{children:`onError`}),`, `,(0,w.jsx)(n.code,{children:`onSettled`}),`, and provider `,(0,w.jsx)(n.code,{children:`feedback`}),`.`]})]}),(0,w.jsxs)(i,{title:`Choosing an API`,id:`choosing-an-api`,children:[(0,w.jsx)(d,{name:`FitChecklist`,source:F,layout:`flush`,children:(0,w.jsx)(N,{})}),(0,w.jsxs)(n.ul,{children:[`
+`,(0,w.jsxs)(n.li,{children:[`Use `,(0,w.jsx)(n.code,{children:`useLocalAction(definition, options)`}),` for incremental migration from a
+page-owned action hook.`]}),`
+`,(0,w.jsxs)(n.li,{children:[`Use `,(0,w.jsx)(n.code,{children:`<ActionScope actions={actions}>`}),` plus `,(0,w.jsx)(n.code,{children:`useActionSurface(...)`}),` when a
+definition appears in multiple surfaces on one page or resource.`]}),`
+`,(0,w.jsxs)(n.li,{children:[`Use provider `,(0,w.jsx)(n.code,{children:`actions`}),` only for app-shell actions that are globally available.`]}),`
+`,(0,w.jsxs)(n.li,{children:[`Use `,(0,w.jsx)(n.code,{children:`features/overlays`}),` directly for one local dialog, drawer, or alert.`]}),`
+`]})]}),(0,w.jsxs)(i,{title:`Requests and errors`,id:`requests-and-errors`,children:[(0,w.jsxs)(n.p,{children:[(0,w.jsx)(n.code,{children:`ActionDefinition.run`}),` gives complete control. `,(0,w.jsx)(n.code,{children:`ActionDefinition.request`}),` is
+data-only and becomes useful when many actions share the same transport. The app
+turns the resolved request into fetch, router, visit, RPC, or another transport
+inside `,(0,w.jsx)(n.code,{children:`requestRunner`}),`.`]}),(0,w.jsx)(l,{language:`tsx`,code:`const archiveCustomer = defineAction<Customer>({
+id: 'customer.archive',
+label: 'Archive customer',
+permission: 'customers.archive',
+surfaces: ['page', 'table-row', 'command'],
+request: {
+	method: 'post',
+	target: ({ payload }) => ({
+		type: 'named',
+		name: 'customers.archive',
+		params: payload?.id,
+	}),
+	options: { preserveScroll: true },
+},
+successMessage: ({ payload }) => \`\${payload?.name} archived\`,
+errorMessage: 'Could not archive customer',
+});`}),(0,w.jsxs)(n.p,{children:[`Use provider `,(0,w.jsx)(n.code,{children:`parseErrors`}),` for shared backend error shapes and action-level
+`,(0,w.jsx)(n.code,{children:`parseErrors`}),` for exceptions. Parsed field errors land on `,(0,w.jsx)(n.code,{children:`action.errors`}),`.`]})]}),(0,w.jsxs)(i,{title:`Modality and forms`,id:`modality-and-forms`,children:[(0,w.jsxs)(n.p,{children:[`Reusable modal workflows should be action definitions first. Set
+`,(0,w.jsx)(n.code,{children:`modality.type`}),` to `,(0,w.jsx)(n.code,{children:`alert`}),`, `,(0,w.jsx)(n.code,{children:`dialog`}),`, or `,(0,w.jsx)(n.code,{children:`drawer`}),`, then let
+`,(0,w.jsx)(n.code,{children:`ActionOverlayOutlet`}),` render the package overlay with the action lifecycle.`]}),(0,w.jsx)(d,{name:`FormsAndState`,source:F,layout:`flush`,children:(0,w.jsx)(M,{})}),(0,w.jsxs)(n.p,{children:[`For package-owned native form submission, use `,(0,w.jsx)(n.code,{children:`modality.formId`}),` and
+`,(0,w.jsx)(n.code,{children:`getFormProps`}),`. For a consumer form library, keep that library in the app and
+call `,(0,w.jsx)(n.code,{children:`action.submit(values)`}),` from the submit handler.`]})]}),(0,w.jsxs)(i,{title:`Surface helpers`,id:`surface-helpers`,children:[(0,w.jsx)(d,{name:`SurfaceHelpers`,source:F,layout:`flush`,children:(0,w.jsx)(j,{})}),(0,w.jsx)(n.p,{children:`The helpers return structural props for package surfaces. They do not navigate,
+mutate, toast, or invalidate caches by themselves; those effects remain in the
+action runtime callbacks.`})]}),(0,w.jsxs)(i,{title:`Rules`,id:`rules`,children:[(0,w.jsxs)(n.ul,{children:[`
+`,(0,w.jsx)(n.li,{children:`Register definitions once per scope. Do not register one action array per row.`}),`
+`,(0,w.jsx)(n.li,{children:`Memoize action arrays created inside React components.`}),`
+`,(0,w.jsx)(n.li,{children:`Keep routes, auth, translation, cache, telemetry, and toast packages in the
+consuming app.`}),`
+`,(0,w.jsxs)(n.li,{children:[`Use `,(0,w.jsx)(n.code,{children:`request.target: { type: 'url', url }`}),` for generic HTTP and
+`,(0,w.jsx)(n.code,{children:`request.target: { type: 'named', name, params }`}),` for app route adapters.`]}),`
+`,(0,w.jsxs)(n.li,{children:[`New code should prefer `,(0,w.jsx)(n.code,{children:`ActionRuntimeGlue`}),` and app-owned runners. Deprecated
+framework-named compatibility helpers remain only for existing consumers.`]}),`
+`]}),(0,w.jsx)(d,{name:`NextRoutes`,source:F,layout:`center`,children:(0,w.jsx)(P,{})})]})]})}function L(e={}){let{wrapper:t}=e.components||{};return t?(0,w.jsx)(t,{...e,children:(0,w.jsx)(I,{...e})}):I(e)}function R(e,t){throw Error(`Expected `+(t?`component`:`object`)+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}export{L as default};