sv5ui 1.5.1 → 1.6.0

package/dist/Checkbox/Checkbox.svelte

@@ -9,7 +9,7 @@
     import { checkboxVariants, checkboxDefaults } from './checkbox.variants.js'
     import { getComponentConfig, iconsDefaults } from '../config.js'
     import Icon from '../Icon/Icon.svelte'
-    import { useFormField } from '../hooks/useFormField.svelte.js'
+    import { useFormField, useFormFieldEmit } from '../hooks/useFormField.svelte.js'
 
     const config = getComponentConfig('checkbox', checkboxDefaults)
     const icons = getComponentConfig('icons', iconsDefaults)
@@ -43,6 +43,7 @@
     }: Props = $props()
 
     const formFieldContext = useFormField()
+    const emit = useFormFieldEmit()
 
     const hasError = $derived(
         formFieldContext?.error !== undefined && formFieldContext?.error !== false
@@ -107,9 +108,14 @@
     <div bind:this={containerRef} class={classes.container}>
         <Checkbox.Root
             bind:checked
-            {onCheckedChange}
+            onCheckedChange={(val) => {
+                emit.onChange()
+                onCheckedChange?.(val)
+            }}
             bind:indeterminate
             {onIndeterminateChange}
+            onblur={() => emit.onBlur()}
+            onfocus={() => emit.onFocus()}
             id={resolvedId}
             name={resolvedName}
             {value}

package/dist/CheckboxGroup/CheckboxGroup.svelte

@@ -9,7 +9,7 @@
     import { checkboxGroupVariants, checkboxGroupDefaults } from './checkbox-group.variants.js'
     import { getComponentConfig, iconsDefaults } from '../config.js'
     import Icon from '../Icon/Icon.svelte'
-    import { useFormField } from '../hooks/useFormField.svelte.js'
+    import { useFormField, useFormFieldEmit } from '../hooks/useFormField.svelte.js'
     import type { CheckboxGroupItem } from './checkbox-group.types.js'
 
     const config = getComponentConfig('checkboxGroup', checkboxGroupDefaults)
@@ -42,6 +42,7 @@
     }: Props = $props()
 
     const formFieldContext = useFormField()
+    const emit = useFormFieldEmit()
 
     const hasError = $derived(
         formFieldContext?.error !== undefined && formFieldContext?.error !== false
@@ -97,6 +98,7 @@
         } else {
             value = value.filter((v) => v !== itemValue)
         }
+        emit.onChange()
         onValueChange?.(value)
     }
 
@@ -169,7 +171,18 @@
 {/snippet}
 
 <div {...restProps} bind:this={ref} class={layoutClasses.root}>
