@faasjs/react 3.7.0-beta.9 → 3.7.1

package/README.md

@@ -56,6 +56,7 @@ npm install @faasjs/react react
 - [useEqualMemoize](functions/useEqualMemoize.md)
 - [useFaas](functions/useFaas.md)
 - [useFormContext](functions/useFormContext.md)
+- [usePrevious](functions/usePrevious.md)
 - [useSplittingState](functions/useSplittingState.md)
 - [validValues](functions/validValues.md)
 - [withFaasData](functions/withFaasData.md)
@@ -88,6 +89,7 @@ npm install @faasjs/react react
 - [FormItemName](type-aliases/FormItemName.md)
 - [FormItemProps](type-aliases/FormItemProps.md)
 - [FormLabelElementProps](type-aliases/FormLabelElementProps.md)
+- [FormLang](type-aliases/FormLang.md)
 - [FormProps](type-aliases/FormProps.md)
 - [FormRule](type-aliases/FormRule.md)
 - [FormRules](type-aliases/FormRules.md)
@@ -101,4 +103,5 @@ npm install @faasjs/react react
 ## Variables
 
 - [FormDefaultElements](variables/FormDefaultElements.md)
+- [FormDefaultLang](variables/FormDefaultLang.md)
 - [FormDefaultRules](variables/FormDefaultRules.md)

package/dist/index.d.mts

@@ -57,6 +57,14 @@ declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
  * @returns The result of the `useCallback` hook with memoized dependencies.
  */
 declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
+/**
+ * Hook to store the previous value of a state or prop.
+ *
+ * @template T - The type of the value.
+ * @param {T} value - The current value to be stored.
+ * @returns {T | undefined} - The previous value, or undefined if there is no previous value.
+ */
+declare function usePrevious<T>(value: T): T | undefined;
 
 /**
  * Creates a splitting context with the given default value.
@@ -396,18 +404,42 @@ declare const OptionalWrapper: React.FC<OptionalWrapperProps> & {
     whyDidYouRender: boolean;
 };
 
+/**
+ * Props for the FormButtonElement component.
+ *
+ * @property {React.ReactNode} [children] - The content to be displayed inside the button.
+ * @property {boolean} disabled - Indicates whether the button is disabled.
+ * @property {() => Promise<void>} submit - A function to be called when the button is clicked, which returns a promise.
+ */
 type FormButtonElementProps = {
     children?: React.ReactNode;
     disabled: boolean;
     submit: () => Promise<void>;
 };
 
+/**
+ * Props for the Form Input Element component.
+ *
+ * @property {string} name - The name of the input element.
+ * @property {any} value - The current value of the input element.
+ * @property {(value: any) => void} onChange - Callback function to handle changes to the input value.
+ */
 type FormInputElementProps = {
     name: string;
     value: any;
     onChange: (value: any) => void;
 };
 
