@r2digisolutions/components 0.1.1

package/dist/utils/filterParams.d.ts

@@ -0,0 +1,30 @@
+import type { FilterValues } from './filterSchema.js';
+import { type AdvancedFilterClause, type AdvancedFilterGroup } from './advancedFilters.js';
+export type { AdvancedFilterClause, AdvancedFilterGroup, AdvancedFilterNode, AdvancedFilterRule, AdvancedFilterValue, FilterCombinator, FilterFieldDef, FilterFieldOption, FilterFieldType, FilterOperator, FilterValueKind } from './advancedFilters.js';
+export { OP_LABELS, DEFAULT_OPS, FILTER_OPERATORS, clausesToGroup, groupToClauses, emptyFilterGroup, emptyFilterRule, flattenRules, countRules, matchGroup, matchRuleValue, resolveValueKind, operatorsForField, formatRuleLabel, asFilterGroup } from './advancedFilters.js';
+/** Serializable catalog / ecommerce filter state (UI + URL). */
+export interface CatalogPriceRange {
+    min?: number;
+    max?: number;
+}
+export interface CatalogFilterState {
+    q: string;
+    /** @deprecated Prefer `values` (schema-driven bag) */
+    facets: Record<string, string[]>;
+    /** Advanced query tree (AND/OR groups + rules) */
+    advanced: AdvancedFilterGroup | AdvancedFilterClause[];
+    sort?: string;
+    page?: number;
+    /** @deprecated Prefer `values.price` as [min,max] */
+    price?: CatalogPriceRange;
+    /** Preferred: one bag for all filter fields */
+    values?: FilterValues;
+}
+export declare const EMPTY_FILTER_STATE: CatalogFilterState;
+/** Parse catalog filter state from a query string or URLSearchParams. */
+export declare function parseFilterParams(search: string | URLSearchParams): CatalogFilterState;
+/** Serialize catalog filter state to URLSearchParams (omit empty keys). */
+export declare function serializeFilterParams(state: CatalogFilterState): URLSearchParams;
+/** Convenience: state → `?q=...&f.brand=...` string (empty string when no params). */
+export declare function filterParamsToSearch(state: CatalogFilterState): string;
+export declare function createEmptyFilterState(partial?: Partial<CatalogFilterState>): CatalogFilterState;

package/dist/utils/filterParams.js

