@monkvision/common 4.2.9 → 4.3.0

package/README/HOOKS.md

@@ -83,6 +83,45 @@ function TestComponent() {
 This custom hook creates an interval that calls the provided callback every `delay` milliseconds. If `delay` is `null`
 or less than 0, the callback will not be called.
 
+### useForm
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import { useForm, required, email } from '@monkvision/common';
+import { Button, TextField } from '@monkvision/common-ui-web';
+
+function TestComponent() {
+  const { t } = useTranslation();
+  const form = useForm({
+    initialValues: {
+      email: '',
+    },
+    validate: {
+      email,
+    },
+  });
+
+  return (
+    <form onSubmit={() => console.log('Submit')}>
+      <label htmlFor='email'>Email</label>
+      <TextField
+        id='email'
+        focusColor={form.isInputErrorDisplayed('email') ? 'alert-base' : 'primary-base'}
+        assistiveText={
+          form.isInputErrorDisplayed('email')
+            ? t(`form.errors.${form.getInputError('email')}`)
+            : undefined
+        }
+        highlighted={form.isInputErrorDisplayed('email')}
+        {...form.getInputProps('email')}
+      />
+      <Button type='submit'>Confirm</Button>
+    </form>
+  );
+}
+```
+Custom hook used to manage forms in ReactJs.
+
 ### useLangProp
 ```tsx
 import { useLangProp } from '@monkvision/common';

package/README/UTILITIES.md

@@ -137,6 +137,48 @@ Returns the value of a given environment variable. If the value does not exist,
 
 ---
 
+# Form Validation Utils
+### mergeValidationFunctions
+```typescript
+import { mergeValidationFunctions } from '@monkvision/common';
+
+const merged = mergeValidationFunctions(
+  (value: any) => typeof value === 'string' && value.length > 3 ? null : 'too-short',
+  (value: any) => typeof value === 'string' && value.length < 3 ? null : 'too-long',
+);
+console.log(merged('ab')); // Output : 'too-short'
+console.log(merged('abcd')); // Output : 'too-long'
+console.log(merged(123)); // Output : 'too-short'
+console.log(merged('abc')); // Output : null
+```
+Util function used to merge multiple validation functions into a single one. The first error discovered will be
+returned.
+
+### required
+```typescript
+import { required } from '@monkvision/common';
+
+console.log(required('')); // Output : 'required'
+console.log(required(null)); // Output : 'required'
+console.log(required(12)); // Output : null
+console.log(merged('abc')); // Output : null
+console.log(merged(false)); // Output : null
+```
+Validation function for required fields.
+
+### email
+```typescript
+import { email } from '@monkvision/common';
+
+console.log(email('')); // Output : 'required'
+console.log(email('abc')); // Output : 'emailNotValid'
+console.log(email(123)); // Output : 'emailNotValid'
+console.log(email('test@acvauctions.com')); // Output : null'
+```
+Validation function for valid email fields.
+
+---
+
 # Mimetype Utils
 ### MIMETYPE_FILE_EXTENSIONS
 ```typescript

package/lib/hooks/index.d.ts

@@ -10,3 +10,4 @@ export * from './useSearchParams';
 export * from './useInterval';
 export * from './useAsyncInterval';
 export * from './useObjectMemo';
+export * from './useForm';

package/lib/hooks/index.js

@@ -26,3 +26,4 @@ __exportStar(require("./useSearchParams"), exports);
 __exportStar(require("./useInterval"), exports);
 __exportStar(require("./useAsyncInterval"), exports);
 __exportStar(require("./useObjectMemo"), exports);
+__exportStar(require("./useForm"), exports);

package/lib/hooks/useForm.d.ts

@@ -0,0 +1,63 @@
+import { FormValidationFunction } from '../utils';
+/**
+ * Base type definition for form initial values.
+ */
+export type FormValuesBaseType = Record<string, any>;
+/**
+ * Type definitions for the input properties that needs to be passed to a form input.
+ */
+export interface FormInputProps<T extends FormValuesBaseType> {
+    value: T[keyof T];
+    onChange: (value: T[keyof T]) => void;
+    onBlur: () => void;
+}
+/**
+ * Options used to set up a form using the `useForm` hook.
+ */
+export interface FormOptions<T extends FormValuesBaseType> {
+    /**
+     * Initial values of the form. This property is used to set the global shape of the form.
+     */
+    initialValues: T;
+    /**
+     * Optional validation functions used to validate the form fields.
+     */
+    validate?: {
+        [Key in keyof T]?: FormValidationFunction<T[Key]>;
+    };
+}
+/**
+ * Form handler used to manage a form using the `useForm` hook.
+ */
+export interface Form<T extends FormValuesBaseType> {
+    /**
+     * Function used to get the value of a form input.
+     */
+    getInputValue: (name: keyof T) => T[keyof T];
+    /**
+     * Function used to get the pass through props of a form input.
+     */
+    getInputProps: (name: keyof T) => FormInputProps<T>;
+    /**
+     * Function indicating if the form is valid or not (i.e. every input in the form is valid).
+     */
+    isValid: () => boolean;
+    /**
+     * Function that returns the validation error of the given form input.
+     */
+    getInputError: (name: keyof T) => string | null;
+    /**
+     * Function indicating if the error message under a form input should be displayed or not.
+     */
+    isInputErrorDisplayed: (name: keyof T) => boolean;
+    /**
+     * Function indicating if a form input has been touched or is dirty.
+     */
+    isInputTouchedOrDirty: (name: keyof T) => boolean;
+}
+/**
+ * Custom hook used to manage forms in ReactJs. Please refer to
+ * [the official documentation](https://github.com/monkvision/monkjs/blob/main/packages/common/README/HOOKS.md) for more
+ * details on how to use this hook.
+ */
+export declare function useForm<T extends FormValuesBaseType = FormValuesBaseType>({ initialValues, validate, }: FormOptions<T>): Form<T>;

package/lib/hooks/useForm.js

@@ -0,0 +1,65 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useForm = void 0;
+var react_1 = require("react");
+var useObjectMemo_1 = require("./useObjectMemo");
+function mapFormValues(values, val) {
+    return Object.keys(values).reduce(function (prev, curr) {
+        var _a;
+        return (__assign(__assign({}, prev), (_a = {}, _a[curr] = val, _a)));
+    }, {});
+}
+/**
+ * Custom hook used to manage forms in ReactJs. Please refer to
+ * [the official documentation](https://github.com/monkvision/monkjs/blob/main/packages/common/README/HOOKS.md) for more
+ * details on how to use this hook.
+ */
+function useForm(_a) {
+    var initialValues = _a.initialValues, validate = _a.validate;
+    var _b = (0, react_1.useState)(initialValues), values = _b[0], setValues = _b[1];
+    var _c = (0, react_1.useState)(mapFormValues(initialValues, false)), touchedInputs = _c[0], setTouchedInputs = _c[1];
+    var touch = (0, react_1.useCallback)(function (name) {
+        setTouchedInputs(function (previousValues) {
+            var _a;
+            return (__assign(__assign({}, previousValues), (_a = {}, _a[name] = true, _a)));
+        });
+    }, []);
+    var getInputValue = (0, react_1.useCallback)(function (name) { return values[name]; }, [values]);
+    var getInputProps = (0, react_1.useCallback)(function (name) { return ({
+        value: values[name],
+        onChange: function (value) {
+            setValues(function (previousValues) {
+                var _a;
+                return (__assign(__assign({}, previousValues), (_a = {}, _a[name] = value, _a)));
+            });
+            touch(name);
+        },
+        onBlur: function () {
+            touch(name);
+        },
+    }); }, [values, touch]);
+    var getInputError = (0, react_1.useCallback)(function (name) { var _a, _b; return (_b = (_a = validate === null || validate === void 0 ? void 0 : validate[name]) === null || _a === void 0 ? void 0 : _a.call(validate, values[name])) !== null && _b !== void 0 ? _b : null; }, [validate, values]);
+    var isValid = (0, react_1.useCallback)(function () { return Object.keys(initialValues).every(function (name) { return getInputError(name) === null; }); }, [initialValues, getInputError]);
+    var isInputTouchedOrDirty = (0, react_1.useCallback)(function (name) { return touchedInputs[name] || values[name] !== initialValues[name]; }, [touchedInputs, values, initialValues]);
+    var isInputErrorDisplayed = (0, react_1.useCallback)(function (name) { return isInputTouchedOrDirty(name) && !!getInputError(name); }, [isInputTouchedOrDirty, getInputError]);
+    return (0, useObjectMemo_1.useObjectMemo)({
+        getInputValue: getInputValue,
+        getInputProps: getInputProps,
+        isValid: isValid,
+        getInputError: getInputError,
+        isInputErrorDisplayed: isInputErrorDisplayed,
+        isInputTouchedOrDirty: isInputTouchedOrDirty,
+    });
+}
+exports.useForm = useForm;

package/lib/utils/formValidation.utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Basic type definition for a form validation function that can be used with the `useForm` hook.
+ */
+export type FormValidationFunction<K> = (value: K) => string | null;
+/**
+ * Basic form validation errors returned by avaliable validation functions in the SDK.
+ */
+export declare enum BasicValidationErrors {
+    /**
+     * Error returned when the field is required by no value has been passed.
+     */
+    REQUIRED = "required",
+    /**
+     * Error returned when the value is not a valid email.
+     */
+    EMAIL_NOT_VALID = "emailNotValid"
+}
+/**
+ * Util function used to merge multiple validation functions into a single one. The first error discovered will be
+ * returned.
+ */
+export declare function mergeValidationFunctions<K>(...validateFunctions: FormValidationFunction<K>[]): FormValidationFunction<K>;
+/**
+ * Validation function for required fields.
+ */
+export declare function required(value: any): string | null;
+/**
+ * Validation function for valid email fields.
+ */
+export declare function email(value: any): string | null;

package/lib/utils/formValidation.utils.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.email = exports.required = exports.mergeValidationFunctions = exports.BasicValidationErrors = void 0;
+var EMAIL_REGEX = /^((?!\.)[\w\-_.]*[^.])(@\w+)(\.\w+(\.\w+)?[^.\W])$/;
+/**
+ * Basic form validation errors returned by avaliable validation functions in the SDK.
+ */
+var BasicValidationErrors;
+(function (BasicValidationErrors) {
+    /**
+     * Error returned when the field is required by no value has been passed.
+     */
+    BasicValidationErrors["REQUIRED"] = "required";
+    /**
+     * Error returned when the value is not a valid email.
+     */
+    BasicValidationErrors["EMAIL_NOT_VALID"] = "emailNotValid";
+})(BasicValidationErrors = exports.BasicValidationErrors || (exports.BasicValidationErrors = {}));
+/**
+ * Util function used to merge multiple validation functions into a single one. The first error discovered will be
+ * returned.
+ */
+function mergeValidationFunctions() {
+    var validateFunctions = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        validateFunctions[_i] = arguments[_i];
+    }
+    return function (value) {
+        for (var i = 0; i < validateFunctions.length; i++) {
+            var error = validateFunctions[i](value);
+            if (error) {
+                return error;
+            }
+        }
+        return null;
+    };
+}
+exports.mergeValidationFunctions = mergeValidationFunctions;
+/**
+ * Validation function for required fields.
+ */
+function required(value) {
+    return value !== null && value !== undefined && value !== ''
+        ? null
+        : BasicValidationErrors.REQUIRED;
+}
+exports.required = required;
+/**
+ * Validation function for valid email fields.
+ */
+function email(value) {
+    var error = required(value);
+    if (error) {
+        return error;
+    }
+    return typeof value === 'string' && value.match(EMAIL_REGEX) !== null
+        ? null
+        : BasicValidationErrors.EMAIL_NOT_VALID;
+}
+exports.email = email;

package/lib/utils/index.d.ts

@@ -8,3 +8,4 @@ export * from './browser.utils';
 export * from './env.utils';
 export * from './state.utils';
 export * from './config.utils';
+export * from './formValidation.utils';

package/lib/utils/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./browser.utils"), exports);
 __exportStar(require("./env.utils"), exports);
 __exportStar(require("./state.utils"), exports);
 __exportStar(require("./config.utils"), exports);
+__exportStar(require("./formValidation.utils"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monkvision/common",
-  "version": "4.2.9",
+  "version": "4.3.0",
   "license": "BSD-3-Clause-Clear",
   "packageManager": "yarn@3.2.4",
   "description": "MonkJs common logic package",
@@ -28,10 +28,10 @@
     "lint:fix": "yarn run prettier:fix && yarn run eslint:fix"
   },
   "dependencies": {
-    "@monkvision/analytics": "4.2.9",
-    "@monkvision/monitoring": "4.2.9",
-    "@monkvision/sights": "4.2.9",
-    "@monkvision/types": "4.2.9",
+    "@monkvision/analytics": "4.3.0",
+    "@monkvision/monitoring": "4.3.0",
+    "@monkvision/sights": "4.3.0",
+    "@monkvision/types": "4.3.0",
     "i18next": "^23.4.5",
     "jsonwebtoken": "^9.0.2",
     "jwt-decode": "^4.0.0",
@@ -47,13 +47,13 @@
     "react-router-dom": "^6.22.3"
   },
   "devDependencies": {
-    "@monkvision/eslint-config-base": "4.2.9",
-    "@monkvision/eslint-config-typescript": "4.2.9",
-    "@monkvision/eslint-config-typescript-react": "4.2.9",
-    "@monkvision/jest-config": "4.2.9",
-    "@monkvision/prettier-config": "4.2.9",
-    "@monkvision/test-utils": "4.2.9",
-    "@monkvision/typescript-config": "4.2.9",
+    "@monkvision/eslint-config-base": "4.3.0",
+    "@monkvision/eslint-config-typescript": "4.3.0",
+    "@monkvision/eslint-config-typescript-react": "4.3.0",
+    "@monkvision/jest-config": "4.3.0",
+    "@monkvision/prettier-config": "4.3.0",
+    "@monkvision/test-utils": "4.3.0",
+    "@monkvision/typescript-config": "4.3.0",
     "@testing-library/react": "^12.1.5",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/jest": "^29.2.2",
@@ -96,5 +96,5 @@
     "url": "https://github.com/monkvision/monkjs/issues"
   },
   "homepage": "https://github.com/monkvision/monkjs",
-  "gitHead": "7454a8e35d2722a1c88c65d5aea1a302d559b161"
+  "gitHead": "afd80da7a5eaa1c16fd1f81e9b889d960f1b0c26"
 }