@xelqun/forms 0.0.0-stage → 0.1.0

package/resources/js/components/fields/XqSelectField.vue

@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import { X } from 'lucide-vue-next';
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import { useField } from '../../composables/useField';
+import type { SchemaNode, SelectOption } from '../../schema/types';
+import XqCombobox from '../../ui/XqCombobox.vue';
+import XqSelect from '../../ui/XqSelect.vue';
+import XqFieldWrapper from '../XqFieldWrapper.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const { store, path, value, error, describedBy, required, disabled, id, onBlur } = useField(
+    props.node,
+);
+const options = computed<SelectOption[]>(() => props.node.props?.options ?? []);
+const useCombobox = computed(() => !!(props.node.props?.searchable || props.node.props?.multiple));
+const isRemote = computed(() => !!props.node.props?.async);
+
+const remoteOptions = ref<SelectOption[]>([]);
+const loading = ref(false);
+const searchFailed = ref(false);
+const debounce = computed<number>(() => props.node.props?.searchDebounce ?? 250);
+const cache = new Map<string, SelectOption[]>();
+let lastTerm = '';
+let timer: ReturnType<typeof setTimeout> | null = null;
+let controller: AbortController | null = null;
+
+watch(options, (next) => (remoteOptions.value = mergeOptions(next, remoteOptions.value)), {
+    immediate: true,
+});
+
+function mergeOptions(first: SelectOption[], second: SelectOption[]): SelectOption[] {
+    const seen = new Set(first.map((option) => String(option.value)));
+
+    return [...first, ...second.filter((option) => !seen.has(String(option.value)))];
+}
+
+function cancelPendingSearch(): void {
+    if (timer) {
+        clearTimeout(timer);
+        timer = null;
+    }
+
+    controller?.abort();
+    loading.value = false;
+}
+
+/**
+ * Called only when the user types (not when the input text is reset after a
+ * selection, a clear or a blur). Waits for a pause in typing, skips empty and
+ * repeated terms, and reuses results it has already fetched.
+ */
+function onSearch(input: string): void {
+    if (!isRemote.value) {
+        return;
+    }
+
+    const term = input.trim();
+
+    cancelPendingSearch();
+    searchFailed.value = false;
+
+    if (term === '') {
+        lastTerm = '';
+        remoteOptions.value = options.value;
+
+        return;
+    }
+
+    if (term === lastTerm) {
+        return;
+    }
+
+    const cached = cache.get(term.toLowerCase());
+
+    if (cached) {
+        lastTerm = term;
+        remoteOptions.value = mergeOptions(cached, options.value);
+
+        return;
+    }
+
+    timer = setTimeout(async () => {
+        timer = null;
+        controller = new AbortController();
+        loading.value = true;
+
+        try {
+            const results = await store.search(path, term, controller.signal);
+
+            cache.set(term.toLowerCase(), results);
+            lastTerm = term;
+            remoteOptions.value = mergeOptions(results, options.value);
+        } catch (searchError) {
+            if (!controller.signal.aborted) {
+                searchFailed.value = true;
+                console.error('[xelqun] Search failed.', searchError);
+            }
+        } finally {
+            loading.value = false;
+        }
+    }, debounce.value);
+}
+
+onBeforeUnmount(cancelPendingSearch);
+
+const hasValue = computed(
+    () => value.value !== null && value.value !== undefined && value.value !== '',
+);
+</script>
+
+<template>
+    <XqFieldWrapper :node="node" :id="id" :error="error" :required="required">
+        <XqCombobox
+            v-if="useCombobox"
+            :id="id"
+            v-model="value"
+            :options="isRemote ? remoteOptions : options"
+            :multiple="!!node.props?.multiple"
+            :remote="isRemote"
+            :loading="loading"
+            :placeholder="node.placeholder"
+            :disabled="disabled"
+            :invalid="!!error"
+            :described-by="describedBy"
+            :search-failed="searchFailed"
+            @search="onSearch"
+            @blur="onBlur"
+        />
+        <div v-else class="relative">
+            <XqSelect
+                :id="id"
+                v-model="value"
+                :options="options"
+                :placeholder="node.placeholder"
+                :disabled="disabled"
+                :invalid="!!error"
+                :described-by="describedBy"
+                :class="!required && hasValue ? '[&>span:first-child]:pr-6' : undefined"
+            />
+            <button
+                v-if="!required && hasValue && !disabled"
+                type="button"
+                class="right-9 size-5 rounded-sm absolute top-1/2 flex -translate-y-1/2 cursor-pointer items-center justify-center text-xq-muted-foreground hover:text-xq-foreground"
+                aria-label="Clear selection"
+                @click="value = null"
+            >
+                <X class="size-3.5" />
+            </button>
+        </div>
+    </XqFieldWrapper>
+</template>

