@xelqun/forms 0.1.0 → 0.2.0

package/resources/js/components/layouts/XqIconNode.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import { iconSizeClasses, toneClasses } from '../../ui/classes';
+import XqIcon from '../../ui/XqIcon.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const options = computed(() => props.node.props ?? {});
+const accessibleName = computed(
+    () => props.node.extraAttributes?.['aria-label'] ?? options.value.tooltip,
+);
+</script>
+
+<template>
+    <span
+        class="inline-flex"
+        :role="accessibleName ? 'img' : undefined"
+        :aria-label="accessibleName"
+        :title="options.tooltip"
+    >
+        <XqIcon
+            :name="options.icon"
+            :class="
+                cn(
+                    iconSizeClasses[options.size] ?? 'size-5',
+                    toneClasses[options.color] ?? 'text-xq-muted-foreground',
+                )
+            "
+        />
+    </span>
+</template>

package/resources/js/components/layouts/XqImageNode.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+
+const props = defineProps<{ node: SchemaNode }>();
+const options = computed(() => props.node.props ?? {});
+
+const alignments: Record<string, string> = {
+    start: 'justify-start',
+    center: 'justify-center',
+    end: 'justify-end',
+};
+
+function cssSize(size: unknown): string | undefined {
+    return typeof size === 'number' ? `${size}px` : (size as string | undefined);
+}
+</script>
+
+<template>
+    <div :class="cn('flex', alignments[options.alignment])">
+        <img
+            :src="options.url"
+            :alt="options.alt"
+            :title="options.tooltip"
+            :style="{ width: cssSize(options.width), height: cssSize(options.height) }"
+            class="max-w-full rounded-xq-md"
+        />
+    </div>
+</template>

package/resources/js/components/layouts/XqSection.vue

@@ -6,7 +6,9 @@ import { gridStyle } from '../../composables/layout';
 import { cn } from '../../lib/utils';
 import type { SchemaNode } from '../../schema/types';
 import XqNode from '../XqNode.vue';
+import { useTranslator } from '../../composables/context';
 
+const t = useTranslator();
 const props = defineProps<{ node: SchemaNode }>();
 const options = computed(() => props.node.props ?? {});
 const collapsed = ref<boolean>(!!props.node.props?.collapsed);
@@ -42,7 +44,7 @@ provide(HEADING_LEVEL, Math.min(headingLevel + 1, 6));
                 type="button"
                 class="size-7 flex cursor-pointer items-center justify-center rounded-xq-md text-xq-muted-foreground hover:bg-xq-accent"
                 :aria-expanded="!collapsed"
-                :aria-label="collapsed ? 'Expand section' : 'Collapse section'"
+                :aria-label="collapsed ? t('Expand section') : t('Collapse section')"
                 @click="collapsed = !collapsed"
             >
                 <ChevronDown

package/resources/js/components/layouts/XqTabsLayout.vue

@@ -2,7 +2,7 @@
 import { computed, ref, watch } from 'vue';
 import { useFormStore } from '../../composables/context';
 import { gridStyle } from '../../composables/layout';
-import { eachNode } from '../../core/patch';
+import { usePanelErrors } from '../../composables/usePanelErrors';
 import type { SchemaNode } from '../../schema/types';
 import XqTabs from '../../ui/XqTabs.vue';
 import XqTabsContent from '../../ui/XqTabsContent.vue';
@@ -21,29 +21,11 @@ watch(tabs, (visible) => {
     }
 });
 
-function pathsIn(tab: SchemaNode): string[] {
-    const paths: string[] = [];
-    eachNode(tab.children ?? [], (child) => child.path && paths.push(child.path));
-
-    return paths;
-}
-
-function errorCount(tab: SchemaNode): number {
-    return pathsIn(tab).filter((path) => store.errors[path]).length;
-}
-
-watch(store.focusRequest, (request) => {
-    const tab =
-        request && tabs.value.find((candidate) => pathsIn(candidate).includes(request.path));
-
-    if (tab) {
-        active.value = tab.key;
-    }
-});
+const { errorCount } = usePanelErrors(tabs, (tab) => (active.value = tab.key));
 </script>
 
 <template>