@@ -0,0 +1,113 @@
+import { parseFilterValues, serializeFilterValues } from './filterSchema.js';
+import { asFilterGroup, emptyFilterGroup, parseAdvancedGroup, serializeAdvancedGroup } from './advancedFilters.js';
+export { OP_LABELS, DEFAULT_OPS, FILTER_OPERATORS, clausesToGroup, groupToClauses, emptyFilterGroup, emptyFilterRule, flattenRules, countRules, matchGroup, matchRuleValue, resolveValueKind, operatorsForField, formatRuleLabel, asFilterGroup } from './advancedFilters.js';
+export const EMPTY_FILTER_STATE = {
+    q: '',
+    facets: {},
+    advanced: emptyFilterGroup(),
+    values: {}
+};
+function parsePrice(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const [minRaw, maxRaw] = raw.split('-');
+    const min = minRaw === '' || minRaw === undefined ? undefined : Number(minRaw);
+    const max = maxRaw === '' || maxRaw === undefined ? undefined : Number(maxRaw);
+    const range = {};
+    if (min !== undefined && !Number.isNaN(min))
+        range.min = min;
+    if (max !== undefined && !Number.isNaN(max))
+        range.max = max;
+    return range.min !== undefined || range.max !== undefined ? range : undefined;
+}
+function serializePrice(price) {
+    if (!price || (price.min === undefined && price.max === undefined))
+        return null;
+    const min = price.min ?? '';
+    const max = price.max ?? '';
+    return `${min}-${max}`;
+}
+/** Parse catalog filter state from a query string or URLSearchParams. */
+export function parseFilterParams(search) {
+    const params = typeof search === 'string'
+        ? new URLSearchParams(search.startsWith('?') ? search.slice(1) : search)
+        : search;
+    const facets = {};
+    for (const [key, value] of params.entries()) {
+        if (!key.startsWith('f.') || !value)
+            continue;
+        const facetId = key.slice(2);
+        facets[facetId] = value
+            .split(',')
+            .map((v) => decodeURIComponent(v.trim()))
+            .filter(Boolean);
+    }
+    const pageRaw = params.get('page');
+    const page = pageRaw ? Number(pageRaw) : undefined;
+    const price = parsePrice(params.get('price'));
+    const fromFacets = Object.fromEntries(Object.entries(facets).map(([k, v]) => [k, v]));
+    if (price?.min !== undefined || price?.max !== undefined) {
+        fromFacets.price = [price?.min ?? 0, price?.max ?? 0];
+    }
+    return {
+        q: params.get('q') ?? '',
+        facets,
+        advanced: parseAdvancedGroup(params.get('a')),
+        sort: params.get('sort') || undefined,
+        page: page !== undefined && !Number.isNaN(page) && page > 0 ? page : undefined,
+        price,
+        values: { ...fromFacets, ...parseFilterValues(params) }
+    };
+}
+/** Serialize catalog filter state to URLSearchParams (omit empty keys). */
+export function serializeFilterParams(state) {
+    const params = new URLSearchParams();
+    if (state.q.trim())
+        params.set('q', state.q.trim());
+    const advanced = serializeAdvancedGroup(asFilterGroup(state.advanced));
+    if (advanced)
+        params.set('a', advanced);
+    if (state.sort)
+        params.set('sort', state.sort);
+    if (state.page !== undefined && state.page > 1)
+        params.set('page', String(state.page));
+    const hasValues = state.values &&
+        Object.values(state.values).some((v) => v !== undefined &&
+            v !== null &&
+            v !== false &&
+            v !== '' &&
+            !(Array.isArray(v) && v.length === 0));
+    if (hasValues && state.values) {
+        const vParams = serializeFilterValues(state.values);
+        for (const [k, v] of vParams.entries())
+            params.set(k, v);
+    }
+    else {
+        for (const [facetId, values] of Object.entries(state.facets)) {
+            if (!values?.length)
+                continue;
+            params.set(`f.${facetId}`, values.map(encodeURIComponent).join(','));
+        }
+        const price = serializePrice(state.price);
+        if (price)
+            params.set('price', price);
+    }
+    return params;
+}
+/** Convenience: state → `?q=...&f.brand=...` string (empty string when no params). */
+export function filterParamsToSearch(state) {
+    const params = serializeFilterParams(state);
+    const s = params.toString();
+    return s ? `?${s}` : '';
+}
+export function createEmptyFilterState(partial) {
+    return {
+        q: partial?.q ?? '',
+        facets: { ...(partial?.facets ?? {}) },
+        advanced: asFilterGroup(partial?.advanced),
+        sort: partial?.sort,
+        page: partial?.page,
+        price: partial?.price ? { ...partial.price } : undefined,
+        values: { ...(partial?.values ?? {}) }
+    };
+}

package/dist/utils/filterSchema.d.ts

@@ -0,0 +1,44 @@
+/** Schema-driven filter builder types & helpers. */
+export type FilterControlType = 'checkbox' | 'radio' | 'range' | 'toggle' | 'rating' | 'select';
+export interface FilterOption {
+    id: string;
+    label: string;
+    count?: number;
+    disabled?: boolean;
+}
+export interface FilterFieldSchema {
+    id: string;
+    label: string;
+    type: FilterControlType;
+    /** Optional section / category heading for grouping fields */
+    category?: string;
+    options?: FilterOption[];
+    /** range */
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    /** checkbox default true; ignored for radio */
+    multiple?: boolean;
+    /** show-more limit for option lists */
+    limit?: number;
+    /** rating max stars */
+    maxRating?: number;
+}
+export type FilterValue = string | string[] | number | boolean | [number, number] | undefined;
+/** Single bag of values keyed by field id — one bind for everything. */
+export type FilterValues = Record<string, FilterValue>;
+export interface FilterCategoryGroup {
+    category: string | null;
+    fields: FilterFieldSchema[];
+}
+export declare function emptyFilterValues(schema?: FilterFieldSchema[]): FilterValues;
+export declare function groupFilterSchema(schema: FilterFieldSchema[]): FilterCategoryGroup[];
+export declare function isFilterValueActive(field: FilterFieldSchema, value: FilterValue): boolean;
+export declare function countActiveFilters(schema: FilterFieldSchema[], values: FilterValues): number;
+export declare function clearFilterValues(schema: FilterFieldSchema[], values?: FilterValues): FilterValues;
+/** Build schema from a plain JSON-like config (runtime-safe-ish). */
+export declare function parseFilterSchema(input: unknown): FilterFieldSchema[];
+/** Serialize filter values → compact query params (`v.brand=a,b`, `v.price=10~99`). */
+export declare function serializeFilterValues(values: FilterValues): URLSearchParams;
+export declare function parseFilterValues(search: string | URLSearchParams, schema?: FilterFieldSchema[]): FilterValues;

