gform-react 2.7.2 → 2.8.0

package/README.md

@@ -1,42 +1,119 @@
-# GForm
-
-![gform-react](https://gform-react.onrender.com/gform-logo.png)
-
-![npm bundle size](https://img.shields.io/bundlephobia/min/gform-react?label=minified%20size&color=darkergreen)
-![npm bundle size](https://img.shields.io/bundlephobia/minzip/gform-react?label=gzip%20size&color=darkergreen)
-![npm peer dependency version](https://img.shields.io/npm/dependency-version/gform-react/peer/react)
-![npm peer dependency version](https://img.shields.io/npm/dependency-version/gform-react/peer/react-dom)
-[![NPM](https://img.shields.io/npm/l/gform-react)](https://unpkg.com/gform-react@latest/LICENSE.md)
-
-#### build generic forms with validations for react-based applications.
-it doesn't matter which UI library you're using,
-it only cares about the form and the inputs inside.
-
-## Pros
-* Lightweight
-* Based on native form and constraint validations (can also add custom and async validations)
-* Can be used with any UI library that preserves native form controls (input, button, etc. can also be adjusted to non-native controls)
-* Tree shakeable
-* Accessibility semi-automatic (required inputs and invalid inputs automatically sets aria-required and aria-invalid)
-* React Native support
-* Supports React 19, Next.js 15
-
-## Docs
+<div align="center">
+    <a href="https://gform-react.onrender.com" title="GForm React – A lightweight React form library built for performance, validation, and clean form logic">
+        <img src="https://gform-react.onrender.com/gform-logo.png" alt="gform-react logo" />
+    </a>
+    <h1>gform-react</h1>
+    <p>A lightweight React form library built for <b>performance</b>, <b>validation</b>, and clean <b>form logic</b></p>
+</div>
+
+## Features
+
+- **Lightweight**
+- **Tree‑shakable** — import only what you use to keep bundles small
+- **Minimal re-renders** — updates only the fields that actually change
+- **Native HTML constraint validation** — full support for `min`, `max`, `pattern`, `minLength`, `maxLength`, `required`, and more
+- **Custom Validations** – add custom validation with any rules
+- **Async Validations** — run asynchronous rules for server-side checks
+- **Supports Yup, Zod, and more** – use any validation library you like
+- **Deeply Nested Forms** — structure forms however you like, across any number of components
+- **Dynamic fields** — add or remove fields at runtime without losing state
+- **Native `<form>` actions** — fully supports browser‑level form submission, including action, method, and HTTP navigation, with no JavaScript required
+- **Next.js Server Actions support** — works seamlessly with Server Actions through standard `<form>` submissions, with no special adapters or client‑side wiring
+- **Accessibility‑friendly** — automatically manages `aria-required` and `aria-invalid`
+- **React Native support** — works seamlessly across web and mobile
+ 
+<br/>
+<div align="center">
+  <a href="https://unpkg.com/gform-react@latest/dist/cjs/gform-react.production.js">
+    <img src="http://img.badgesize.io/https://unpkg.com/gform-react@latest/dist/cjs/gform-react.production.js?compression=gzip&style=for-the-badge" alt="Minified size">
+  </a>
+  
+  <img src="https://img.shields.io/npm/dt/gform-react.svg?style=for-the-badge" alt="React DOM peer dependency">
+  <img src="https://img.shields.io/npm/dm/gform-react?style=for-the-badge" alt="npm downloads">
+</div>
+<div align="center">
+  <img src="https://img.shields.io/npm/dependency-version/gform-react/peer/react?style=for-the-badge" alt="React peer dependency">
+
+  <img src="https://img.shields.io/npm/dependency-version/gform-react/peer/react-dom?style=for-the-badge" alt="React DOM peer dependency">
+
+  <a href="https://unpkg.com/gform-react@latest/LICENSE.md">
+    <img src="https://img.shields.io/npm/l/gform-react?style=for-the-badge" alt="MIT License">
+  </a>
+</div>
+<br/>
+
+## Documentation
+
+Full documentation, examples, and API reference:
+
 https://gform-react.onrender.com
 
-## Demo:
-https://codesandbox.io/p/sandbox/gifted-elbakyan-fs5g2c
+## QuickStart
+```tsx
+import {GForm, GInput, GValidator, type GValidators} from "gform-react";
+
+interface SignInForm {
+  username: string;
+  password: string;
+}
+
+const baseValidator = new GValidator().withRequiredMessage('this field is required');
+
+const validators: GValidators<SignInForm> = {
+  '*': baseValidator, // a default validator for all other fields in the form
+
+  password: new GValidator(baseValidator)
+          .withMinLengthMessage((input) => `${input.formKey} must contain atleast ${input.minLength} chars`),
+};
+
+const App: FC = () => {
+    return (
+            <GForm<SignInForm> className='some-class'
+                               validators={validators}
+                               onSubmit={(formState, e) => { //can be used with native `action` or with Next.js `server actions`
+                                    e.preventDefault();
+                                    console.log(formState);
+                               }}>
+                <GInput formKey='username'
+                        required
+                        element={(input, props) => <div>
+                            <input {...props} placeholder='username'/>
+                            {input.error && <small className="p-error">{input.errorText}</small>}
+                        </div>}
+                />
+                <GInput formKey='password' 
+                        type='password'
+                        required
+                        minLength={5}
+                        element={(input, props) => <div>
+                            <input {...props} placeholder='password'/>
+                            {input.error && <small className="p-error">{input.errorText}</small>}
+                        </div>}
+                />
+                <button>Submit</button>
+            </GForm>
+    );
+};
+```
 
 ## Installation
+
 npm:
-```shell
+
+```sh
 npm install gform-react
 ```
 
 yarn:
-```shell
+
+```sh
 yarn add gform-react
 ```
 
-#### NOTE:
-react >=16.8.0, react-dom >=16.8.0 are peer dependencies
+## Peer dependencies
+react >=16.8.0, react-dom >=16.8.0 are peer dependencies
+
+## License
+
+MIT © Tal  
+https://www.npmjs.com/package/gform-react

package/dist/cjs/gform-react.development.js

@@ -20,87 +20,52 @@ const typeValueDict = {
   number: 'valueAsNumber'
 };
 const _generateIdUnsafe = () => (+new Date()).toString(36) + (1 - Math.random()).toString(36).substring(2, 16);
-const _copyStateFields = (source, destination) => {
-  for (const key in destination.fields) {
-    const sourceField = source.fields[key];
-    const destField = destination.fields[key];
-    if (!sourceField || sourceField.type !== destField.type) continue;
-    destination.fields[key] = {
-      ...destField,
-      ...sourceField
-    };
-  }
-};
-const _buildFormInitialValues = (rows = []) => {
-  const fields = {};
-  const inputs = _findInputs(rows);
-  inputs.forEach(config => {
-    if (fields[config.formKey]) {
-      console.warn(`DEV ONLY - [Duplicate Keys] - field with key '${config.formKey}' already defined.`);
-    }
-    const {
-      required = false,
-      max,
-      maxLength,
-      min,
-      minLength,
-      step,
-      pattern,
-      type = "text",
-      defaultValue,
-      value,
-      checked,
-      defaultChecked,
-      formKey,
-      debounce,
-      validatorKey
-    } = config;
-    const defaultProps = defaultFieldProps[type] || defaultFieldProps.text;
-    const inputValue = value || defaultValue || checked || defaultChecked || defaultProps.value;
-    fields[formKey] = {
-      formKey,
-      type,
-      required,
-      max,
-      maxLength,
-      min,
-      minLength,
-      step,
-      pattern,
-      value: inputValue,
-      validatorKey,
-      debounce,
-      dirty: false,
-      touched: false,
-      gid: _generateIdUnsafe()
-    };
-  });
+const _buildInputInitialValues = input => {
+  const {
+    required = false,
+    max,
+    maxLength,
+    min,
+    minLength,
+    step,
+    pattern,
+    type = "text",
+    defaultValue,
+    value,
+    checked,
+    defaultChecked,
+    formKey,
+    debounce,
+    validatorKey
+  } = input;
+  const defaultProps = defaultFieldProps[type] || defaultFieldProps.text;
+  const inputValue = value || defaultValue || checked || defaultChecked || defaultProps.value;
   return {
-    fields: fields
-  };
-};
-const _findInputs = (root, total = []) => {
-  if (!root) return total;
-  React.Children.forEach(root, child => {
-    if (!React.isValidElement(child)) return;
-    if (child.props) {
-      const {
-        formKey,
-        children
-      } = child.props;
-      if (formKey) {
-        total.push(child.props);
-      }
-      if (children) {
-        _findInputs(children, total);
-      }
+    formKey,
+    type,
+    required,
+    max,
+    maxLength,
+    min,
+    minLength,
+    step,
+    pattern,
+    value: inputValue,
+    validatorKey,
+    debounce,
+    dirty: false,
+    touched: false,
+    gid: _generateIdUnsafe(),
+    error: false,
+    errorText: '',
+    dispatchChanges(changes) {},
+    checkValidity() {
+      return false;
     }
-  });
-  return total;
+  };
 };
-const _findValidityKey = (validity, exclude = []) => {
+const _findValidityKey = validity => {
   for (const key in validity) {
-    if (exclude.includes(key)) continue;
     if (key !== 'valid' && validity[key]) {
       return key;
     }
@@ -350,7 +315,7 @@ class GValidator {
       }
       this.track.push(validityKey);
     }
-    this._constraintHandlers.push((input, key) => {
+    const constraintHandler = (input, key) => {
       {
         if (validityKey && validityMap[validityKey] && typeof input[validityMap[validityKey]] === 'undefined') {
           console.warn(`DEV ONLY - [Missing Prop] - the input '${input.formKey}' has registered validator for the violation '${validityKey}' but the input hasn't described the constraint '${validityMap[validityKey]}'.\nadd '${validityMap[validityKey]}' to the input props.\nexample:\n<GInput formKey='${input.formKey}' ${validityMap[validityKey]}={...} />\n\nor either remove '.${handlersMap[validityMap[validityKey]]}(...)' validation`);
@@ -361,7 +326,11 @@ class GValidator {
         return true;
       }
       return false;
+    };
+    Object.defineProperty(constraintHandler, 'name', {
+      value: `constraintHandler_${validityKey}`
     });
+    this._constraintHandlers.push(constraintHandler);
     return this;
   }
 }
@@ -370,30 +339,32 @@ const useFormHandlers = (getState, setState, validators = {}, optimized = false)
   const _viHandler = (input, e) => {
     if (!input) return;
     const element = e && e.target;
+    input.touched = true;
     if (typeof document !== 'undefined' && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement)) {
       if (!input.checkValidity) input.checkValidity = () => element.checkValidity();
-      const hasInitialValue = !input.dirty && input.value && !input.touched;
+      const hasInitialValue = !input.dirty && input.value;
       if (hasInitialValue) {
-        _checkInputManually(input);
+        const {
+          validityKey = 'custom'
+        } = _checkInputManually(input);
+        element.setCustomValidity(validityKey);
         _dispatchChanges(input, input.formKey);
         return;
       }
       element.setCustomValidity('');
-      const exclude = input.type && (input.pattern || hasCustomValidation(input)) ? ['typeMismatch'] : [];
-      const validityKey = _findValidityKey(element.validity, exclude);
+      const validityKey = _findValidityKey(element.validity);
       _validateInput(input, validityKey, v => element.setCustomValidity(v));
       if (!validityKey && input.error) {
         element.setCustomValidity(input.errorText || 'error');
       }
       _dispatchChanges(input, input.formKey);
     } else {
-      input.checkValidity = () => _checkInputManually(input);
+      input.checkValidity = () => _checkInputManually(input).isValid;
       input.checkValidity();
       _dispatchChanges(input, input.formKey);
     }
   };
   const _checkInputManually = input => {
-    const exclude = input.type && (input.pattern || hasCustomValidation(input)) ? ['typeMismatch'] : [];
     let validityKey = _findValidityKey({
       valueMissing: input.required && !input.value || false,
       typeMismatch: _checkTypeMismatch(input),
@@ -402,28 +373,34 @@ const useFormHandlers = (getState, setState, validators = {}, optimized = false)
       patternMismatch: input.pattern && _checkResult(input.pattern, input.value) || false,
       rangeUnderflow: input.min && Number(input.value) < Number(input.min) || false,
       rangeOverflow: input.max && Number(input.value) > Number(input.max) || false
-    }, exclude);
+    });
     if (!validityKey && input.error) {
       validityKey = 'customError';
     }
     _validateInput(input, validityKey);
-    return !input.error;
+    return {
+      isValid: !input.error,
+      validityKey
+    };
   };
   const _updateInputHandler = (input, e, unknown) => {
     input.value = _extractValue(e, unknown);
+    input.dirty = true;
     _viHandler(input, e);
   };
   const _validateInput = (input, validityKey, setValidity) => {
     const inputValidator = validators[input.validatorKey || input.formKey] || validators['*'];
     {
       if (validityKey && !inputValidator?.hasConstraint(validityKey)) {
-        if (validityKey === 'typeMismatch') console.warn(`DEV ONLY - [Missing Validator] - the input '${input.formKey}' has described the constraint '${validityMap[validityKey]}' however, a correspond validator/custom validation/pattern validator is missing.\nadd '${handlersMap[validityMap[validityKey]]}' or 'withCustomValidation' or '${handlersMap[validityMap.patternMismatch]}' to the input validator.\nexample:\nconst validators: GValidators = {\n\temail: new GValidator().withPatternMismatchMessage('pattern mismatch'),\n\t...\n}\n\nor either remove the constraint '${validityMap[validityKey]}' from the input props`);else console.warn(`DEV ONLY - [Missing Validator] - the input '${input.formKey}' has described the constraint '${validityMap[validityKey]}' however, a correspond validator is missing.\nadd '${handlersMap[validityMap[validityKey]]}' to the input validator.\nexample:\nconst validators: GValidators = {\n\temail: new GValidator().withPatternMismatchMessage('pattern mismatch'),\n\t...\n}\n\nor either remove the constraint '${validityMap[validityKey]}' from the input props`);
+        if (validityKey === 'typeMismatch') {
+          if (!inputValidator?.handlers.length) console.warn(`DEV ONLY - [Missing Validator] - the input '${input.formKey}' has described the constraint '${validityMap[validityKey]}' however, a correspond validator is missing.\nadd '${handlersMap[validityMap[validityKey]]}' or 'withCustomValidation' or '${handlersMap[validityMap.patternMismatch]}' to the input validator.\nexample:\nconst validators: GValidators = {\n\temail: new GValidator().withTypeMismatchMessage('pattern mismatch'),\n\t...\n}\nif you added on of these validators then the input is still suffering from '${validityKey}' violation.\n\nor either remove the constraint '${validityMap[validityKey]}' from the input props.\n`);else console.warn(`DEV ONLY - [Missing Validator] - the input '${input.formKey}' has described the constraint '${validityMap[validityKey]}' however, a correspond validator is missing or not satisfies the native constraint.\nadd '${handlersMap[validityMap[validityKey]]}' or 'withCustomValidation' to the input validator.\nexample:\nconst validators: GValidators = {\n\temail: new GValidator().withTypeMismatchMessage('pattern mismatch'),\n\t...\n}\n\nif you already have a Custom Validation then the input is still not satisfies the native type pattern.\neither enforce it or remove the constraint '${validityMap[validityKey]}' from the input props`);
+        } else console.warn(`DEV ONLY - [Missing Validator] - the input '${input.formKey}' has described the constraint '${validityMap[validityKey]}' however, a correspond validator is missing.\nadd '${handlersMap[validityMap[validityKey]]}' to the input validator.\nexample:\nconst validators: GValidators = {\n\temail: new GValidator().withPatternMismatchMessage('pattern mismatch'),\n\t...\n}\n\nor either remove the constraint '${validityMap[validityKey]}' from the input props`);
+        console.warn(`form submition is prevented due to violation(s) of input '${input.formKey}': violation '${validityKey}' caused by '${validityMap[validityKey]}' property (<Ginput ${validityMap[validityKey]}={...} />)`);
       }
     }
     if (inputValidator) {
       __validateInput(input, inputValidator, validityKey, setValidity);
     }
-    input.touched = true;
   };
   const _dispatchChanges = (changes, key) => setState(prev => {
     if (key) {
@@ -446,12 +423,14 @@ const useFormHandlers = (getState, setState, validators = {}, optimized = false)
   const __validateInput = (input, inputValidator, validityKey, setValidity) => {
     const fields = getState().fields;
     for (const index in inputValidator.constraintHandlers) {
-      const result = inputValidator.constraintHandlers[index](input, validityKey);
+      const handler = inputValidator.constraintHandlers[index];
+      const result = handler(input, validityKey);
       input.error = _checkResult(result, input.value);
       if (input.error) return;
     }
     for (const index in inputValidator.handlers) {
-      const result = inputValidator.handlers[index](input, fields);
+      const handler = inputValidator.handlers[index];
+      const result = handler(input, fields);
       input.error = _checkResult(result, input.value);
       if (input.error) return;
     }
@@ -461,7 +440,8 @@ const useFormHandlers = (getState, setState, validators = {}, optimized = false)
       _debounce(input.debounce || 300, `${input.gid}-async`).then(() => {
         const validateAsync = async () => {
           for (const index in inputValidator.asyncHandlers) {
-            const result = await inputValidator.asyncHandlers[index](input, fields);
+            const handler = inputValidator.asyncHandlers[index];
+            const result = await handler(input, fields);
             input.error = _checkResult(result, input.value);
             if (input.error) break;
           }
@@ -478,10 +458,6 @@ const useFormHandlers = (getState, setState, validators = {}, optimized = false)
       });
     }
   };
-  const hasCustomValidation = input => {
-    const validator = validators[input.validatorKey || input.formKey] || validators['*'];
-    return validator && (validator.asyncHandlers.length > 0 || validator.handlers.length > 0);
-  };
   return {
     _updateInputHandler,
     _viHandler,
@@ -496,7 +472,8 @@ const GFormContextProvider = ({
   children,
   initialState,
   validators,
-  optimized
+  optimized,
+  formRef
 }) => {
   const stateRef = React.useRef(initialState);
   const listeners = React.useRef(null);
@@ -507,19 +484,59 @@ const GFormContextProvider = ({
       return;
     }
     stateRef.current = nextState;
-    listeners.current.forEach(l => l());
+    listeners.current.forEach(listener => listener());
   }, []);
   const handlers = useFormHandlers(() => stateRef.current, setState, validators, optimized);
+  const getInputElement = React.useCallback(formKey => {
+    if (formRef && formRef.current) {
+      return formRef.current[formKey];
+    }
+  }, []);
+  const registerField = React.useCallback(config => {
+    const prev = stateRef.current;
+    if (prev.fields[config.formKey]) {
+      {
+        console.warn(`DEV ONLY - [Duplicate Keys] - field with key '${config.formKey}' already defined.`);
+      }
+      return;
+    }
+    const inputState = _buildInputInitialValues(config);
+    stateRef.current = {
+      ...prev,
+      fields: {
+        ...prev.fields,
+        [config.formKey]: {
+          ...inputState,
+          dispatchChanges: changes => handlers._dispatchChanges(changes, config.formKey)
+        }
+      }
+    };
+  }, [handlers]);
+  const unregisterField = React.useCallback(formKey => {
+    const prev = stateRef.current;
+    if (!prev.fields[formKey]) return;
+    const {
+      [formKey]: _,
+      ...remainingFields
+    } = prev.fields;
+    stateRef.current = {
+      ...prev,
+      fields: remainingFields
+    };
+    listeners.current.forEach(listener => listener());
+  }, []);
   const store = React.useMemo(() => {
     if (!listeners.current) {
       listeners.current = new Set();
+      stateRef.current = initialState;
+      for (const fieldKey in initialState.fields) {
+        initialState.fields[fieldKey].dispatchChanges = changes => handlers._dispatchChanges(changes, fieldKey);
+      }
     } else {
       listeners.current.clear();
-      _copyStateFields(stateRef.current, initialState);
-    }
-    stateRef.current = initialState;
-    for (const fieldKey in initialState.fields) {
-      initialState.fields[fieldKey].dispatchChanges = changes => handlers._dispatchChanges(changes, fieldKey);
+      for (const fieldKey in stateRef.current.fields) {
+        stateRef.current.fields[fieldKey].dispatchChanges = changes => handlers._dispatchChanges(changes, fieldKey);
+      }
     }
     return {
       getState: () => stateRef.current,
@@ -528,7 +545,10 @@ const GFormContextProvider = ({
         listeners.current.add(listener);
         return () => listeners.current.delete(listener);
       },
-      handlers
+      handlers,
+      registerField,
+      unregisterField,
+      getInputElement
     };
   }, [initialState]);
   return React.createElement(GFormContext.Provider, {
@@ -537,7 +557,7 @@ const GFormContextProvider = ({
 };
 const useFormStore = () => {
   const store = React.useContext(GFormContext);
-  if (!store.getState) throw new Error('useGFormStore must be used within `GForm` component');
+  if (!store.getState) throw new Error('useFormStore must be used within `GForm` component');
   return store;
 };
 const useFormSelector = selector => {
@@ -567,9 +587,9 @@ const FormRenderer = React.forwardRef(({
   onKeyUp,
   children,
   onInit,
+  formRef,
   ...rest
 }, ref) => {
-  const formRef = React.useRef(null);
   const {
     handlers,
     getState
@@ -663,15 +683,18 @@ const GForm = React.forwardRef(({
   optimized,
   ...props
 }, ref) => {
-  const initialState = React.useMemo(() => {
-    return _buildFormInitialValues(typeof children === 'function' ? children({}) : children);
-  }, [children]);
+  const initialState = React.useMemo(() => ({
+    fields: {}
+  }), []);
+  const formRef = React.useRef(null);
   return React.createElement(GFormContextProvider, {
     initialState: initialState,
+    formRef: formRef,
     validators: validators,
     optimized: optimized
   }, React.createElement(FormRenderer, _extends({
-    ref: ref
+    ref: ref,
+    formRef: formRef
   }, props), children));
 });
 
@@ -681,27 +704,42 @@ const makeSelectFields = (keys = []) => createSelector(selectFields, fields => {
   return selected.length ? selected : null;
 });
 
-const _GInput = React.forwardRef(({
-  formKey,
-  element,
-  title,
-  type = 'text',
-  fetch,
-  fetchDeps,
-  optimized,
-  debounce = 300,
-  defaultChecked,
-  defaultValue,
-  checked,
-  validatorKey,
-  value,
-  ...rest
-}, ref) => {
-  const inputState = useFormSelector(state => state.fields[formKey]);
+const _GInput = React.forwardRef((props, ref) => {
   const store = useFormStore();
+  const {
+    formKey,
+    element,
+    title,
+    type = 'text',
+    fetch,
+    fetchDeps,
+    optimized,
+    debounce = 300,
+    defaultChecked,
+    defaultValue,
+    checked,
+    validatorKey,
+    value,
+    ...rest
+  } = props;
+  if (!store.getState().fields[formKey]) {
+    store.registerField(props);
+  }
+  const inputState = useFormSelector(state => state.fields[formKey]);
+  const _fetchDeps = useFormSelector(makeSelectFields(fetchDeps));
+  React.useEffect(() => {
+    if (inputState.value) {
+      store.handlers._viHandler(inputState, {
+        target: store.getInputElement(formKey)
+      });
+    }
+    return () => {
+      store.unregisterField(formKey);
+    };
+  }, []);
   const _element = React.useMemo(() => {
     let value, checked;
-    if (type === 'checkbox') checked = inputState.value || false;else value = inputState.value || '';
+    if (type === 'checkbox') checked = inputState.value || false;else if (type === 'number') value = inputState.value || 0;else value = inputState.value || '';
     const _props = {
       ...rest,
       type,
@@ -734,25 +772,12 @@ const _GInput = React.forwardRef(({
       } : (e, unknown) => {
         store.handlers._updateInputHandler(inputState, e, unknown);
       };
-      if (!inputState.touched && inputState.dispatchChanges) {
-        _props.onFocus = rest.onFocus ? e => {
-          rest.onFocus(e);
-          inputState.dispatchChanges({
-            touched: true
-          });
-        } : () => {
-          inputState.dispatchChanges({
-            touched: true
-          });
-        };
-      }
     }
     if (element) {
       return element(inputState, _props);
     }
     return React.createElement("input", _props);
   }, [inputState, element]);
-  const _fetchDeps = useFormSelector(makeSelectFields(fetchDeps));
   React.useEffect(() => {
     if (fetch) {
       _debounce(debounce, `${inputState.gid}-fetch`).then(() => {