@native-form/core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,9 +1,495 @@
-export { Serializer, type SerializeFieldsOptions, } from "./serialization/Serializer";
-export { FieldNode } from "./field/FieldNode";
-export { Runtime, type RuntimeFormState, type RuntimeOptions, type RuntimePublicApi, } from "./Runtime";
-export { arrayItemPath, type ArrayItemPathInfo, type FieldPathSegment, formPath, getByPath, isArrayItemPath, matchArrayItemPath, normalizePath, parseArrayItemPath, remapArrayItemIndex, setByPath, shiftArrayItemIndex, splitPath, toNestedValues, } from "./Path";
-export { createValidationPipeline, type ValidationFieldMeta, type ValidationPipeline, type ValidationPipelineCapabilities, type ValidationPipelineContext, type ValidationPipelineOptions, } from "./ValidationPipeline";
-export { createValidator, type AsyncFieldValidator, type InferSchemaOutput, type SchemaLike, type StandardSchemaIssue, type StandardSchemaResult, type StandardSchemaV1, type ValidationContext, type ValidationIssue, type ValidationResult, type Validator, } from "./Validation";
-export { type FieldState } from "./FieldState";
-export { type FieldEvents, type FormEvents, type NativeFormElement, type NativeFormFlatValues, type NativeFormNestedValue, type NativeFormValue, type NativeFormValues, type RuntimeEvent, type RuntimeEventType, type RuntimeListener, type SerializationMode, type ValidationEvents, type ValidationMode, } from "./types";
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Supported validation modes for form and field lifecycle.
+ * - onChange: validates on every input/change event (live)
+ * - onBlur: validates when an input loses focus
+ * - onSubmit: validates only upon form submission
+ * - onTouched: validates on blur first, then on change for touched fields
+ * - all: validates on both input and blur events
+ * @public
+ */
+type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
+/** @public */
+type NativeFormElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+/**
+ * Supported serialization modes.
+ * - 'native': extracts string / FormData values matching browser native FormData.
+ * - 'typed': preserves typed primitives (numbers, booleans, FileLists, string arrays) via serializeFields.
+ * @public
+ */
+type SerializationMode = "native" | "typed";
+/** @public */
+type NativeFormValue = FormDataEntryValue | FormDataEntryValue[] | number | boolean | FileList | null;
+/** @public */
+type NativeFormFlatValues = Record<string, NativeFormValue>;
+/** @public */
+type NativeFormNestedValue = NativeFormValue | {
+    [key: string]: NativeFormNestedValue;
+} | NativeFormNestedValue[];
+/** @public */
+type NativeFormValues = Record<string, NativeFormNestedValue>;
+/** @public */
+type RuntimeEventType = "form:mount" | "form:unmount" | "form:invalid" | "form:reset" | "form:submit" | "validation:end" | "validation:start" | "field:blur" | "field:mount" | "field:unmount" | "field:update" | "field:input" | "field:change" | "field:reset" | "field:submit";
+/** @public */
+type FormEvents = {
+    type: "form:mount" | "form:unmount";
+} | {
+    type: "form:reset" | "form:submit";
+    values: NativeFormValues;
+} | {
+    type: "form:invalid";
+    errors: Record<string, string>;
+    values: NativeFormValues;
+};
+/** @public */
+type ValidationEvents = {
+    type: "validation:start";
+    values: NativeFormValues;
+} | {
+    type: "validation:end";
+    errors: Record<string, string>;
+    values: NativeFormValues;
+};
+/** @public */
+type FieldEvents = {
+    type: "field:blur" | "field:update" | "field:input" | "field:change" | "field:reset";
+    field: string;
+    value: NativeFormValue | undefined;
+    values: NativeFormValues;
+} | {
+    type: "field:mount" | "field:unmount" | "field:submit";
+    field: string;
+};
+/** @public */
+type RuntimeEvent = FieldEvents | ValidationEvents | FormEvents;
+/** @public */
+type RuntimeListener = (event: RuntimeEvent) => void;
+
+/** @public */
+interface FieldState {
+    name: string;
+    dirty: boolean;
+    touched: boolean;
+    mounted: boolean;
+    initialValue: NativeFormValue | undefined;
+    value: NativeFormValue | undefined;
+    error?: string;
+    validating?: boolean;
+}
+
+/** @public */
+declare class FieldNode {
+    readonly element: NativeFormElement;
+    constructor(element: NativeFormElement);
+    private dirty;
+    private touched;
+    private mounted;
+    private initialValue;
+    private stateValue;
+    private error?;
+    private validating;
+    get name(): string;
+    get tag(): string;
+    get type(): string;
+    get value(): unknown;
+    focus(): void;
+    blur(): void;
+    get isDirty(): boolean;
+    get isTouched(): boolean;
+    get isMounted(): boolean;
+    get isValidating(): boolean;
+    setValidating(validating: boolean): void;
+    register(initialValue?: NativeFormValue): void;
+    unregister(): void;
+    getState(): FieldState;
+    updateValue(value?: NativeFormValue): void;
+    markTouched(): void;
+    setError(message: string | undefined): void;
+    reset(value: NativeFormValue | undefined): void;
+    handleInput(value?: NativeFormValue): void;
+    handleChange(value?: NativeFormValue): void;
+    handleBlur(): void;
+    handleReset(value?: NativeFormValue): void;
+    handleSubmit(): void;
+}
+
+/**
+ * Configuration options for field-driven serialization.
+ * @public
+ */
+interface SerializeFieldsOptions {
+    /**
+     * Whether to include disabled inputs in the serialized output.
+     * @defaultValue false
+     */
+    includeDisabled?: boolean;
+    /**
+     * Whether to coerce standalone unchecked checkboxes to `false` instead of omitting them.
+     * @defaultValue true
+     */
+    coerceUncheckedCheckboxes?: boolean;
+    /**
+     * Mode for value extraction:
+     * - 'typed': preserves numbers (valueAsNumber), booleans, and FileLists.
+     * - 'raw': extracts raw strings matching standard FormData entries.
+     * @defaultValue 'typed'
+     */
+    valueMode?: "typed" | "raw";
+    /**
+     * Output structure format:
+     * - 'flat': preserves exact input field names as top-level keys.
+     * - 'nested': resolves dot and bracket notation into deeply nested objects and arrays.
+     * @defaultValue 'flat'
+     */
+    nesting?: "flat" | "nested";
+    /**
+     * Custom value extractors for specific element tag names or input types.
+     */
+    customSerializers?: Record<string, (element: NativeFormElement, node: FieldNode) => unknown>;
+}
+/**
+ * Handles serialization of HTML forms and field node collections into structured key-value maps.
+ * @public
+ */
+declare class Serializer {
+    /**
+     * Native FormData serialization baseline (100% backward compatible with browser form submission).
+     */
+    serialize(form: HTMLFormElement): NativeFormFlatValues;
+    /**
+     * Field-node-driven serialization supporting type preservation, unchecked checkbox coercion,
+     * disabled filtering, and custom element serializers.
+     */
+    serializeFields(fields: Iterable<FieldNode>, options?: SerializeFieldsOptions): NativeFormValues;
+}
+
+/** @public */
+interface ValidationIssue {
+    name: string;
+    message: string;
+}
+/** @public */
+interface ValidationContext {
+    form: HTMLFormElement;
+    signal: AbortSignal;
+}
+/** @public */
+type ValidationResult<TValues extends NativeFormValues = NativeFormValues> = {
+    success: true;
+    values: TValues;
+    issues?: never;
+} | {
+    success: false;
+    values?: never;
+    issues: ValidationIssue[];
+};
+/** @public */
+type AsyncFieldValidator<TValue = unknown> = (value: TValue, context: ValidationContext) => Promise<string | undefined | void>;
+/** @public */
+interface Validator<TValues extends NativeFormValues = NativeFormValues> {
+    validate(values: NativeFormValues, context?: ValidationContext): ValidationResult<TValues> | Promise<ValidationResult<TValues>>;
+}
+/** @public */
+interface StandardSchemaIssue {
+    message: string;
+    path?: readonly (PropertyKey | {
+        key: PropertyKey;
+    })[];
+}
+/** @public */
+type StandardSchemaResult<TValues> = {
+    value: TValues;
+    issues?: never;
+} | {
+    value?: never;
+    issues: readonly StandardSchemaIssue[];
+};
+/** @public */
+interface StandardSchemaV1<TValues extends NativeFormValues = NativeFormValues> {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate(value: unknown): StandardSchemaResult<TValues> | Promise<StandardSchemaResult<TValues>>;
+        types?: {
+            input: unknown;
+            output: TValues;
+        };
+    };
+}
+/** @public */
+type SchemaLike<TValues extends NativeFormValues = NativeFormValues> = Validator<TValues> | StandardSchemaV1<TValues>;
+/** @public */
+type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<infer TValues> ? TValues : TSchema extends Validator<infer TValues> ? TValues : NativeFormValues;
+/** @public */
+declare function createValidator<TValues extends NativeFormValues>(schema: SchemaLike<TValues>): Validator<TValues>;
+
+/** @public */
+interface ValidationFieldMeta {
+    name: string;
+    validationMessage: string;
+}
+/** @public */
+interface ValidationPipelineContext extends ValidationContext {
+    fields: ValidationFieldMeta[];
+}
+/** @public */
+interface ValidationPipelineCapabilities {
+    /**
+     * When true, Runtime will call `validateField` for input/change-triggered
+     * validation. When false, Runtime falls back to `validate` even for
+     * field-triggered events.
+     */
+    supportsFieldScopedValidation: boolean;
+}
+/** @public */
+interface ValidationPipeline<TValues extends NativeFormValues = NativeFormValues> {
+    /**
+     * Declares optional runtime behavior flags for how this pipeline wants to be
+     * invoked.
+     */
+    readonly capabilities?: ValidationPipelineCapabilities;
+    /**
+     * @example
+     * const pipeline: ValidationPipeline = {
+     *   capabilities: { supportsFieldScopedValidation: false },
+     *   async validate(values) {
+     *     return { success: true, values };
+     *   },
+     *   async validateField(_field, values) {
+     *     return { success: true, values };
+     *   },
+     * };
+     */
+    /**
+     * Validates the full serialized values snapshot.
+     *
+     * Used for full-form validation flows (for example, submit).
+     */
+    validate(values: NativeFormValues, context: ValidationPipelineContext): ValidationResult<TValues> | Promise<ValidationResult<TValues>>;
+    /**
+     * Validates a field-triggered update with access to the active field and the
+     * full serialized snapshot.
+     *
+     * Used for input/change-triggered validation when supported.
+     */
+    validateField(field: ValidationFieldMeta, values: NativeFormValues, context: ValidationPipelineContext): ValidationResult<TValues> | Promise<ValidationResult<TValues>>;
+}
+/** @public */
+interface ValidationPipelineOptions<TValues extends NativeFormValues = NativeFormValues> {
+    schema?: SchemaLike<TValues>;
+    validator?: Validator<TValues>;
+}
+/** @public */
+declare function createValidationPipeline<TValues extends NativeFormValues = NativeFormValues>(options?: ValidationPipelineOptions<TValues>): ValidationPipeline<TValues>;
+
+/** @public */
+interface RuntimeOptions<TValues extends NativeFormValues = NativeFormValues> {
+    mode?: ValidationMode;
+    serializationMode?: SerializationMode;
+    serializeFieldsOptions?: SerializeFieldsOptions;
+    nesting?: "flat" | "nested";
+    /**
+     * When true, preserves serialized values of fields that are removed from the DOM,
+     * merging them into subsequent serializations and final submit.
+     * @defaultValue false
+     */
+    preserveUnmountedValues?: boolean;
+    schema?: SchemaLike<TValues>;
+    validator?: Validator<TValues>;
+    pipeline?: ValidationPipeline<TValues>;
+    debounceMs?: number;
+    asyncValidators?: Record<string, AsyncFieldValidator>;
+    onSubmit?: (values: TValues, event?: SubmitEvent) => void | Promise<void>;
+    onInvalid?: (errors: Record<string, string>, values: NativeFormValues, event?: SubmitEvent) => void;
+}
+/** @public */
+interface RuntimeFormState {
+    dirty: boolean;
+    touched: boolean;
+    valid: boolean;
+    submitting: boolean;
+    validating: boolean;
+    errors: Record<string, string>;
+    fields: FieldState[];
+    values: NativeFormFlatValues;
+}
+/** @public */
+interface RuntimePublicApi<TValues extends NativeFormValues = NativeFormValues> {
+    readonly fields: FieldState[];
+    readonly serializationMode: SerializationMode;
+    /**
+     * Preserved values from fields that have been unmounted from the DOM
+     * when `preserveUnmountedValues: true` is configured.
+     */
+    readonly preservedValues: Record<string, NativeFormValue>;
+    mount(form: HTMLFormElement): void;
+    unmount(): void;
+    serialize(): NativeFormFlatValues;
+    serializeFields(options?: SerializeFieldsOptions): NativeFormValues;
+    validate(): Promise<ValidationResult<TValues>>;
+    validateFields(fieldNames: readonly string[]): Promise<ValidationResult<TValues>>;
+    submit(event?: SubmitEvent): Promise<ValidationResult<TValues>>;
+    subscribe(listener: RuntimeListener): () => void;
+    unsubscribe(listener: RuntimeListener): void;
+    getFieldValue(name: string): NativeFormValue | undefined;
+    getFieldState(name: string): FieldState | undefined;
+    getFieldStates(): FieldState[];
+    getFormState(): RuntimeFormState;
+    setOptions(options: Partial<RuntimeOptions<TValues>>): void;
+    removeArrayItem(arrayName: string, index: number): void;
+    swapArrayItems(arrayName: string, indexA: number, indexB: number): void;
+    moveArrayItem(arrayName: string, fromIndex: number, toIndex: number): void;
+    insertArrayItem(arrayName: string, index: number): void;
+}
+/** @public */
+declare class Runtime<TValues extends NativeFormValues = NativeFormValues> implements RuntimePublicApi<TValues> {
+    private readonly options;
+    private readonly registry;
+    private readonly discovery;
+    private readonly serializer;
+    private readonly fieldErrorRenderer;
+    private form?;
+    private readonly listeners;
+    private observer?;
+    private validationController?;
+    private readonly debounceTimers;
+    private readonly fieldValidationControllers;
+    private submitting;
+    private validating;
+    private errors;
+    private preservedValuesStore;
+    private isSyncingFields;
+    private pipeline;
+    constructor(options?: RuntimeOptions<TValues>);
+    mount(form: HTMLFormElement): void;
+    unmount(): void;
+    private clearDebounceTimers;
+    private abortAllValidations;
+    private getAsyncValidator;
+    serialize(): NativeFormFlatValues;
+    serializeFields(options?: SerializeFieldsOptions): NativeFormValues;
+    get fields(): FieldState[];
+    get serializationMode(): SerializationMode;
+    get preservedValues(): Record<string, NativeFormValue>;
+    private extractCurrentValues;
+    subscribe(listener: RuntimeListener): () => void;
+    unsubscribe(listener: RuntimeListener): void;
+    private notify;
+    private emitFieldEvent;
+    private emitValidationEvent;
+    private emitFormEvent;
+    submit(event?: SubmitEvent): Promise<ValidationResult<TValues>>;
+    validate(): Promise<ValidationResult<TValues>>;
+    validateFields(fieldNames: readonly string[]): Promise<ValidationResult<TValues>>;
+    private handleSubmit;
+    private processSubmitFlow;
+    private runValidation;
+    private handleFieldUpdate;
+    private processInputFlow;
+    private processChangeFlow;
+    private processUpdateFlow;
+    private prepareFieldFlow;
+    private triggerFieldValidation;
+    private executeFieldValidation;
+    private handleFieldBlur;
+    private runFieldValidation;
+    private handleReset;
+    private processResetFlow;
+    getFieldState(name: string): FieldState | undefined;
+    getFieldStates(): FieldState[];
+    setOptions(options: Partial<RuntimeOptions<TValues>>): void;
+    removeArrayItem(arrayName: string, index: number): void;
+    swapArrayItems(arrayName: string, indexA: number, indexB: number): void;
+    moveArrayItem(arrayName: string, fromIndex: number, toIndex: number): void;
+    insertArrayItem(arrayName: string, index: number): void;
+    getFormState(): RuntimeFormState;
+    private ensureField;
+    getFieldValue(name: string): NativeFormValue | undefined;
+    private getValidationFields;
+    private toValidationField;
+    private syncFields;
+    private handleMutation;
+    private applyFieldValidationResult;
+    private applyValidationResult;
+    private applyNativeErrors;
+}
+
+/** @public */
+type FieldPathSegment = string | number;
+/** @public */
+interface ArrayItemPathInfo {
+    arrayName: string;
+    index: number;
+    subPath: string;
+}
+/** @public */
+declare function formPath(...segments: FieldPathSegment[]): string;
+/** @public */
+declare function arrayItemPath(arrayName: string, index: number, ...segments: FieldPathSegment[]): string;
+/**
+ * Splits any dot or bracket notation path into string segments.
+ *
+ * @example
+ * splitPath("user.name") // ["user", "name"]
+ * splitPath("user[profile][name]") // ["user", "profile", "name"]
+ * splitPath("items[0].title") // ["items", "0", "title"]
+ *
+ * @public
+ */
+declare function splitPath(path: string): string[];
+/**
+ * Normalizes any dot or bracket notation path into canonical dot notation.
+ *
+ * @example
+ * normalizePath("user[profile][name]") // "user.profile.name"
+ * normalizePath("tasks[0].title") // "tasks.0.title"
+ *
+ * @public
+ */
+declare function normalizePath(path: string): string;
+/** @public */
+declare function parseArrayItemPath(path: string): ArrayItemPathInfo | null;
+/** @public */
+declare function isArrayItemPath(path: string, arrayName?: string): boolean;
+/** @public */
+declare function matchArrayItemPath(path: string, arrayName: string): {
+    index: number;
+    subPath: string;
+} | null;
+/** @public */
+declare function shiftArrayItemIndex(path: string, arrayName: string, fromIndex: number, delta: number): string;
+/** @public */
+declare function remapArrayItemIndex(path: string, arrayName: string, oldIndex: number, newIndex: number): string;
+/**
+ * Safely accesses a value at a nested path inside an object or array.
+ *
+ * @param target - The root object or array
+ * @param path - Dot or bracket path string or segment array
+ * @param defaultValue - Optional fallback if the resolved value is undefined
+ *
+ * @public
+ */
+declare function getByPath(target: unknown, path: string | readonly string[], defaultValue?: unknown): unknown;
+/**
+ * Safely sets a value at a nested path, automatically creating intermediate
+ * objects or arrays (for numeric integer segments).
+ * Protects against prototype pollution by skipping __proto__, prototype, and constructor.
+ *
+ * @param target - The root object to modify
+ * @param path - Dot or bracket path string or segment array
+ * @param value - The value to assign
+ *
+ * @public
+ */
+declare function setByPath(target: Record<string, unknown>, path: string | readonly string[], value: unknown): void;
+/**
+ * Transforms a flat key-value map into deeply nested objects and arrays.
+ *
+ * @param flatValues - Flat map of field names to values
+ * @returns Deeply nested object/array structure
+ *
+ * @public
+ */
+declare function toNestedValues<TOutput extends Record<string, unknown> = Record<string, unknown>>(flatValues: Record<string, unknown>): TOutput;
+
+export { FieldNode, Runtime, Serializer, arrayItemPath, createValidationPipeline, createValidator, formPath, getByPath, isArrayItemPath, matchArrayItemPath, normalizePath, parseArrayItemPath, remapArrayItemIndex, setByPath, shiftArrayItemIndex, splitPath, toNestedValues };
+export type { ArrayItemPathInfo, AsyncFieldValidator, FieldEvents, FieldPathSegment, FieldState, FormEvents, InferSchemaOutput, NativeFormElement, NativeFormFlatValues, NativeFormNestedValue, NativeFormValue, NativeFormValues, RuntimeEvent, RuntimeEventType, RuntimeFormState, RuntimeListener, RuntimeOptions, RuntimePublicApi, SchemaLike, SerializationMode, SerializeFieldsOptions, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, ValidationContext, ValidationEvents, ValidationFieldMeta, ValidationIssue, ValidationMode, ValidationPipeline, ValidationPipelineCapabilities, ValidationPipelineContext, ValidationPipelineOptions, ValidationResult, Validator };