@xelqun/forms 0.1.1 → 0.2.0

package/resources/js/core/translate.ts

@@ -0,0 +1,17 @@
+export type Replacements = Record<string, string | number>;
+
+/**
+ * Text is written in English and that is its key, so a missing line reads fine.
+ * Fill :placeholders the way Laravel does.
+ */
+export function translate(
+    messages: Record<string, string> | undefined,
+    text: string,
+    replacements: Replacements = {},
+): string {
+    return Object.entries(replacements).reduce(
+        // A function, so a "$&" in a file name isn't read as a pattern.
+        (line, [name, value]) => line.replaceAll(`:${name}`, () => String(value)),
+        messages?.[text] ?? text,
+    );
+}

package/resources/js/core/validation.ts

@@ -0,0 +1,126 @@
+import type { ClientRule, FieldValidation } from '../schema/types';
+import { isPlainObject } from './values';
+
+/**
+ * Laravel's rules, for the browser. Each one may let through what the server
+ * rejects, and must never reject what the server accepts: the server has the
+ * last word, and a wrong "no" here is a form nobody can submit. Keep
+ * tests/Fixtures/conformance/validation.json passing on both sides.
+ */
+
+/** PHP's trim(). JavaScript's also takes spaces PHP treats as text. */
+function phpTrim(text: string): string {
+    const spaces = ' \t\n\r\0\x0B';
+    let start = 0;
+    let end = text.length;
+
+    while (start < end && spaces.includes(text[start])) {
+        start++;
+    }
+
+    while (end > start && spaces.includes(text[end - 1])) {
+        end--;
+    }
+
+    return text.slice(start, end);
+}
+
+const length = (text: string) => Array.from(text).length;
+
+function isBlank(value: unknown): boolean {
+    if (value === null || value === undefined) {
+        return true;
+    }
+
+    if (typeof value === 'string') {
+        return phpTrim(value) === '';
+    }
+
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+
+    return isPlainObject(value) && Object.keys(value).length === 0;
+}
+
+function isNumeric(text: string): boolean {
+    return /^[ \t\n\r\v\f]*[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?[ \t\n\r\v\f]*$/.test(text);
+}
+
+/**
+ * An app may or may not trim strings before validating, so a length only fails
+ * if it fails either way: the raw text for a minimum, the trimmed text for a maximum.
+ */
+function passesString(rule: ClientRule, text: string): boolean {
+    const longest = length(text);
+    const shortest = length(phpTrim(text));
+    const limit = rule.value ?? 0;
+
+    return rule.rule === 'min'
+        ? longest >= limit
+        : rule.rule === 'max'
+          ? shortest <= limit
+          : shortest <= limit && limit <= longest;
+}
+
+function passes(rule: ClientRule, value: unknown): boolean {
+    const text = String(value);
+
+    switch (rule.rule) {
+        case 'accepted':
+            return [true, 1, 'yes', 'on', '1', 'true'].includes(value as never);
+        case 'email':
+            // Anything else an address can look like is Laravel's call: quotes and spaces are valid.
+            return /.@./s.test(text);
+        case 'numeric':
+            return isNumeric(text);
+        case 'integer':
+            return /^[ \t\n\r\v\f]*[+-]?\d+[ \t\n\r\v\f]*$/.test(text);
+        case 'size':
+            return passesString(rule, text);
+        case 'min':
+        case 'max':
+            if (rule.type === 'string') {
+                return passesString(rule, text);
+            }
+
+            if (!isNumeric(text)) {
+                return true;
+            }
+
+            return rule.rule === 'min'
+                ? Number(text) >= (rule.value ?? 0)
+                : Number(text) <= (rule.value ?? 0);
+        default:
+            return true;
+    }
+}
+
+/**
+ * The message of the first rule this value breaks, in the order the server
+ * checks them, or null if none.
+ */
+export function firstFailure(
+    validation: FieldValidation,
+    value: unknown,
+    required: boolean,
+): string | null {
+    for (const rule of validation.rules) {
+        const isRequiredRule = rule.rule === 'required' || rule.rule === 'accepted';
+
+        if (isRequiredRule) {
+            if (required && (rule.rule === 'accepted' ? !passes(rule, value) : isBlank(value))) {
+                return rule.message;
+            }
+
+            continue;
+        }
+
+        // Laravel skips other rules on an empty value.
+        if (!isBlank(value) && !passes(rule, value)) {
+            return rule.message;
+        }
+    }
+
+    return null;
+}

package/resources/js/index.ts

@@ -1,5 +1,5 @@
 export { createXelqunForms } from './plugin';
-export type { XelqunFormsOptions } from './plugin';
+export type { XelqunFormsOptions, XelqunPlugin, XelqunPluginContext } from './plugin';
 
 export { default as XqForm } from './components/XqForm.vue';
 export { default as XqNode } from './components/XqNode.vue';
@@ -8,13 +8,14 @@ export { createRegistry, defaultComponents } from './components/defaults';
 
 export { useXqForm } from './composables/useXqForm';
 export { useField } from './composables/useField';
-export { useFormStore } from './composables/context';
+export { useFormStore, useTranslator } from './composables/context';
 export { gridStyle, spanStyle } from './composables/layout';
-export type { ComponentResolver } from './composables/registry';
+export type { ComponentRegistry, ComponentResolver } from './composables/registry';
 
 export { createFormStore, defaultLiveConfig } from './core/store';
 export type { FormStore, FormStoreOptions, SubmitOptions } from './core/store';
 export type { RequestKind, RequestLogEntry } from './core/log';
+export { HttpError } from './core/http';
 export { evaluateCondition } from './core/conditions';
 export { evaluateExpression } from './core/expressions';
 export { getPath, overlaps } from './core/paths';

package/resources/js/lib/utils.ts

@@ -6,6 +6,21 @@ export function cn(...inputs: ClassValue[]): string {
     return twMerge(clsx(inputs));
 }
 
+/**
+ * Keep keyboard users in place: focus the first of these that can take it.
+ */
+export function focusFirstEnabled(container: HTMLElement | null, selectors: string[]): void {
+    for (const selector of selectors) {
+        const control = container?.querySelector<HTMLButtonElement>(selector);
+
+        if (control && !control.disabled) {
+            control.focus();
+
+            return;
+        }
+    }
+}
+
 export function formatBytes(bytes: number | null | undefined): string {
     if (!bytes) {
         return '';

package/resources/js/plugin.ts

@@ -1,17 +1,114 @@
-import type { Plugin } from 'vue';
-import { createRegistry } from './components/defaults';
-import { REGISTRY } from './composables/registry';
-import type { ComponentResolver } from './composables/registry';
+import type { App, Component, Plugin } from 'vue';
+import { createRegistry, defaultComponents } from './components/defaults';
+import { REGISTRY, toComponent } from './composables/registry';
+import type { ComponentRegistry, ComponentResolver } from './composables/registry';
+import { registerIcons } from './ui/icons';
+
+export interface XelqunPluginContext {
+    app: App;
+}
+
+/**
+ * The browser half of a plugin. Give it a function that returns this, so the
+ * host writes `plugins: [ratingPlugin()]` and options have somewhere to go.
+ */
+export interface XelqunPlugin {
+    id: string;
+    /** Renderers keyed by vendor-prefixed schema type, e.g. { 'acme/rating': () => import('./Rating.vue') }. */
+    components?: Record<string, ComponentResolver>;
+    /** Built-in types this plugin takes over on purpose. Another plugin's type is always a collision. */
+    replaces?: string[];
+    /** Icons PHP can name, as { name: component }. */
+    icons?: Record<string, Component>;
+    /** Runs once, after every plugin has registered its components. */
+    setup?: (context: XelqunPluginContext) => void;
+}
 
 export interface XelqunFormsOptions {
-    /** Extra or replacement renderers keyed by schema type, e.g. { rating: () => import('./Rating.vue') }. */
+    plugins?: XelqunPlugin[];
+    /** The app's own renderers, keyed by schema type. These win over plugins and built-ins. */
     components?: Record<string, ComponentResolver>;
+    /** Icons PHP can name, as { name: component }, on top of the built-in set. */
+    icons?: Record<string, Component>;
+}
+
+const VENDOR_PREFIXED_TYPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
+
+const BUILT_IN = 'built-in';
+
+/**
+ * Add each plugin's components to the registry. A collision is a bug in the app,
+ * so it throws in development. In production the page should still work: the
+ * error is logged and the type that was registered first stays.
+ */
+export function registerPlugins(
+    registry: ComponentRegistry,
+    plugins: XelqunPlugin[],
+    strict: boolean,
+): void {
+    const owners = new Map(Object.keys(defaultComponents()).map((type) => [type, BUILT_IN]));
+    const ids = new Set<string>();
+
+    const refuse = (message: string): void => {
+        if (strict) {
+            throw new Error(`[xelqun] ${message}`);
+        }
+
+        console.error(`[xelqun] ${message}`);
+    };
+
+    for (const plugin of plugins) {
+        if (ids.has(plugin.id)) {
+            refuse(`The plugin "${plugin.id}" is registered twice.`);
+
+            continue;
+        }
+
+        ids.add(plugin.id);
+
+        for (const [type, resolver] of Object.entries(plugin.components ?? {})) {
+            const owner = owners.get(type);
+            const isBuiltIn = owner === BUILT_IN;
+            const mayReplace = isBuiltIn && (plugin.replaces?.includes(type) ?? false);
+
+            if (owner && !isBuiltIn) {
+                refuse(
+                    `The plugins "${owner}" and "${plugin.id}" both register the type "${type}".`,
+                );
+
+                continue;
+            }
+
+            if (!VENDOR_PREFIXED_TYPE.test(type) && !mayReplace) {
+                refuse(
+                    `The plugin "${plugin.id}" registers the type "${type}". Plugin types need a vendor prefix such as "acme/rating". Names without one are reserved for built-in fields. To replace a built-in on purpose, list it in "replaces".`,
+                );
+
+                continue;
+            }
+
+            registry.set(type, toComponent(resolver));
+            owners.set(type, plugin.id);
+        }
+    }
 }
 
 export function createXelqunForms(options: XelqunFormsOptions = {}): Plugin {
     return {
         install(app) {
-            app.provide(REGISTRY, createRegistry(options.components));
+            const plugins = options.plugins ?? [];
+            const registry = createRegistry();
+
+            registerPlugins(registry, plugins, import.meta.env?.DEV ?? false);
+            plugins.forEach((plugin) => registerIcons(plugin.icons ?? {}));
+            registerIcons(options.icons ?? {});
+
+            for (const [type, resolver] of Object.entries(options.components ?? {})) {
+                registry.set(type, toComponent(resolver));
+            }
+
+            plugins.forEach((plugin) => plugin.setup?.({ app }));
+            app.provide(REGISTRY, registry);
         },
     };
 }

package/resources/js/schema/types.ts

@@ -13,6 +13,14 @@ export type ConditionNode =
       }
     | { op: 'filled' | 'blank'; path: string };
 
+export interface ConditionalText {
+    when: ConditionNode;
+    text: string;
+    otherwise: string | null;
+}
+
+export type TextKey = 'label' | 'hint' | 'placeholder';
+
 export type ExpressionNode =
     | { lit: unknown }
     | { ref: string }
@@ -40,23 +48,81 @@ export interface SchemaNode {
     placeholder?: string | null;
     required?: boolean;
     disabled?: boolean;
+    /** The server ignores this field's value. Text controls stay readable, others render disabled. */
+    readOnly?: boolean;
+    autofocus?: boolean;
+    hiddenLabel?: boolean;
+    inlineLabel?: boolean;
+    extraAttributes?: Record<string, unknown>;
     rules?: {
         visible?: ConditionNode | null;
         required?: ConditionNode | null;
         disabled?: ConditionNode | null;
+        text?: Partial<Record<TextKey, ConditionalText>>;
     };
     computed?: { src: string; ast: ExpressionNode } | null;
     live?: LiveConfig | null;
+    /** Set by fields with rows. They need props.template, rowPlaceholder, rows and newRow. */
+    containsRows?: boolean;
+    /** Set by fields that hold a file, which a copied row can't share. */
+    acceptsUploads?: boolean;
     span?: ColumnSpan;
+    /** False keeps a child of a Flex at its own width. */
+    grow?: boolean;
+    /** Rules the browser can check, on forms with frontendValidation(). */
+    validation?: FieldValidation | null;
+    /** The place around its field, or in its repeater row's header, this child renders in. */
+    slot?: FieldSlot | 'itemAction';
     props?: Record<string, any>;
     children?: SchemaNode[];
     deps?: string[];
 }
 
+/** One kind of row in a builder. */
+export interface BlockOption {
+    name: string;
+    label: string;
+    icon: string | null;
+    group: string | null;
+    maxItems: number | null;
+    template: SchemaNode[];
+    newRow: Record<string, unknown>;
+}
+
+export interface ClientRule {
+    rule: 'required' | 'accepted' | 'email' | 'numeric' | 'integer' | 'min' | 'max' | 'size';
+    type?: 'string' | 'numeric';
+    value?: number;
+    message: string;
+}
+
+export interface FieldValidation {
+    attribute: string;
+    rules: ClientRule[];
+}
+
+export type FieldSlot =
+    | 'aboveLabel'
+    | 'beforeLabel'
+    | 'afterLabel'
+    | 'belowLabel'
+    | 'aboveContent'
+    | 'beforeContent'
+    | 'afterContent'
+    | 'belowContent'
+    | 'aboveErrorMessage'
+    | 'belowErrorMessage'
+    | 'prefixAction'
+    | 'suffixAction'
+    | 'optionAction'
+    | 'markdownPreview';
+
 export interface FormEndpoints {
     update: string;
     upload: string;
     search: string;
+    validate: string;
+    action: string;
 }
 
 export interface FormSchema {
@@ -65,6 +131,10 @@ export interface FormSchema {
     id: string;
     token: string | null;
     endpoints: FormEndpoints;
+    locale?: string;
+    /** Text in this locale, by its English original. Anything missing stays English. */
+    messages?: Record<string, string>;
+    unsavedChangesAlert?: boolean;
     state: { data: Record<string, any> };
     components: SchemaNode[];
 }
@@ -77,6 +147,22 @@ export interface UpdateRequest {
     deps: Record<string, string[]>;
 }
 
+export interface ValidateRequest {
+    token: string;
+    step: string;
+    state: { data: Record<string, any> };
+    deps: Record<string, string[]>;
+}
+
+export interface ActionRequest {
+    token: string;
+    action: string;
+    phase: 'mount' | 'run';
+    state: { data: Record<string, any> };
+    data?: Record<string, any>;
+    deps: Record<string, string[]>;
+}
+
 export interface UpdatePatch {
     $xq: number;
     seq: number;
@@ -85,10 +171,26 @@ export interface UpdatePatch {
     errors: Record<string, string | string[]>;
 }
 
+export interface ActionResult extends UpdatePatch {
+    result?: unknown;
+}
+
 export interface SelectOption {
     value: string | number;
     label: string;
     description?: string | null;
+    disabled?: boolean;
+    /** The group this option is listed under. */
+    group?: string;
+}
+
+/** Text a select shows in place of its defaults. */
+export interface SelectMessages {
+    loading?: string;
+    noOptions?: string;
+    noResults?: string;
+    prompt?: string;
+    searching?: string;
 }
 
 export interface UploadResult {

package/resources/js/testing.ts

@@ -0,0 +1,50 @@
+import type { FormSchema, SchemaNode } from './schema/types';
+
+/**
+ * Hand-built schema for testing a renderer without a server, from
+ * '@xelqun/forms/testing'. Pass it to XqForm in a mounted test.
+ */
+export function fieldNode(
+    path: string,
+    type = 'text-input',
+    extra: Partial<SchemaNode> = {},
+): SchemaNode {
+    return {
+        key: path,
+        type,
+        hidden: false,
+        path,
+        label: path.split('.').pop(),
+        required: false,
+        disabled: false,
+        rules: { visible: null, required: null, disabled: null },
+        computed: null,
+        live: null,
+        props: {},
+        children: [],
+        deps: [],
+        ...extra,
+    };
+}
+
+export function formSchema(
+    components: SchemaNode[],
+    data: Record<string, any> = {},
+    token: string | null = 'token',
+): FormSchema {
+    return {
+        $xq: 1,
+        pkg: '0.1.0',
+        id: 'test-form',
+        token,
+        endpoints: {
+            update: '/_xelqun/forms/update',
+            upload: '/_xelqun/forms/upload',
+            search: '/_xelqun/forms/search',
+            validate: '/_xelqun/forms/validate',
+            action: '/_xelqun/forms/action',
+        },
+        state: { data },
+        components,
+    };
+}

package/resources/js/ui/XqCalendar.vue

@@ -22,6 +22,8 @@ const props = defineProps<{
     minValue?: DateValue;
     maxValue?: DateValue;
     placeholder?: DateValue;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    locale?: string;
     class?: HTMLAttributes['class'];
 }>();
 const model = defineModel<DateValue | undefined>();
@@ -37,6 +39,8 @@ const navClass =
         :min-value="minValue"
         :max-value="maxValue"
         :placeholder="placeholder"
+        :locale="locale"
+        :is-date-unavailable="isDateUnavailable"
         fixed-weeks
         weekday-format="short"
         data-slot="xq-calendar"