-    <fieldset class={layoutClasses.fieldset} aria-describedby={ariaDescribedBy}>
+    <fieldset
+        class={layoutClasses.fieldset}
+        aria-describedby={ariaDescribedBy}
+        onfocusin={() => emit.onFocus()}
+        onfocusout={(e) => {
+            // Only emit blur when focus leaves the fieldset entirely, not when
+            // moving between checkboxes within the group.
+            if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+                emit.onBlur()
+            }
+        }}
+    >
         {#if legend || legendSlot}
             {#if legendSlot}
                 {@render legendSlot({ legend })}

package/dist/Form/Form.svelte

@@ -0,0 +1,203 @@
+<script lang="ts" module>
+    import type { FormProps, FormSchema } from './form.types.js'
+
+    export type Props<
+        S extends FormSchema | undefined = FormSchema | undefined,
+        T extends boolean = true,
+        N extends boolean = false
+    > = FormProps<S, T, N>
+</script>
+
+<script
+    lang="ts"
+    generics="S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false"
+>
+    import { setContext, onMount, onDestroy, untrack } from 'svelte'
+    import type { HTMLAttributes } from 'svelte/elements'
+    import { formVariants, formDefaults } from './form.variants.js'
+    import { FormContext, FORM_CONTEXT_KEY, getFormContext } from './form.context.svelte.js'
+    import { getComponentConfig } from '../config.js'
+    import type { FormApi, FormErrorWithId } from './form.types.js'
+
+    const config = getComponentConfig('form', formDefaults)
+
+    let {
+        ref = $bindable(null),
+        api = $bindable<FormApi<unknown> | undefined>(),
+        id,
+        schema,
+        state = $bindable({} as never),
+        validate: customValidate,
+        validateOn = ['input', 'blur', 'change'],
+        validateOnInputDelay = 300,
+        disabled = false,
+        loadingAuto = true,
+        transform = true as T,
+        nested = false as N,
+        name,
+        onsubmit,
+        onerror,
+        class: className,
+        ui,
+        children,
+        ...restProps
+    }: Props<S, T, N> = $props()
+
+    // Generate a stable form id. Both `id` and `nested` are effectively init-only
+    // (they should not change over a form instance's lifetime), so `untrack`
+    // silences Svelte's state_referenced_locally warning.
+    const formId: string | number = untrack(
+        () =>
+            (id as string | number | undefined) ??
+            (typeof crypto !== 'undefined' && 'randomUUID' in crypto
+                ? crypto.randomUUID()
+                : `sv5ui-form-${Math.random().toString(36).slice(2)}`)
+    )
+
+    // Parent context captured once at init — `nested` is effectively immutable
+    // over a form instance's lifetime. We warn (dev-only) if it's mutated later.
+    const parentCtx = untrack(() => (nested ? getFormContext() : undefined))
+    const initialNested = untrack(() => nested)
+    $effect(() => {
+        if (nested !== initialNested) {
+            // eslint-disable-next-line no-console
+            console.warn(
+                '[sv5ui Form] The `nested` prop was changed after mount. This is ' +
+                    'not supported — nested/standalone status is fixed at mount time. ' +
+                    'Unmount and remount the Form to toggle.'
+            )
+        }
+    })
+
+    // Create the reactive form context. All config is passed via getter closures
+    // so that reactive prop changes are visible inside the class.
+    const ctx = new FormContext(
+        {
+            getState: () => state as unknown,
+            getSchema: () => schema as FormSchema | undefined,
+            getCustomValidate: () =>
+                customValidate as
+                    | ((s: unknown) => ReturnType<NonNullable<typeof customValidate>>)
+                    | undefined,
+            getValidateOn: () => validateOn,
+            getValidateOnInputDelay: () => validateOnInputDelay,
+            getDisabled: () => disabled,
+            getLoadingAuto: () => loadingAuto,
+            getTransform: () => transform,
+            getName: () => name as string | undefined,
+            getOnSubmit: () =>
+                onsubmit as
+                    | ((
+                          e: import('./form.types.js').FormSubmitEvent<unknown>
+                      ) => void | Promise<void>)
+                    | undefined,
+            getOnError: () => onerror
+        },
+        formId,
+        parentCtx
+    )
+
+    setContext(FORM_CONTEXT_KEY, ctx)
+
+    // Build the bindable API object. Getters ensure reactive state reads stay live.
+    const apiObject: FormApi<unknown> = {
+        validate: (opts) => ctx.validate(opts) as Promise<unknown | false>,
+        submit: () => ctx.submit(),
+        clear: (name) => ctx.clear(name),
+        getErrors: (name) => ctx.getErrors(name),
+        setErrors: (errs, name) => ctx.setErrors(errs, name),
+        reset: () => ctx.reset(),
+        get errors() {
+            return ctx.errors
+        },
+        get loading() {
+            return ctx.loading
+        },
+        get disabled() {
+            return ctx.disabled
+        },
+        get dirty() {
+            return ctx.dirty
+        },
+        get dirtyFields() {
+            return ctx.dirtyFields as ReadonlySet<string>
+        },
+        get touchedFields() {
+            return ctx.touchedFields as ReadonlySet<string>
+        },
+        get blurredFields() {
+            return ctx.blurredFields as ReadonlySet<string>
+        },
+        get submitCount() {
+            return ctx.submitCount
+        }
+    }
+
+    // Sync the api object to the bindable prop once at setup time. `apiObject`
+    // is a stable reference built from getters, so there's nothing reactive to
+    // track — direct assignment is sufficient.
+    api = apiObject as typeof api
+
+    // Nested form attach/detach lifecycle.
+    onMount(() => {
+        if (parentCtx && nested) {
+            parentCtx.attachChild(formId, {
+                formId,
+                name: name as string | undefined,
+                validate: (opts) => ctx.validate(opts) as Promise<unknown | false>,
+                clear: (n) => ctx.clear(n),
+                reset: () => ctx.reset(),
+                setErrors: (errs, n) => ctx.setErrors(errs, n)
+            })
+        }
+    })
+
+    onDestroy(() => {
+        if (parentCtx && nested) parentCtx.detachChild(formId)
+        ctx.dispose()
+    })
+
+    async function handleSubmit(event: SubmitEvent) {
+        event.preventDefault()
+        // Forward the real SubmitEvent so user handlers can read `submitter`,
+        // `target`, etc. When `api.submit()` is called programmatically, ctx.submit
+        // synthesizes a fresh event instead.
+        await ctx.submit(event)
+    }
+
+    // `formVariants` has no variants (only a single `root` slot), so its
+    // output is stable — compute once at setup rather than via $derived.
+    const variantSlots = formVariants()
+    const classes = $derived({
+        root: variantSlots.root({
+            class: [config.slots.root, className, ui?.root]
+        })
+    })
+
+    // Slot props for children
+    const slotProps = $derived({
+        errors: ctx.errors as FormErrorWithId[],
+        loading: ctx.loading
+    })
+</script>
+
+{#if nested}
+    <div
+        {...restProps as unknown as HTMLAttributes<HTMLDivElement>}
+        bind:this={ref}
+        id={typeof id === 'number' ? String(id) : id}
+        class={classes.root}
+    >
+        {@render children?.(slotProps)}
+    </div>
+{:else}
+    <form
+        {...restProps}
+        bind:this={ref}
+        id={typeof id === 'number' ? String(id) : id}
+        class={classes.root}
+        onsubmit={handleSubmit}
+    >
+        {@render children?.(slotProps)}
+    </form>
+{/if}

package/dist/Form/Form.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { FormProps, FormSchema } from './form.types.js';
+export type Props<S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false> = FormProps<S, T, N>;
+declare function $$render<S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false>(): {
+    props: Props<S, T, N>;
+    exports: {};
+    bindings: "ref" | "api" | "state";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false> {
+    props(): ReturnType<typeof $$render<S, T, N>>['props'];
+    events(): ReturnType<typeof $$render<S, T, N>>['events'];
+    slots(): ReturnType<typeof $$render<S, T, N>>['slots'];
+    bindings(): "ref" | "api" | "state";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<S, T, N>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<S, T, N>['props']>, ReturnType<__sveltets_Render<S, T, N>['events']>, ReturnType<__sveltets_Render<S, T, N>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<S, T, N>['bindings']>;
+    } & ReturnType<__sveltets_Render<S, T, N>['exports']>;
+    <S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false>(internal: unknown, props: ReturnType<__sveltets_Render<S, T, N>['props']> & {}): ReturnType<__sveltets_Render<S, T, N>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any, any>['bindings']>;
+}
+declare const Form: $$IsomorphicComponent;
+type Form<S extends FormSchema | undefined = FormSchema | undefined, T extends boolean = true, N extends boolean = false> = InstanceType<typeof Form<S, T, N>>;
+export default Form;

package/dist/Form/form.context.svelte.d.ts

@@ -0,0 +1,64 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { type FormError, type FormErrorWithId, type FormErrorEvent, type FormFieldRegistryEntry, type FormInputEvents, type FormSchema, type FormSubmitEvent, type FormValidateOpts, type NestedFormEntry } from './form.types.js';
+export declare const FORM_CONTEXT_KEY: unique symbol;
+export declare function getFormContext<T = unknown>(): FormContext<T> | undefined;
+export interface FormContextOptions<T> {
+    getState: () => T;
+    getSchema: () => FormSchema | undefined;
+    getCustomValidate: () => ((state: T) => FormError[] | Promise<FormError[]>) | undefined;
+    getValidateOn: () => FormInputEvents[];
+    getValidateOnInputDelay: () => number;
+    getDisabled: () => boolean;
+    getLoadingAuto: () => boolean;
+    getTransform: () => boolean;
+    getName: () => string | undefined;
+    getOnSubmit: () => ((event: FormSubmitEvent<unknown>) => void | Promise<void>) | undefined;
+    getOnError: () => ((event: FormErrorEvent) => void) | undefined;
+}
+export declare class FormContext<T = unknown> {
+    #private;
+    errors: FormErrorWithId[];
+    loading: boolean;
+    submitCount: number;
+    dirtyFields: SvelteSet<string>;
+    touchedFields: SvelteSet<string>;
+    blurredFields: SvelteSet<string>;
+    formId: string | number;
+    constructor(opts: FormContextOptions<T>, formId: string | number, parentCtx?: FormContext);
+    get dirty(): boolean;
+    get disabled(): boolean;
+    /**
+     * Current state. For nested forms, read the sub-tree from parent state by name.
+     * Falls back to `{}` if the parent hasn't initialized the sub-object yet —
+     * avoids crashing downstream validators when consumers forget to prefill it.
+     */
+    get state(): T;
+    getErrors(name?: string | RegExp): FormErrorWithId[];
+    setErrors(errs: FormError[], name?: string | RegExp): void;
+    clear(name?: string | RegExp): void;
+    /**
+     * Reset all form tracking state: errors, dirty/touched/blurred field sets,
+     * and submitCount. Does NOT modify `state` (caller owns that). Cascades to
+     * nested forms.
+     */
+    reset(): void;
+    registerField(name: string, entry: FormFieldRegistryEntry): void;
+    unregisterField(name: string): void;
+    attachChild(childFormId: string | number, entry: NestedFormEntry): void;
+    detachChild(childFormId: string | number): void;
+    onFocus(name: string): void;
+    onBlur(name: string): void;
+    onChange(name: string): void;
+    onInput(name: string, eager?: boolean): void;
+    validate(opts?: FormValidateOpts): Promise<T | false>;
+    /**
+     * Run full validation and fire onsubmit / onerror.
+     *
+     * @param sourceEvent - Real SubmitEvent from the `<form>` submit handler,
+     *   forwarded to the user's onsubmit / onerror so they can read `submitter`,
+     *   `preventDefault`, etc. When called programmatically (via the public API),
+     *   a fresh SubmitEvent is synthesized.
+     */
+    submit(sourceEvent?: SubmitEvent): Promise<void>;
+    dispose(): void;
+}