@xelqun/forms 0.3.1 → 0.5.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.3.1",
+    "version": "0.5.0",
     "description": "Vue renderer for Xelqun Forms: PHP-defined, schema-driven forms for Laravel + Inertia.",
     "license": "MIT",
     "repository": {

package/resources/css/xelqun.css

@@ -6,6 +6,12 @@
 @source "../js";
 
 @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);
     --color-xq-foreground: var(--xq-foreground);
     --color-xq-card: var(--xq-card);
@@ -281,3 +287,43 @@
     max-width: 100%;
     height: auto;
 }
+
+@keyframes xq-fade-in {
+    from {
+        opacity: 0;
+    }
+}
+
+@keyframes xq-fade-out {
+    to {
+        opacity: 0;
+    }
+}
+
+@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;
+        scale: 0.96;
+    }
+}
+
+@keyframes xq-dialog-out {
+    to {
+        opacity: 0;
+        scale: 0.98;
+    }
+}

package/resources/js/components/XqAction.vue

@@ -8,50 +8,57 @@ export type ActionRunner = Pick<FormStore, 'mountAction' | 'runAction' | 'proces
 </script>
 
 <script setup lang="ts">
-import { Link } from '@inertiajs/vue3';
+import { Link, router } from '@inertiajs/vue3';
 import { LoaderCircle } from 'lucide-vue-next';
 import { computed, onScopeDispose, ref, shallowRef, watch } from 'vue';
 import { useFormStore } from '../composables/context';
-import { createFormStore } from '../core/store';
+import { createFormStore, LOADING_INDICATOR_DELAY } from '../core/store';
+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';
+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);
+const showsSpinner = ref(false);
 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, and a new tab isn't a visit.