package/dist/utils/filterSchema.js

@@ -0,0 +1,192 @@
+/** Schema-driven filter builder types & helpers. */
+export function emptyFilterValues(schema = []) {
+    const values = {};
+    for (const field of schema) {
+        if (field.type === 'checkbox' || (field.type === 'select' && field.multiple !== false)) {
+            values[field.id] = [];
+        }
+        else if (field.type === 'radio' || field.type === 'select') {
+            values[field.id] = undefined;
+        }
+        else if (field.type === 'range') {
+            values[field.id] = undefined;
+        }
+        else if (field.type === 'toggle') {
+            values[field.id] = false;
+        }
+        else if (field.type === 'rating') {
+            values[field.id] = undefined;
+        }
+    }
+    return values;
+}
+export function groupFilterSchema(schema) {
+    const map = new Map();
+    for (const field of schema) {
+        const key = field.category?.trim() || null;
+        const list = map.get(key) ?? [];
+        list.push(field);
+        map.set(key, list);
+    }
+    return [...map.entries()].map(([category, fields]) => ({ category, fields }));
+}
+export function isFilterValueActive(field, value) {
+    if (value === undefined || value === null || value === false || value === '')
+        return false;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return false;
+        if (field.type === 'range' &&
+            value.length === 2 &&
+            typeof value[0] === 'number' &&
+            typeof value[1] === 'number') {
+            const min = field.min ?? 0;
+            const max = field.max ?? 100;
+            return value[0] > min || value[1] < max;
+        }
+        return true;
+    }
+    return true;
+}
+export function countActiveFilters(schema, values) {
+    return schema.reduce((n, field) => n + (isFilterValueActive(field, values[field.id]) ? 1 : 0), 0);
+}
+export function clearFilterValues(schema, values = {}) {
+    const next = { ...values };
+    for (const field of schema) {
+        if (field.type === 'checkbox' || (field.type === 'select' && field.multiple !== false)) {
+            next[field.id] = [];
+        }
+        else if (field.type === 'toggle') {
+            next[field.id] = false;
+        }
+        else {
+            next[field.id] = undefined;
+        }
+    }
+    return next;
+}
+/** Build schema from a plain JSON-like config (runtime-safe-ish). */
+export function parseFilterSchema(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input
+        .map((raw) => {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const o = raw;
+        if (typeof o.id !== 'string' || typeof o.label !== 'string' || typeof o.type !== 'string') {
+            return null;
+        }
+        const type = o.type;
+        const field = {
+            id: o.id,
+            label: o.label,
+            type,
+            category: typeof o.category === 'string' ? o.category : undefined,
+            min: typeof o.min === 'number' ? o.min : undefined,
+            max: typeof o.max === 'number' ? o.max : undefined,
+            step: typeof o.step === 'number' ? o.step : undefined,
+            unit: typeof o.unit === 'string' ? o.unit : undefined,
+            multiple: typeof o.multiple === 'boolean' ? o.multiple : undefined,
+            limit: typeof o.limit === 'number' ? o.limit : undefined,
+            maxRating: typeof o.maxRating === 'number' ? o.maxRating : undefined
+        };
+        if (Array.isArray(o.options)) {
+            const options = [];
+            for (const opt of o.options) {
+                if (!opt || typeof opt !== 'object')
+                    continue;
+                const x = opt;
+                const id = typeof x.id === 'string' ? x.id : typeof x.value === 'string' ? x.value : null;
+                const label = typeof x.label === 'string' ? x.label : id;
+                if (!id || !label)
+                    continue;
+                options.push({
+                    id,
+                    label,
+                    count: typeof x.count === 'number' ? x.count : undefined,
+                    disabled: Boolean(x.disabled)
+                });
+            }
+            field.options = options;
+        }
+        return field;
+    })
+        .filter((f) => f !== null);
+}
+/** Serialize filter values → compact query params (`v.brand=a,b`, `v.price=10~99`). */
+export function serializeFilterValues(values) {
+    const params = new URLSearchParams();
+    for (const [id, value] of Object.entries(values)) {
+        if (value === undefined || value === null || value === false || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                continue;
+            if (value.length === 2 && typeof value[0] === 'number' && typeof value[1] === 'number') {
+                params.set(`v.${id}`, `${value[0]}~${value[1]}`);
+            }
+            else {
+                params.set(`v.${id}`, value.map(encodeURIComponent).join(','));
+            }
+        }
+        else if (typeof value === 'boolean') {
+            if (value)
+                params.set(`v.${id}`, '1');
+        }
+        else {
+            params.set(`v.${id}`, encodeURIComponent(String(value)));
+        }
+    }
+    return params;
+}
+export function parseFilterValues(search, schema = []) {
+    const params = typeof search === 'string'
+        ? new URLSearchParams(search.startsWith('?') ? search.slice(1) : search)
+        : search;
+    const byId = new Map(schema.map((f) => [f.id, f]));
+    const values = emptyFilterValues(schema);
+    for (const [key, raw] of params.entries()) {
+        if (!key.startsWith('v.') || !raw)
+            continue;
+        const id = key.slice(2);
+        const field = byId.get(id);
+        if (raw.includes('~') && (!field || field.type === 'range')) {
+            const [a, b] = raw.split('~');
+            const min = Number(a);
+            const max = Number(b);
+            if (!Number.isNaN(min) && !Number.isNaN(max))
+                values[id] = [min, max];
+            continue;
+        }
+        if (field?.type === 'toggle') {
+            values[id] = raw === '1' || raw === 'true';
+            continue;
+        }
+        if (field?.type === 'rating' || field?.type === 'radio' || field?.type === 'select') {
+            if (field.multiple) {
+                values[id] = raw.split(',').map((v) => decodeURIComponent(v));
+            }
+            else if (field.type === 'rating') {
+                const n = Number(raw);
+                values[id] = Number.isNaN(n) ? undefined : n;
+            }
+            else {
+                values[id] = decodeURIComponent(raw);
+            }
+            continue;
+        }
+        // checkbox / default multi
+        if (raw.includes(',')) {
+            values[id] = raw.split(',').map((v) => decodeURIComponent(v));
+        }
+        else if (field?.type === 'checkbox' || !field) {
+            values[id] = [decodeURIComponent(raw)];
+        }
+        else {
+            values[id] = decodeURIComponent(raw);
+        }
+    }
+    return values;
+}

