@pilotiq/pilotiq 0.7.2 → 0.8.1

package/src/react/schemaRenderer/action/ActionModalDialog.tsx

@@ -0,0 +1,273 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { XIcon } from 'lucide-react'
+import type { ElementMeta } from '../../../schema/Element.js'
+import {
+  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+} from '../../ui/dialog.js'
+import { useIconFor } from '../../icon-context.js'
+import { useNavigate } from '../../navigate.js'
+import { useToast } from '../../Toaster.js'
+
+/**
+ * Modal-form action dialog. Opens a Dialog with an optional form schema
+ * (rendered via the injected `renderFormChild`) plus header/footer chrome
+ * from `meta.modal`. On submit, fetches the dispatchUrl with `Accept:
+ * application/json` so the server can return:
+ *   - 200 `{ ok: true, redirect }` → navigate (SPA via useNavigate)
+ *   - 422 `{ ok: false, errors: { field: string[] } }` → inline errors
+ *   - 500 `{ ok: false, error }` → server error banner
+ *
+ * Used for handler-style actions that have a schema and/or a modal config.
+ * Confirm-only actions without a schema also flow through here (no fields
+ * rendered, just header + footer = same UX as the old confirm dialog).
+ *
+ * `renderFormChild` is injected (form-layer concern, Phase 4) and
+ * `renderElement` is injected for `modalContentFooter` auxiliary Elements
+ * (avoids the SchemaRenderer ↔ action cycle).
+ */
+export function ActionModalDialog({
+  trigger,
+  meta,
+  ids,
+  initialValues = {},
+  open: controlledOpen,
+  onOpenChange,
+  renderFormChild,
+  renderElement,
+}: {
+  trigger?:       (open: () => void) => React.ReactNode
+  meta:           ElementMeta
+  ids:            string[]
+  initialValues?: Record<string, unknown>
+  open?:          boolean
+  onOpenChange?:  (open: boolean) => void
+  renderFormChild: (child: ElementMeta, index: number, values: Record<string, unknown>, errors: Record<string, string[]>) => React.ReactNode
+  renderElement:  (el: ElementMeta, index: number) => React.ReactNode
+}) {
+  const [internalOpen, setInternalOpen] = useState(false)
+  const isControlled = controlledOpen !== undefined
+  const open = isControlled ? controlledOpen : internalOpen
+  const setOpen = (o: boolean): void => {
+    if (isControlled) onOpenChange?.(o)
+    else setInternalOpen(o)
+  }
+  const [errors, setErrors] = useState<Record<string, string[]>>({})
+  const [serverError, setServerError] = useState<string | null>(null)
+  const [submitting, setSubmitting] = useState(false)
+  const navigate = useNavigate()
+  const { notify } = useToast()
+
+  const modal       = meta['modal']    as {
+    heading?:     string
+    description?: string
+    submitLabel?: string
+    cancelLabel?: string
+    icon?:        string
+    iconColor?:   'gray'|'primary'|'success'|'warning'|'destructive'|'info'
+    width?:       'sm'|'md'|'lg'|'xl'
+    alignment?:   'start'|'center'|'end'
+    slideOver?:   boolean
+    closeByClickingAway?: boolean
+    closeByEscaping?:     boolean
+    stickyHeader?:        boolean
+    stickyFooter?:        boolean
+    autofocus?:           boolean
+    closeButton?:         boolean
+  } | undefined
+  const confirm     = meta['confirm']  as { title?: string; message: string } | undefined
+  const destructive = Boolean(meta['destructive'])
+  const dispatchUrl = meta['dispatchUrl'] as string | undefined
+  const fields      = (meta.children ?? []) as ElementMeta[]
+  const hasForm     = fields.length > 0
+  // Filament v5 — auxiliary Elements stamped by the resolver between
+  // the body and the footer (Alert / Text / Heading / Action / …).
+  const contentFooter = (meta['modalContentFooter'] ?? []) as ElementMeta[]
+
+  const heading     = modal?.heading ?? confirm?.title ?? (hasForm ? String(meta['label'] ?? 'Submit') : 'Are you sure?')
+  const description = modal?.description ?? confirm?.message
+  const submitLabel = modal?.submitLabel ?? (destructive ? 'Delete' : (hasForm ? 'Submit' : 'Confirm'))
+  const cancelLabel = modal?.cancelLabel ?? 'Cancel'
+  const widthClass  = ({ sm: 'sm:max-w-sm', md: 'sm:max-w-lg', lg: 'sm:max-w-2xl', xl: 'sm:max-w-4xl' } as const)[modal?.width ?? 'md']
+
+  // Modal chrome extras (Tier-2 audit gap #2). Defaults match the
+  // previous renderer behaviour exactly — sparse meta keys round-trip
+  // as `undefined` so existing modals are byte-identical.
+  const closeByClickingAway = modal?.closeByClickingAway !== false
+  const closeByEscaping     = modal?.closeByEscaping     !== false
+  const stickyHeader        = modal?.stickyHeader === true
+  const stickyFooter        = modal?.stickyFooter === true
+  const showCloseButton     = modal?.closeButton  === true
+  const alignmentClass      = ({ start: 'text-left', center: 'text-center sm:text-left', end: 'text-right' } as const)[modal?.alignment ?? 'center']
+  const iconColorClass      = modal?.iconColor
+    ? ({
+        gray:        'text-muted-foreground',
+        primary:     'text-primary',
+        success:     'text-emerald-600 dark:text-emerald-300',
+        warning:     'text-amber-600   dark:text-amber-300',
+        destructive: 'text-destructive',
+        info:        'text-blue-600    dark:text-blue-300',
+      } as const)[modal.iconColor]
+    : undefined
+  // Existing default: only the submit button autofocuses (and only for
+  // confirm-only modals). When `modalAutofocus(false)` is set the user
+  // wants nothing to autofocus; `modalAutofocus(true)` shifts focus to
+  // the first form input via a mount-effect ref.
+  const explicitAutofocus = modal?.autofocus
+  const submitAutofocus   = explicitAutofocus === false ? false
+                          : explicitAutofocus === true  ? !hasForm
+                          : !hasForm
+  const formRef = useRef<HTMLFormElement | null>(null)
+  useEffect(() => {
+    if (!open || explicitAutofocus !== true || !hasForm) return
+    // Wait for the popup to mount + fields to render. Microtask is enough
+    // because Base UI's mount transition is decoupled from our render.
+    const id = window.requestAnimationFrame(() => {
+      const form = formRef.current
+      if (!form) return
+      const target = form.querySelector<HTMLElement>(
+        'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled])',
+      )
+      if (target) target.focus()
+    })
+    return () => window.cancelAnimationFrame(id)
+  }, [open, explicitAutofocus, hasForm])
+
+  const reset = (): void => { setErrors({}); setServerError(null); setSubmitting(false) }
+
+  const onSubmit = async (e: React.FormEvent<HTMLFormElement>): Promise<void> => {
+    e.preventDefault()
+    if (!dispatchUrl) return
+    setSubmitting(true)
+    setServerError(null)
+    setErrors({})
+
+    const fd = new FormData(e.currentTarget)
+    for (const id of ids) fd.append('ids', id)
+
+    try {
+      const res = await fetch(dispatchUrl, {
+        method: 'POST',
+        headers: { 'Accept': 'application/json' },
+        body: fd,
+      })
+      const data = await res.json().catch(() => ({}))
+      if (res.status === 422) {
+        setErrors((data as { errors?: Record<string, string[]> }).errors ?? {})
+        setSubmitting(false)
+        return
+      }
+      if (!res.ok) {
+        setServerError(String((data as { error?: string }).error ?? `Request failed (${res.status})`))
+        setSubmitting(false)
+        return
+      }
+      setOpen(false)
+      reset()
+      // Server-emitted notifications come through the JSON response;
+      // surface them via the Toaster before navigating so the user
+      // sees the success/error toast even when navigation re-renders.
+      const notifs = (data as { notifications?: Array<{ id: string; type: string; title: string; body?: string; icon?: string; duration?: number }> }).notifications
+      if (notifs && notifs.length > 0) {
+        for (const n of notifs) notify(n as Parameters<typeof notify>[0])
+      }
+      const redirect = String((data as { redirect?: string }).redirect ?? '')
+      if (redirect) navigate(redirect)
+      else if (typeof window !== 'undefined') navigate(window.location.pathname + window.location.search)
+    } catch (err) {
+      setServerError(err instanceof Error ? err.message : 'Submit failed')
+      setSubmitting(false)
+    }
+  }
+
+  const cancelClass  = 'inline-flex items-center justify-center rounded-md border border-input bg-background px-3 h-9 text-sm font-medium hover:bg-accent hover:text-accent-foreground'
+  const confirmClass = destructive
+    ? 'inline-flex items-center justify-center rounded-md bg-destructive px-3 h-9 text-sm font-medium text-destructive-foreground hover:bg-destructive/90 disabled:opacity-50'
+    : 'inline-flex items-center justify-center rounded-md bg-primary px-3 h-9 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:opacity-50'
+
+  // Resolved icon component for the modal header (Filament-style chrome
+  // — leading glyph next to the heading). Passed through `useIconFor`
+  // for the same registry lookup used by Resource / Page / Action icons.
+  const HeaderIcon = useIconFor(modal?.icon)
+
+  // Build a className for the popup that respects width + sticky-chrome
+  // + slideOver. Sticky modes give the popup a max height + overflow so
+  // the inner scroll surface exists for sticky to bite onto.
+  const stickyMode  = stickyHeader || stickyFooter
+  const popupClass  = [
+    widthClass,
+    stickyMode ? 'max-h-[90vh] overflow-hidden p-0' : '',
+  ].filter(Boolean).join(' ')
+
+  // Inner scroll body (only used in sticky mode). When inactive the
+  // existing flat layout applies (header / fields / footer flow).
+  const headerCls   = `${alignmentClass} ${stickyHeader ? 'sticky top-0 bg-background z-10 px-6 pt-6 pb-3 border-b' : ''}`.trim()
+  const footerCls   = stickyFooter   ? 'sticky bottom-0 bg-background z-10 px-6 py-3 border-t' : ''
+  const bodyCls     = stickyMode ? 'flex-1 overflow-y-auto px-6 py-3' : ''
+  const formCls     = stickyMode ? 'flex flex-col h-full' : ''
+
+  return (
+    <>
+      {trigger?.(() => { reset(); setOpen(true) })}
+      <Dialog
+        open={open}
+        disablePointerDismissal={!closeByClickingAway}
+        onOpenChange={(o, details) => {
+          // Cancel Esc-triggered closes when the user has opted out.
+          // Base UI's `details.cancel()` aborts the open-state change.
+          if (!o && !closeByEscaping && details && (details as { reason?: string }).reason === 'escapeKey') {
+            const cancel = (details as { cancel?: () => void }).cancel
+            if (typeof cancel === 'function') cancel()
+            return
+          }
+          if (!o) reset()
+          setOpen(o)
+        }}
+      >
+        <DialogContent className={popupClass}>
+          {showCloseButton && (
+            <button
+              type="button"
+              aria-label="Close"
+              onClick={() => setOpen(false)}
+              className="absolute top-3 right-3 z-20 inline-flex items-center justify-center rounded-md h-8 w-8 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+            >
+              <XIcon className="size-4" />
+            </button>
+          )}
+          <form ref={formRef} onSubmit={onSubmit} className={formCls}>
+            <DialogHeader className={headerCls}>
+              <DialogTitle className={modal?.icon ? 'flex items-center gap-2' : undefined}>
+                {HeaderIcon && (
+                  <HeaderIcon
+                    aria-hidden
+                    className={`size-5 shrink-0 ${iconColorClass ?? ''}`.trim()}
+                  />
+                )}
+                <span>{heading}</span>
+              </DialogTitle>
+              {description && <DialogDescription>{description}</DialogDescription>}
+            </DialogHeader>
+            {(hasForm || contentFooter.length > 0) && (
+              <div className={`flex flex-col gap-3 py-2 ${bodyCls}`.trim()}>
+                {fields.map((f, i) => renderFormChild(f, i, initialValues, errors))}
+                {contentFooter.map((c, i) => renderElement(c, fields.length + i))}
+              </div>
+            )}
+            {!hasForm && contentFooter.length === 0 && stickyMode && <div className={bodyCls} />}
+            {serverError && (
+              <p className={`py-2 text-sm text-destructive ${stickyMode ? 'px-6' : ''}`.trim()}>{serverError}</p>
+            )}
+            <DialogFooter className={footerCls}>
+              <button type="button" onClick={() => setOpen(false)} className={cancelClass}>
+                {cancelLabel}
+              </button>
+              <button type="submit" disabled={submitting} autoFocus={submitAutofocus} className={confirmClass}>
+                {submitting ? 'Working…' : submitLabel}
+              </button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}

package/src/react/schemaRenderer/action/ConfirmActionDialog.tsx

@@ -0,0 +1,61 @@
+import React, { useState } from 'react'
+import {
+  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+} from '../../ui/dialog.js'
+
+/**
+ * Confirm-style dialog wrapping an action's button. The trigger button is
+ * rendered inline; clicking it opens the dialog. On confirm we run
+ * `onConfirm` (which is action-style-specific — submit a form, programmatic
+ * POST, etc.) and close the dialog. Used by submit-style and form-method
+ * actions; handler-style + confirm/modal flows through `ActionModalDialog`
+ * instead.
+ */
+export function ConfirmActionDialog({
+  trigger,
+  title,
+  message,
+  destructive,
+  onConfirm,
+}: {
+  trigger:     (open: () => void) => React.ReactNode
+  title:       string | undefined
+  message:     string
+  destructive: boolean
+  onConfirm:   () => void
+}) {
+  const [open, setOpen] = useState(false)
+  const confirmClass = destructive
+    ? 'inline-flex items-center justify-center rounded-md bg-destructive px-3 h-9 text-sm font-medium text-destructive-foreground hover:bg-destructive/90'
+    : 'inline-flex items-center justify-center rounded-md bg-primary px-3 h-9 text-sm font-medium text-primary-foreground hover:bg-primary/90'
+  return (
+    <>
+      {trigger(() => setOpen(true))}
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{title ?? 'Are you sure?'}</DialogTitle>
+            <DialogDescription>{message}</DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <button
+              type="button"
+              onClick={() => setOpen(false)}
+              className="inline-flex items-center justify-center rounded-md border border-input bg-background px-3 h-9 text-sm font-medium hover:bg-accent hover:text-accent-foreground"
+            >
+              Cancel
+            </button>
+            <button
+              type="button"
+              onClick={() => { setOpen(false); onConfirm() }}
+              className={confirmClass}
+              autoFocus
+            >
+              {destructive ? 'Delete' : 'Confirm'}
+            </button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}

package/src/react/schemaRenderer/action/HandlerActionButton.tsx

@@ -0,0 +1,43 @@
+import React from 'react'
+import { useNavigate } from '../../navigate.js'
+import { useToast } from '../../Toaster.js'
+import { withTooltip } from '../helpers.js'
+import { dispatchHandlerAction } from './helpers.js'
+
+/**
+ * Button for a handler-style action without confirm/modal. Click →
+ * fetch + JSON via `dispatchHandlerAction`, then SPA-navigate +
+ * show notifications. No full page reload.
+ */
+export function HandlerActionButton({
+  url,
+  ids,
+  className,
+  name,
+  ariaLabel,
+  tooltip,
+  inner,
+}: {
+  url:       string
+  ids:       string[]
+  className: string
+  name:      string
+  ariaLabel: string | undefined
+  tooltip:   string | undefined
+  inner:     React.ReactNode
+}) {
+  const navigate = useNavigate()
+  const { notify } = useToast()
+  return withTooltip(
+    <button
+      type="button"
+      onClick={() => void dispatchHandlerAction(url, ids, navigate, notify)}
+      className={className}
+      data-action-name={name}
+      aria-label={ariaLabel}
+    >
+      {inner}
+    </button>,
+    tooltip,
+  )
+}

package/src/react/schemaRenderer/action/MethodActionButton.tsx

@@ -0,0 +1,64 @@
+import React from 'react'
+import { useNavigate } from '../../navigate.js'
+import { useToast } from '../../Toaster.js'
+import { withTooltip } from '../helpers.js'
+import { dispatchMethodAction } from './helpers.js'
+import { ConfirmActionDialog } from './ConfirmActionDialog.js'
+
+/**
+ * Button + optional confirm dialog for a form-method action (Delete and
+ * the like). Click → fetch + JSON dispatch via `dispatchMethodAction` —
+ * no full page reload, no server-rendered form. Confirm dialog gates the
+ * dispatch when configured.
+ */
+export function MethodActionButton({
+  url,
+  method,
+  confirm,
+  destructive,
+  className,
+  name,
+  ariaLabel,
+  tooltip,
+  inner,
+}: {
+  url:         string | undefined
+  method:      'post' | 'put' | 'patch' | 'delete'
+  confirm:     { title?: string; message: string } | undefined
+  destructive: boolean
+  className:   string
+  name:        string
+  ariaLabel:   string | undefined
+  tooltip:     string | undefined
+  inner:       React.ReactNode
+}) {
+  const navigate = useNavigate()
+  const { notify } = useToast()
+  const dispatch = (): void => {
+    if (!url) return
+    void dispatchMethodAction(url, method, navigate, notify)
+  }
+
+  if (confirm) {
+    return (
+      <ConfirmActionDialog
+        title={confirm.title}
+        message={confirm.message}
+        destructive={destructive}
+        onConfirm={dispatch}
+        trigger={(open) => withTooltip(
+          <button type="button" onClick={open} className={className} data-action-name={name} aria-label={ariaLabel}>
+            {inner}
+          </button>,
+          tooltip,
+        )}
+      />
+    )
+  }
+  return withTooltip(
+    <button type="button" onClick={dispatch} className={className} data-action-name={name} aria-label={ariaLabel}>
+      {inner}
+    </button>,
+    tooltip,
+  )
+}

package/src/react/schemaRenderer/action/buttons.tsx

@@ -0,0 +1,99 @@
+import React from 'react'
+import type { ElementMeta } from '../../../schema/Element.js'
+import { resolveIcon } from '../helpers.js'
+
+// ─── Button-chrome helpers ──────────────────────────────────
+//
+// Shared between renderAction, MethodActionButton, HandlerActionButton,
+// ActionGroupTrigger, and the wizard nav buttons. All stateless — they
+// produce className strings and inline JSX for the icon / badge glyphs.
+
+export interface RenderActionOptions {
+  /** Ids to send when this action is handler-style. Used by row + bulk
+   * placements to pass selected/current record id(s). */
+  ids?: string[]
+  /** Optional sizing override (e.g. row actions render smaller). */
+  size?: 'sm' | 'md'
+}
+
+/** Color preset → tailwind class group. `ghost` is bg-less and works
+ * with hover:bg-accent. `destructive` uses a soft tonal style (Filament-
+ * style) so per-row Delete buttons sit calmly next to primary actions
+ * instead of shouting in saturated red — the modal confirm CTA still
+ * renders solid red via its own hardcoded class. Others are solid + hover-
+ * darken. */
+const COLOR_VARIANTS: Record<string, string> = {
+  primary:     'bg-primary text-primary-foreground hover:bg-primary/90',
+  destructive: 'bg-red-50 text-red-700 hover:bg-red-100 dark:bg-red-950/40 dark:text-red-400 dark:hover:bg-red-950/60',
+  success:     'bg-emerald-600 text-white hover:bg-emerald-600/90',
+  warning:     'bg-amber-500 text-white hover:bg-amber-500/90',
+  info:        'bg-blue-600 text-white hover:bg-blue-600/90',
+  ghost:       'bg-transparent text-foreground hover:bg-accent hover:text-accent-foreground',
+}
+
+/** Outlined variant — replaces solid bg with a border + transparent bg. */
+const OUTLINED_VARIANTS: Record<string, string> = {
+  primary:     'border border-primary/40 text-primary bg-transparent hover:bg-primary/10',
+  destructive: 'border border-destructive/40 text-destructive bg-transparent hover:bg-destructive/10',
+  success:     'border border-emerald-600/40 text-emerald-700 dark:text-emerald-400 bg-transparent hover:bg-emerald-600/10',
+  warning:     'border border-amber-500/40 text-amber-700 dark:text-amber-400 bg-transparent hover:bg-amber-500/10',
+  info:        'border border-blue-600/40 text-blue-700 dark:text-blue-400 bg-transparent hover:bg-blue-600/10',
+  ghost:       'border border-input text-foreground bg-transparent hover:bg-accent',
+}
+
+/** Size preset → tailwind sizing classes. Icon-only buttons use the
+ * width=height variants from the second map. */
+const SIZE_CLASSES: Record<string, string> = {
+  sm: 'h-7 px-2 text-xs',
+  md: 'h-8 px-3 text-sm',
+  lg: 'h-10 px-4 text-base',
+}
+const ICON_SIZE_CLASSES: Record<string, string> = {
+  sm: 'h-7 w-7 text-xs',
+  md: 'h-8 w-8 text-sm',
+  lg: 'h-10 w-10 text-base',
+}
+
+/** Build the trigger button className from action meta + render context. */
+export function actionButtonClass(el: ElementMeta, opts: RenderActionOptions): string {
+  const destructive = Boolean(el['destructive'])
+  const placement   = String(el['placement'] ?? 'inline')
+  const outlined    = Boolean(el['outlined'])
+  const iconOnly    = Boolean(el['iconOnly'])
+  const explicitColor = el['color'] as string | undefined
+  const explicitSize  = el['size'] as 'sm' | 'md' | 'lg' | undefined
+
+  // Color: explicit `.color()` wins; `destructive` flag falls back to
+  // 'destructive'; otherwise 'primary'.
+  const color = explicitColor ?? (destructive ? 'destructive' : 'primary')
+  const variant = (outlined ? OUTLINED_VARIANTS[color] : COLOR_VARIANTS[color]) ?? COLOR_VARIANTS['primary']
+
+  // Size: explicit `.size()` wins; otherwise small for row context, md elsewhere.
+  const size = explicitSize ?? (opts.size === 'sm' || placement === 'row' ? 'sm' : 'md')
+  const sizingMap = iconOnly ? ICON_SIZE_CLASSES : SIZE_CLASSES
+  const sizing = sizingMap[size] ?? sizingMap['md']
+
+  return `relative inline-flex items-center justify-center gap-1.5 rounded-md font-medium transition ${variant} ${sizing}`
+}
+
+/** Render the action's icon (when set). String names resolve through the
+ * user-extensible icon registry; missing names render nothing rather
+ * than a fallback glyph (action icons are decorative, not load-bearing). */
+export function renderActionIcon(el: ElementMeta): React.ReactNode {
+  const name = typeof el['icon'] === 'string' ? el['icon'] : undefined
+  const Icon = resolveIcon(name)
+  if (!Icon) return null
+  return <Icon className="size-4" aria-hidden="true" />
+}
+
+/** Tiny corner badge for actions that set `.badge(...)`. */
+export function renderActionBadge(el: ElementMeta): React.ReactNode {
+  const value = el['badge']
+  if (value === undefined || value === null || value === '') return null
+  const color = (el['badgeColor'] as string | undefined) ?? 'bg-primary text-primary-foreground'
+  return (
+    <span className={`absolute -top-1 -right-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] font-medium ${color}`}>
+      {String(value)}
+    </span>
+  )
+}

package/src/react/schemaRenderer/action/helpers.ts

@@ -0,0 +1,140 @@
+import type { NotificationMeta } from '../../../notifications/Notification.js'
+
+// ─── Action dispatch helpers ────────────────────────────────
+//
+// Pure (non-React) helpers shared by every action-button component:
+// JSON dispatch, notification drain, and the download branch that
+// converts an attachment response into a synthetic `<a download>` click.
+
+export type Notify   = (n: NotificationMeta | Omit<NotificationMeta, 'id'>) => void
+export type Navigate = (url: string) => void
+
+/** Drain `notifications[]` from a JSON response into `useToast().notify`. */
+export function dispatchNotifications(data: unknown, notify: Notify): void {
+  const notifs = (data as { notifications?: NotificationMeta[] }).notifications
+  if (!notifs || notifs.length === 0) return
+  for (const n of notifs) notify(n)
+}
+
+/**
+ * Fetch + JSON dispatch for form-method actions (Delete-style — no
+ * server-rendered <form>, no 303 redirect, no full page reload). Sends
+ * `_method` as a body field so Hono's POST handler dispatches the
+ * intended verb. On success: drain notifications, SPA-navigate to the
+ * server-supplied redirect (or stay on current path if none).
+ *
+ * Failure modes:
+ *   - 4xx/5xx with `{ error }`: surfaced as an error toast.
+ *   - Network errors: error toast with the exception message.
+ */
+export async function dispatchMethodAction(
+  url:      string,
+  method:   'post' | 'put' | 'patch' | 'delete',
+  navigate: Navigate,
+  notify:   Notify,
+): Promise<void> {
+  try {
+    const fd = new FormData()
+    if (method !== 'post') fd.append('_method', method)
+    const res = await fetch(url, {
+      method:  'POST',
+      headers: { 'Accept': 'application/json' },
+      body:    fd,
+    })
+    const data = await res.json().catch(() => ({}))
+    if (!res.ok) {
+      const message = String((data as { error?: string }).error ?? `Request failed (${res.status})`)
+      notify({ type: 'error', title: 'Action failed', body: message })
+      return
+    }
+    dispatchNotifications(data, notify)
+    const redirect = String((data as { redirect?: string }).redirect ?? '')
+    if (redirect) navigate(redirect)
+    else if (typeof window !== 'undefined') navigate(window.location.pathname + window.location.search)
+  } catch (err) {
+    notify({ type: 'error', title: 'Action failed', body: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+/**
+ * Fetch + JSON dispatch for handler-style actions (no schema, no modal,
+ * just a button). Sends `ids[]` plus arbitrary `values` fields. Server
+ * returns `{ ok, redirect, notifications }` (or `{ ok: false, error }` on
+ * failure). On success: drain notifications, SPA-navigate; on failure:
+ * surface the error as a toast. No full page reload in any case.
+ */
+export async function dispatchHandlerAction(
+  url:      string,
+  ids:      string[],
+  navigate: Navigate,
+  notify:   Notify,
+  values:   Record<string, string> = {},
+  formSnapshot?: FormData,
+): Promise<void> {
+  try {
+    // When `formSnapshot` is set (Repeater / Builder `extraItemActions`
+    // dispatch), the snapshot already carries the form's full state — we
+    // just append `ids` / `values` on top so the server sees both the
+    // form body (for coerceFormValues + row hydration) and the action's
+    // own meta keys.
+    const fd = formSnapshot ?? new FormData()
+    for (const id of ids) fd.append('ids', id)
+    for (const [k, v] of Object.entries(values)) fd.append(k, v)
+    const res = await fetch(url, {
+      method:  'POST',
+      headers: { 'Accept': 'application/json' },
+      body:    fd,
+    })
+    // Download branch — handlers that return `{ download }` ask the server
+    // to write the body inline with `Content-Disposition: attachment`. Trip
+    // a browser download via a synthetic `<a download>` and exit early
+    // (no notify drain / no SPA-nav — the file IS the success signal).
+    if (res.ok && triggerDownloadIfAttachment(res)) {
+      await res.blob().then(triggerBlobDownload(res))
+      return
+    }
+    const data = await res.json().catch(() => ({}))
+    if (!res.ok) {
+      const message = String((data as { error?: string }).error ?? `Request failed (${res.status})`)
+      notify({ type: 'error', title: 'Action failed', body: message })
+      return
+    }
+    dispatchNotifications(data, notify)
+    const redirect = String((data as { redirect?: string }).redirect ?? '')
+    if (redirect) navigate(redirect)
+    else if (typeof window !== 'undefined') navigate(window.location.pathname + window.location.search)
+  } catch (err) {
+    notify({ type: 'error', title: 'Action failed', body: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+/** Returns true when the response carries `Content-Disposition: attachment`,
+ *  which is how the route layer signals a download payload. The header
+ *  match is case-insensitive (different runtimes normalize differently). */
+function triggerDownloadIfAttachment(res: Response): boolean {
+  const cd = res.headers.get('Content-Disposition') ?? res.headers.get('content-disposition') ?? ''
+  return cd.toLowerCase().includes('attachment')
+}
+
+/** Returns a closure that converts the blob into a download by clicking
+ *  a synthetic `<a download="…">`. Filename is parsed from
+ *  `Content-Disposition`'s `filename="…"` parameter; falls back to
+ *  `'download'` when missing. Only mounted when `document` is present
+ *  (no-op in SSR). */
+function triggerBlobDownload(res: Response): (blob: Blob) => void {
+  const cd = res.headers.get('Content-Disposition') ?? res.headers.get('content-disposition') ?? ''
+  const match = cd.match(/filename\*?=(?:UTF-8'')?["']?([^"';\r\n]+)["']?/i)
+  const filename = (match?.[1] ?? 'download').trim()
+  return (blob) => {
+    if (typeof document === 'undefined' || typeof URL === 'undefined') return
+    const objUrl = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = objUrl
+    a.download = filename
+    a.style.display = 'none'
+    document.body.appendChild(a)
+    a.click()
+    a.remove()
+    URL.revokeObjectURL(objUrl)
+  }
+}