+/**
+ * Props for the FormLabelElement component.
+ *
+ * @typedef {Object} FormLabelElementProps
+ * @property {string} name - The name of the form element.
+ * @property {ReactNode} [title] - Optional title for the form element.
+ * @property {ReactNode} [description] - Optional description for the form element.
+ * @property {Error} [error] - Optional error associated with the form element.
+ * @property {ReactNode} children - The child elements, typically an input element.
+ */
 type FormLabelElementProps = {
     name: string;
     title?: ReactNode;
@@ -417,6 +449,14 @@ type FormLabelElementProps = {
     children: ReactNode;
 };
 
+/**
+ * Represents the types of form elements used in the form.
+ *
+ * @typedef {Object} FormElementTypes
+ * @property {ComponentType<FormLabelElementProps>} Label - The component type for the form label element.
+ * @property {ComponentType<FormInputElementProps>} Input - The component type for the form input element.
+ * @property {ComponentType<FormButtonElementProps>} Button - The component type for the form button element.
+ */
 type FormElementTypes = {
     Label: ComponentType<FormLabelElementProps>;
     Input: ComponentType<FormInputElementProps>;
@@ -432,12 +472,44 @@ declare const FormDefaultLang: {
 };
 type FormLang = typeof FormDefaultLang;
 
+/**
+ * A type representing a form validation rule.
+ *
+ * @template Options - The type of the options that can be passed to the rule.
+ *
+ * @param value - The value to be validated.
+ * @param options - Optional. Additional options that can be used in the validation.
+ * @param lang - Optional. The language settings that can be used in the validation.
+ *
+ * @returns A promise that resolves if the validation is successful, or rejects with an error if the validation fails.
+ *
+ * @example
+ * ```ts
+ * async function required(value: any, options: boolean, lang?: FormLang) {
+ *   if (value === null || value === undefined || value === '' || Number.isNaN(value))
+ *     throw Error(lang?.required)
+ * }
+ * ```
+ */
 type FormRule<Options = any> = (value: any, options?: Options, lang?: FormLang) => Promise<void>;
 type InferRuleOption<T> = T extends (value: any, options: infer O, lang?: FormLang) => Promise<void> ? O : never;
+/**
+ * A type representing a set of form validation rules.
+ *
+ * @typedef {Record<string, FormRule>} FormRules
+ *
+ * Each key in the record represents the name of a form field, and the corresponding value is a `FormRule` object that defines the validation rules for that field.
+ */
 type FormRules = Record<string, FormRule>;
 type InferFormRulesOptions<T> = {
     [K in keyof T]: InferRuleOption<T[K]>;
 };
+/**
+ * Default validation rules for a form.
+ *
+ * @constant
+ * @type {FormRules}
+ */
 declare const FormDefaultRules: FormRules;
 type FormDefaultRulesOptions = InferFormRulesOptions<typeof FormDefaultRules>;
 declare function validValues(rules: FormRules, items: FormItemProps[], values: Record<string, any>, lang: FormLang): Promise<Record<string, Error>>;
@@ -487,6 +559,19 @@ type FormProps<Values extends Record<string, any> = Record<string, any>, FormEle
  * @param {Partial<FormContextProps>} props - Additional properties for the form context.
  *
  * @returns {JSX.Element} The FormContainer component.
+ *
+ * @example
+ * ```tsx
+ * import { Form } from '@faasjs/react'
+ *
+ * function MyForm() {
+ *   return <Form
+ *     items={[
+ *       { name: 'name' },
+ *     ]}
+ *   />
+ * }
+ * ```
  */
 declare function FormContainer<Values extends Record<string, any> = Record<string, any>, FormElements extends FormElementTypes = FormElementTypes, Rules extends FormRules = typeof FormDefaultRules>({ defaultValues, Elements, rules, lang, ...props }: FormProps<Values, FormElements, Rules>): react_jsx_runtime.JSX.Element;
 declare namespace FormContainer {
@@ -515,4 +600,4 @@ declare const FormContextProvider: <NewT extends FormContextProps<Record<string,
 }) => react.ReactNode;
 declare const useFormContext: <NewT extends FormContextProps<Record<string, any>, FormRules> = FormContextProps<Record<string, any>, FormRules>>() => Readonly<NewT>;
 
-export { ErrorBoundary, type ErrorBoundaryProps, type ErrorChildrenProps, type FaasDataInjection, FaasDataWrapper, type FaasDataWrapperProps, FaasReactClient, type FaasReactClientInstance, type FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, type FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultRules, type FormDefaultRulesOptions, type FormElementTypes, type FormInputElementProps, FormItem, type FormItemName, type FormItemProps, type FormLabelElementProps, type FormProps, type FormRule, type FormRules, type InferFormRulesOptions, type OnError, OptionalWrapper, type OptionalWrapperProps, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFormContext, useSplittingState, validValues, withFaasData };
+export { ErrorBoundary, type ErrorBoundaryProps, type ErrorChildrenProps, type FaasDataInjection, FaasDataWrapper, type FaasDataWrapperProps, FaasReactClient, type FaasReactClientInstance, type FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, type FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, type FormDefaultRulesOptions, type FormElementTypes, type FormInputElementProps, FormItem, type FormItemName, type FormItemProps, type FormLabelElementProps, type FormLang, type FormProps, type FormRule, type FormRules, type InferFormRulesOptions, type OnError, OptionalWrapper, type OptionalWrapperProps, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFormContext, usePrevious, useSplittingState, validValues, withFaasData };

package/dist/index.d.ts

@@ -57,6 +57,14 @@ declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
  * @returns The result of the `useCallback` hook with memoized dependencies.
  */
 declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
+/**
+ * Hook to store the previous value of a state or prop.
+ *
+ * @template T - The type of the value.
+ * @param {T} value - The current value to be stored.
+ * @returns {T | undefined} - The previous value, or undefined if there is no previous value.
+ */
+declare function usePrevious<T>(value: T): T | undefined;
 
 /**
  * Creates a splitting context with the given default value.
@@ -396,18 +404,42 @@ declare const OptionalWrapper: React.FC<OptionalWrapperProps> & {
     whyDidYouRender: boolean;
 };
 
+/**
+ * Props for the FormButtonElement component.
+ *
+ * @property {React.ReactNode} [children] - The content to be displayed inside the button.
+ * @property {boolean} disabled - Indicates whether the button is disabled.
+ * @property {() => Promise<void>} submit - A function to be called when the button is clicked, which returns a promise.
+ */
 type FormButtonElementProps = {
     children?: React.ReactNode;
     disabled: boolean;
     submit: () => Promise<void>;
 };
 
+/**
+ * Props for the Form Input Element component.
+ *
+ * @property {string} name - The name of the input element.
+ * @property {any} value - The current value of the input element.
+ * @property {(value: any) => void} onChange - Callback function to handle changes to the input value.
+ */
 type FormInputElementProps = {
     name: string;
     value: any;
     onChange: (value: any) => void;
 };
 
+/**
+ * Props for the FormLabelElement component.
+ *
+ * @typedef {Object} FormLabelElementProps
+ * @property {string} name - The name of the form element.
+ * @property {ReactNode} [title] - Optional title for the form element.
+ * @property {ReactNode} [description] - Optional description for the form element.
+ * @property {Error} [error] - Optional error associated with the form element.
+ * @property {ReactNode} children - The child elements, typically an input element.
+ */
 type FormLabelElementProps = {
     name: string;
     title?: ReactNode;
@@ -417,6 +449,14 @@ type FormLabelElementProps = {
     children: ReactNode;
 };
 
+/**
+ * Represents the types of form elements used in the form.
+ *
+ * @typedef {Object} FormElementTypes
+ * @property {ComponentType<FormLabelElementProps>} Label - The component type for the form label element.
+ * @property {ComponentType<FormInputElementProps>} Input - The component type for the form input element.
+ * @property {ComponentType<FormButtonElementProps>} Button - The component type for the form button element.
+ */
 type FormElementTypes = {
     Label: ComponentType<FormLabelElementProps>;
     Input: ComponentType<FormInputElementProps>;
@@ -432,12 +472,44 @@ declare const FormDefaultLang: {
 };
 type FormLang = typeof FormDefaultLang;
 
+/**
+ * A type representing a form validation rule.
+ *
+ * @template Options - The type of the options that can be passed to the rule.
+ *
+ * @param value - The value to be validated.
+ * @param options - Optional. Additional options that can be used in the validation.
+ * @param lang - Optional. The language settings that can be used in the validation.
+ *
+ * @returns A promise that resolves if the validation is successful, or rejects with an error if the validation fails.
+ *
+ * @example
+ * ```ts
+ * async function required(value: any, options: boolean, lang?: FormLang) {
+ *   if (value === null || value === undefined || value === '' || Number.isNaN(value))
+ *     throw Error(lang?.required)
+ * }
+ * ```
+ */
 type FormRule<Options = any> = (value: any, options?: Options, lang?: FormLang) => Promise<void>;
 type InferRuleOption<T> = T extends (value: any, options: infer O, lang?: FormLang) => Promise<void> ? O : never;
+/**
+ * A type representing a set of form validation rules.
+ *
+ * @typedef {Record<string, FormRule>} FormRules
+ *
+ * Each key in the record represents the name of a form field, and the corresponding value is a `FormRule` object that defines the validation rules for that field.
+ */
 type FormRules = Record<string, FormRule>;
 type InferFormRulesOptions<T> = {
     [K in keyof T]: InferRuleOption<T[K]>;
 };
+/**
+ * Default validation rules for a form.
+ *
+ * @constant
+ * @type {FormRules}
+ */
 declare const FormDefaultRules: FormRules;
 type FormDefaultRulesOptions = InferFormRulesOptions<typeof FormDefaultRules>;
 declare function validValues(rules: FormRules, items: FormItemProps[], values: Record<string, any>, lang: FormLang): Promise<Record<string, Error>>;
@@ -487,6 +559,19 @@ type FormProps<Values extends Record<string, any> = Record<string, any>, FormEle
  * @param {Partial<FormContextProps>} props - Additional properties for the form context.
  *
  * @returns {JSX.Element} The FormContainer component.
+ *
+ * @example
+ * ```tsx
+ * import { Form } from '@faasjs/react'
+ *
+ * function MyForm() {
+ *   return <Form
+ *     items={[
+ *       { name: 'name' },
+ *     ]}
+ *   />
+ * }
+ * ```
  */
 declare function FormContainer<Values extends Record<string, any> = Record<string, any>, FormElements extends FormElementTypes = FormElementTypes, Rules extends FormRules = typeof FormDefaultRules>({ defaultValues, Elements, rules, lang, ...props }: FormProps<Values, FormElements, Rules>): react_jsx_runtime.JSX.Element;
 declare namespace FormContainer {
@@ -515,4 +600,4 @@ declare const FormContextProvider: <NewT extends FormContextProps<Record<string,
 }) => react.ReactNode;
 declare const useFormContext: <NewT extends FormContextProps<Record<string, any>, FormRules> = FormContextProps<Record<string, any>, FormRules>>() => Readonly<NewT>;
 
-export { ErrorBoundary, type ErrorBoundaryProps, type ErrorChildrenProps, type FaasDataInjection, FaasDataWrapper, type FaasDataWrapperProps, FaasReactClient, type FaasReactClientInstance, type FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, type FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultRules, type FormDefaultRulesOptions, type FormElementTypes, type FormInputElementProps, FormItem, type FormItemName, type FormItemProps, type FormLabelElementProps, type FormProps, type FormRule, type FormRules, type InferFormRulesOptions, type OnError, OptionalWrapper, type OptionalWrapperProps, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFormContext, useSplittingState, validValues, withFaasData };
+export { ErrorBoundary, type ErrorBoundaryProps, type ErrorChildrenProps, type FaasDataInjection, FaasDataWrapper, type FaasDataWrapperProps, FaasReactClient, type FaasReactClientInstance, type FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, type FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, type FormDefaultRulesOptions, type FormElementTypes, type FormInputElementProps, FormItem, type FormItemName, type FormItemProps, type FormLabelElementProps, type FormLang, type FormProps, type FormRule, type FormRules, type InferFormRulesOptions, type OnError, OptionalWrapper, type OptionalWrapperProps, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFormContext, usePrevious, useSplittingState, validValues, withFaasData };

package/dist/index.js

@@ -48,10 +48,8 @@ function equal(a, b) {
     case Promise:
       return a === b;
     case Object: {
-      const keys = Object.keys(a);
-      for (const key of keys) {
+      for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]))
         if (!equal(a[key], b[key])) return false;
-      }
       return true;
     }
     default:
