svelora 2.1.0

package/dist/Form/form.variants.js

@@ -0,0 +1,17 @@
+import { tv } from 'tailwind-variants';
+/**
+ * Form component variants.
+ *
+ * The Form component renders a near-styleless `<form>` (or `<div>` for nested forms) —
+ * matching Nuxt UI v4's minimal form theme. This exists primarily so users can inject
+ * shared form spacing via `defineConfig({ form: { slots: { root: 'space-y-4' } } })`.
+ */
+export const formVariants = tv({
+    slots: {
+        root: ''
+    }
+});
+export const formDefaults = {
+    defaultVariants: {},
+    slots: {}
+};

package/dist/Form/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Form } from './Form.svelte';
+export { getFormContext } from './form.context.svelte.js';
+export type { FormApi, FormData, FormError, FormErrorEvent, FormErrorWithId, FormInputEvents, FormProps, FormSchema, FormSubmitEvent, FormValidateOpts, InferInput, InferOutput, JoiSchema, StandardSchemaV1 } from './form.types.js';
+export { FormValidationException } from './form.types.js';

package/dist/Form/index.js

@@ -0,0 +1,6 @@
+export { default as Form } from './Form.svelte';
+// Exposed so users can build custom input components that integrate with a parent Form
+// (read errors, emit blur/input/change/focus events). Internal implementation details
+// like FormContext, validateSchema, getAtPath, etc. are intentionally not re-exported.
+export { getFormContext } from './form.context.svelte.js';
+export { FormValidationException } from './form.types.js';

package/dist/Form/validate-schema.d.ts

@@ -0,0 +1,13 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FormError, FormSchema, JoiSchema } from './form.types.js';
+export declare function isStandardSchema(schema: unknown): schema is StandardSchemaV1;
+export declare function isJoiSchema(schema: unknown): schema is JoiSchema;
+export interface ValidateResult<T = unknown> {
+    errors: FormError[] | null;
+    value: T | null;
+}
+export declare function validateStandardSchema<T>(state: unknown, schema: StandardSchemaV1<unknown, T>): Promise<ValidateResult<T>>;
+export declare function validateJoiSchema<T>(state: unknown, schema: JoiSchema): Promise<ValidateResult<T>>;
+export declare function validateSchema<T>(state: unknown, schema: FormSchema): Promise<ValidateResult<T>>;
+export declare function getAtPath<T extends Record<string, unknown>>(data: T, path?: string): unknown;
+export declare function setAtPath<T extends Record<string, unknown>>(data: T, path: string, value: unknown): T;

package/dist/Form/validate-schema.js