package/dist/utils/formContext.d.ts

@@ -0,0 +1,104 @@
+import type { RemoteForm, RemoteFormInput, RemoteFormIssue } from '@sveltejs/kit';
+export type { RemoteForm, RemoteFormInput, RemoteFormIssue };
+export declare const FORM_CONTEXT_KEY = "r2-form";
+export type FormErrors = Record<string, string>;
+export type FormDataValues = Record<string, unknown>;
+export type FormFieldStatus = 'default' | 'error' | 'success' | 'warning';
+/**
+ * Build a dotted path for nested form errors / remote issues
+ * (e.g. `items.0.email`).
+ */
+export declare function fieldPath(...segments: Array<string | number>): string;
+/**
+ * Spreadable remote form binding: a Kit `RemoteForm` or the object returned by `.enhance(...)`.
+ *
+ * @example
+ * ```ts
+ * remote={createPost}
+ * remote={createPost.enhance(async (form) => { ... })}
+ * ```
+ */
+export type FormRemote<Input extends RemoteFormInput | void = RemoteFormInput, Output = unknown> = RemoteForm<Input, Output> | ReturnType<RemoteForm<Input, Output>['enhance']>;
+/** @deprecated Use `FormRemote` (or `RemoteForm` from `@sveltejs/kit`) */
+export type RemoteFormSpread<Input extends RemoteFormInput | void = RemoteFormInput, Output = unknown> = FormRemote<Input, Output>;
+export interface FormContext<TData extends FormDataValues = FormDataValues, TResult = unknown> {
+    /** Current field values (bindable from `<Form bind:data>`) */
+    data: TData;
+    errors: FormErrors;
+    submitted: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** Last result from a remote form / submit handler, if any */
+    result: TResult | undefined;
+    setError: (name: string, message: string) => void;
+    clearError: (name: string) => void;
+    clearErrors: () => void;
+    setData: <K extends keyof TData & string>(name: K, value: TData[K]) => void;
+    getError: (name: string) => string | undefined;
+    getData: <K extends keyof TData & string>(name: K) => TData[K] | undefined;
+}
+/**
+ * Access the nearest `<Form>` context from a child component.
+ * Returns `null` when used outside a Form.
+ *
+ * @example
+ * ```ts
+ * const form = getFormContext<{ email: string }, { ok: boolean }>();
+ * form?.getData('email');
+ * form?.result?.ok;
+ * ```
+ */
+export declare function getFormContext<TData extends FormDataValues = FormDataValues, TResult = unknown>(): FormContext<TData, TResult> | null;
+/**
+ * Map Kit `RemoteFormIssue[]` → `{ field: message }` for `<Form bind:errors>`.
+ *
+ * @example
+ * ```ts
+ * errors = remoteIssuesToErrors(createPost.fields.allIssues());
+ * ```
+ */
+export declare function remoteIssuesToErrors(issues: RemoteFormIssue[] | null | undefined): FormErrors;
+/** True when the spread value is a full `RemoteForm` (has `fields` / `pending`). */
+export declare function isRemoteForm<Input extends RemoteFormInput | void = RemoteFormInput, Output = unknown>(remote: FormRemote<Input, Output> | null | undefined): remote is RemoteForm<Input, Output>;
+/**
+ * Shared resolution for form-aware controls (error / status / disabled).
+ */
+export declare function resolveFormFieldState(options: {
+    name?: string;
+    errorMessage?: string;
+    helperText?: string;
+    status?: FormFieldStatus;
+    disabled?: boolean;
+    form?: FormContext | null;
+}): {
+    error?: string;
+    status: FormFieldStatus;
+    helperText?: string;
+    disabled: boolean;
+};
+/**
+ * Push context → local inside an `$effect` that tracks `form.data[name]`.
+ * Local value is read under `untrack` so user input is not overwritten when
+ * the local state updates before `setData` lands.
+ *
+ * @example
+ * ```ts
+ * $effect(() => {
+ *   if (!bindData || !name || !form) return;
+ *   applyFormDataSync({
+ *     fromCtx: form.data[name],
+ *     getLocal: () => value,
+ *     setLocal: (v) => { value = v; },
+ *     map: (raw) => (raw !== undefined ? String(raw) : undefined)
+ *   });
+ * });
+ * ```
+ */
+export declare function applyFormDataSync<T>(options: {
+    fromCtx: unknown;
+    getLocal: () => T;
+    setLocal: (next: T) => void;
+    map: (raw: unknown) => T | undefined;
+    equals?: (a: T, b: T) => boolean;
+}): void;
+export declare function sameStringArray(a: string[], b: string[]): boolean;

