@xelqun/forms 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xelqun/forms",
-    "version": "0.3.1",
+    "version": "0.4.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,10 @@
 @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-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 +285,29 @@
     max-width: 100%;
     height: auto;
 }
+
+@keyframes xq-fade-in {
+    from {
+        opacity: 0;
+    }
+}
+
+@keyframes xq-fade-out {
+    to {
+        opacity: 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,15 +8,17 @@ 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 } from '../lib/utils';
 import type { SchemaNode } from '../schema/types';
 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';
 
@@ -24,6 +26,7 @@ const props = defineProps<{ node: SchemaNode; runner?: ActionRunner }>();
 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);
@@ -41,17 +44,26 @@ const variant = computed(() =>
           : (variants[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;
-    }
-
-    const url: string = options.value.url;
-
+// 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));
+
+let spinnerTimer: ReturnType<typeof setTimeout> | undefined;
+
+// A quick action changes nothing on screen until it's done, so it can't flicker.
+watch(running, (isRunning) => {
+    clearTimeout(spinnerTimer);
+    showsSpinner.value = false;
+
+    if (isRunning) {
+        spinnerTimer = setTimeout(() => (showsSpinner.value = true), LOADING_INDICATOR_DELAY);
+    }
 });
 
 async function run(): Promise<void> {
@@ -62,14 +74,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,7 +130,10 @@ watch(modalOpen, (isOpen) => {
     }
 });
 
-onScopeDispose(closeModal);
+onScopeDispose(() => {
+    clearTimeout(spinnerTimer);
+    closeModal();
+});
 </script>
 
 <template>
@@ -131,20 +161,32 @@ onScopeDispose(closeModal);
             type="button"
             :variant="variant"
             :size="options.style === 'icon' ? 'icon-sm' : 'sm'"
-            :disabled="!!options.disabled || running || store.processing.value"
+            :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"
         >
-            <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>
+            <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>
         <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'"
@@ -156,10 +198,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 +215,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/XqActions.vue

@@ -0,0 +1,78 @@
+<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 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>
+        <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/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 XqActions } from './components/XqActions.vue';
 export type { ActionRunner } from './components/XqAction.vue';
 export { default as XqFieldWrapper } from './components/XqFieldWrapper.vue';
 export { createRegistry, defaultComponents } from './components/defaults';

package/resources/js/schema/types.ts

@@ -173,6 +173,8 @@ export interface UpdatePatch {
 
 export interface ActionResult extends UpdatePatch {
     result?: unknown;
+    /** Where the action sends the user, in place of staying on the page. */
+    redirect?: string | null;
 }
 
 export interface SelectOption {

package/resources/js/ui/XqConfirmDialog.vue

@@ -9,17 +9,38 @@ import {
     AlertDialogRoot,
     AlertDialogTitle,
 } from 'reka-ui';
-import XqButton from './XqButton.vue';
 import { useTranslator } from '../composables/context';
+import { cn } from '../lib/utils';
+import { dialogContentClass, dialogOverlayClass } from './classes';
+import XqButton from './XqButton.vue';
+import XqDialogFooter from './XqDialogFooter.vue';
+import XqDialogHeader from './XqDialogHeader.vue';
 
 const t = useTranslator();
-defineProps<{
-    title: string;
-    message?: string | null;
-    confirmLabel?: string | null;
-    cancelLabel?: string | null;
-    confirmVariant?: 'default' | 'destructive';
-}>();
+
+withDefaults(
+    defineProps<{
+        title: string;
+        message?: string | null;
+        confirmLabel?: string | null;
+        cancelLabel?: string | null;
+        confirmVariant?: 'default' | 'destructive';
+        icon?: string | null;
+        iconColor?: string | null;
+        alignment?: 'start' | 'center' | null;
+        footerAlignment?: 'start' | 'center' | 'end' | 'full' | null;
+    }>(),
+    {
+        message: undefined,
+        confirmLabel: undefined,
+        cancelLabel: undefined,
+        confirmVariant: 'destructive',
+        icon: 'triangle-alert',
+        iconColor: undefined,
+        alignment: 'center',
+        footerAlignment: 'full',
+    },
+);
 defineEmits<{ confirm: [] }>();
 const open = defineModel<boolean>('open', { default: false });
 </script>
@@ -27,15 +48,29 @@ const open = defineModel<boolean>('open', { default: false });
 <template>
     <AlertDialogRoot v-model:open="open">
         <AlertDialogPortal>
-            <AlertDialogOverlay class="inset-0 bg-black/50 fixed z-50" />
+            <AlertDialogOverlay :class="dialogOverlayClass" />
             <AlertDialogContent
-                class="max-w-sm p-5 shadow-lg gap-3 fixed top-1/2 left-1/2 z-50 grid w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 rounded-xq-lg border border-xq-border bg-xq-popover text-xq-popover-foreground"
+                v-bind="message ? {} : { 'aria-describedby': undefined }"
+                :class="cn(dialogContentClass, 'max-w-sm p-6 gap-5 overflow-y-auto')"
             >
-                <AlertDialogTitle class="text-sm font-semibold">{{ title }}</AlertDialogTitle>
-                <AlertDialogDescription class="text-sm text-xq-muted-foreground">
-                    {{ message ?? '' }}
-                </AlertDialogDescription>
-                <div class="gap-2 flex justify-end">
+                <XqDialogHeader
+                    :icon="icon"
+                    :icon-color="
+                        iconColor ?? (confirmVariant === 'destructive' ? 'danger' : 'primary')
+                    "
+                    :alignment="alignment"
+                >
+                    <AlertDialogTitle class="text-base font-semibold text-balance">
+                        {{ title }}
+                    </AlertDialogTitle>
+                    <AlertDialogDescription
+                        v-if="message"
+                        class="text-sm text-pretty text-xq-muted-foreground"
+                    >
+                        {{ message }}
+                    </AlertDialogDescription>
+                </XqDialogHeader>
+                <XqDialogFooter :alignment="footerAlignment">
                     <AlertDialogCancel as-child>
                         <XqButton type="button" variant="outline" size="sm">
                             {{ cancelLabel ?? t('Cancel') }}
@@ -44,14 +79,14 @@ const open = defineModel<boolean>('open', { default: false });
                     <AlertDialogAction as-child>
                         <XqButton
                             type="button"
-                            :variant="confirmVariant ?? 'destructive'"
+                            :variant="confirmVariant"
                             size="sm"
                             @click="$emit('confirm')"
                         >
                             {{ confirmLabel ?? t('Delete') }}
                         </XqButton>
                     </AlertDialogAction>
-                </div>
+                </XqDialogFooter>
             </AlertDialogContent>
         </AlertDialogPortal>
     </AlertDialogRoot>

package/resources/js/ui/XqDialog.vue

@@ -1,5 +1,7 @@
 <script setup lang="ts">
+import { X } from 'lucide-vue-next';
 import {
+    DialogClose,
     DialogContent,
     DialogDescription,
     DialogOverlay,
@@ -7,9 +9,26 @@ import {
     DialogRoot,
     DialogTitle,
 } from 'reka-ui';
+import { useTranslator } from '../composables/context';
 import { cn } from '../lib/utils';
+import { dialogContentClass, dialogOverlayClass } from './classes';
+import XqButton from './XqButton.vue';
+import XqDialogHeader from './XqDialogHeader.vue';
 
-const props = defineProps<{ title: string; description?: string | null; width?: string | null }>();
+const t = useTranslator();
+const props = withDefaults(
+    defineProps<{
+        title: string;
+        description?: string | null;
+        width?: string | null;
+        icon?: string | null;
+        iconColor?: string | null;
+        alignment?: 'start' | 'center' | null;
+        closeButton?: boolean;
+        closeOnClickAway?: boolean;
+    }>(),
+    { closeButton: true, closeOnClickAway: true },
+);
 const open = defineModel<boolean>('open', { default: false });
 
 const widths: Record<string, string> = {
@@ -18,28 +37,60 @@ const widths: Record<string, string> = {
     lg: 'max-w-lg',
     xl: 'max-w-xl',
     '2xl': 'max-w-2xl',
+    '3xl': 'max-w-3xl',
+    '4xl': 'max-w-4xl',
+    '5xl': 'max-w-5xl',
 };
+
+function keepOpenUnlessAllowed(event: Event): void {
+    if (!props.closeOnClickAway) {
+        event.preventDefault();
+    }
+}
 </script>
 
 <template>
     <DialogRoot v-model:open="open">
         <DialogPortal>
-            <DialogOverlay class="inset-0 bg-black/50 fixed z-50" />
+            <DialogOverlay :class="dialogOverlayClass" />
             <DialogContent
-                :class="
-                    cn(
-                        'p-5 shadow-lg gap-4 fixed top-1/2 left-1/2 z-50 grid max-h-[85vh] w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto rounded-xq-lg border border-xq-border bg-xq-popover text-xq-popover-foreground',
-                        widths[props.width ?? 'md'],
-                    )
-                "
+                v-bind="description ? {} : { 'aria-describedby': undefined }"
+                :class="cn(dialogContentClass, widths[props.width ?? 'md'])"
+                @interact-outside="keepOpenUnlessAllowed"
             >
-                <div class="gap-1 grid">
-                    <DialogTitle class="text-sm font-semibold">{{ title }}</DialogTitle>
-                    <DialogDescription class="text-sm text-xq-muted-foreground">
-                        {{ description ?? '' }}
+                <XqDialogHeader
+                    :icon="icon"
+                    :icon-color="iconColor"
+                    :alignment="alignment"
+                    class="px-6 py-4 min-h-0 overflow-y-auto border-b border-xq-border"
+                    :class="closeButton && 'pr-12'"
+                >
+                    <DialogTitle class="text-base font-semibold text-balance">
+                        {{ title }}
+                    </DialogTitle>
+                    <DialogDescription
+                        v-if="description"
+                        class="text-sm text-pretty text-xq-muted-foreground"
+                    >
+                        {{ description }}
                     </DialogDescription>
+                </XqDialogHeader>
+                <!-- A sticky footer can't leave its parent, so it brings its own space. -->
+                <div class="px-6 pt-5 pb-6 has-data-xq-dialog-footer:pb-0 min-h-0 overflow-y-auto">
+                    <slot />
                 </div>
-                <slot />
+                <!-- Last, so a modal's first field gets the focus and not this. -->
+                <DialogClose v-if="closeButton" as-child>
+                    <XqButton
+                        type="button"
+                        variant="ghost"
+                        size="icon-sm"
+                        class="top-3.5 right-3.5 absolute text-xq-muted-foreground"
+                        :aria-label="t('Close')"
+                    >
+                        <X />
+                    </XqButton>
+                </DialogClose>
             </DialogContent>
         </DialogPortal>
     </DialogRoot>

package/resources/js/ui/XqDialogFooter.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { cn } from '../lib/utils';
+
+defineProps<{
+    alignment?: 'start' | 'center' | 'end' | 'full' | null;
+    /** Keeps the buttons in reach while a long form scrolls behind them. */
+    sticky?: boolean;
+}>();
+
+const alignments: Record<string, string> = {
+    start: 'justify-start',
+    center: 'justify-center',
+    end: 'justify-end',
+    full: '*:flex-1',
+};
+</script>
+
+<template>
+    <div
+        data-xq-dialog-footer
+        :class="
+            cn(
+                'gap-2 flex',
+                alignments[alignment ?? 'end'] ?? alignments.end,
+                sticky && 'bottom-0 -mx-6 px-6 py-4 sticky border-t border-xq-border bg-xq-popover',
+            )
+        "
+    >
+        <slot />
+    </div>
+</template>

package/resources/js/ui/XqDialogHeader.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { cn } from '../lib/utils';
+import { dialogIconClasses } from './classes';
+import XqIcon from './XqIcon.vue';
+
+defineProps<{
+    icon?: string | null;
+    iconColor?: string | null;
+    alignment?: 'start' | 'center' | null;
+}>();
+</script>
+
+<template>
+    <div
+        :class="
+            cn(
+                'gap-4 flex',
+                alignment === 'center' ? 'flex-col items-center text-center' : 'items-start',
+            )
+        "
+    >
+        <span
+            v-if="icon"
+            data-xq-dialog-icon
+            :class="
+                cn(
+                    'size-10 flex shrink-0 items-center justify-center rounded-full',
+                    dialogIconClasses[iconColor ?? 'primary'] ?? dialogIconClasses.primary,
+                )
+            "
+        >
+            <XqIcon :name="icon" class="size-5" />
+        </span>
+        <div class="gap-1 min-w-0 grid">
+            <slot />
+        </div>
+    </div>
+</template>

package/resources/js/ui/classes.ts

@@ -15,6 +15,22 @@ export const groupLabelClass = 'px-2 py-1.5 text-xs font-medium text-xq-muted-fo
 export const optionClass =
     'relative flex w-full cursor-default items-center gap-2 rounded-xq-sm py-1.5 pr-8 pl-2 text-sm outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-xq-accent data-[highlighted]:text-xq-accent-foreground';
 
+export const dialogOverlayClass =
+    'inset-0 bg-black/50 fixed z-50 backdrop-blur-[2px] motion-safe:data-[state=open]:animate-xq-fade-in motion-safe:data-[state=closed]:animate-xq-fade-out';
+
+export const dialogContentClass =
+    'shadow-xl fixed top-1/2 left-1/2 z-50 flex max-h-[85vh] w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-xq-xl border border-xq-border bg-xq-popover text-xq-popover-foreground outline-none motion-safe:data-[state=open]:animate-xq-dialog-in motion-safe:data-[state=closed]:animate-xq-dialog-out';
+
+/** The tinted circle behind a dialog's icon. */
+export const dialogIconClasses: Record<string, string> = {
+    primary: 'bg-xq-primary/10 text-xq-primary',
+    danger: 'bg-xq-destructive/10 text-xq-destructive',
+    info: 'bg-xq-info/10 text-xq-info',
+    success: 'bg-xq-success/10 text-xq-success',
+    warning: 'bg-xq-warning/10 text-xq-warning',
+    gray: 'bg-xq-muted text-xq-muted-foreground',
+};
+
 /** Text colors the PHP side can name. */
 export const toneClasses: Record<string, string> = {
     neutral: 'text-xq-foreground',