-    <XqTabs v-model="active">
+    <XqTabs v-model="active" :unmount-on-hide="false">
         <XqTabsList>
             <XqTabsTrigger v-for="tab in tabs" :key="tab.key" :value="tab.key">
                 {{ tab.label }}

package/resources/js/components/layouts/XqTextNode.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import { textSizeClasses, toneClasses } from '../../ui/classes';
+import XqBadge from '../../ui/XqBadge.vue';
+import XqIcon from '../../ui/XqIcon.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const options = computed(() => props.node.props ?? {});
+
+const weights: Record<string, string> = {
+    thin: 'font-thin',
+    light: 'font-light',
+    normal: 'font-normal',
+    medium: 'font-medium',
+    semibold: 'font-semibold',
+    bold: 'font-bold',
+    black: 'font-black',
+};
+const families: Record<string, string> = {
+    sans: 'font-sans',
+    serif: 'font-serif',
+    mono: 'font-mono',
+};
+const classes = computed(() =>
+    cn(
+        textSizeClasses[options.value.size] ?? 'text-sm',
+        toneClasses[options.value.color] ?? 'text-xq-muted-foreground',
+        weights[options.value.weight],
+        families[options.value.fontFamily],
+    ),
+);
+</script>
+
+<template>
+    <XqBadge v-if="options.badge" variant="secondary" :class="classes" :title="options.tooltip">
+        <XqIcon v-if="options.icon" :name="options.icon" class="size-3" />
+        {{ options.content }}
+    </XqBadge>
+    <!-- Only an Htmlable from PHP lands here, so the form's author vouched for it. -->
+    <div
+        v-else-if="options.html !== null && options.html !== undefined"
+        :class="classes"
+        :title="options.tooltip"
+        v-html="options.html"
+    />
+    <p v-else :class="classes" :title="options.tooltip">{{ options.content }}</p>
+</template>

package/resources/js/components/layouts/XqUnorderedList.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import { textSizeClasses } from '../../ui/classes';
+import XqNode from '../XqNode.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const size = computed(() => textSizeClasses[props.node.props?.size] ?? 'text-sm');
+</script>
+
+<template>
+    <ul :class="cn('gap-1 ps-5 grid list-disc text-xq-muted-foreground', size)">
+        <li v-for="child in node.children ?? []" :key="child.key">
+            <XqNode :node="child" />
+        </li>
+    </ul>
+</template>

package/resources/js/components/layouts/XqWizard.vue