@@ -79,6 +77,13 @@ function useEqualCallback(callback, dependencies) {
     useEqualMemoize(dependencies)
   );
 }
+function usePrevious(value) {
+  const ref = react.useRef();
+  react.useEffect(() => {
+    ref.current = value;
+  });
+  return ref.current;
+}
 function useSplittingState(initialStates) {
   const states = {};
   for (const key of Object.keys(initialStates)) {
@@ -359,21 +364,56 @@ var FormContext = createSplittingContext([
 ]);
 var FormContextProvider = FormContext.Provider;
 var useFormContext = FormContext.use;
-function FormItem(props) {
-  const { Elements, values, setValues, errors } = useFormContext();
-  const Label = props.label?.Label ?? Elements.Label;
-  const Input = props.input?.Input ?? Elements.Input;
-  return /* @__PURE__ */ jsxRuntime.jsx(Label, { name: props.name, ...props.label, error: errors[props.name], children: /* @__PURE__ */ jsxRuntime.jsx(
-    Input,
+function processValue(input, rules) {
+  switch (rules?.type) {
+    case "number":
+      return Number(input);
+    case "string":
+      return String(input);
+    default:
+      return input;
+  }
+}
+function FormInput({
+  name,
+  rules,
+  ...rest
+}) {
+  const { Elements, values, setValues } = useFormContext();
+  const value = values?.[name];
+  if (rest.Input) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      rest.Input,
+      {
+        name,
+        value,
+        onChange: (v) => setValues((prev) => ({
+          ...prev,
+          [name]: processValue(v, rules)
+        })),
+        ...rest.props
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    Elements.Input,
     {
-      name: props.name,
-      value: values[props.name],
+      name,
+      value,
       onChange: (v) => setValues((prev) => ({
         ...prev,
-        [props.name]: v
-      }))
+        [name]: processValue(v, rules)
+      })),
+      ...rest.props
     }
-  ) });
+  );
+}
+FormInput.displayName = "FormInput";
+FormInput.whyDidYouRender = true;
+function FormItem(props) {
+  const { Elements, errors } = useFormContext();
+  const Label = props.label?.Label ?? Elements.Label;
+  return /* @__PURE__ */ jsxRuntime.jsx(Label, { name: props.name, ...props.label, error: errors[props.name], children: /* @__PURE__ */ jsxRuntime.jsx(FormInput, { name: props.name, rules: props.rules, ...props.input }) });
 }
 FormItem.displayName = "FormItem";
 FormItem.whyDidYouRender = true;
