sv5ui 1.5.0 → 1.6.0

package/dist/Form/form.types.d.ts

@@ -0,0 +1,164 @@
+import type { Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+import type { ClassNameValue } from 'tailwind-merge';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FormSlots } from './form.variants.js';
+export type { StandardSchemaV1 };
+export type StandardSchemaV1InferInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
+export type StandardSchemaV1InferOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+export interface JoiSchema {
+    validate: (value: unknown, options?: object) => {
+        value: unknown;
+        error?: {
+            details: Array<{
+                message: string;
+                path: Array<string | number>;
+            }>;
+        };
+    };
+    validateAsync: (value: unknown, options?: object) => Promise<unknown>;
+    $_root: unknown;
+    type: string;
+}
+export type FormSchema = StandardSchemaV1 | JoiSchema;
+export type InferInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1InferInput<Schema> : never;
+export type InferOutput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1InferOutput<Schema> : never;
+export type FormData<S, T extends boolean = true> = T extends true ? InferOutput<S> : InferInput<S>;
+export interface FormError<P extends string = string> {
+    name?: P;
+    message: string;
+}
+export interface FormErrorWithId extends FormError {
+    id?: string;
+}
+export type FormInputEvents = 'input' | 'blur' | 'change' | 'focus';
+export type FormSubmitEvent<T = unknown> = SubmitEvent & {
+    data: T;
+};
+export type FormErrorEvent = SubmitEvent & {
+    errors: FormErrorWithId[];
+};
+export declare class FormValidationException extends Error {
+    formId: string | number;
+    errors: FormErrorWithId[];
+    constructor(formId: string | number, errors: FormErrorWithId[]);
+}
+export interface FormFieldRegistryEntry {
+    id?: string;
+    pattern?: RegExp;
+    eagerValidation?: boolean;
+    validateOnInputDelay?: number;
+}
+export interface NestedFormEntry {
+    formId: string | number;
+    name?: string;
+    validate: (opts?: FormValidateOpts) => Promise<unknown | false>;
+    clear: (name?: string | RegExp) => void;
+    reset: () => void;
+    setErrors: (errs: FormError[], name?: string | RegExp) => void;
+}
+export interface FormValidateOpts {
+    name?: string | string[];
+    silent?: boolean;
+    nested?: boolean;
+    transform?: boolean;
+}
+export interface FormApi<T = unknown> {
+    validate(opts?: FormValidateOpts): Promise<T | false>;
+    submit(): Promise<void>;
+    clear(name?: string | RegExp): void;
+    getErrors(name?: string | RegExp): FormErrorWithId[];
+    setErrors(errs: FormError[], name?: string | RegExp): void;
+    /**
+     * Reset form tracking state: clears all errors, dirty/touched/blurred field
+     * sets, and resets submitCount to 0. Does NOT modify `state` — you own that
+     * and should reassign it yourself if you want to restore initial values.
+     */
+    reset(): void;
+    readonly errors: FormErrorWithId[];
+    readonly loading: boolean;
+    readonly disabled: boolean;
+    readonly dirty: boolean;
+    readonly dirtyFields: ReadonlySet<string>;
+    readonly touchedFields: ReadonlySet<string>;
+    readonly blurredFields: ReadonlySet<string>;
+    /** Number of times `submit()` has been called (whether validation passed or not). */
+    readonly submitCount: number;
+}
+export type FormProps<S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false> = Omit<HTMLFormAttributes, 'class' | 'id' | 'name' | 'onsubmit' | 'onerror'> & {
+    /** Bindable reference to the root DOM element. */
+    ref?: HTMLElement | null;
+    /**
+     * Bindable form API — methods and reactive state accessors.
+     *
+     * For typed access to `validate()` / `submit()` results, annotate the
+     * consumer variable explicitly:
+     *
+     * ```ts
+     * import type { FormApi } from 'sv5ui'
+     * import type { z } from 'zod'
+     *
+     * const schema = z.object({ email: z.string().email() })
+     * let form = $state<FormApi<z.infer<typeof schema>>>()
+     * ```
+     */
+    api?: FormApi<unknown>;
+    /** Optional explicit id for the form (used as key for internal bus). */
+    id?: string | number;
+    /**
+     * Schema to validate the form state.
+     * Standard Schema (Zod 3.24+, Valibot 1.0+, Yup 1.7+) or Joi.
+     */
+    schema?: S;
+    /** The object representing the current state of the form. Bindable. */
+    state?: S extends FormSchema ? (N extends false ? Partial<InferInput<S>> : never) : object;
+    /**
+     * Custom validation function. Runs alongside `schema` if both provided.
+     */
+    validate?: (state: S extends FormSchema ? Partial<InferInput<S>> : object) => FormError[] | Promise<FormError[]>;
+    /**
+     * Input events that trigger field-level validation.
+     * Submit always triggers full validation regardless.
+     * @default ['input', 'blur', 'change']
+     */
+    validateOn?: FormInputEvents[];
+    /**
+     * Debounce delay in ms for `input` event validation.
+     * @default 300
+     */
+    validateOnInputDelay?: number;
+    /** Disable all inputs inside the form (propagated via context). */
+    disabled?: boolean;
+    /**
+     * When `true`, the form is automatically disabled during async submit.
+     * @default true
+     */
+    loadingAuto?: boolean;
+    /**
+     * When `true`, apply schema transformations on submit.
+     * @default true
+     */
+    transform?: T;
+    /**
+     * When `true`, this form attaches to its parent Form and validates alongside it.
+     * @default false
+     */
+    nested?: N & boolean;
+    /**
+     * Dotted path of this form's state within its parent. Only meaningful when `nested = true`.
+     */
+    name?: N extends true ? string : never;
+    /** Submit handler. Called with validated (and optionally transformed) data. */
+    onsubmit?: (event: FormSubmitEvent<S extends FormSchema ? FormData<S, T> : object>) => void | Promise<void>;
+    /** Error handler. Called when validation fails on submit. */
+    onerror?: (event: FormErrorEvent) => void;
+    /** Additional CSS classes for the root element. */
+    class?: ClassNameValue;
+    /** Override styles for specific form slots. */
+    ui?: Partial<Record<FormSlots, ClassNameValue>>;
+    /** Default slot — receives reactive `errors` and `loading`. */
+    children?: Snippet<[{
+        errors: FormErrorWithId[];
+        loading: boolean;
+    }]>;
+};