@@ -0,0 +1,168 @@
+<script setup lang="ts">
+import { router } from '@inertiajs/vue3';
+import { Check, ChevronLeft, ChevronRight, LoaderCircle } from 'lucide-vue-next';
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { useFormStore } from '../../composables/context';
+import { gridStyle } from '../../composables/layout';
+import { usePanelErrors } from '../../composables/usePanelErrors';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import XqButton from '../../ui/XqButton.vue';
+import XqIcon from '../../ui/XqIcon.vue';
+import XqNode from '../XqNode.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const store = useFormStore();
+const { t, validating } = store;
+const options = computed(() => props.node.props ?? {});
+const steps = computed(() => (props.node.children ?? []).filter((step) => store.isVisible(step)));
+const startKey = options.value.startKey;
+const active = ref<string>(
+    steps.value.find((step) => step.key === startKey)?.key ?? steps.value[0]?.key ?? '',
+);
+const activeIndex = computed(() => steps.value.findIndex((step) => step.key === active.value));
+const panels = ref<Record<string, HTMLElement>>({});
+
+const { errorCount } = usePanelErrors(steps, (step) => (active.value = step.key));
+
+watch(steps, (visible) => {
+    if (!visible.some((step) => step.key === active.value)) {
+        active.value = visible[0]?.key ?? '';
+    }
+});
+
+watch(active, (key) => {
+    const slug = steps.value.find((step) => step.key === key)?.props?.slug;
+
+    if (options.value.queryKey && slug) {
+        const url = new URL(window.location.href);
+
+        url.searchParams.set(options.value.queryKey, slug);
+        router.replace({
+            url: `${url.pathname}${url.search}`,
+            preserveState: true,
+            preserveScroll: true,
+        });
+    }
+});
+
+async function show(key: string): Promise<void> {
+    active.value = key;
+    await nextTick();
+    panels.value[key]?.focus({ preventScroll: true });
+    panels.value[key]?.scrollIntoView?.({ block: 'nearest' });
+}
+
+async function next(): Promise<void> {
+    const step = steps.value[activeIndex.value];
+
+    if (!step || validating.value) {
+        return;
+    }
+
+    if (options.value.skippable || (await store.validateStep(step))) {
+        // Looked up now: what a step's hooks set can hide the step that was next.
+        const following = steps.value[activeIndex.value + 1];
+
+        if (following) {
+            await show(following.key);
+        }
+    }
+}
+
+function canOpen(index: number): boolean {
+    return !!options.value.skippable || index <= activeIndex.value;
+}
+
+const stepper = { hasNext: () => activeIndex.value < steps.value.length - 1, next };
+
+onMounted(() => store.steppers.add(stepper));
+onBeforeUnmount(() => store.steppers.delete(stepper));
+</script>
+
+<template>
+    <div class="gap-5 grid">
+        <ol class="gap-2 sm:flex-row sm:gap-4 flex flex-col">
+            <li v-for="(step, index) in steps" :key="step.key" class="min-w-0 flex-1">
+                <button
+                    type="button"
+                    class="gap-2.5 flex w-full cursor-pointer items-center rounded-xq-md text-start disabled:cursor-default"
+                    :aria-current="step.key === active ? 'step' : undefined"
+                    :disabled="!canOpen(index)"
+                    @click="show(step.key)"
+                >
+                    <span
+                        :class="
+                            cn(
+                                'size-7 text-xs font-medium flex shrink-0 items-center justify-center rounded-full border border-xq-border',
+                                step.key === active &&
+                                    'border-xq-primary bg-xq-primary text-xq-primary-foreground',
+                                index < activeIndex && 'border-xq-primary text-xq-primary',
+                                errorCount(step) > 0 && 'border-xq-destructive text-xq-destructive',
+                            )
+                        "
+                    >
+                        <XqIcon
+                            v-if="index < activeIndex && step.props?.completedIcon"
+                            :name="step.props.completedIcon"
+                        />
+                        <Check v-else-if="index < activeIndex" class="size-4" aria-hidden="true" />
+                        <XqIcon v-else-if="step.props?.icon" :name="step.props.icon" />
+                        <template v-else>{{ index + 1 }}</template>
+                    </span>
+                    <span class="min-w-0 grid">
+                        <span class="text-sm font-medium truncate">{{ step.label }}</span>
+                        <span
+                            v-if="step.props?.description"
+                            class="text-xs truncate text-xq-muted-foreground"
+                        >
+                            {{ step.props.description }}
+                        </span>
+                    </span>
+                </button>
+            </li>
+        </ol>
+        <section
+            v-for="step in steps"
+            :key="step.key"
+            :ref="(element) => (panels[step.key] = element as HTMLElement)"
+            :hidden="step.key !== active"
+            :aria-label="step.label ?? undefined"
+            tabindex="-1"
+            class="outline-none"
+        >
+            <div class="xq-grid" :style="gridStyle(step.props?.columns)">
+                <XqNode v-for="child in step.children ?? []" :key="child.key" :node="child" />
+            </div>
+        </section>
+        <div class="gap-3 flex items-center justify-between">
+            <XqButton
+                v-if="activeIndex > 0"
+                type="button"
+                variant="outline"
+                size="sm"
+                data-xq-wizard-back
+                @click="show(steps[activeIndex - 1].key)"
+            >
+                <ChevronLeft />{{ t('Back') }}
+            </XqButton>
+            <XqButton
+                v-if="activeIndex < steps.length - 1"
+                type="button"
+                size="sm"
+                class="ms-auto"
+                data-xq-wizard-next
+                :disabled="validating"
+                @click="next"
+            >
+                {{ t('Next') }}
+                <LoaderCircle
+                    v-if="validating"
+                    class="motion-safe:animate-spin"
+                    aria-hidden="true"
+                />
+                <ChevronRight v-else />
+            </XqButton>
+        </div>
+    </div>
+</template>