package/resources/js/components/fields/XqTextInputField.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { useField } from '../../composables/useField';
+import { isNumeric, toNumber } from '../../core/values';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import { controlClass } from '../../ui/classes';
+import XqFieldWrapper from '../XqFieldWrapper.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const { path, value, error, describedBy, required, disabled, id, onBlur } = useField(props.node);
+const options = computed(() => props.node.props ?? {});
+
+function format(next: unknown): string {
+    return next === null || next === undefined ? '' : String(next);
+}
+
+/**
+ * Keep the typed text locally so "1." or "-" can be typed into numeric fields
+ * while the state already holds a number.
+ */
+const text = ref(format(value.value));
+
+watch(value, (next) => {
+    const matchesText = options.value.numeric
+        ? text.value.trim() !== '' && isNumeric(text.value) && toNumber(text.value) === next
+        : text.value === next;
+
+    if (!matchesText) {
+        text.value = format(next);
+    }
+});
+
+function onInput(event: Event): void {
+    text.value = (event.target as HTMLInputElement).value;
+
+    if (!options.value.numeric) {
+        value.value = text.value;
+
+        return;
+    }
+
+    const trimmed = text.value.trim();
+    value.value = trimmed === '' ? null : isNumeric(trimmed) ? toNumber(trimmed) : trimmed;
+}
+
+const inputType = computed(() =>
+    options.value.numeric ? 'text' : (options.value.inputType ?? 'text'),
+);
+</script>
+
+<template>
+    <XqFieldWrapper :node="node" :id="id" :error="error" :required="required">
+        <div
+            :class="
+                cn(
+                    controlClass,
+                    'h-9 flex items-center overflow-hidden focus-within:border-xq-ring focus-within:ring-[3px] focus-within:ring-xq-ring/25',
+                    error && 'border-xq-destructive',
+                    disabled && 'bg-xq-muted/60',
+                )
+            "
+        >
+            <span
+                v-if="options.prefix"
+                class="px-3 text-sm flex h-full items-center border-r border-xq-input bg-xq-muted text-xq-muted-foreground"
+            >
+                {{ options.prefix }}
+            </span>
+            <input
+                :id="id"
+                :name="path"
+                :value="text"
+                :type="inputType"
+                :inputmode="options.numeric ? 'decimal' : undefined"
+                :placeholder="node.placeholder ?? undefined"
+                :disabled="disabled"
+                :required="required"
+                :maxlength="options.maxLength ?? undefined"
+                :autocomplete="options.autocomplete ?? undefined"
+                :aria-invalid="error ? true : undefined"
+                :aria-describedby="describedBy"
+                :class="
+                    cn(
+                        'min-w-0 px-3 h-full flex-1 bg-transparent outline-none placeholder:text-xq-muted-foreground disabled:cursor-not-allowed',
+                        options.numeric && 'tabular-nums',
+                    )
+                "
+                @input="onInput"
+                @blur="onBlur"
+            />
+            <span
+                v-if="options.suffix"
+                class="px-3 text-sm flex h-full items-center border-l border-xq-input bg-xq-muted text-xq-muted-foreground"
+            >
+                {{ options.suffix }}
+            </span>
+        </div>
+    </XqFieldWrapper>
+</template>