-const isVisit = computed(() => {
-    if (options.value.openInNewTab) {
-        return false;
-    }
+// A new tab isn't a visit.
+const isVisit = computed(() => !options.value.openInNewTab && isOwnUrl(options.value.url));
+
+let spinnerTimer: ReturnType<typeof setTimeout> | undefined;
 
-    const url: string = options.value.url;
+// A quick action changes nothing on screen until it's done, so it can't flicker.
+watch(running, (isRunning) => {
+    clearTimeout(spinnerTimer);
+    showsSpinner.value = false;
 
-    return typeof window === 'undefined'
-        ? url.startsWith('/')
-        : new URL(url, window.location.href).origin === window.location.origin;
+    if (isRunning) {
+        spinnerTimer = setTimeout(() => (showsSpinner.value = true), LOADING_INDICATOR_DELAY);
+    }
 });
 
 async function run(): Promise<void> {
@@ -62,14 +69,29 @@ async function run(): Promise<void> {
 
     running.value = true;
 
-    if (await store.runAction(props.node, modal.value ?? undefined)) {
+    const result = await store.runAction(props.node, modal.value ?? undefined);
+
+    if (result) {
         modalOpen.value = false;
     }
 
+    if (result?.redirect) {
+        if (isOwnUrl(result.redirect)) {
+            router.visit(result.redirect);
+        } else {
+            window.location.assign(result.redirect);
+        }
+    }
+
     running.value = false;
 }
 
 async function open(): Promise<void> {
+    // Disabling the button would dim it and drop keyboard focus, so a second click lands here.
+    if (running.value) {
+        return;
+    }
+
     if (!options.value.hasForm) {
         if (options.value.confirmation) {
             confirming.value = true;
@@ -103,51 +125,74 @@ watch(modalOpen, (isOpen) => {
     }
 });
 
-onScopeDispose(closeModal);
+watch(showsSpinner, (shows) => emit('spinner', shows));
+
+defineExpose({ open });
+
+onScopeDispose(() => {
+    clearTimeout(spinnerTimer);
+    closeModal();
+});
 </script>
 
 <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'"
-            :disabled="!!options.disabled || running || store.processing.value"
-            :title="options.tooltip"
-            :aria-label="options.style === 'icon' ? options.label : undefined"
-            @click="open"
-        >
-            <LoaderCircle v-if="running" class="motion-safe:animate-spin" aria-hidden="true" />
-            <XqIcon v-else-if="options.icon" :name="options.icon" />
-            <template v-if="options.style !== 'icon'">{{ options.label }}</template>
-        </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"
             :title="options.heading"
             :message="options.description ?? store.t('Are you sure?')"
+            :icon="options.modalIcon"
+            :icon-color="options.modalIconColor ?? options.color"
+            :alignment="options.alignment"
+            :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
@@ -156,10 +201,15 @@ onScopeDispose(closeModal);
             :title="options.heading"
             :description="options.description"
             :width="options.width"
+            :icon="options.modalIcon"
+            :icon-color="options.modalIconColor"
+            :alignment="options.alignment"
+            :close-button="options.closeButton !== false"
+            :close-on-click-away="options.closeOnClickAway !== false"
         >
             <XqForm :form="modal" @submit="run">
                 <template #actions>
-                    <div class="gap-2 flex justify-end">
+                    <XqDialogFooter sticky :alignment="options.footerAlignment">
                         <XqButton
                             type="button"
                             variant="outline"
@@ -168,15 +218,22 @@ onScopeDispose(closeModal);
                         >
                             {{ options.cancelLabel ?? store.t('Cancel') }}
                         </XqButton>
-                        <XqButton type="submit" size="sm" :disabled="running">
+                        <XqButton
+                            type="submit"
+                            size="sm"
+                            :class="showsSpinner && 'pointer-events-none'"
+                            :aria-busy="running || undefined"
+                        >
+                            <span :class="showsSpinner && 'invisible'">
+                                {{ options.submitLabel ?? store.t('Save') }}
+                            </span>
                             <LoaderCircle
-                                v-if="running"
-                                class="motion-safe:animate-spin"
+                                v-if="showsSpinner"
+                                class="motion-safe:animate-spin absolute"
                                 aria-hidden="true"
                             />
-                            {{ options.submitLabel ?? store.t('Save') }}
                         </XqButton>
-                    </div>
+                    </XqDialogFooter>
                 </template>
             </XqForm>
         </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

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+import { router } from '@inertiajs/vue3';
+import { CircleAlert } from 'lucide-vue-next';
+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';
+
+/**
+ * The buttons of an ActionSet, with no form around them.
+ */
+const props = defineProps<{ actions: FormSchema }>();
+const store = shallowRef(createFormStore(props.actions));
+const visibleActions = computed(() => props.actions.components.filter((node) => !node.hidden));
+
+/**
+ * Resolves once the page has the new data, so the button stays busy until then.
+ *
+ * shortcut: a global "before" listener that cancels this leaves the button busy.
+ * Forms' own unsaved changes alert ignores reloads, so only an app's own could.
+ */
+function reloadPage(): Promise<void> {
+    return new Promise((resolve) => router.reload({ onFinish: () => resolve() }));
+}
+
+// One runner for good: a new one, or a new key, would rebuild the buttons and lose focus.
+const runner: ActionRunner = {
+    get processing() {
+        return store.value.processing;
+    },
+    t: (...args) => store.value.t(...args),
+    mountAction: (node) => store.value.mountAction(node),
+    async runAction(node, modal) {
+        const result = await store.value.runAction(node, modal);
+
+        if (result && !result.redirect) {
+            await reloadPage();
+        }
+
+        return result;
+    },
+};
+
+// With no fields to land on, a failure has to show here.
+const failure = computed(() => {
+    const { errors, fatalError, liveError, t } = store.value;
+
+    return (
+        fatalError.value ??
+        (liveError.value ? t('That action could not run.') : Object.values(errors)[0])
+    );
+});
+
+watch(
+    () => props.actions,
+    (next) => {
+        store.value.dispose();
+        store.value = createFormStore(next);
+    },
+);
+
+onScopeDispose(() => store.value.dispose());
+</script>
+
+<template>
+    <div class="gap-2 flex flex-wrap items-center" data-xq-actions>
+        <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"
+            class="gap-2 text-sm flex basis-full items-start text-xq-destructive"
+        >
+            <CircleAlert class="mt-0.5 size-4 shrink-0" aria-hidden="true" />
+            {{ failure }}
+        </p>
+    </div>
+</template>

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;
+    }
+}