@@ -547,6 +587,7 @@ exports.FaasReactClient = FaasReactClient;
 exports.Form = FormContainer;
 exports.FormContextProvider = FormContextProvider;
 exports.FormDefaultElements = FormDefaultElements;
+exports.FormDefaultLang = FormDefaultLang;
 exports.FormDefaultRules = FormDefaultRules;
 exports.FormItem = FormItem;
 exports.OptionalWrapper = OptionalWrapper;
@@ -561,6 +602,7 @@ exports.useEqualMemo = useEqualMemo;
 exports.useEqualMemoize = useEqualMemoize;
 exports.useFaas = useFaas;
 exports.useFormContext = useFormContext;
+exports.usePrevious = usePrevious;
 exports.useSplittingState = useSplittingState;
 exports.validValues = validValues;
 exports.withFaasData = withFaasData;

package/dist/index.mjs

@@ -46,10 +46,8 @@ function equal(a, b) {
     case Promise:
       return a === b;
     case Object: {
-      const keys = Object.keys(a);
-      for (const key of keys) {
+      for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]))
         if (!equal(a[key], b[key])) return false;
-      }
       return true;
     }
     default:
@@ -77,6 +75,13 @@ function useEqualCallback(callback, dependencies) {
     useEqualMemoize(dependencies)
   );
 }