package/resources/js/components/fields/XqTextareaField.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { useField } from '../../composables/useField';
+import type { SchemaNode } from '../../schema/types';
+import XqTextarea from '../../ui/XqTextarea.vue';
+import XqFieldWrapper from '../XqFieldWrapper.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const { path, value, error, describedBy, required, disabled, id, onBlur } = useField<string | null>(
+    props.node,
+);
+</script>
+
+<template>
+    <XqFieldWrapper :node="node" :id="id" :error="error" :required="required">
+        <XqTextarea
+            :id="id"
+            v-model="value"
+            :name="path"
+            :rows="node.props?.rows ?? 3"
+            :maxlength="node.props?.maxLength ?? undefined"
+            :placeholder="node.placeholder ?? undefined"
+            :disabled="disabled"
+            :aria-invalid="error ? true : undefined"
+            :aria-describedby="describedBy"
+            @blur="onBlur"
+        />
+    </XqFieldWrapper>
+</template>

package/resources/js/components/fields/XqToggleField.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { LoaderCircle } from 'lucide-vue-next';
+import { computed } from 'vue';
+import { useField } from '../../composables/useField';
+import type { SchemaNode } from '../../schema/types';
+import XqLabel from '../../ui/XqLabel.vue';
+import XqSwitch from '../../ui/XqSwitch.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const { value, error, loading, required, disabled, id } = useField<boolean>(props.node);
+const hasHint = computed(() => !!(props.node.props?.description || props.node.hint));
+const describedBy = computed(() =>
+    error.value ? `${id}-error` : hasHint.value ? `${id}-hint` : undefined,
+);
+</script>
+
+<template>
+    <div class="gap-2 grid" :data-xq-path="node.path" :aria-busy="loading || undefined">
+        <div class="gap-3 flex items-start">
+            <XqSwitch
+                :id="id"
+                v-model="value"
+                :disabled="disabled"
+                :aria-invalid="error ? true : undefined"
+                :aria-describedby="describedBy"
+            />
+            <div class="gap-1.5 grid">
+                <XqLabel :for="id" class="gap-0.5 leading-5 cursor-pointer">
+                    {{ node.label }}
+                    <span v-if="required" class="text-xq-destructive" aria-hidden="true">*</span>
+                    <span v-if="required" class="sr-only">(required)</span>
+                    <LoaderCircle
+                        v-if="loading"
+                        class="ml-1 size-3 motion-safe:animate-spin text-xq-muted-foreground"
+                        aria-hidden="true"
+                    />
+                </XqLabel>
+                <p v-if="hasHint" :id="`${id}-hint`" class="text-xs text-xq-muted-foreground">
+                    {{ node.props?.description ?? node.hint }}
+                </p>
+            </div>
+        </div>
+        <p v-if="error" :id="`${id}-error`" class="text-xs font-medium text-xq-destructive">
+            {{ error }}
+        </p>
+    </div>
+</template>

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

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { gridStyle } from '../../composables/layout';
+import type { SchemaNode } from '../../schema/types';
+import XqNode from '../XqNode.vue';
+
+defineProps<{ node: SchemaNode }>();
+</script>
+
+<template>
+    <fieldset class="px-4 pt-2 pb-4 rounded-xq-lg border border-xq-border">
+        <legend v-if="node.label" class="px-1.5 text-sm font-medium">{{ node.label }}</legend>
+        <div class="xq-grid mt-2" :style="gridStyle(node.props?.columns)">
+            <XqNode v-for="child in node.children ?? []" :key="child.key" :node="child" />
+        </div>
+    </fieldset>
+</template>

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

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+import { gridStyle } from '../../composables/layout';
+import type { SchemaNode } from '../../schema/types';
+import XqNode from '../XqNode.vue';
+
+defineProps<{ node: SchemaNode }>();
+</script>
+
+<template>
+    <div class="xq-grid" :style="gridStyle(node.props?.columns)">
+        <XqNode v-for="child in node.children ?? []" :key="child.key" :node="child" />
+    </div>
+</template>

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

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import { ChevronDown } from 'lucide-vue-next';
+import { computed, inject, provide, ref } from 'vue';
+import { HEADING_LEVEL } from '../../composables/context';
+import { gridStyle } from '../../composables/layout';
+import { cn } from '../../lib/utils';
+import type { SchemaNode } from '../../schema/types';
+import XqNode from '../XqNode.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const options = computed(() => props.node.props ?? {});
+const collapsed = ref<boolean>(!!props.node.props?.collapsed);
+const hasHeader = computed(() => !!(props.node.label || options.value.description));
+const headingLevel = inject(HEADING_LEVEL, 2);
+
+provide(HEADING_LEVEL, Math.min(headingLevel + 1, 6));
+</script>
+
+<template>
+    <section
+        class="shadow-xs rounded-xq-lg border border-xq-border bg-xq-card text-xq-card-foreground"
+    >
+        <header
+            v-if="hasHeader"
+            :class="
+                cn(
+                    'gap-4 px-5 py-4 flex items-start justify-between',
+                    !collapsed && 'border-b border-xq-border',
+                )
+            "
+        >
+            <div class="gap-1 grid">
+                <component :is="`h${headingLevel}`" v-if="node.label" class="text-sm font-semibold">
+                    {{ node.label }}
+                </component>
+                <p v-if="options.description" class="text-sm text-xq-muted-foreground">
+                    {{ options.description }}
+                </p>
+            </div>
+            <button
+                v-if="options.collapsible"
+                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'"
+                @click="collapsed = !collapsed"
+            >
+                <ChevronDown
+                    :class="
+                        cn(
+                            'size-4 transition-transform motion-reduce:transition-none',
+                            collapsed && '-rotate-90',
+                        )
+                    "
+                />
+            </button>
+        </header>
+        <div v-show="!collapsed" class="xq-grid p-5" :style="gridStyle(options.columns)">
+            <XqNode v-for="child in node.children ?? []" :key="child.key" :node="child" />
+        </div>
+    </section>
+</template>

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

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { useFormStore } from '../../composables/context';
+import { gridStyle } from '../../composables/layout';
+import { eachNode } from '../../core/patch';
+import type { SchemaNode } from '../../schema/types';
+import XqTabs from '../../ui/XqTabs.vue';
+import XqTabsContent from '../../ui/XqTabsContent.vue';
+import XqTabsList from '../../ui/XqTabsList.vue';
+import XqTabsTrigger from '../../ui/XqTabsTrigger.vue';
+import XqNode from '../XqNode.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const store = useFormStore();
+const tabs = computed(() => (props.node.children ?? []).filter((tab) => store.isVisible(tab)));
+const active = ref<string>(tabs.value[0]?.key ?? '');
+
+watch(tabs, (visible) => {
+    if (!visible.some((tab) => tab.key === active.value)) {
+        active.value = visible[0]?.key ?? '';
+    }
+});
+
+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;
+    }
+});
+</script>
+
+<template>
+    <XqTabs v-model="active">
+        <XqTabsList>
+            <XqTabsTrigger v-for="tab in tabs" :key="tab.key" :value="tab.key">
+                {{ tab.label }}
+                <span
+                    v-if="errorCount(tab)"
+                    class="size-4 font-semibold inline-flex items-center justify-center rounded-full bg-xq-destructive text-[0.65rem] text-xq-destructive-foreground"
+                >
+                    {{ errorCount(tab) }}
+                </span>
+            </XqTabsTrigger>
+        </XqTabsList>
+        <XqTabsContent v-for="tab in tabs" :key="tab.key" :value="tab.key">
+            <div class="xq-grid" :style="gridStyle(tab.props?.columns)">
+                <XqNode v-for="child in tab.children ?? []" :key="child.key" :node="child" />
+            </div>
+        </XqTabsContent>
+    </XqTabs>
+</template>

