@neutro/form 0.0.4 → 0.1.0

package/dist/core.d.cts

@@ -1 +1,248 @@
-export * from '@neutro/form-core';
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer U> ? _DeepPartialArray<U> : T extends object ? _DeepPartialObject<T> : T | undefined;
+interface _DeepPartialArray<T> extends Array<DeepPartial<T>> {
+}
+type _DeepPartialObject<T> = {
+    [P in keyof T]?: DeepPartial<T[P]>;
+};
+type Prev = [never, 0, 1, 2, 3, 4, 5, ...any[]];
+type PathImpl<T, K extends keyof T, Depth extends number = 5> = [Depth] extends [never] ? never : K extends string ? T[K] extends Primitive ? K : T[K] extends Array<infer U> ? K | `${K}.${number}` | (U extends object ? `${K}.${number}.${PathImpl<U, keyof U, Prev[Depth]>}` : never) : NonNullable<T[K]> extends object ? K | `${K}.${PathImpl<NonNullable<T[K]>, keyof NonNullable<T[K]>, Prev[Depth]>}` : K : never;
+type Path<T> = PathImpl<T, keyof T> & string;
+type _GetPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? _GetPathValue<NonNullable<T[K]>, Rest> : T extends readonly any[] ? _GetPathValue<NonNullable<T[number]>, Rest> : unknown : P extends keyof T ? T[P] : T extends readonly any[] ? T[number] : unknown;
+type GetPathValue<T, P extends string> = _GetPathValue<T, P>;
+interface FormState<T> {
+    values: T;
+    errors: Record<string, string>;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    isSubmitting: boolean;
+    isValidating: boolean;
+}
+type FormSubscriber<T> = (state: FormState<T>) => void;
+type PathSubscriber<V = any> = (value: V, fieldState: {
+    error?: string;
+    touched?: boolean;
+    dirty?: boolean;
+}) => void;
+type BuiltInRule = 'required' | 'accepted' | 'email' | 'url' | 'numeric' | 'integer' | 'positive' | 'nonNegative' | 'alpha' | 'alphanumeric' | 'date' | {
+    minLength: number;
+    message?: string;
+} | {
+    maxLength: number;
+    message?: string;
+} | {
+    min: number;
+    message?: string;
+} | {
+    max: number;
+    message?: string;
+} | {
+    startsWith: string;
+    message?: string;
+} | {
+    endsWith: string;
+    message?: string;
+} | {
+    includes: string;
+    message?: string;
+} | {
+    pattern: string | RegExp;
+    message?: string;
+} | {
+    minItems: number;
+    message?: string;
+} | {
+    maxItems: number;
+    message?: string;
+} | 'unique' | {
+    contains: unknown;
+    message?: string;
+} | {
+    oneOf: unknown[];
+    message?: string;
+} | {
+    notOneOf: unknown[];
+    message?: string;
+} | {
+    matches: string;
+    message?: string;
+} | {
+    doesNotMatch: string;
+    message?: string;
+} | {
+    greaterThan: string;
+    message?: string;
+} | {
+    lessThan: string;
+    message?: string;
+} | {
+    after: string;
+    message?: string;
+} | {
+    before: string;
+    message?: string;
+} | {
+    requiredIf: string;
+    message?: string;
+} | {
+    requiredUnless: string;
+    message?: string;
+};
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmitOnly';
+interface ValidationModeConfig<T extends object> {
+    default?: ValidationMode;
+    fields?: Partial<Record<Path<T> | (string & {}), ValidationMode>>;
+}
+type FormAction = {
+    type: 'SET';
+    path: string;
+    value: unknown;
+    options?: {
+        touch?: boolean;
+        validate?: boolean;
+    };
+} | {
+    type: 'VALIDATE';
+    paths?: string[];
+} | {
+    type: 'SUBMIT';
+} | {
+    type: 'RESET';
+    newValues?: unknown;
+} | {
+    type: 'SET_ERRORS';
+    errors: Record<string, string>;
+} | {
+    type: 'CONNECT';
+    path: string;
+} | {
+    type: 'DISCONNECT';
+    path: string;
+} | {
+    type: 'BLUR';
+    path: string;
+} | {
+    type: 'BATCH_START';
+} | {
+    type: 'BATCH_END';
+} | {
+    type: 'ARRAY_APPEND';
+    path: string;
+    item: unknown;
+} | {
+    type: 'ARRAY_INSERT';
+    path: string;
+    index: number;
+    item: unknown;
+} | {
+    type: 'ARRAY_REMOVE';
+    path: string;
+    index: number;
+} | {
+    type: 'ARRAY_MOVE';
+    path: string;
+    from: number;
+    to: number;
+} | {
+    type: 'ARRAY_SWAP';
+    path: string;
+    i: number;
+    j: number;
+} | {
+    type: 'CLEAR_ERRORS';
+};
+interface AriaPropsOptions {
+    required?: boolean;
+    errorId?: string;
+}
+interface AriaProps {
+    'aria-invalid': 'true' | 'false';
+    'aria-describedby': string | undefined;
+    'aria-required': true | undefined;
+}
+interface FormConfig<T extends object> {
+    initialValues: T;
+    rules?: Partial<Record<Path<T> | (string & {}), BuiltInRule | BuiltInRule[]>>;
+    validator?: (values: T, scopePaths?: string[], signal?: AbortSignal) => Record<string, string> | Promise<Record<string, string>>;
+    dependencies?: Record<string, string[]>;
+    asyncDebounceMs?: number;
+    /** Per-field validation trigger mode. Defaults to 'onTouched'. */
+    validationMode?: ValidationMode | ValidationModeConfig<T>;
+}
+interface ConnectOptions {
+    persist?: boolean;
+    format?: (val: string) => string;
+    validateOn?: ValidationMode;
+}
+interface FormInstance<T extends object> {
+    subscribe: (fn: FormSubscriber<T>) => () => void;
+    subscribeToPath<P extends Path<T>>(path: P, fn: PathSubscriber<GetPathValue<T, P>>): () => void;
+    subscribeToPath(path: string, fn: PathSubscriber): () => void;
+    get<P extends Path<T>>(path: P): GetPathValue<T, P>;
+    get(path: string | string[]): any;
+    set: (path: Path<T> | string | string[], val: any, options?: {
+        touch?: boolean;
+        validate?: boolean;
+    }) => void;
+    validate: (scopePaths?: Path<T>[] | string[] | string[][]) => Promise<boolean>;
+    connect: (path: Path<T> | string, el: HTMLElement, options?: ConnectOptions) => () => void;
+    submit: (onValid: (payload: Partial<T>) => void | Promise<void>) => Promise<boolean>;
+    handleSubmit: (onValid: (payload: Partial<T>) => void | Promise<void>, onInvalid?: (errors: Record<string, string>) => void) => (e?: Event) => void;
+    getState: () => FormState<T>;
+    getPayload: () => Partial<T>;
+    getAriaProps: (path: Path<T> | string, options?: AriaPropsOptions) => AriaProps;
+    batch: (fn: () => void) => void;
+    arrayAppend: (path: Path<T> | string | string[], item: any) => void;
+    arrayInsert: (path: Path<T> | string | string[], index: number, item: any) => void;
+    arrayRemove: (path: Path<T> | string | string[], index: number) => void;
+    arrayMove: (path: Path<T> | string | string[], fromIndex: number, toIndex: number) => void;
+    arraySwap: (path: Path<T> | string | string[], indexA: number, indexB: number) => void;
+    reset: (newValues?: T) => void;
+    getConnectedCount: () => number;
+    destroy: () => void;
+    setErrors: (errors: Record<Path<T> | (string & {}), string>) => void;
+    clearErrors: () => void;
+    /**
+     * Returns the effective ValidationMode for a field. Useful for debugging
+     * validation timing; framework adapters should rely on this only in custom
+     * event handlers, not in render logic.
+     */
+    getFieldMode: (path: string) => ValidationMode;
+    _subscribeToActions: (fn: (action: FormAction, state: FormState<T>) => void) => () => void;
+}
+declare function zodAdapter<T>(schema: {
+    safeParse: (values: T) => any;
+}): (values: T) => Record<string, string>;
+declare function valibotAdapter<T>(schema: {
+    safeParse: (values: T) => {
+        success: boolean;
+        issues?: Array<{
+            path: Array<{
+                key: string | number;
+            }>;
+            message: string;
+        }>;
+    };
+}): (values: T) => Record<string, string>;
+declare function yupAdapter<T>(schema: {
+    validate: (values: T, options: {
+        abortEarly: boolean;
+    }) => Promise<any>;
+}): (values: T) => Promise<Record<string, string>>;
+declare function classValidatorAdapter<T extends object>(cls: new () => T, validate: (obj: T) => Promise<Array<{
+    property: string;
+    constraints?: Record<string, string>;
+}>>): (values: T) => Promise<Record<string, string>>;
+declare function deepClone<T>(val: T, hash?: WeakMap<object, any>): T;
+declare function getNestedValue(obj: any, path: string): any;
+declare function setNestedValue(obj: any, path: string, value: any): void;
+declare function isDeepEqual(a: any, b: any, hash?: WeakMap<object, any>): boolean;
+declare function extractAllPaths(obj: any, prefix?: string): string[];
+declare function compileDependencyScopes(dependencies: Record<string, string[]>, initialValues: any): Record<string, string[]>;
+declare function createForm<T extends object>(config: FormConfig<T>): FormInstance<T>;
+
+export { type AriaProps, type AriaPropsOptions, type BuiltInRule, type ConnectOptions, type DeepPartial, type FormAction, type FormConfig, type FormInstance, type FormState, type FormSubscriber, type GetPathValue, type Path, type PathImpl, type PathSubscriber, type Primitive, type ValidationMode, type ValidationModeConfig, classValidatorAdapter, compileDependencyScopes, createForm, deepClone, extractAllPaths, getNestedValue, isDeepEqual, setNestedValue, valibotAdapter, yupAdapter, zodAdapter };

