@xelqun/forms 0.4.0 → 0.6.0

package/README.md

@@ -41,7 +41,8 @@ class OrderForm extends Form
 - **Secure by default.** Forms rebuild from an encrypted token, and every endpoint re-runs `authorize()` and validation.
 - **Repeaters and uploads included.** Nested rows map to validation errors, and files upload as soon as they're picked.
 - **Every field you'd expect.** Select with relationships, date and time pickers, tags, sliders, colors, a block `Builder`, and rich text, Markdown and code editors.
-- **Wizards and actions.** Multi-step forms check each step on the server, and buttons can run PHP through a modal with its own fields.
+- **Wizards and actions.** Multi-step forms check each step on the server, and buttons can run PHP through a modal with its own fields. Group them in a menu with `ActionGroup`.
+- **Notifications.** Send one from an action, a hook or a controller with `Notification::make()`, and it reaches the page by itself. Add buttons with `NotificationAction`.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xelqun/forms",
-    "version": "0.4.0",
+    "version": "0.6.0",
     "description": "Vue renderer for Xelqun Forms: PHP-defined, schema-driven forms for Laravel + Inertia.",
     "license": "MIT",
     "repository": {

package/resources/css/xelqun.css

@@ -8,6 +8,8 @@
 @theme inline {
     --animate-xq-fade-in: xq-fade-in 150ms ease-out;
     --animate-xq-fade-out: xq-fade-out 100ms ease-in forwards;
+    --animate-xq-toast-in: xq-toast-in 200ms cubic-bezier(0.16, 1, 0.3, 1);
+    --animate-xq-toast-out: xq-toast-out 150ms ease-in forwards;
     --animate-xq-dialog-in: xq-dialog-in 180ms cubic-bezier(0.16, 1, 0.3, 1);
     --animate-xq-dialog-out: xq-dialog-out 100ms ease-in forwards;
     --color-xq-background: var(--xq-background);
@@ -298,6 +300,20 @@
     }
 }
 