package/resources/js/composables/context.ts

@@ -1,12 +1,16 @@
 import { inject, provide } from 'vue';
 import type { InjectionKey } from 'vue';
 import type { FormStore } from '../core/store';
+import { translate } from '../core/translate';
 
 export const FORM_STORE: InjectionKey<FormStore> = Symbol('xelqun-form-store');
 
 /** Heading level for the next section title. Nested sections go one level deeper. */
 export const HEADING_LEVEL: InjectionKey<number> = Symbol('xelqun-heading-level');
 
+/** Set inside a FusedGroup, which lists its fields' errors below the whole group. */
+export const FUSED_GROUP: InjectionKey<boolean> = Symbol('xelqun-fused-group');
+
 export function provideFormStore(store: FormStore): void {
     provide(FORM_STORE, store);
 }
@@ -20,3 +24,13 @@ export function useFormStore(): FormStore {
 
     return store;
 }
+
+/**
+ * The form's translator, or plain English for a control used outside a form.
+ */
+export function useTranslator(): FormStore['t'] {
+    return (
+        inject(FORM_STORE, null)?.t ??
+        ((text, replacements) => translate(undefined, text, replacements))
+    );
+}

package/resources/js/composables/useField.ts

@@ -1,7 +1,15 @@
 import { computed } from 'vue';
 import type { SchemaNode } from '../schema/types';
+import type { FormStore } from '../core/store';
 import { useFormStore } from './context';
 
+/**
+ * The id of a field's control. Its error and hint hang off this.
+ */
+export function fieldId(store: FormStore, path: string): string {
+    return `xq-${store.id}-${path}`.replace(/[^\w-]/g, '-');
+}
+
 /**
  * Everything a field component needs: a writable value bound to the form
  * state, its error, and the evaluated required/disabled rules.
@@ -10,8 +18,9 @@ export function useField<T = any>(nodeOrPath: SchemaNode | string) {
     const store = useFormStore();
     const node = typeof nodeOrPath === 'string' ? store.nodes.get(nodeOrPath)! : nodeOrPath;
     const path = node.path ?? node.key;
-    const id = `xq-${store.id}-${path}`.replace(/[^\w-]/g, '-');
+    const id = fieldId(store, path);
     const error = computed(() => store.errors[path] ?? null);
+    const hint = computed(() => store.text(node, 'hint'));
 
     const value = computed<T>({
         get: () => store.get(path),
@@ -25,17 +34,26 @@ export function useField<T = any>(nodeOrPath: SchemaNode | string) {
         id,
         value,
         error,
+        label: computed(() => store.text(node, 'label')),
+        hint,
+        placeholder: computed(() => store.text(node, 'placeholder')),
         /** The id for aria-describedby: the error when there is one, otherwise the hint. */
         describedBy: computed(() => {
             if (error.value) {
                 return `${id}-error`;
             }
 
-            return node.hint ? `${id}-hint` : undefined;
+            return hint.value ? `${id}-hint` : undefined;
         }),
         loading: computed(() => store.isLoading(node)),
