@neutro/form 0.0.5 → 0.1.0

package/dist/core.d.cts

@@ -10,7 +10,7 @@ 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) : T[K] extends object ? K | `${K}.${PathImpl<T[K], keyof T[K], Prev[Depth]>}` : K : never;
+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>;
@@ -23,7 +23,7 @@ interface FormState<T> {
     isValidating: boolean;
 }
 type FormSubscriber<T> = (state: FormState<T>) => void;
-type PathSubscriber = (value: any, fieldState: {
+type PathSubscriber<V = any> = (value: V, fieldState: {
     error?: string;
     touched?: boolean;
     dirty?: boolean;
@@ -92,21 +92,98 @@ type BuiltInRule = 'required' | 'accepted' | 'email' | 'url' | 'numeric' | 'inte
     requiredUnless: string;
     message?: string;
 };
-interface FormConfig<T> {
+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<string, BuiltInRule | BuiltInRule[]>>;
+    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: (path: Path<T> | string, fn: PathSubscriber) => () => void;
-    get: (path: Path<T> | string | string[]) => any;
+    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;
@@ -117,6 +194,7 @@ interface FormInstance<T extends object> {
     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;
@@ -126,6 +204,15 @@ interface FormInstance<T extends object> {
     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;
@@ -158,4 +245,4 @@ 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 BuiltInRule, type ConnectOptions, type DeepPartial, type FormConfig, type FormInstance, type FormState, type FormSubscriber, type GetPathValue, type Path, type PathImpl, type PathSubscriber, type Primitive, classValidatorAdapter, compileDependencyScopes, createForm, deepClone, extractAllPaths, getNestedValue, isDeepEqual, setNestedValue, valibotAdapter, yupAdapter, zodAdapter };
+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

@@ -10,7 +10,7 @@ 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) : T[K] extends object ? K | `${K}.${PathImpl<T[K], keyof T[K], Prev[Depth]>}` : K : never;
+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>;
@@ -23,7 +23,7 @@ interface FormState<T> {
     isValidating: boolean;
 }
 type FormSubscriber<T> = (state: FormState<T>) => void;
-type PathSubscriber = (value: any, fieldState: {
+type PathSubscriber<V = any> = (value: V, fieldState: {
     error?: string;
     touched?: boolean;
     dirty?: boolean;
@@ -92,21 +92,98 @@ type BuiltInRule = 'required' | 'accepted' | 'email' | 'url' | 'numeric' | 'inte
     requiredUnless: string;
     message?: string;
 };
-interface FormConfig<T> {
+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<string, BuiltInRule | BuiltInRule[]>>;
+    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: (path: Path<T> | string, fn: PathSubscriber) => () => void;
-    get: (path: Path<T> | string | string[]) => any;
+    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;
@@ -117,6 +194,7 @@ interface FormInstance<T extends object> {
     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;
@@ -126,6 +204,15 @@ interface FormInstance<T extends object> {
     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;
@@ -158,4 +245,4 @@ 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 BuiltInRule, type ConnectOptions, type DeepPartial, type FormConfig, type FormInstance, type FormState, type FormSubscriber, type GetPathValue, type Path, type PathImpl, type PathSubscriber, type Primitive, classValidatorAdapter, compileDependencyScopes, createForm, deepClone, extractAllPaths, getNestedValue, isDeepEqual, setNestedValue, valibotAdapter, yupAdapter, zodAdapter };
+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 };