package/resources/js/composables/context.ts

@@ -0,0 +1,22 @@
+import { inject, provide } from 'vue';
+import type { InjectionKey } from 'vue';
+import type { FormStore } from '../core/store';
+
+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');
+
+export function provideFormStore(store: FormStore): void {
+    provide(FORM_STORE, store);
+}
+
+export function useFormStore(): FormStore {
+    const store = inject(FORM_STORE, null);
+
+    if (!store) {
+        throw new Error('[xelqun] useFormStore() must be used inside <XqForm>.');
+    }
+
+    return store;
+}

package/resources/js/composables/layout.ts

@@ -0,0 +1,55 @@
+import type { ColumnSpan } from '../schema/types';
+
+const BREAKPOINTS = ['default', 'sm', 'md', 'lg', 'xl'] as const;
+
+function suffix(breakpoint: string): string {
+    return breakpoint === 'default' ? '' : `-${breakpoint}`;
+}
+
+/**
+ * CSS variables for a responsive grid, read by the .xq-grid class.
+ */
+export function gridStyle(
+    columns: Partial<Record<string, number>> | null | undefined,
+): Record<string, string> {
+    const style: Record<string, string> = {};
+
+    for (const breakpoint of BREAKPOINTS) {
+        const count = columns?.[breakpoint];
+
+        if (count) {
+            style[`--xq-cols${suffix(breakpoint)}`] = String(count);
+        }
+    }
+
+    return style;
+}
+
+/**
+ * CSS variables for a cell's column span, read by the .xq-cell class.
+ * A plain number applies from the "md" breakpoint, where grids gain columns.
+ */
+export function spanStyle(span: ColumnSpan | undefined): Record<string, string> {
+    if (span === null || span === undefined) {
+        return {};
+    }
+
+    const spans =
+        typeof span === 'object'
+            ? span
+            : span === 'full'
+              ? { default: 'full' as const }
+              : { md: span };
+    const style: Record<string, string> = {};
+
+    for (const breakpoint of BREAKPOINTS) {
+        const value = spans[breakpoint];
+
+        if (value !== undefined) {
+            style[`--xq-span${suffix(breakpoint)}`] =
+                value === 'full' ? '1 / -1' : `span ${value} / span ${value}`;
+        }
+    }
+
+    return style;
+}