+        /** Delayed version of loading, for the spinner: fast requests never show one. */
+        showLoading: computed(() => store.showsLoadingIndicator(node)),
         required: computed(() => store.isRequired(node)),
-        disabled: computed(() => store.isDisabled(node) || store.processing.value),
+        /** True when read-only too, so a control with no read-only mode can't be changed. */
+        disabled: computed(
+            () => store.isDisabled(node) || !!node.readOnly || store.processing.value,
+        ),
+        readOnly: computed(() => !!node.readOnly),
         onBlur: () => store.blur(path),
     };
 }

package/resources/js/composables/usePanelErrors.ts

@@ -0,0 +1,37 @@
+import { watch } from 'vue';
+import type { ComputedRef } from 'vue';
+import { eachNode } from '../core/patch';
+import type { SchemaNode } from '../schema/types';
+import { useFormStore } from './context';
+
+/**
+ * For layouts that show one panel at a time: count each panel's errors, and open
+ * the panel holding the field the form wants to focus.
+ */
+export function usePanelErrors(
+    panels: ComputedRef<SchemaNode[]>,
+    open: (panel: SchemaNode) => void,
+) {
+    const store = useFormStore();
+
+    function pathsIn(panel: SchemaNode): string[] {
+        const paths: string[] = [];
+        eachNode(panel.children ?? [], (child) => child.path && paths.push(child.path));
+
+        return paths;
+    }
+
+    watch(store.focusRequest, (request) => {
+        const panel =
+            request && panels.value.find((candidate) => pathsIn(candidate).includes(request.path));
+
+        if (panel) {
+            open(panel);
+        }
+    });
+
+    return {
+        errorCount: (panel: SchemaNode) =>
+            pathsIn(panel).filter((path) => store.errors[path]).length,
+    };
+}

package/resources/js/composables/useSortable.ts

@@ -0,0 +1,70 @@
+import type SortableType from 'sortablejs';
+import { onBeforeUnmount, watch } from 'vue';
+import type { Ref } from 'vue';
+
+export interface SortableOptions {
+    /** Which children can move. Start with ">" so a nested list's items don't count. */
+    draggable: string;
+    /** Only this part starts a drag. Without it, the whole item does. */
+    handle?: string;
+    enabled: () => boolean;
+    /** Called with indexes among the draggable items, once the drag ends somewhere new. */
+    onMove: (from: number, to: number) => void;
+}
+
+/**
+ * Drag to reorder. SortableJS loads only when a list can actually be dragged, and
+ * move buttons stay next to it, because keyboard users can't drag.
+ */
+export function useSortable(container: Ref<HTMLElement | null>, options: SortableOptions): void {
+    let sortable: SortableType | null = null;
+
+    function destroy(): void {
+        sortable?.destroy();
+        sortable = null;
+    }
+
+    watch(
+        [container, options.enabled],
+        async ([element, enabled]) => {
+            destroy();
+
+            if (!element || !enabled) {
+                return;
+            }
+
+            const { default: Sortable } = await import('sortablejs');
+
+            if (container.value !== element || !options.enabled() || sortable) {
+                return;
+            }
+
+            sortable = Sortable.create(element, {
+                draggable: options.draggable,
+                handle: options.handle,
+                filter: 'input, textarea, button:not([data-xq-drag])',
+                preventOnFilter: false,
+                animation: 150,
+                ghostClass: 'opacity-40',
+                // The same drag for mouse and touch, and no text dropped into inputs.
+                forceFallback: true,
+                onEnd({ item, from, oldIndex, newIndex, oldDraggableIndex, newDraggableIndex }) {
+                    if (oldDraggableIndex === newDraggableIndex) {
+                        return;
+                    }
+
+                    // Put the element back: Vue owns this order and moves it from the state.
+                    from.insertBefore(
+                        item,
+                        from.children[oldIndex! + (oldIndex! > newIndex! ? 1 : 0)] ?? null,
+                    );
+
+                    options.onMove(oldDraggableIndex!, newDraggableIndex!);
+                },
+            });
+        },
+        { immediate: true },
+    );
+
+    onBeforeUnmount(destroy);
+}