package/dist/Form/form.types.js

@@ -0,0 +1,12 @@
+// ==================== EXCEPTIONS ====================
+export class FormValidationException extends Error {
+    formId;
+    errors;
+    constructor(formId, errors) {
+        super('Form validation exception');
+        this.name = 'FormValidationException';
+        this.formId = formId;
+        this.errors = errors;
+        Object.setPrototypeOf(this, FormValidationException.prototype);
+    }
+}

package/dist/Form/form.variants.d.ts

@@ -0,0 +1,39 @@
+import { type VariantProps } 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 declare const formVariants: import("tailwind-variants").TVReturnType<{
+    [key: string]: {
+        [key: string]: import("tailwind-merge").ClassNameValue | {
+            root?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: import("tailwind-merge").ClassNameValue | {
+            root?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {}, {
+    root: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: import("tailwind-merge").ClassNameValue | {
+            root?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {}, {
+    root: string;
+}, import("tailwind-variants").TVReturnType<unknown, {
+    root: string;
+}, undefined, unknown, unknown, undefined>>;
+export type FormVariantProps = VariantProps<typeof formVariants>;
+export type FormSlots = keyof ReturnType<typeof formVariants>;
+export declare const formDefaults: {
+    defaultVariants: NonNullable<typeof formVariants.defaultVariants>;
+    slots: Partial<Record<FormSlots, string>>;
+};

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 type { FormProps, FormApi, FormError, FormErrorWithId, FormSubmitEvent, FormErrorEvent, FormSchema, FormInputEvents, FormValidateOpts, InferInput, InferOutput, FormData, StandardSchemaV1, JoiSchema } from './form.types.js';
+export { FormValidationException } from './form.types.js';
+export { getFormContext } from './form.context.svelte.js';

package/dist/Form/index.js

@@ -0,0 +1,6 @@
+export { default as Form } from './Form.svelte';
+export { FormValidationException } from './form.types.js';
+// 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';

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

@@ -8,8 +8,9 @@
     import { Label, useId } from 'bits-ui'
     import { formFieldVariants, formFieldDefaults } from './form-field.variants.js'
     import { getComponentConfig } from '../config.js'
-    import { setContext } from 'svelte'
-    import type { FormFieldContext } from '../hooks/useFormField.svelte.js'
+    import { setContext, untrack } from 'svelte'
+    import { type FormFieldContext, FORM_FIELD_CONTEXT_KEY } from '../hooks/useFormField.svelte.js'
+    import { getFormContext } from '../Form/form.context.svelte.js'
 
     const config = getComponentConfig('formField', formFieldDefaults)
 
@@ -25,6 +26,9 @@
         size = config.defaultVariants.size ?? 'md',
         required = false,
         orientation = config.defaultVariants.orientation ?? 'vertical',
+        eagerValidation,
+        validateOnInputDelay,
+        errorPattern,
         class: className,
         children,
         labelSlot,
@@ -38,6 +42,56 @@
     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] }),
@@ -55,10 +109,10 @@
         help: variantSlots.help({ class: [config.slots.help, ui?.help] })
     })
 
-    const hasError = $derived(error !== undefined && error !== false)
-    const errorMessage = $derived(typeof error === 'string' ? error : undefined)
+    const hasError = $derived(resolvedError !== undefined && resolvedError !== false)
+    const errorMessage = $derived(typeof resolvedError === 'string' ? resolvedError : undefined)
 
-    setContext<FormFieldContext>('formField', {
+    setContext<FormFieldContext>(FORM_FIELD_CONTEXT_KEY, {
         get name() {
             return name
         },
@@ -66,10 +120,19 @@
             return size
         },
         get error() {
-            return error
+            return resolvedError
         },
         get ariaId() {
             return ariaId
+        },
+        get eagerValidation() {
+            return eagerValidation
+        },
+        get validateOnInputDelay() {
+            return validateOnInputDelay
+        },
+        get errorPattern() {
+            return errorPattern
         }
     })
 </script>
@@ -103,12 +166,12 @@
 
     <div class={classes.container}>
         {#if children}
-            {@render children({ error })}
+            {@render children({ error: resolvedError })}
         {/if}
 
         {#if hasError && (errorMessage || errorSlot)}
             {#if errorSlot}
-                {@render errorSlot({ error })}
+                {@render errorSlot({ error: resolvedError })}
             {:else if errorMessage}
                 <p id="{ariaId}-error" class={classes.error}>{errorMessage}</p>
             {/if}

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

@@ -47,6 +47,21 @@ export type FormFieldProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
      * @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.
      */

package/dist/Input/Input.svelte

@@ -1,10 +1,10 @@
 <script lang="ts" module>
-    import type { InputProps } from './input.types.js'
+    import type { InputProps, InputValue } from './input.types.js'
 
-    export type Props = InputProps
+    export type Props<T extends InputValue = InputValue> = InputProps<T>
 </script>
 
-<script lang="ts">
+<script lang="ts" generics="T extends InputValue = InputValue">
     import { inputVariants, inputDefaults } from './input.variants.js'
     import { getComponentConfig, iconsDefaults } from '../config.js'
     import { getContext } from 'svelte'
@@ -15,7 +15,7 @@
     import Icon from '../Icon/Icon.svelte'
     import Avatar from '../Avatar/Avatar.svelte'
     import type { AvatarSize } from '../Avatar/avatar.types.js'
-    import { useFormField } from '../hooks/useFormField.svelte.js'
+    import { useFormField, useFormFieldEmit } from '../hooks/useFormField.svelte.js'
 
     const config = getComponentConfig('input', inputDefaults)
     const icons = getComponentConfig('icons', iconsDefaults)
@@ -42,10 +42,32 @@
         leadingSlot,
         trailingSlot,
         class: className,
+        onblur,
+        oninput,
+        onchange,
+        onfocus,
         ...restProps
-    }: Props = $props()
+    }: Props<T> = $props()
 
     const formFieldContext = useFormField()
+    const emit = useFormFieldEmit()
+
+    function handleBlur(event: FocusEvent & { currentTarget: HTMLInputElement }) {
+        emit.onBlur()
+        onblur?.(event)
+    }
+    function handleInput(event: Event & { currentTarget: HTMLInputElement }) {
+        emit.onInput()
+        oninput?.(event)
+    }
+    function handleChange(event: Event & { currentTarget: HTMLInputElement }) {
+        emit.onChange()
+        onchange?.(event)
+    }
+    function handleFocus(event: FocusEvent & { currentTarget: HTMLInputElement }) {
+        emit.onFocus()
+        onfocus?.(event)
+    }
 
     const fieldGroupContext = getContext<
         | {
@@ -153,6 +175,10 @@
         aria-describedby={ariaDescribedBy}
         aria-invalid={resolvedHighlight ? true : undefined}
         class={classes.base}
+        onblur={handleBlur}
+        oninput={handleInput}
+        onchange={handleChange}
+        onfocus={handleFocus}
     />
 
     {#if trailingSlot}

package/dist/Input/Input.svelte.d.ts

@@ -1,5 +1,26 @@
-import type { InputProps } from './input.types.js';
-export type Props = InputProps;
-declare const Input: import("svelte").Component<InputProps, {}, "ref" | "value">;
-type Input = ReturnType<typeof Input>;
+import type { InputProps, InputValue } from './input.types.js';
+export type Props<T extends InputValue = InputValue> = InputProps<T>;
+declare function $$render<T extends InputValue = InputValue>(): {
+    props: Props<T>;
+    exports: {};
+    bindings: "ref" | "value";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends InputValue = InputValue> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "ref" | "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends InputValue = InputValue>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends InputValue = InputValue>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Input: $$IsomorphicComponent;
+type Input<T extends InputValue = InputValue> = InstanceType<typeof Input<T>>;
 export default Input;

package/dist/Input/input.types.d.ts

@@ -3,15 +3,36 @@ import type { HTMLInputAttributes } from 'svelte/elements';
 import type { ClassNameValue } from 'tailwind-merge';
 import type { InputVariantProps, InputSlots } from './input.variants.js';
 import type { AvatarProps } from '../Avatar/avatar.types.js';
-export type InputProps = Omit<HTMLInputAttributes, 'class' | 'size'> & {
+/**
+ * Valid value types for `<Input bind:value>`.
+ *
+ * Covers every HTML input `type` except `"file"` (which uses `FileList` and is
+ * typically handled via `onchange` events, not `bind:value`). Pattern borrowed
+ * from Nuxt UI v4's `AcceptableValue` — it's the minimum union that covers
+ * real-world usage while still giving TypeScript enough to catch mistakes.
+ *
+ * Use with the component generic for strict typing:
+ * ```ts
+ * let age = $state<number | undefined>(undefined)
+ * <Input type="number" bind:value={age} />   // age stays number
+ * ```
+ */
+export type InputValue = string | number | bigint | boolean | null | undefined;
+export type InputProps<T extends InputValue = InputValue> = Omit<HTMLInputAttributes, 'class' | 'size' | 'value'> & {
     /**
      * Bind a reference to the underlying HTMLInputElement.
      */
     ref?: HTMLInputElement | null;
     /**
      * The current value of the input. Supports two-way binding with `bind:value`.
-     */
-    value?: string;
+     *
+     * The type is inferred from the bound variable — Svelte's `bind:value`
+     * coerces based on the `type` attribute automatically:
+     * - `string` for `text | email | password | url | search | tel | date | time | color` etc.
+     * - `number` for `type="number" | "range"`
+     * - `boolean` for hidden boolean state (rare)
+     */
+    value?: T;
     /**
      * Controls the visual style of the input.
      * @default 'outline'