@@ -0,0 +1,113 @@
+// ==================== TYPE GUARDS ====================
+export function isStandardSchema(schema) {
+    return (typeof schema === 'object' &&
+        schema !== null &&
+        '~standard' in schema &&
+        typeof schema['~standard'] === 'object');
+}
+export function isJoiSchema(schema) {
+    if (typeof schema !== 'object' || schema === null)
+        return false;
+    const s = schema;
+    return (typeof s.validate === 'function' &&
+        typeof s.validateAsync === 'function' &&
+        '$_root' in s &&
+        typeof s.type === 'string');
+}
+// ==================== NORMALIZE STANDARD SCHEMA PATH ====================
+function normalizePath(path) {
+    if (!path || path.length === 0)
+        return '';
+    return path
+        .map((segment) => {
+        if (typeof segment === 'object' && segment !== null && 'key' in segment) {
+            return String(segment.key);
+        }
+        return String(segment);
+    })
+        .join('.');
+}
+// ==================== STANDARD SCHEMA VALIDATOR ====================
+// Handles Zod 3.24+, Valibot 1.0+, Yup 1.7+ (and any other library
+// implementing the Standard Schema spec).
+export async function validateStandardSchema(state, schema) {
+    let result = schema['~standard'].validate(state);
+    if (result instanceof Promise)
+        result = await result;
+    if ('issues' in result && result.issues) {
+        return {
+            errors: result.issues.map((issue) => ({
+                name: normalizePath(issue.path),
+                message: issue.message
+            })),
+            value: null
+        };
+    }
+    return {
+        errors: null,
+        value: result.value
+    };
+}
+// ==================== JOI VALIDATOR ====================
+export async function validateJoiSchema(state, schema) {
+    // abortEarly: false → collect all errors, not just the first.
+    const result = schema.validate(state, { abortEarly: false });
+    if (result.error) {
+        return {
+            errors: result.error.details.map((detail) => ({
+                name: detail.path.map(String).join('.'),
+                message: detail.message
+            })),
+            value: null
+        };
+    }
+    return {
+        errors: null,
+        value: (result.value ?? null)
+    };
+}
+// ==================== DISPATCH ====================
+export function validateSchema(state, schema) {
+    // Joi is checked first, even though Joi 18+ also implements Standard Schema:
+    // Joi's Standard Schema impl defaults to `abortEarly: true` (stopping at the
+    // first error), whereas we want to surface ALL errors per field so the user
+    // can see every invalid field at once. The dedicated Joi adapter passes
+    // `{ abortEarly: false }` explicitly.
+    if (isJoiSchema(schema)) {
+        return validateJoiSchema(state, schema);
+    }
+    if (isStandardSchema(schema)) {
+        return validateStandardSchema(state, schema);
+    }
+    throw new Error('Form validation failed: Unsupported form schema');
+}
+// ==================== PATH UTILITIES (nested form support) ====================
+export function getAtPath(data, path) {
+    if (!path)
+        return data;
+    return path.split('.').reduce((value, key) => {
+        if (value === null || value === undefined)
+            return undefined;
+        return value[key];
+    }, data);
+}
+export function setAtPath(data, path, value) {
+    if (!path) {
+        return Object.assign(data, value);
+    }
+    if (!data)
+        return data;
+    const keys = path.split('.');
+    let current = data;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] === undefined || current[key] === null) {
+            const nextKey = keys[i + 1];
+            current[key] = !Number.isNaN(Number(nextKey)) ? [] : {};
+        }
+        current = current[key];
+    }
+    const lastKey = keys[keys.length - 1];
+    current[lastKey] = value;
+    return data;
+}

package/dist/FormField/FormField.svelte