package/resources/js/composables/useUnsavedChangesAlert.ts

@@ -0,0 +1,48 @@
+import { router } from '@inertiajs/vue3';
+import { nextTick, onBeforeUnmount, onMounted } from 'vue';
+import type { FormStore } from '../core/store';
+
+/**
+ * Warn before the user leaves with changes, when the form asks for it. The
+ * browser's own dialog covers closing the tab, because nothing else may run there.
+ */
+export function useUnsavedChangesAlert(store: FormStore): void {
+    if (!store.schema.unsavedChangesAlert) {
+        return;
+    }
+
+    let stopListening = (): void => {};
+
+    function warnBeforeUnload(event: BeforeUnloadEvent): void {
+        if (store.isDirty()) {
+            event.preventDefault();
+        }
+    }
+
+    onMounted(async () => {
+        // Computed fields settle a tick after they mount, and that isn't an edit.
+        await nextTick();
+        store.markClean();
+
+        window.addEventListener('beforeunload', warnBeforeUnload);
+        stopListening = router.on('before', (event) => {
+            const { visit } = event.detail;
+            const staysOnPage =
+                store.processing.value ||
+                visit.prefetch ||
+                visit.only.length > 0 ||
+                (visit.preserveState === true && visit.url.pathname === window.location.pathname);
+
+            if (!staysOnPage && store.isDirty()) {
+                if (!window.confirm(store.t('You have unsaved changes. Leave this page?'))) {
+                    event.preventDefault();
+                }
+            }
+        });
+    });
+
+    onBeforeUnmount(() => {
+        window.removeEventListener('beforeunload', warnBeforeUnload);
+        stopListening();
+    });
+}

package/resources/js/core/dates.ts

@@ -0,0 +1,38 @@
+function name(date: Date, options: Intl.DateTimeFormatOptions, locale?: string): string {
+    return new Intl.DateTimeFormat(locale, options).format(date);
+}
+
+function pad(value: number): string {
+    return String(value).padStart(2, '0');
+}
+
+const TOKENS: Record<string, (date: Date, locale?: string) => string> = {
+    d: (date) => pad(date.getDate()),
+    j: (date) => String(date.getDate()),
+    D: (date, locale) => name(date, { weekday: 'short' }, locale),
+    l: (date, locale) => name(date, { weekday: 'long' }, locale),
+    m: (date) => pad(date.getMonth() + 1),
+    n: (date) => String(date.getMonth() + 1),
+    M: (date, locale) => name(date, { month: 'short' }, locale),
+    F: (date, locale) => name(date, { month: 'long' }, locale),
+    Y: (date) => String(date.getFullYear()),
+    y: (date) => String(date.getFullYear()).slice(-2),
+    H: (date) => pad(date.getHours()),
+    G: (date) => String(date.getHours()),
+    h: (date) => pad(date.getHours() % 12 || 12),
+    g: (date) => String(date.getHours() % 12 || 12),
+    i: (date) => pad(date.getMinutes()),
+    s: (date) => pad(date.getSeconds()),
+    A: (date) => (date.getHours() < 12 ? 'AM' : 'PM'),
+    a: (date) => (date.getHours() < 12 ? 'am' : 'pm'),
+};
+
+/**
+ * Format a date with PHP's date tokens, so a format written in PHP reads the same
+ * in the browser. A backslash escapes the next character.
+ */
+export function formatPhpDate(date: Date, format: string, locale?: string): string {
+    return format.replace(/\\(.)|[a-zA-Z]/g, (token, escaped?: string) => {
+        return escaped ?? TOKENS[token]?.(date, locale) ?? token;
+    });
+}