@neutro/form 0.0.4 → 0.1.0

package/dist/testing.d.cts

@@ -0,0 +1,254 @@
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+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;
+}
+
+/** Batch-sets multiple field values in one notification flush. */
+declare function fillForm<T extends object>(form: FormInstance<T>, values: Partial<Record<string, unknown>>): void;
+/**
+ * Marks a field as touched without changing its value.
+ *
+ * This simulates a user visiting and leaving a field. It does NOT trigger
+ * validation automatically — call triggerValidation() (or fixture.validate())
+ * afterwards to assert the resulting errors.
+ *
+ * Implementation note: form.set() is a no-op when the value is unchanged, so a
+ * unique sentinel object is used to force the touched flag, then the original
+ * value is restored. Both calls are wrapped in batch() so subscribers see only
+ * the final state.
+ */
+declare function blurField<T extends object>(form: FormInstance<T>, path: string): void;
+/**
+ * Runs form validation and returns whether the form is valid.
+ *
+ * Thin wrapper around form.validate() for discoverability. When using the
+ * standalone function (not createFormFixture), set asyncDebounceMs: 0 on the
+ * form to prevent tests from timing out on async validators.
+ */
+declare function triggerValidation<T extends object>(form: FormInstance<T>, paths?: string[]): Promise<boolean>;
+interface FormFixture<T extends object> {
+    form: FormInstance<T>;
+    fill(values: Partial<Record<string, unknown>>): void;
+    blur(path: string): void;
+    validate(paths?: string[]): Promise<boolean>;
+    cleanup(): void;
+}
+/**
+ * Creates a test fixture wrapping a form instance.
+ *
+ * Defaults asyncDebounceMs to 0 so async validators resolve in tests without
+ * fake timers. Pass asyncDebounceMs explicitly to override.
+ *
+ * @example
+ * const fixture = createFormFixture({ initialValues: { email: '' }, rules: { email: ['required'] } });
+ * afterEach(() => fixture.cleanup());
+ */
+declare function createFormFixture<T extends object>(config: FormConfig<T>): FormFixture<T>;
+
+export { type FormFixture, blurField, createFormFixture, fillForm, triggerValidation };

package/dist/testing.d.ts

@@ -0,0 +1,254 @@
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+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;
+}
+
+/** Batch-sets multiple field values in one notification flush. */
+declare function fillForm<T extends object>(form: FormInstance<T>, values: Partial<Record<string, unknown>>): void;
+/**
+ * Marks a field as touched without changing its value.
+ *
+ * This simulates a user visiting and leaving a field. It does NOT trigger
+ * validation automatically — call triggerValidation() (or fixture.validate())
+ * afterwards to assert the resulting errors.
+ *
+ * Implementation note: form.set() is a no-op when the value is unchanged, so a
+ * unique sentinel object is used to force the touched flag, then the original
+ * value is restored. Both calls are wrapped in batch() so subscribers see only
+ * the final state.
+ */
+declare function blurField<T extends object>(form: FormInstance<T>, path: string): void;
+/**
+ * Runs form validation and returns whether the form is valid.
+ *
+ * Thin wrapper around form.validate() for discoverability. When using the
+ * standalone function (not createFormFixture), set asyncDebounceMs: 0 on the
+ * form to prevent tests from timing out on async validators.
+ */
+declare function triggerValidation<T extends object>(form: FormInstance<T>, paths?: string[]): Promise<boolean>;
+interface FormFixture<T extends object> {
+    form: FormInstance<T>;
+    fill(values: Partial<Record<string, unknown>>): void;
+    blur(path: string): void;
+    validate(paths?: string[]): Promise<boolean>;
+    cleanup(): void;
+}
+/**
+ * Creates a test fixture wrapping a form instance.
+ *
+ * Defaults asyncDebounceMs to 0 so async validators resolve in tests without
+ * fake timers. Pass asyncDebounceMs explicitly to override.
+ *
+ * @example
+ * const fixture = createFormFixture({ initialValues: { email: '' }, rules: { email: ['required'] } });
+ * afterEach(() => fixture.cleanup());
+ */
+declare function createFormFixture<T extends object>(config: FormConfig<T>): FormFixture<T>;
+
+export { type FormFixture, blurField, createFormFixture, fillForm, triggerValidation };

package/dist/testing.js

@@ -0,0 +1,39 @@
+import {
+  be
+} from "./chunk-FDAQJJJ7.js";
+
+// ../testing/dist/index.js
+function fillForm(form, values) {
+  form.batch(() => {
+    for (const [path, value] of Object.entries(values)) {
+      form.set(path, value);
+    }
+  });
+}
+function blurField(form, path) {
+  const current = form.get(path);
+  const sentinel = /* @__PURE__ */ Object.create(null);
+  form.batch(() => {
+    form.set(path, sentinel, { touch: true });
+    form.set(path, current);
+  });
+}
+function triggerValidation(form, paths) {
+  return form.validate(paths);
+}
+function createFormFixture(config) {
+  const form = be({ ...config, asyncDebounceMs: config.asyncDebounceMs ?? 0 });
+  return {
+    form,
+    fill: (values) => fillForm(form, values),
+    blur: (path) => blurField(form, path),
+    validate: (paths) => triggerValidation(form, paths),
+    cleanup: () => form.destroy()
+  };
+}
+export {
+  blurField,
+  createFormFixture,
+  fillForm,
+  triggerValidation
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutro/form",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "High-performance, zero-dependency, framework-agnostic reactive form engine.",
   "keywords": [
     "form",
@@ -23,12 +23,18 @@
     "README.md"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     "./core": {
       "types": "./dist/core.d.ts",
       "import": "./dist/core.js",
       "require": "./dist/core.cjs"
     },
+    "./devtools": {
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js",
+      "require": "./dist/devtools.cjs"
+    },
     "./adapters/react": {
       "types": "./dist/adapters/react.d.ts",
       "import": "./dist/adapters/react.js",
@@ -53,6 +59,11 @@
       "types": "./dist/adapters/angular.d.ts",
       "import": "./dist/adapters/angular.js",
       "require": "./dist/adapters/angular.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
     }
   },
   "typesVersions": {
@@ -60,6 +71,9 @@
       "core": [
         "./dist/core.d.ts"
       ],
+      "devtools": [
+        "./dist/devtools.d.ts"
+      ],
       "adapters/react": [
         "./dist/adapters/react.d.ts"
       ],
@@ -74,6 +88,9 @@
       ],
       "adapters/angular": [
         "./dist/adapters/angular.d.ts"
+      ],
+      "testing": [
+        "./dist/testing.d.ts"
       ]
     }
   },
@@ -107,12 +124,13 @@
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "@neutro/form-core": "0.0.1",
-    "@neutro/form-react": "0.0.1",
-    "@neutro/form-vue": "0.0.1",
-    "@neutro/form-svelte": "0.0.1",
-    "@neutro/form-angular": "0.0.1",
-    "@neutro/form-solid": "0.0.1"
+    "@neutro/form-core": "0.1.0",
+    "@neutro/form-vue": "0.1.0",
+    "@neutro/form-solid": "0.1.0",
+    "@neutro/form-angular": "0.1.0",
+    "@neutro/form-svelte": "0.1.0",
+    "@neutro/form-testing": "0.1.0",
+    "@neutro/form-react": "0.1.0"
   },
   "scripts": {
     "build": "tsup"