package/dist/core.d.ts

@@ -1 +1,248 @@
-export * from '@neutro/form-core';
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer U> ? _DeepPartialArray<U> : T extends object ? _DeepPartialObject<T> : T | undefined;
+interface _DeepPartialArray<T> extends Array<DeepPartial<T>> {
+}
+type _DeepPartialObject<T> = {
+    [P in keyof T]?: DeepPartial<T[P]>;
+};
+type Prev = [never, 0, 1, 2, 3, 4, 5, ...any[]];
+type PathImpl<T, K extends keyof T, Depth extends number = 5> = [Depth] extends [never] ? never : K extends string ? T[K] extends Primitive ? K : T[K] extends Array<infer U> ? K | `${K}.${number}` | (U extends object ? `${K}.${number}.${PathImpl<U, keyof U, Prev[Depth]>}` : never) : NonNullable<T[K]> extends object ? K | `${K}.${PathImpl<NonNullable<T[K]>, keyof NonNullable<T[K]>, Prev[Depth]>}` : K : never;
+type Path<T> = PathImpl<T, keyof T> & string;
+type _GetPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? _GetPathValue<NonNullable<T[K]>, Rest> : T extends readonly any[] ? _GetPathValue<NonNullable<T[number]>, Rest> : unknown : P extends keyof T ? T[P] : T extends readonly any[] ? T[number] : unknown;
+type GetPathValue<T, P extends string> = _GetPathValue<T, P>;
+interface FormState<T> {
+    values: T;
+    errors: Record<string, string>;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    isSubmitting: boolean;
+    isValidating: boolean;
+}
+type FormSubscriber<T> = (state: FormState<T>) => void;
+type PathSubscriber<V = any> = (value: V, fieldState: {
+    error?: string;
+    touched?: boolean;
+    dirty?: boolean;
+}) => void;
+type BuiltInRule = 'required' | 'accepted' | 'email' | 'url' | 'numeric' | 'integer' | 'positive' | 'nonNegative' | 'alpha' | 'alphanumeric' | 'date' | {
+    minLength: number;
+    message?: string;
+} | {
+    maxLength: number;
+    message?: string;
+} | {
+    min: number;
+    message?: string;
+} | {
+    max: number;
+    message?: string;
+} | {
+    startsWith: string;
+    message?: string;
+} | {
+    endsWith: string;
+    message?: string;
+} | {
+    includes: string;
+    message?: string;
+} | {
+    pattern: string | RegExp;
+    message?: string;
+} | {
+    minItems: number;
+    message?: string;
+} | {
+    maxItems: number;
+    message?: string;
+} | 'unique' | {
+    contains: unknown;
+    message?: string;
+} | {
+    oneOf: unknown[];
+    message?: string;
+} | {
+    notOneOf: unknown[];
+    message?: string;
+} | {
+    matches: string;
+    message?: string;
+} | {
+    doesNotMatch: string;
+    message?: string;
+} | {
+    greaterThan: string;
+    message?: string;
+} | {
+    lessThan: string;
+    message?: string;
+} | {
+    after: string;
+    message?: string;
+} | {
+    before: string;
+    message?: string;
+} | {
+    requiredIf: string;
+    message?: string;
+} | {
+    requiredUnless: string;
+    message?: string;
+};
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmitOnly';
+interface ValidationModeConfig<T extends object> {
+    default?: ValidationMode;
+    fields?: Partial<Record<Path<T> | (string & {}), ValidationMode>>;
+}
+type FormAction = {
+    type: 'SET';
+    path: string;
+    value: unknown;
+    options?: {
+        touch?: boolean;
+        validate?: boolean;
+    };
+} | {
+    type: 'VALIDATE';
+    paths?: string[];
+} | {
+    type: 'SUBMIT';
+} | {
+    type: 'RESET';
+    newValues?: unknown;
+} | {
+    type: 'SET_ERRORS';
+    errors: Record<string, string>;
+} | {
+    type: 'CONNECT';
+    path: string;
+} | {
+    type: 'DISCONNECT';
+    path: string;
+} | {
+    type: 'BLUR';
+    path: string;
+} | {
+    type: 'BATCH_START';
+} | {
+    type: 'BATCH_END';
+} | {
+    type: 'ARRAY_APPEND';
+    path: string;
+    item: unknown;
+} | {
+    type: 'ARRAY_INSERT';
+    path: string;
+    index: number;
+    item: unknown;
+} | {
+    type: 'ARRAY_REMOVE';
+    path: string;
+    index: number;
+} | {
+    type: 'ARRAY_MOVE';
+    path: string;
+    from: number;
+    to: number;
+} | {
+    type: 'ARRAY_SWAP';
+    path: string;
+    i: number;
+    j: number;
+} | {
+    type: 'CLEAR_ERRORS';
+};
+interface AriaPropsOptions {
+    required?: boolean;
+    errorId?: string;
+}
+interface AriaProps {
+    'aria-invalid': 'true' | 'false';
+    'aria-describedby': string | undefined;
+    'aria-required': true | undefined;
+}
+interface FormConfig<T extends object> {
+    initialValues: T;
+    rules?: Partial<Record<Path<T> | (string & {}), BuiltInRule | BuiltInRule[]>>;
+    validator?: (values: T, scopePaths?: string[], signal?: AbortSignal) => Record<string, string> | Promise<Record<string, string>>;
+    dependencies?: Record<string, string[]>;
+    asyncDebounceMs?: number;
+    /** Per-field validation trigger mode. Defaults to 'onTouched'. */
+    validationMode?: ValidationMode | ValidationModeConfig<T>;
+}
+interface ConnectOptions {
+    persist?: boolean;
+    format?: (val: string) => string;
+    validateOn?: ValidationMode;
+}
+interface FormInstance<T extends object> {
+    subscribe: (fn: FormSubscriber<T>) => () => void;
+    subscribeToPath<P extends Path<T>>(path: P, fn: PathSubscriber<GetPathValue<T, P>>): () => void;
+    subscribeToPath(path: string, fn: PathSubscriber): () => void;
+    get<P extends Path<T>>(path: P): GetPathValue<T, P>;
+    get(path: string | string[]): any;
+    set: (path: Path<T> | string | string[], val: any, options?: {
+        touch?: boolean;
+        validate?: boolean;
+    }) => void;
+    validate: (scopePaths?: Path<T>[] | string[] | string[][]) => Promise<boolean>;
+    connect: (path: Path<T> | string, el: HTMLElement, options?: ConnectOptions) => () => void;
+    submit: (onValid: (payload: Partial<T>) => void | Promise<void>) => Promise<boolean>;
+    handleSubmit: (onValid: (payload: Partial<T>) => void | Promise<void>, onInvalid?: (errors: Record<string, string>) => void) => (e?: Event) => void;
+    getState: () => FormState<T>;
+    getPayload: () => Partial<T>;
+    getAriaProps: (path: Path<T> | string, options?: AriaPropsOptions) => AriaProps;
+    batch: (fn: () => void) => void;
+    arrayAppend: (path: Path<T> | string | string[], item: any) => void;
+    arrayInsert: (path: Path<T> | string | string[], index: number, item: any) => void;
+    arrayRemove: (path: Path<T> | string | string[], index: number) => void;
+    arrayMove: (path: Path<T> | string | string[], fromIndex: number, toIndex: number) => void;
+    arraySwap: (path: Path<T> | string | string[], indexA: number, indexB: number) => void;
+    reset: (newValues?: T) => void;
+    getConnectedCount: () => number;
+    destroy: () => void;
+    setErrors: (errors: Record<Path<T> | (string & {}), string>) => void;
+    clearErrors: () => void;
+    /**
+     * Returns the effective ValidationMode for a field. Useful for debugging
+     * validation timing; framework adapters should rely on this only in custom
+     * event handlers, not in render logic.
+     */
+    getFieldMode: (path: string) => ValidationMode;
+    _subscribeToActions: (fn: (action: FormAction, state: FormState<T>) => void) => () => void;
+}
+declare function zodAdapter<T>(schema: {
+    safeParse: (values: T) => any;
+}): (values: T) => Record<string, string>;
+declare function valibotAdapter<T>(schema: {
+    safeParse: (values: T) => {
+        success: boolean;
+        issues?: Array<{
+            path: Array<{
+                key: string | number;
+            }>;
+            message: string;
+        }>;
+    };
+}): (values: T) => Record<string, string>;
+declare function yupAdapter<T>(schema: {
+    validate: (values: T, options: {
+        abortEarly: boolean;
+    }) => Promise<any>;
+}): (values: T) => Promise<Record<string, string>>;
+declare function classValidatorAdapter<T extends object>(cls: new () => T, validate: (obj: T) => Promise<Array<{
+    property: string;
+    constraints?: Record<string, string>;
+}>>): (values: T) => Promise<Record<string, string>>;
+declare function deepClone<T>(val: T, hash?: WeakMap<object, any>): T;
+declare function getNestedValue(obj: any, path: string): any;
+declare function setNestedValue(obj: any, path: string, value: any): void;
+declare function isDeepEqual(a: any, b: any, hash?: WeakMap<object, any>): boolean;
+declare function extractAllPaths(obj: any, prefix?: string): string[];
+declare function compileDependencyScopes(dependencies: Record<string, string[]>, initialValues: any): Record<string, string[]>;
+declare function createForm<T extends object>(config: FormConfig<T>): FormInstance<T>;
+
+export { type AriaProps, type AriaPropsOptions, type BuiltInRule, type ConnectOptions, type DeepPartial, type FormAction, type FormConfig, type FormInstance, type FormState, type FormSubscriber, type GetPathValue, type Path, type PathImpl, type PathSubscriber, type Primitive, type ValidationMode, type ValidationModeConfig, classValidatorAdapter, compileDependencyScopes, createForm, deepClone, extractAllPaths, getNestedValue, isDeepEqual, setNestedValue, valibotAdapter, yupAdapter, zodAdapter };