+function usePrevious(value) {
+  const ref = useRef();
+  useEffect(() => {
+    ref.current = value;
+  });
+  return ref.current;
+}
 function useSplittingState(initialStates) {
   const states = {};
   for (const key of Object.keys(initialStates)) {
@@ -357,21 +362,56 @@ var FormContext = createSplittingContext([
 ]);
 var FormContextProvider = FormContext.Provider;
 var useFormContext = FormContext.use;
-function FormItem(props) {
-  const { Elements, values, setValues, errors } = useFormContext();
-  const Label = props.label?.Label ?? Elements.Label;
-  const Input = props.input?.Input ?? Elements.Input;
-  return /* @__PURE__ */ jsx(Label, { name: props.name, ...props.label, error: errors[props.name], children: /* @__PURE__ */ jsx(
-    Input,
+function processValue(input, rules) {
+  switch (rules?.type) {
+    case "number":
+      return Number(input);
+    case "string":
+      return String(input);
+    default:
+      return input;
+  }
+}
+function FormInput({
+  name,
+  rules,
+  ...rest
+}) {
+  const { Elements, values, setValues } = useFormContext();
+  const value = values?.[name];
+  if (rest.Input) {
+    return /* @__PURE__ */ jsx(
+      rest.Input,
+      {
+        name,
+        value,
+        onChange: (v) => setValues((prev) => ({
+          ...prev,
+          [name]: processValue(v, rules)
+        })),
+        ...rest.props
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    Elements.Input,
     {
-      name: props.name,
-      value: values[props.name],
+      name,
+      value,
       onChange: (v) => setValues((prev) => ({
         ...prev,
-        [props.name]: v
-      }))
+        [name]: processValue(v, rules)
+      })),
+      ...rest.props
     }
-  ) });
+  );
+}
+FormInput.displayName = "FormInput";
+FormInput.whyDidYouRender = true;
+function FormItem(props) {
+  const { Elements, errors } = useFormContext();
+  const Label = props.label?.Label ?? Elements.Label;
+  return /* @__PURE__ */ jsx(Label, { name: props.name, ...props.label, error: errors[props.name], children: /* @__PURE__ */ jsx(FormInput, { name: props.name, rules: props.rules, ...props.input }) });
 }
 FormItem.displayName = "FormItem";
 FormItem.whyDidYouRender = true;
@@ -539,4 +579,4 @@ function FormContainer({
 FormContainer.displayName = "FormContainer";
 FormContainer.whyDidYouRender = true;
 
-export { ErrorBoundary, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultRules, FormItem, OptionalWrapper, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFormContext, useSplittingState, validValues, withFaasData };
+export { ErrorBoundary, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormItem, OptionalWrapper, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFormContext, usePrevious, useSplittingState, validValues, withFaasData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faasjs/react",
-  "version": "3.7.0-beta.9",
+  "version": "3.7.1",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -34,10 +34,10 @@
     "dist"
   ],
   "peerDependencies": {
-    "@faasjs/browser": "3.7.0-beta.9"
+    "@faasjs/browser": "3.7.1"
   },
   "devDependencies": {
-    "@faasjs/browser": "3.7.0-beta.9",
+    "@faasjs/browser": "3.7.1",
     "@types/react": "*",
     "react": "*"
   },