[BD-46] feat: added FormControl input mask

package.json

@@ -68,6 +68,7 @@
     "react-colorful": "^5.6.1",
     "react-dropzone": "^14.2.1",
     "react-focus-on": "^3.5.4",
+    "react-imask": "^7.1.3",
     "react-loading-skeleton": "^3.1.0",
     "react-popper": "^2.2.5",
     "react-proptype-conditional-require": "^1.0.4",

src/Form/FormControl.jsx

@@ -2,6 +2,7 @@ import React, { useCallback, useEffect } from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
 import RBFormControl from 'react-bootstrap/FormControl';
+import { IMaskInput } from 'react-imask';
 import { useFormGroupContext } from './FormGroupContext';
 import FormControlFeedback from './FormControlFeedback';
 import FormControlDecoratorGroup from './FormControlDecoratorGroup';
@@ -17,6 +18,7 @@ const FormControl = React.forwardRef(({
   floatingLabel,
   autoResize,
   onChange,
+  inputMask,
   ...props
 }, ref) => {
   const {
@@ -71,7 +73,7 @@ const FormControl = React.forwardRef(({
       className={className}
     >
       <RBFormControl
-        as={as}
+        as={inputMask ? IMaskInput : as}
         ref={resolvedRef}
         size={size}
         isInvalid={isInvalid}
@@ -80,6 +82,7 @@ const FormControl = React.forwardRef(({
           'has-value': hasValue,
         })}
         onChange={handleOnChange}
+        mask={inputMask}
         {...controlProps}
       />
     </FormControlDecoratorGroup>
@@ -122,6 +125,8 @@ FormControl.propTypes = {
   isInvalid: PropTypes.bool,
   /** Only for `as="textarea"`. Specifies whether the input can be resized according to the height of content. */
   autoResize: PropTypes.bool,
+  /** Specifies what format to use for the input mask. */
+  inputMask: PropTypes.string,
 };
 
 FormControl.defaultProps = {
@@ -140,6 +145,7 @@ FormControl.defaultProps = {
   isValid: undefined,
   isInvalid: undefined,
   autoResize: false,
+  inputMask: undefined,
 };
 
 export default FormControl;

src/Form/form-control.mdx

@@ -43,7 +43,6 @@ or [select attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element
 }
 ```
 
-
 ## Input types
 
 ```jsx live
@@ -163,6 +162,160 @@ or [select attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element
 }
 ```
 
+## Input masks
+Paragon uses the [react-imask](https://www.npmjs.com/package/react-imask) library,
+which allows you to add masks of different types for inputs.
+To create your own mask, you need to pass the required mask pattern (`+{1}(000)000-00-00`) to the `inputMask` property. <br />
+See [react-imask](https://imask.js.org) for documentation on available props.
+
+```jsx live
+() => {
+  {/* start example state */}
+  const [maskType, setMaskType] = useState('phone');
+  {/* end example state */}
+
+  const inputsWithMask = {
+    phone: (
+      <>
+        <h3>Phone</h3>
+        <Form.Group>
+          <Form.Control
+            inputMask="+{1}(000)000-00-00"
+            value={value}
+            onChange={handleChange}
+            leadingElement={<Icon src={FavoriteBorder} />}
+            floatingLabel="What is your phone number?"
+          />
+        </Form.Group>
+      </>
+    ),
+    creditCard: (<>
+      <h3>Credit card</h3>
+      <Form.Group>
+        <Form.Control
+          inputMask="0000 0000 0000 0000"
+          value={value}
+          onChange={handleChange}
+          leadingElement={<Icon src={FavoriteBorder} />}
+          floatingLabel="What is your credit card number?"
+        />
+      </Form.Group>
+    </>),
+    date: (<>
+      <h3>Date</h3>
+      <Form.Group>
+        <Form.Control
+          inputMask={Date}
+          value={value}
+          onChange={handleChange}
+          leadingElement={<Icon src={FavoriteBorder} />}
+          floatingLabel="What is your date of birth?"
+        />
+      </Form.Group>
+    </>),
+    securePassword: (<>
+      <h3>Secure password</h3>
+      <Form.Group>
+        <Form.Control
+          inputMask="XXX-XX-0000"
+          value={value}
+          definitions={{
+            X: {
+              mask: '0',
+              displayChar: 'X',
+              placeholderChar: '#',
+            },
+          }}
+          onChange={handleChange}
+          leadingElement={<Icon src={FavoriteBorder} />}
+          floatingLabel="What is your password?"
+        />
+      </Form.Group>
+    </>),
+    OTPpassword: (<>
+      <h3>OTP password</h3>
+      <Form.Group>
+        <Form.Control
+          inputMask="G-00000"
+          value={value}
+          onChange={handleChange}
+          leadingElement={<Icon src={FavoriteBorder} />}
+          floatingLabel="What is your OPT password?"
+        />
+      </Form.Group>
+    </>),
+    price: (
+        <>
+          <h3>Course prise</h3>
+          <Form.Group>
+            <Form.Control
+              inputMask="$num"
+              blocks={{
+                num: {
+                  // nested masks are available!
+                  mask: Number,
+                  thousandsSeparator: ' '
+                }
+              }}
+              value={value}
+              onChange={handleChange}
+              leadingElement={<Icon src={FavoriteBorder} />}
+              floatingLabel="What is the price of this course?"
+            />
+          </Form.Group>
+        </>
+    ),
+  };
+
+  const [value, setValue] = useState('');
+
+  const handleChange = (e) => setValue(e.target.value);
+
+  return (
+    <>
+      {/* start example form block */}
+      <ExamplePropsForm
+        inputs={[
+          { value: maskType, setValue: setMaskType, options: Object.keys(inputsWithMask), name: 'Mask variants' },
+        ]}
+      />
+      {/* end example form block */}
+
+      {inputsWithMask[maskType]}
+    </>
+  );
+}
+```
+
+## Input masks with clear value
+To get a value without a mask, you need to use `onChange` instead of `onAccept` to handle changes.
+
+```jsx live
+() => {
+  const [value, setValue] = useState('');
+
+  return (
+      <>
+        <Form.Group>
+          <Form.Control
+            inputMask="+{1}(000)000-00-00"
+            leadingElement={<Icon src={FavoriteBorder} />}
+            trailingElement={<Icon src={Verified} />}
+            floatingLabel="What is your phone number?"
+            value={value}
+            // depending on prop above first argument is
+            // `value` if `unmask=false`,
+            // `unmaskedValue` if `unmask=true`,
+            // `typedValue` if `unmask='typed'`
+            onAccept={(_, mask) => setValue(mask._unmaskedValue)}
+          />
+        </Form.Group>
+        Unmasked value: {JSON.stringify(value)}
+      </>
+  );
+}
+```
+
 ## Textarea autoResize
 
 `autoResize` prop allows input to be resized according to the content height.

src/Form/tests/FormControl.test.jsx

@@ -1,5 +1,7 @@
-import React from 'react';
-import { render, screen } from '@testing-library/react';
+import React, { useState } from 'react';
+import {
+  render, screen, act, fireEvent,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 import FormControl from '../FormControl';
@@ -8,6 +10,22 @@ const ref = {
   current: null,
 };
 
+// eslint-disable-next-line react/prop-types
+function Component({ isClearValue }) {
+  const onChangeFunc = jest.fn();
+  const [inputValue, setInputValue] = useState('');
+
+  return (
+    <FormControl
+      inputMask="+{1}(000)000-00-00"
+      value={inputValue}
+      onChange={isClearValue ? onChangeFunc : (e) => setInputValue(e.target.value)}
+      onAccept={isClearValue ? onChangeFunc : (value) => setInputValue(value)}
+      data-testid="form-control-with-mask"
+    />
+  );
+}
+
 describe('FormControl', () => {
   it('textarea changes its height with autoResize prop', async () => {
     const useReferenceSpy = jest.spyOn(React, 'useRef').mockReturnValue(ref);
@@ -31,4 +49,21 @@ describe('FormControl', () => {
     expect(onChangeFunc).toHaveBeenCalledTimes(inputText.length);
     expect(ref.current.style.height).toEqual(`${ref.current.scrollHeight + ref.current.offsetHeight}px`);
   });
+
+  it('should apply and accept input mask for phone numbers', () => {
+    render(<Component />);
+
+    act(() => {
+      const input = screen.getByTestId('form-control-with-mask');
+      userEvent.type(input, '1234567890');
+      expect(input.value).toBe('+1(234)567-89-0');
+    });
+  });
+  it('should be cleared from the mask elements value', () => {
+    render(<Component isClearValue />);
+
+    const input = screen.getByTestId('form-control-with-mask');
+    fireEvent.change(input, { target: { value: '1234567890' } });
+    expect(input.value).toBe('1234567890');
+  });
 });