package/dist/utils/formContext.js

@@ -0,0 +1,89 @@
+import { getContext, untrack } from 'svelte';
+export const FORM_CONTEXT_KEY = 'r2-form';
+/**
+ * Build a dotted path for nested form errors / remote issues
+ * (e.g. `items.0.email`).
+ */
+export function fieldPath(...segments) {
+    return segments.map(String).filter((s) => s.length > 0).join('.');
+}
+/**
+ * Access the nearest `<Form>` context from a child component.
+ * Returns `null` when used outside a Form.
+ *
+ * @example
+ * ```ts
+ * const form = getFormContext<{ email: string }, { ok: boolean }>();
+ * form?.getData('email');
+ * form?.result?.ok;
+ * ```
+ */
+export function getFormContext() {
+    return getContext(FORM_CONTEXT_KEY) ?? null;
+}
+/**
+ * Map Kit `RemoteFormIssue[]` → `{ field: message }` for `<Form bind:errors>`.
+ *
+ * @example
+ * ```ts
+ * errors = remoteIssuesToErrors(createPost.fields.allIssues());
+ * ```
+ */
+export function remoteIssuesToErrors(issues) {
+    if (!issues?.length)
+        return {};
+    const next = {};
+    for (const issue of issues) {
+        const key = issue.path.map(String).filter(Boolean).join('.') || '_form';
+        if (!next[key])
+            next[key] = issue.message;
+    }
+    return next;
+}
+/** True when the spread value is a full `RemoteForm` (has `fields` / `pending`). */
+export function isRemoteForm(remote) {
+    return !!remote && 'fields' in remote && typeof remote.fields === 'object';
+}
+/**
+ * Shared resolution for form-aware controls (error / status / disabled).
+ */
+export function resolveFormFieldState(options) {
+    const { name, errorMessage, helperText, status = 'default', disabled = false, form = null } = options;
+    const error = errorMessage ?? (name && form ? form.getError(name) : undefined);
+    return {
+        error,
+        status: error ? 'error' : status,
+        helperText: error ?? helperText,
+        disabled: disabled || Boolean(form?.loading) || Boolean(form?.disabled)
+    };
+}
+/**
+ * Push context → local inside an `$effect` that tracks `form.data[name]`.
+ * Local value is read under `untrack` so user input is not overwritten when
+ * the local state updates before `setData` lands.
+ *
+ * @example
+ * ```ts
+ * $effect(() => {
+ *   if (!bindData || !name || !form) return;
+ *   applyFormDataSync({
+ *     fromCtx: form.data[name],
+ *     getLocal: () => value,
+ *     setLocal: (v) => { value = v; },
+ *     map: (raw) => (raw !== undefined ? String(raw) : undefined)
+ *   });
+ * });
+ * ```
+ */
+export function applyFormDataSync(options) {
+    const { fromCtx, getLocal, setLocal, map, equals = Object.is } = options;
+    const next = map(fromCtx);
+    if (next === undefined)
+        return;
+    if (equals(untrack(getLocal), next))
+        return;
+    setLocal(next);
+}
+export function sameStringArray(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}