@@ -0,0 +1,186 @@
+<script lang="ts" module>
+    import type { FormFieldProps } from './form-field.types.js'
+
+    export type Props = FormFieldProps
+</script>
+
+<script lang="ts">
+    import { Label, useId } from 'bits-ui'
+    import { setContext, untrack } from 'svelte'
+    import { getComponentConfig } from '../config.js'
+    import { getFormContext } from '../Form/form.context.svelte.js'
+    import { FORM_FIELD_CONTEXT_KEY, type FormFieldContext } from '../hooks/useFormField.svelte.js'
+    import { formFieldDefaults, formFieldVariants } from './form-field.variants.js'
+
+    const config = getComponentConfig('formField', formFieldDefaults)
+
+    let {
+        ref = $bindable(null),
+        ui,
+        name,
+        label,
+        description,
+        hint,
+        help,
+        error,
+        size = config.defaultVariants.size ?? 'md',
+        required = false,
+        orientation = config.defaultVariants.orientation ?? 'vertical',
+        eagerValidation,
+        validateOnInputDelay,
+        errorPattern,
+        class: className,
+        children,
+        labelSlot,
+        hintSlot,
+        descriptionSlot,
+        helpSlot,
+        errorSlot,
+        ...restProps
+    }: Props = $props()
+
+    const id = useId()
+    const ariaId = $derived(name ? `form-field-${name}` : id)
+
+    // Form-level context (undefined when FormField is used standalone).
+    const formCtx = getFormContext()
+
+    // Resolve error: explicit `error` prop always wins; otherwise ask the Form for
+    // errors matching this field's name (or errorPattern regex, if provided).
+    const resolvedError = $derived.by<string | boolean | undefined>(() => {
+        if (error !== undefined) return error
+        if (!formCtx || !name) return undefined
+        const errs = errorPattern ? formCtx.getErrors(errorPattern) : formCtx.getErrors(name)
+        return errs[0]?.message
+    })
+
+    // Register this field with the form. Split into two effects:
+    //
+    // 1. Lifecycle effect — tracks only `name`. Handles the initial registration
+    //    and cleanup on unmount / rename. Reads other entry fields via `untrack`
+    //    so they don't retrigger the lifecycle.
+    // 2. Update effect — tracks ariaId / errorPattern / eagerValidation /
+    //    validateOnInputDelay and rewrites the entry via `.set()`. No cleanup —
+    //    a single atomic overwrite, so no window where the registry is empty.
+    //
+    // Without this split, changing an unrelated prop (e.g. errorPattern) would
+    // cause cleanup→re-register, briefly leaving `#fieldRegistry.get(name)`
+    // undefined for any concurrent `#resolveErrorIds` call.
+    $effect(() => {
+        if (!formCtx || !name) return
+        const registeredName = name
+        untrack(() => {
+            formCtx.registerField(registeredName, {
+                id: ariaId,
+                pattern: errorPattern,
+                eagerValidation,
+                validateOnInputDelay
+            })
+        })
+        return () => {
+            formCtx.unregisterField(registeredName)
+        }
+    })
+
+    $effect(() => {
+        if (!formCtx || !name) return
+        formCtx.registerField(name, {
+            id: ariaId,
+            pattern: errorPattern,
+            eagerValidation,
+            validateOnInputDelay
+        })
+    })
+
+    const variantSlots = $derived(formFieldVariants({ size, required, orientation }))
+    const classes = $derived({
+        root: variantSlots.root({ class: [config.slots.root, className, ui?.root] }),
+        wrapper: variantSlots.wrapper({ class: [config.slots.wrapper, ui?.wrapper] }),
+        labelWrapper: variantSlots.labelWrapper({
+            class: [config.slots.labelWrapper, ui?.labelWrapper]
+        }),
+        label: variantSlots.label({ class: [config.slots.label, ui?.label] }),
+        container: variantSlots.container({ class: [config.slots.container, ui?.container] }),
+        description: variantSlots.description({
+            class: [config.slots.description, ui?.description]
+        }),
+        error: variantSlots.error({ class: [config.slots.error, ui?.error] }),
+        hint: variantSlots.hint({ class: [config.slots.hint, ui?.hint] }),
+        help: variantSlots.help({ class: [config.slots.help, ui?.help] })
+    })
+
+    const hasError = $derived(resolvedError !== undefined && resolvedError !== false)
+    const errorMessage = $derived(typeof resolvedError === 'string' ? resolvedError : undefined)
+
+    setContext<FormFieldContext>(FORM_FIELD_CONTEXT_KEY, {
+        get name() {
+            return name
+        },
+        get size() {
+            return size
+        },
+        get error() {
+            return resolvedError
+        },
+        get ariaId() {
+            return ariaId
+        },
+        get eagerValidation() {
+            return eagerValidation
+        },
+        get validateOnInputDelay() {
+            return validateOnInputDelay
+        },
+        get errorPattern() {
+            return errorPattern
+        }
+    })
+</script>
+
+<div bind:this={ref} class={classes.root} {...restProps}>
+    <div class={classes.wrapper}>
+        {#if label || labelSlot || hint || hintSlot}
+            <div class={classes.labelWrapper}>
+                {#if labelSlot}
+                    {@render labelSlot({ label })}
+                {:else if label}
+                    <Label.Root for={ariaId} class={classes.label}>
+                        {label}
+                    </Label.Root>
+                {/if}
+
+                {#if hintSlot}
+                    {@render hintSlot({ hint })}
+                {:else if hint}
+                    <span class={classes.hint}>{hint}</span>
+                {/if}
+            </div>
+        {/if}
+
+        {#if descriptionSlot}
+            {@render descriptionSlot({ description })}
+        {:else if description}
+            <p id="{ariaId}-description" class={classes.description}>{description}</p>
+        {/if}
+    </div>
+
+    <div class={classes.container}>
+        {#if children}
+            {@render children({ error: resolvedError })}
+        {/if}
+
+        {#if hasError && (errorMessage || errorSlot)}
+            {#if errorSlot}
+                {@render errorSlot({ error: resolvedError })}
+            {:else if errorMessage}
+                <p id="{ariaId}-error" class={classes.error}>{errorMessage}</p>
+            {/if}
+        {:else if help || helpSlot}
+            {#if helpSlot}
+                {@render helpSlot({ help })}
+            {:else if help}
+                <p id="{ariaId}-help" class={classes.help}>{help}</p>
+            {/if}
+        {/if}
+    </div>
+</div>

package/dist/FormField/FormField.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { FormFieldProps } from './form-field.types.js';
+export type Props = FormFieldProps;
+declare const FormField: import("svelte").Component<FormFieldProps, {}, "ref">;
+type FormField = ReturnType<typeof FormField>;
+export default FormField;

package/dist/FormField/form-field.types.d.ts

@@ -0,0 +1,109 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ClassNameValue } from 'tailwind-merge';
+import type { FormFieldSlots, FormFieldVariantProps } from './form-field.variants.js';
+export type FormFieldProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+    /**
+     * Bindable reference to the root DOM element.
+     */
+    ref?: HTMLElement | null;
+    /**
+     * The name of the form field, used for matching form errors.
+     */
+    name?: string;
+    /**
+     * The label text displayed above the form control.
+     */
+    label?: string;
+    /**
+     * Additional description text displayed below the label.
+     */
+    description?: string;
+    /**
+     * Hint text displayed next to the label (right side).
+     */
+    hint?: string;
+    /**
+     * Help text displayed below the form control.
+     */
+    help?: string;
+    /**
+     * Error message to display. When set, replaces the help text.
+     * Can be a string (error message) or boolean (error state without message).
+     */
+    error?: string | boolean;
+    /**
+     * Controls the size of the form field labels and text.
+     * @default 'md'
+     */
+    size?: NonNullable<FormFieldVariantProps['size']>;
+    /**
+     * Whether the field is required. Adds an asterisk indicator to the label.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Controls the layout direction.
+     * @default 'vertical'
+     */
+    orientation?: NonNullable<FormFieldVariantProps['orientation']>;
+    /**
+     * When `true`, input events validate this field before first blur.
+     * By default, `input`-triggered validation only runs after the field has
+     * been blurred at least once.
+     */
+    eagerValidation?: boolean;
+    /**
+     * Per-field override for the form's `validateOnInputDelay` (debounce in ms).
+     */
+    validateOnInputDelay?: number;
+    /**
+     * Regex pattern to match form errors for this field (in addition to exact name match).
+     * Useful for array-style fields like `items.0.name`, `items.1.name`, etc.
+     */
+    errorPattern?: RegExp;
+    /**
+     * Additional CSS classes for the root element.
+     */
+    class?: ClassNameValue;
+    /**
+     * Override styles for specific form field slots.
+     */
+    ui?: Partial<Record<FormFieldSlots, ClassNameValue>>;
+    /**
+     * The default slot content (form control).
+     */
+    children?: Snippet<[{
+        error?: string | boolean;
+    }]>;
+    /**
+     * Custom label slot.
+     */
+    labelSlot?: Snippet<[{
+        label?: string;
+    }]>;
+    /**
+     * Custom hint slot.
+     */
+    hintSlot?: Snippet<[{
+        hint?: string;
+    }]>;
+    /**
+     * Custom description slot.
+     */
+    descriptionSlot?: Snippet<[{
+        description?: string;
+    }]>;
+    /**
+     * Custom help slot.
+     */
+    helpSlot?: Snippet<[{
+        help?: string;
+    }]>;
+    /**
+     * Custom error slot.
+     */
+    errorSlot?: Snippet<[{
+        error?: string | boolean;
+    }]>;
+};

package/dist/FormField/form-field.types.js

@@ -0,0 +1 @@
+export {};