Introduce more options

Author: agjs

README.md

@@ -14,20 +14,24 @@ This library is a part of the toolkit used extensively on [Programmer Network](h
 - **Plugin Extensibility**: Supports Ajv [plugins](https://ajv.js.org/packages/) for custom validators, enhancing schema flexibility.
 - **Design Agnostic**: Offers full freedom in how you structure, style, and handle your forms.
 
-## Features
-
-- **JSON Schema Validation**: Validates form data against a specified JSON schema.
-- **Dirty State Tracking**: Identifies changes in form fields.
-- **Remote Error Handling**: Manages errors from external sources (like APIs) as part of schema validation.
-
 ## Installation
 
 ```bash
 pnpm add @programmer_network/use-ajv-form
-# or
-bun install @programmer_network/use-ajv-form
-# or
-yarn add @programmer_network/use-ajv-form
-# or
-npm install @programmer_network/use-ajv-form
 ```
+
+## Options
+
+Below is a table describing the options you can pass to `useAJVForm`:
+
+| Option                      | Type                                 | Description                                                                                            |
+| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `customKeywords`            | `KeywordDefinition[]`                | Custom AJV keywords for additional validation logic.                                                   |
+| `errors`                    | `ErrorObject[]`                      | Pre-defined errors to set initial form errors. This could also be errors originating from your API.    |
+| `userDefinedMessages`       | `Record<string, AJVMessageFunction>` | Custom error messages for validation errors.                                                           |
+| `shouldDebounceAndValidate` | `boolean`                            | If `true`, enables debouncing for field validation.                                                    |
+| `debounceTime`              | `number`                             | Time in milliseconds for debouncing validation. Ignore if `shouldDebounceAndValidate` is set to false. |
+
+## Usage
+
+Here's a basic example of using `useAJVForm` inside of our [Yail Storybook](https://yail.programmer.network/?path=/story/input-forms--use-ajv-form)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programmer_network/use-ajv-form",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Custom React Hook that integrates with Ajv JSON Schema Validator",
   "main": "dist/use-ajv-form.es.js",
   "author": "Aleksandar Grbic",
@@ -73,13 +73,13 @@
     "husky": "8.0.3",
     "jsdom": "22.1.0",
     "prettier": "3.0.3",
+    "programmer-network-ajv": "github:Programmer-Network/Programmer-Network-AJV",
     "react-hooks": "link:@types/@testing-library/react-hooks",
     "typescript": "5.2.2",
     "vite": "5.0.2",
     "vite-plugin-dts": "3.6.3",
     "vite-tsconfig-paths": "4.2.1",
-    "vitest": "0.34.6",
-    "programmer-network-ajv": "github:Programmer-Network/Programmer-Network-AJV"
+    "vitest": "0.34.6"
   },
   "files": [
     "dist"

src/index.ts

@@ -19,6 +19,8 @@ const useAJVForm = <T extends Record<string, any>>(
     customKeywords?: KeywordDefinition[];
     errors?: ErrorObject[];
     userDefinedMessages?: Record<string, AJVMessageFunction>;
+    shouldDebounceAndValidate?: boolean;
+    debounceTime?: number;
   },
 ): UseFormReturn<T> => {
   const initialStateRef = useRef<IState<T>>(getInitial(initial));
@@ -30,7 +32,7 @@ const useAJVForm = <T extends Record<string, any>>(
     editId: number;
   } | null>(null);
   const [editCounter, setEditCounter] = useState(0);
-  const debouncedField = useDebounce(currentField, 500);
+  const debouncedField = useDebounce(currentField, options?.debounceTime || 500);
 
   if (options?.customKeywords?.length) {
     addUserDefinedKeywords(ajv, options.customKeywords);
@@ -151,15 +153,23 @@ const useAJVForm = <T extends Record<string, any>>(
     );
   };
 
+  const isFormValid = (currentState: IState<T>): boolean => {
+    return !Object.keys(currentState).some((key) => currentState[key].error !== '');
+  };
+
   const isDirty = useMemo(
     () => isFormDirty(state, initialStateRef.current),
     [state],
   );
 
+  const isValid = useMemo(() => isFormValid(state), [state]);
+
   useEffect(() => {
-    if (debouncedField) {
-      validateField(debouncedField.name);
+    if (options?.shouldDebounceAndValidate === false || !debouncedField) {
+      return;
     }
+
+    validateField(debouncedField.name);
   }, [debouncedField]);
 
   useEffect(() => {
@@ -175,6 +185,7 @@ const useAJVForm = <T extends Record<string, any>>(
     set: setFormState,
     validate: validateForm,
     onBlur: handleBlur,
+    isValid,
     isDirty,
     state,
   };

src/useAjvForm.test.tsx

@@ -225,6 +225,45 @@ describe('useAJVForm', () => {
     expect(result.current.state.title.error).not.toBe('');
   });
 
+  it('should not validate and debounce if shouldDebounceAndValidate is set to false', async () => {
+    const initialData = { title: '' };
+    const schema: JSONSchemaType<{ title: string }> = {
+      type: 'object',
+      required: ['title'],
+      properties: {
+        title: { type: 'string', minLength: 3 },
+      },
+    };
+
+    const { result } = renderHook(() => useAJVForm(initialData, schema));
+
+    result.current.set({ title: 'Hi' });
+    expect(result.current.state.title.error).toBe('');
+  });
+
+  it('should use debounceTime argument for the useDebounce', async () => {
+    const initialData = { title: '' };
+    const schema: JSONSchemaType<{ title: string }> = {
+      type: 'object',
+      required: ['title'],
+      properties: {
+        title: { type: 'string', minLength: 3 },
+      },
+    };
+
+    const { result } = renderHook(() =>
+      useAJVForm(initialData, schema, { debounceTime: 1000 }),
+    );
+
+    result.current.set({ title: 'Hi' });
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+
+    expect(result.current.state.title.error).not.toBe('');
+  });
+
   it('validates immediately on blur event', () => {
     const initialData = { title: '' };
     const schema: JSONSchemaType<{ title: string }> = {
@@ -244,4 +283,54 @@ describe('useAJVForm', () => {
       'Should be at least 3 characters long.',
     );
   });
+
+  it('should overwrite the existing error message by providing userDefinedMessages', () => {
+    const initialData = { title: '' };
+    const schema: JSONSchemaType<{ title: string }> = {
+      type: 'object',
+      required: ['title'],
+      properties: {
+        title: { type: 'string', minLength: 3 },
+      },
+    };
+
+    const { result } = renderHook(() =>
+      useAJVForm(initialData, schema, {
+        userDefinedMessages: {
+          minLength: () => 'Monkey message',
+        },
+      }),
+    );
+
+    result.current.set({ title: 'Hi' });
+    result.current.onBlur('title');
+
+    expect(result.current.state.title.error).toBe('Monkey message');
+  });
+
+  it('should correctly update isValid based on form errors', () => {
+    const initialData = { title: '' };
+    const schema: JSONSchemaType<{ title: string }> = {
+      type: 'object',
+      required: ['title'],
+      properties: {
+        title: { type: 'string', minLength: 3 },
+      },
+    };
+
+    const { result } = renderHook(() => useAJVForm(initialData, schema));
+
+    result.current.validate();
+
+    expect(result.current.isValid).toBe(false);
+
+    result.current.set({ title: 'Hello' });
+    result.current.onBlur('title');
+
+    expect(result.current.isValid).toBe(true);
+    result.current.set({ title: 'Hi' });
+    result.current.onBlur('title');
+
+    expect(result.current.isValid).toBe(false);
+  });
 });

src/utils/types.ts

@@ -59,5 +59,6 @@ export interface UseFormReturn<T> {
   reset: () => void;
   validate: () => ValidateResult<T>;
   isDirty: boolean;
+  isValid: boolean;
   onBlur: (fieldName: string) => void;
 }