package/resources/js/composables/registry.ts

@@ -0,0 +1,25 @@
+import { defineAsyncComponent, inject } from 'vue';
+import type { Component, InjectionKey } from 'vue';
+
+export type ComponentLoader = () => Promise<Component | { default: Component }>;
+
+export type ComponentResolver = Component | ComponentLoader;
+
+export type ComponentRegistry = Map<string, Component>;
+
+export const REGISTRY: InjectionKey<ComponentRegistry> = Symbol('xelqun-registry');
+
+/**
+ * A zero-argument function is treated as a lazy loader, e.g. () => import('./Rating.vue').
+ */
+export function toComponent(resolver: ComponentResolver): Component {
+    if (typeof resolver === 'function' && resolver.length === 0 && !('render' in resolver)) {
+        return defineAsyncComponent(resolver as ComponentLoader);
+    }
+
+    return resolver as Component;
+}
+
+export function useRegistry(): ComponentRegistry | null {
+    return inject(REGISTRY, null);
+}

package/resources/js/composables/useField.ts

@@ -0,0 +1,41 @@
+import { computed } from 'vue';
+import type { SchemaNode } from '../schema/types';
+import { useFormStore } from './context';
+
+/**
+ * Everything a field component needs: a writable value bound to the form
+ * state, its error, and the evaluated required/disabled rules.
+ */
+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 error = computed(() => store.errors[path] ?? null);
+
+    const value = computed<T>({
+        get: () => store.get(path),
+        set: (next) => store.set(path, next, 'user'),
+    });
+
+    return {
+        store,
+        node,
+        path,
+        id,
+        value,
+        error,
+        /** 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;
+        }),
+        loading: computed(() => store.isLoading(node)),
+        required: computed(() => store.isRequired(node)),
+        disabled: computed(() => store.isDisabled(node) || store.processing.value),
+        onBlur: () => store.blur(path),
+    };
+}

package/resources/js/composables/useXqForm.ts

@@ -0,0 +1,16 @@
+import { onScopeDispose } from 'vue';
+import { createFormStore } from '../core/store';
+import type { FormStore, FormStoreOptions } from '../core/store';
+import type { FormSchema } from '../schema/types';
+
+/**
+ * Create a form store from the schema prop sent by the server.
+ * Pass the result to <XqForm :form="form">.
+ */
+export function useXqForm(schema: FormSchema, options: FormStoreOptions = {}): FormStore {
+    const store = createFormStore(schema, options);
+
+    onScopeDispose(() => store.dispose());
+
+    return store;
+}