+@keyframes xq-toast-in {
+    from {
+        opacity: 0;
+        translate: 0 -0.5rem;
+    }
+}
+
+@keyframes xq-toast-out {
+    to {
+        opacity: 0;
+        translate: 1rem 0;
+    }
+}
+
 @keyframes xq-dialog-in {
     from {
         opacity: 0;

package/resources/js/components/XqAction.vue

@@ -13,8 +13,9 @@ import { LoaderCircle } from 'lucide-vue-next';
 import { computed, onScopeDispose, ref, shallowRef, watch } from 'vue';
 import { useFormStore } from '../composables/context';
 import { createFormStore, LOADING_INDICATOR_DELAY } from '../core/store';
-import { cn } from '../lib/utils';
+import { cn, isOwnUrl } from '../lib/utils';
 import type { SchemaNode } from '../schema/types';
+import { actionVariants } from '../ui/classes';
 import XqButton from '../ui/XqButton.vue';
 import XqConfirmDialog from '../ui/XqConfirmDialog.vue';
 import XqDialog from '../ui/XqDialog.vue';
@@ -22,7 +23,13 @@ import XqDialogFooter from '../ui/XqDialogFooter.vue';
 import XqIcon from '../ui/XqIcon.vue';
 import XqForm from './XqForm.vue';
 
-const props = defineProps<{ node: SchemaNode; runner?: ActionRunner }>();
+const props = defineProps<{
+    node: SchemaNode;
+    runner?: ActionRunner;
+    /** Keep the dialogs and leave the button out, for a menu that has its own. */
+    headless?: boolean;
+}>();
+const emit = defineEmits<{ spinner: [showsSpinner: boolean] }>();
 const store = props.runner ?? useFormStore();
 const options = computed(() => props.node.props ?? {});
 const running = ref(false);
@@ -31,26 +38,14 @@ const confirming = ref(false);
 const modalOpen = ref(false);
 const modal = shallowRef<FormStore | null>(null);
 
-const variants: Record<string, 'default' | 'destructive' | 'outline'> = {
-    primary: 'default',
-    danger: 'destructive',
-    gray: 'outline',
-};
 const variant = computed(() =>
     options.value.style === 'link'
         ? 'link'
         : options.value.style === 'icon'
           ? 'ghost'
-          : (variants[options.value.color] ?? 'outline'),
+          : (actionVariants[options.value.color] ?? 'outline'),
 );
 
-// Inertia can only visit its own app.
-function isOwnUrl(url: string): boolean {
-    return typeof window === 'undefined'
-        ? url.startsWith('/')
-        : new URL(url, window.location.href).origin === window.location.origin;
-}
-
 // A new tab isn't a visit.
 const isVisit = computed(() => !options.value.openInNewTab && isOwnUrl(options.value.url));
 
@@ -130,6 +125,10 @@ watch(modalOpen, (isOpen) => {
     }
 });
 
+watch(showsSpinner, (shows) => emit('spinner', shows));
+
+defineExpose({ open });
+
 onScopeDispose(() => {
     clearTimeout(spinnerTimer);
     closeModal();
@@ -138,46 +137,48 @@ onScopeDispose(() => {
 
 <template>
     <div class="inline-flex" data-xq-action>
-        <XqButton
-            v-if="options.url"
-            as-child
-            :variant="variant"
-            :size="options.style === 'icon' ? 'icon-sm' : 'sm'"
-            :title="options.tooltip"
-            :aria-label="options.style === 'icon' ? options.label : undefined"
-        >
-            <component
-                :is="isVisit ? Link : 'a'"
-                :href="options.url"
-                :target="options.openInNewTab ? '_blank' : undefined"
-                :rel="options.openInNewTab ? 'noopener noreferrer' : undefined"
+        <template v-if="!headless">
+            <XqButton
+                v-if="options.url"
+                as-child
+                :variant="variant"
+                :size="options.style === 'icon' ? 'icon-sm' : 'sm'"
+                :title="options.tooltip"
+                :aria-label="options.style === 'icon' ? options.label : undefined"
             >
-                <XqIcon v-if="options.icon" :name="options.icon" />
-                <template v-if="options.style !== 'icon'">{{ options.label }}</template>
-            </component>
-        </XqButton>
-        <XqButton
-            v-else
-            type="button"
-            :variant="variant"
-            :size="options.style === 'icon' ? 'icon-sm' : 'sm'"
-            :class="showsSpinner && 'pointer-events-none'"
-            :disabled="!!options.disabled || store.processing.value"
-            :title="options.tooltip"
-            :aria-label="options.style === 'icon' ? options.label : undefined"
-            :aria-busy="running || undefined"
-            @click="open"
-        >
-            <span :class="cn('gap-1.5 inline-flex items-center', showsSpinner && 'invisible')">
-                <XqIcon v-if="options.icon" :name="options.icon" />
-                <template v-if="options.style !== 'icon'">{{ options.label }}</template>
-            </span>
-            <LoaderCircle
-                v-if="showsSpinner"
-                class="motion-safe:animate-spin absolute"
-                aria-hidden="true"
-            />
-        </XqButton>
+                <component
+                    :is="isVisit ? Link : 'a'"
+                    :href="options.url"
+                    :target="options.openInNewTab ? '_blank' : undefined"
+                    :rel="options.openInNewTab ? 'noopener noreferrer' : undefined"
+                >
+                    <XqIcon v-if="options.icon" :name="options.icon" />
+                    <template v-if="options.style !== 'icon'">{{ options.label }}</template>
+                </component>
+            </XqButton>
+            <XqButton
+                v-else
+                type="button"
+                :variant="variant"
+                :size="options.style === 'icon' ? 'icon-sm' : 'sm'"
+                :class="showsSpinner && 'pointer-events-none'"
+                :disabled="!!options.disabled || store.processing.value"
+                :title="options.tooltip"
+                :aria-label="options.style === 'icon' ? options.label : undefined"
+                :aria-busy="running || undefined"
+                @click="open"
+            >
+                <span :class="cn('gap-1.5 inline-flex items-center', showsSpinner && 'invisible')">
+                    <XqIcon v-if="options.icon" :name="options.icon" />
+                    <template v-if="options.style !== 'icon'">{{ options.label }}</template>
+                </span>
+                <LoaderCircle
+                    v-if="showsSpinner"
+                    class="motion-safe:animate-spin absolute"
+                    aria-hidden="true"
+                />
+            </XqButton>
+        </template>
         <XqConfirmDialog
             v-if="options.confirmation && !options.hasForm"
             v-model:open="confirming"
@@ -189,7 +190,9 @@ onScopeDispose(() => {
             :footer-alignment="options.footerAlignment"
             :confirm-label="options.submitLabel ?? store.t('Confirm')"
             :cancel-label="options.cancelLabel"
-            :confirm-variant="variants[options.color] === 'destructive' ? 'destructive' : 'default'"
+            :confirm-variant="
+                actionVariants[options.color] === 'destructive' ? 'destructive' : 'default'
+            "
             @confirm="run"
         />
         <XqDialog

package/resources/js/components/XqActionGroup.vue

@@ -0,0 +1,145 @@
+<script setup lang="ts">
+import { Link } from '@inertiajs/vue3';
+import { LoaderCircle } from 'lucide-vue-next';
+import {
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuPortal,
+    DropdownMenuRoot,
+    DropdownMenuTrigger,
+} from 'reka-ui';
+import { computed, ref } from 'vue';
+import type { ComponentPublicInstance } from 'vue';
+import { useFormStore } from '../composables/context';
+import { cn, isOwnUrl } from '../lib/utils';
+import type { SchemaNode } from '../schema/types';
+import { actionVariants, optionClass, popoverClass } from '../ui/classes';
+import XqButton from '../ui/XqButton.vue';
+import XqIcon from '../ui/XqIcon.vue';
+import XqAction from './XqAction.vue';
+import type { ActionRunner } from './XqAction.vue';
+
+/**
+ * A menu of actions. Closing a menu destroys what's in it, so each item only
+ * asks an XqAction outside the menu to open, and the dialogs live there.
+ */
+const props = defineProps<{ node: SchemaNode; runner?: ActionRunner }>();
+const form = props.runner ? null : useFormStore();
+const store = props.runner ?? form!;
+const options = computed(() => props.node.props ?? {});
+const items = computed(() =>
+    (props.node.children ?? []).filter((item) => form?.isVisible(item) ?? !item.hidden),
+);
+const headlessActions = computed(() => items.value.filter((item) => !item.props?.url));
+const hasLabel = computed(() => !!options.value.label);
+const showsSpinner = ref(false);
+const actions = new Map<string, { open: () => Promise<void> }>();
+let selected: string | null = null;
+
+function remember(key: string, action: Element | ComponentPublicInstance | null): void {
+    if (action) {
+        actions.set(key, action as unknown as { open: () => Promise<void> });
+    } else {
+        actions.delete(key);
+    }
+}
+
+/**
+ * Waits for the menu to give focus back to its button, so that a dialog, which
+ * returns focus to wherever it found it, comes back to the button too.
+ */
+function openSelected(): void {
+    if (selected) {
+        void actions.get(selected)?.open();
+        selected = null;
+    }
+}
+</script>
+
+<template>
+    <div class="inline-flex" data-xq-action-group>
+        <DropdownMenuRoot v-if="items.length > 0" :modal="false">
+            <DropdownMenuTrigger as-child>
+                <XqButton
+                    type="button"
+                    :variant="hasLabel ? (actionVariants[options.color] ?? 'outline') : 'ghost'"
+                    :size="hasLabel ? 'sm' : 'icon-sm'"
+                    :class="showsSpinner && 'pointer-events-none'"
+                    :disabled="store.processing.value"
+                    :title="options.tooltip"
+                    :aria-label="hasLabel ? undefined : store.t('Actions')"
+                    :aria-busy="showsSpinner || undefined"
+                >
+                    <span
+                        :class="cn('gap-1.5 inline-flex items-center', showsSpinner && 'invisible')"
+                    >
+                        <XqIcon :name="options.icon ?? 'ellipsis-vertical'" />
+                        <template v-if="hasLabel">{{ options.label }}</template>
+                    </span>
+                    <LoaderCircle
+                        v-if="showsSpinner"
+                        class="motion-safe:animate-spin absolute"
+                        aria-hidden="true"
+                    />
+                </XqButton>
+            </DropdownMenuTrigger>
+            <DropdownMenuPortal>
+                <DropdownMenuContent
+                    align="end"
+                    :side-offset="4"
+                    :class="cn(popoverClass, 'p-1 min-w-40')"
+                    @close-auto-focus="openSelected"
+                >
+                    <template v-for="item in items" :key="item.key">
+                        <DropdownMenuItem
+                            v-if="item.props?.url"
+                            as-child
+                            :class="cn(optionClass, 'pr-2')"
+                        >
+                            <component
+                                :is="
+                                    !item.props.openInNewTab && isOwnUrl(item.props.url)
+                                        ? Link
+                                        : 'a'
+                                "
+                                :href="item.props.url"
+                                :target="item.props.openInNewTab ? '_blank' : undefined"
+                                :rel="item.props.openInNewTab ? 'noopener noreferrer' : undefined"
+                            >
+                                <XqIcon v-if="item.props.icon" :name="item.props.icon" />
+                                {{ item.props.label }}
+                            </component>
+                        </DropdownMenuItem>
+                        <DropdownMenuItem
+                            v-else
+                            :disabled="!!item.props?.disabled"
+                            :class="
+                                cn(
+                                    optionClass,
+                                    'pr-2',
+                                    item.props?.color === 'danger' &&
+                                        'text-xq-destructive data-[highlighted]:text-xq-destructive',
+                                )
+                            "
+                            @select="selected = item.key"
+                        >
+                            <XqIcon v-if="item.props?.icon" :name="item.props.icon" />
+                            {{ item.props?.label }}
+                        </DropdownMenuItem>
+                    </template>
+                </DropdownMenuContent>
+            </DropdownMenuPortal>
+        </DropdownMenuRoot>
+        <div hidden>
+            <XqAction
+                v-for="item in headlessActions"
+                :key="item.key"
+                :ref="(action) => remember(item.key, action)"
+                :node="item"
+                :runner="store"
+                headless
+                @spinner="showsSpinner = $event"
+            />
+        </div>
+    </div>
+</template>

package/resources/js/components/XqActions.vue

@@ -5,6 +5,7 @@ import { computed, onScopeDispose, shallowRef, watch } from 'vue';
 import { createFormStore } from '../core/store';
 import type { FormSchema } from '../schema/types';
 import XqAction from './XqAction.vue';
+import XqActionGroup from './XqActionGroup.vue';
 import type { ActionRunner } from './XqAction.vue';
 
 /**
@@ -65,7 +66,13 @@ onScopeDispose(() => store.value.dispose());
 
 <template>
     <div class="gap-2 flex flex-wrap items-center" data-xq-actions>
-        <XqAction v-for="node in visibleActions" :key="node.key" :node="node" :runner="runner" />
+        <component
+            :is="node.type === 'action-group' ? XqActionGroup : XqAction"
+            v-for="node in visibleActions"
+            :key="node.key"
+            :node="node"
+            :runner="runner"
+        />
         <p
             v-if="failure"
             role="alert"

package/resources/js/components/XqForm.vue

@@ -135,6 +135,7 @@ function submit(): void {
             </XqButton>
         </div>
         <slot
+            v-if="!store.isFormDisabled"
             name="actions"
             :store="store"
             :processing="processing"

package/resources/js/components/defaults.ts

@@ -1,6 +1,7 @@
 import { toComponent } from '../composables/registry';
 import type { ComponentRegistry, ComponentResolver } from '../composables/registry';
 import XqAction from './XqAction.vue';
+import XqActionGroup from './XqActionGroup.vue';
 import XqCheckboxField from './fields/XqCheckboxField.vue';
 import XqRadioField from './fields/XqRadioField.vue';
 import XqRepeaterField from './fields/XqRepeaterField.vue';
@@ -55,6 +56,7 @@ export function defaultComponents(): Record<string, ComponentResolver> {
         fieldset: XqFieldset,
         tabs: XqTabsLayout,
         action: XqAction,
+        'action-group': XqActionGroup,
         actions: XqActions,
         wizard: XqWizard,
         block: XqBlock,

package/resources/js/core/notifications.ts

@@ -0,0 +1,64 @@
+import { router } from '@inertiajs/vue3';
+import { createToastManager } from 'reka-ui';
+import { isOwnUrl } from '../lib/utils';
+import type { ActionResult, XqNotification, XqNotificationAction } from '../schema/types';
+import { HttpError, postJson } from './http';
+
+/** Where the server puts notifications for the next page. See NotificationQueue. */
+export const FLASH_KEY = 'xelqunNotifications';
+
+export const notificationManager =
+    createToastManager<Pick<XqNotification, 'icon' | 'closeLabel' | 'actions'>>();
+
+/**
+ * Show a notification.
+ */
+export function notify(notification: XqNotification): void {
+    const { title, body, status, icon, duration, persistent, actions, closeLabel } = notification;
+
+    notificationManager.add({
+        title: title ?? undefined,
+        description: body ?? undefined,
+        status: status ?? undefined,
+        type: status === 'danger' || status === 'warning' ? 'foreground' : 'background',
+        duration: persistent ? Number.POSITIVE_INFINITY : (duration ?? undefined),
+        data: { icon, closeLabel, actions },
+    });
+}
+
+/**
+ * Press a button that runs an action, then do what any action does afterwards.
+ * Says whether it worked, and a failure shows as a notification of its own.
+ */
+export async function runNotificationAction(action: XqNotificationAction): Promise<boolean> {
+    const { endpoint, token, action: key } = action.run!;
+
+    try {
+        const result = await postJson<ActionResult>(endpoint, {
+            token,
+            action: key,
+            phase: 'run',
+            state: { data: {} },
+            deps: {},
+        });
+
+        result.notifications?.forEach(notify);
+
+        if (!result.redirect) {
+            router.reload();
+        } else if (isOwnUrl(result.redirect)) {
+            router.visit(result.redirect);
+        } else {
+            window.location.assign(result.redirect);
+        }
+
+        return true;
+    } catch (failure) {
+        const [message] =
+            failure instanceof HttpError ? Object.values(failure.validationErrors).flat() : [];
+
+        notify({ title: message ?? action.failureMessage, status: 'danger' });
+
+        return false;
+    }
+}

package/resources/js/core/store.ts

@@ -23,6 +23,7 @@ import { HttpError, postJson, uploadFile } from './http';
 import { eachNode, mergeNode } from './patch';
 import { clone, deletePath, getPath, overlaps, replaceRow, setPath, startsWithPath } from './paths';
 import { RequestLog } from './log';
+import { notify as showNotification } from './notifications';
 import { RequestQueue } from './queue';
 import { newRowKey } from './rows';
 import { translate } from './translate';
@@ -470,6 +471,8 @@ export function createFormStore(schema: FormSchema, options: FormStoreOptions =
     }
 
     function applyPatch(patch: UpdatePatch, versions: Map<string, number>): void {
+        patch.notifications?.forEach(showNotification);
+
         for (const [key, partial] of Object.entries(patch.schema ?? {})) {
             const node = nodes.get(key);
 
@@ -892,7 +895,7 @@ export function createFormStore(schema: FormSchema, options: FormStoreOptions =
     }
 
     async function submit(url: string, submitOptions: SubmitOptions = {}): Promise<void> {
-        if (processing.value) {
+        if (processing.value || schema.disabled) {
             return;
         }
 
@@ -1033,6 +1036,7 @@ export function createFormStore(schema: FormSchema, options: FormStoreOptions =
         isVisible,
         isRequired,
         isDisabled,
+        isFormDisabled: !!schema.disabled,
         text,
         isLoading,
         showsLoadingIndicator,

package/resources/js/index.ts

@@ -4,6 +4,7 @@ export type { XelqunFormsOptions, XelqunPlugin, XelqunPluginContext } from './pl
 export { default as XqForm } from './components/XqForm.vue';
 export { default as XqNode } from './components/XqNode.vue';
 export { default as XqAction } from './components/XqAction.vue';
+export { default as XqActionGroup } from './components/XqActionGroup.vue';
 export { default as XqActions } from './components/XqActions.vue';
 export type { ActionRunner } from './components/XqAction.vue';
 export { default as XqFieldWrapper } from './components/XqFieldWrapper.vue';
@@ -20,6 +21,7 @@ export { createFormStore, defaultLiveConfig, reportRequestFailure } from './core
 export type { ActionModal, FormStore, FormStoreOptions, SubmitOptions } from './core/store';
 export type { RequestKind, RequestLogEntry } from './core/log';
 export { HttpError, postJson } from './core/http';
+export { notify } from './core/notifications';
 export { translate } from './core/translate';
 export { evaluateCondition } from './core/conditions';
 export { evaluateExpression } from './core/expressions';

package/resources/js/lib/utils.ts

@@ -6,6 +6,15 @@ export function cn(...inputs: ClassValue[]): string {
     return twMerge(clsx(inputs));
 }
 
+/**
+ * Inertia can only visit its own app.
+ */
+export function isOwnUrl(url: string): boolean {
+    return typeof window === 'undefined'
+        ? url.startsWith('/')
+        : new URL(url, window.location.href).origin === window.location.origin;
+}
+
 /**
  * Keep keyboard users in place: focus the first of these that can take it.
  */

package/resources/js/plugin.ts

@@ -1,8 +1,13 @@
+import { router } from '@inertiajs/vue3';
+import { createApp } from 'vue';
 import type { App, Component, Plugin } from 'vue';
 import { createRegistry, defaultComponents } from './components/defaults';
 import { REGISTRY, toComponent } from './composables/registry';
 import type { ComponentRegistry, ComponentResolver } from './composables/registry';
+import { FLASH_KEY, notify } from './core/notifications';
+import type { XqNotification } from './schema/types';
 import { registerIcons } from './ui/icons';
+import XqNotifications from './ui/XqNotifications.vue';
 
 export interface XelqunPluginContext {
     app: App;
@@ -30,6 +35,8 @@ export interface XelqunFormsOptions {
     components?: Record<string, ComponentResolver>;
     /** Icons PHP can name, as { name: component }, on top of the built-in set. */
     icons?: Record<string, Component>;
+    /** What screen readers call the notifications region. {hotkey} is the key that jumps to it. */
+    notificationsLabel?: string;
 }
 
 const VENDOR_PREFIXED_TYPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
@@ -93,6 +100,28 @@ export function registerPlugins(
     }
 }
 
+/**
+ * Put the toaster on the page and listen for flash data. Returns how to undo both.
+ */
+function mountNotifications(label?: string): () => void {
+    const host = document.body.appendChild(document.createElement('div'));
+    const toaster = createApp(XqNotifications, { label });
+    const stopListening = router.on('flash', (event) => {
+        // An app can type its flash data, and this key is ours, not part of that type.
+        const flash = event.detail.flash as Record<string, unknown>;
+
+        (flash[FLASH_KEY] as XqNotification[] | undefined)?.forEach(notify);
+    });
+
+    toaster.mount(host);
+
+    return () => {
+        stopListening();
+        toaster.unmount();
+        host.remove();
+    };
+}
+
 export function createXelqunForms(options: XelqunFormsOptions = {}): Plugin {
     return {
         install(app) {
@@ -109,6 +138,10 @@ export function createXelqunForms(options: XelqunFormsOptions = {}): Plugin {
 
             plugins.forEach((plugin) => plugin.setup?.({ app }));
             app.provide(REGISTRY, registry);
+
+            if (typeof document !== 'undefined') {
+                app.onUnmount(mountNotifications(options.notificationsLabel));
+            }
         },
     };
 }

package/resources/js/schema/types.ts

@@ -135,6 +135,7 @@ export interface FormSchema {
     /** Text in this locale, by its English original. Anything missing stays English. */
     messages?: Record<string, string>;
     unsavedChangesAlert?: boolean;
+    disabled?: boolean;
     state: { data: Record<string, any> };
     components: SchemaNode[];
 }
@@ -169,6 +170,32 @@ export interface UpdatePatch {
     set: Record<string, unknown>;
     schema: Record<string, Partial<SchemaNode>>;
     errors: Record<string, string | string[]>;
+    /** Left out when there are none. */
+    notifications?: XqNotification[];
+}
+
+export interface XqNotification {
+    title?: string | null;
+    body?: string | null;
+    status?: 'success' | 'danger' | 'warning' | 'info' | null;
+    icon?: string | null;
+    /** In milliseconds. */
+    duration?: number | null;
+    persistent?: boolean;
+    actions?: XqNotificationAction[];
+    closeLabel?: string;
+}
+
+export interface XqNotificationAction {
+    label: string;
+    icon?: string | null;
+    color?: string | null;
+    /** Close the notification once the button has done its work. */
+    close: boolean;
+    url?: string;
+    openInNewTab?: boolean;
+    run?: { endpoint: string; token: string; action: string };
+    failureMessage?: string;
 }
 
 export interface ActionResult extends UpdatePatch {

package/resources/js/ui/XqNotificationList.vue

@@ -0,0 +1,124 @@
+<script setup lang="ts">
+import { router } from '@inertiajs/vue3';
+import { X } from 'lucide-vue-next';
+import { ToastClose, ToastDescription, ToastRoot, ToastTitle, useToastManager } from 'reka-ui';
+import type { ToastObject } from 'reka-ui';
+import { reactive } from 'vue';
+import { runNotificationAction } from '../core/notifications';
+import { cn, isOwnUrl } from '../lib/utils';
+import type { XqNotificationAction } from '../schema/types';
+import { actionVariants } from './classes';
+import XqButton from './XqButton.vue';
+import XqIcon from './XqIcon.vue';
+
+const { toasts, close } = useToastManager();
+const running = reactive(new Set<string>());
+
+const statusIcons: Record<string, string> = {
+    success: 'circle-check',
+    danger: 'circle-alert',
+    warning: 'triangle-alert',
+    info: 'info',
+};
+
+function iconFor(toast: ToastObject): string | undefined {
+    return toast.data?.icon ?? statusIcons[toast.status ?? ''];
+}
+
+const iconClasses: Record<string, string> = {
+    success: 'text-xq-success',
+    danger: 'text-xq-destructive',
+    warning: 'text-xq-warning',
+    info: 'text-xq-info',
+};
+
+async function press(toast: ToastObject, action: XqNotificationAction): Promise<void> {
+    // A second click on "Undo" would run it twice.
+    if (running.has(toast.id)) {
+        return;
+    }
+
+    running.add(toast.id);
+
+    const hasWorked = !action.run || (await runNotificationAction(action));
+
+    running.delete(toast.id);
+
+    if (hasWorked && action.close) {
+        close(toast.id);
+    }
+}
+
+function follow(event: MouseEvent, toast: ToastObject, action: XqNotificationAction): void {
+    const opensElsewhere = event.ctrlKey || event.metaKey || event.shiftKey || action.openInNewTab;
+
+    if (action.close) {
+        close(toast.id);
+    }
+
+    if (!opensElsewhere && isOwnUrl(action.url!)) {
+        event.preventDefault();
+        router.visit(action.url!);
+    }
+}
+</script>
+
+<template>
+    <ToastRoot
+        v-for="toast in toasts"
+        :key="toast.id"
+        :toast="toast"
+        class="gap-3 p-3 shadow-lg inset-x-0 top-0 ease-out data-[swipe=cancel]:translate-x-0 absolute flex [transform:translateY(calc(var(--reka-toast-offset-y)+var(--reka-toast-index)*0.5rem))] items-start rounded-xq-md border border-xq-border bg-xq-popover text-xq-popover-foreground transition-[transform,opacity] duration-200 outline-none focus-visible:ring-[3px] focus-visible:ring-xq-ring/25 data-[limited]:invisible data-[swipe=end]:translate-x-(--reka-toast-swipe-end-x) data-[swipe=move]:translate-x-(--reka-toast-swipe-move-x) data-[swipe=move]:transition-none motion-safe:data-[state=closed]:animate-xq-toast-out motion-safe:data-[state=open]:animate-xq-toast-in motion-reduce:transition-none"
+    >
+        <XqIcon
+            v-if="iconFor(toast)"
+            :name="iconFor(toast)!"
+            :class="cn('mt-0.5', iconClasses[toast.status ?? ''])"
+        />
+        <div class="min-w-0 flex-1 wrap-break-word">
+            <ToastTitle v-if="toast.title" class="text-sm font-medium">
+                {{ toast.title }}
+            </ToastTitle>
+            <ToastDescription v-if="toast.description" class="text-sm text-xq-muted-foreground">
+                {{ toast.description }}
+            </ToastDescription>
+            <div v-if="toast.data?.actions?.length" class="mt-2 gap-2 flex flex-wrap">
+                <template v-for="action in toast.data.actions" :key="action.label">
+                    <XqButton
+                        v-if="action.url"
+                        as-child
+                        size="sm"
+                        :variant="actionVariants[action.color ?? ''] ?? 'outline'"
+                    >
+                        <a
+                            :href="action.url"
+                            :target="action.openInNewTab ? '_blank' : undefined"
+                            :rel="action.openInNewTab ? 'noopener noreferrer' : undefined"
+                            @click="follow($event, toast, action)"
+                        >
+                            <XqIcon v-if="action.icon" :name="action.icon" />
+                            {{ action.label }}
+                        </a>
+                    </XqButton>
+                    <XqButton
+                        v-else
+                        type="button"
+                        size="sm"
+                        :variant="actionVariants[action.color ?? ''] ?? 'outline'"
+                        :aria-busy="running.has(toast.id) || undefined"
+                        @click="press(toast, action)"
+                    >
+                        <XqIcon v-if="action.icon" :name="action.icon" />
+                        {{ action.label }}
+                    </XqButton>
+                </template>
+            </div>
+        </div>
+        <ToastClose
+            :aria-label="toast.data?.closeLabel ?? 'Close'"
+            class="rounded-xq-sm text-xq-muted-foreground outline-none hover:text-xq-foreground focus-visible:ring-[3px] focus-visible:ring-xq-ring/25"
+        >
+            <X class="size-4" aria-hidden="true" />
+        </ToastClose>
+    </ToastRoot>
+</template>

package/resources/js/ui/XqNotifications.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { ToastProvider, ToastViewport } from 'reka-ui';
+import { notificationManager } from '../core/notifications';
+import XqNotificationList from './XqNotificationList.vue';
+
+/**
+ * Shows every notification. createXelqunForms mounts it as an app of its own,
+ * because Reka keeps toasts in the provider, and a layout that changes between
+ * pages would take them with it.
+ *
+ * It sits above dialogs, and takes pointer events back from an open one, which
+ * turns them off for the whole page.
+ */
+withDefaults(defineProps<{ label?: string }>(), { label: 'Notifications ({hotkey})' });
+</script>
+
+<template>
+    <ToastProvider :toast-manager="notificationManager" :limit="5">
+        <XqNotificationList />
+        <ToastViewport
+            :label="label"
+            data-slot="xq-notifications"
+            class="top-4 right-4 max-w-sm pointer-events-auto fixed z-[60] w-[calc(100%-2rem)] outline-none"
+        />
+    </ToastProvider>
+</template>

package/resources/js/ui/classes.ts

@@ -5,6 +5,13 @@
 export const controlClass =
     'w-full min-w-0 rounded-xq-md border border-xq-input bg-xq-background text-sm text-xq-foreground shadow-xs transition-[color,box-shadow,border-color] outline-none placeholder:text-xq-muted-foreground focus-visible:border-xq-ring focus-visible:ring-[3px] focus-visible:ring-xq-ring/25 disabled:cursor-not-allowed disabled:opacity-60 aria-invalid:border-xq-destructive aria-invalid:ring-xq-destructive/20';
 
+/** How an action's color looks on a button. */
+export const actionVariants: Record<string, 'default' | 'destructive' | 'outline'> = {
+    primary: 'default',
+    danger: 'destructive',
+    gray: 'outline',
+};
+
 export const spinnerClass = 'size-4 shrink-0 motion-safe:animate-spin text-xq-muted-foreground';
 
 export const popoverClass =

package/resources/js/ui/icons.ts

@@ -8,6 +8,7 @@ import {
     Clock,
     CreditCard,
     DollarSign,
+    EllipsisVertical,
     Eye,
     File,
     Folder,
@@ -53,6 +54,7 @@ const icons: Record<string, Component> = {
     clock: Clock,
     'credit-card': CreditCard,
     'dollar-sign': DollarSign,
+    'ellipsis-vertical': EllipsisVertical,
     eye: Eye,
     file: File,
     folder: Folder,