package/dist/utils/formValidate.d.ts

@@ -0,0 +1,37 @@
+import { type MessageParams, type UiMessages } from './i18n.js';
+import type { FormDataValues, FormErrors } from './formContext.js';
+export type BuiltinRule = 'required' | 'email' | 'url' | `minLength:${number}` | `maxLength:${number}` | `min:${number}` | `max:${number}`;
+export type CustomRule<T extends FormDataValues> = (value: unknown, data: T) => string | undefined | null | false;
+export type PatternRule = {
+    pattern: RegExp;
+    message?: string;
+};
+export type FieldRule<T extends FormDataValues = FormDataValues> = BuiltinRule | PatternRule | CustomRule<T>;
+export type FormRules<T extends FormDataValues = FormDataValues> = {
+    [K in keyof T]?: FieldRule<T> | FieldRule<T>[];
+};
+export interface ValidateOptions {
+    /** Locale for built-in messages (`es`, `en`, …) */
+    locale?: string;
+    /** Override validation copy */
+    messages?: Partial<UiMessages>;
+    /** Translate helper (e.g. `i18n.t`) */
+    t?: (key: keyof UiMessages, params?: MessageParams) => string;
+}
+/**
+ * Declarative validation → `FormErrors` for `<Form bind:errors>`.
+ *
+ * @example
+ * ```ts
+ * errors = validateForm(data, {
+ *   email: ['required', 'email'],
+ *   password: ['required', 'minLength:8'],
+ *   age: ['min:18']
+ * }, { locale: 'es' });
+ * ```
+ */
+export declare function validateForm<T extends FormDataValues>(data: T, rules: FormRules<T>, options?: ValidateOptions): FormErrors;
+/** True when `current` differs from `initial` (shallow JSON compare). */
+export declare function isFormDirty<T>(current: T, initial: T): boolean;
+/** First error message, or `undefined` when valid. */
+export declare function firstFormError(errors: FormErrors): string | undefined;