@simplybusiness/mobius 6.1.1 → 6.2.0

package/src/components/MaskedField/MaskedField.mdx

@@ -0,0 +1,209 @@
+import { Meta, ArgTypes, Canvas } from "@storybook/addon-docs/blocks";
+import * as MaskedFieldStories from "./MaskedField.stories";
+import { MaskedField } from "./MaskedField";
+
+<Meta of={MaskedFieldStories} />
+
+# MaskedField
+
+The `MaskedField` component is a form input field that automatically formats user input to match supplied patterns. It supports e.g. phone number formatting, comma-separated numbers, and custom mask patterns to ensure consistent data entry.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { MaskedField } from "@simplybusiness/mobius";
+```
+
+### Phone Number
+
+<Canvas of={MaskedFieldStories.PhoneNumber} />
+
+### Comma Separated Number
+
+<Canvas of={MaskedFieldStories.CommaSeparatedNumber} />
+
+## Props
+
+The `MaskedField` component accepts all props from the `TextField` component, plus the following specific props:
+
+### `mask` (required)
+
+**Type:** `ReactMaskOpts` (from react-imask)
+
+The mask configuration that defines how the input should be formatted. This can be:
+
+- **String pattern**: A string using placeholders like `(000) 000-0000` for phone numbers
+- **RegExp**: A regular expression pattern
+- **Function**: A custom masking function
+- **Number**: For numeric inputs with formatting options
+- **Date**: For date inputs
+- **Object**: Configuration object with mask options
+
+For comprehensive documentation on mask configuration options, see the [IMask.js guide](https://imask.js.org/guide.html).
+
+#### Number Masks
+
+Number masks are used for formatting numeric inputs with various options for decimal places, thousands separators, and value constraints.
+
+**Basic Example:**
+```js
+const numberMask = {
+  mask: Number,
+  thousandsSeparator: ",",
+  scale: 0, // Number of decimal places
+  signed: false // Allow negative numbers
+};
+```
+
+**Advanced Example:**
+```js
+const advancedNumberMask = {
+  mask: Number,
+  scale: 2, // digits after point, 0 for integers
+  thousandsSeparator: ',', // any single char
+  padFractionalZeros: false, // if true, pads zeros at end to the length of scale
+  normalizeZeros: true, // appends or removes zeros at ends
+  radix: '.', // fractional delimiter
+  mapToRadix: ['.'], // symbols to process as radix
+  min: -10000, // minimum value
+  max: 10000, // maximum value
+  autofix: true // automatically fix values that exceed min/max
+};
+```
+
+**Available Options:**
+- **`scale`** (number): Digits after the decimal point (0 for integers only)
+- **`thousandsSeparator`** (string): Character to use as thousands separator (e.g., ',' or ' ')
+- **`padFractionalZeros`** (boolean): If true, pads zeros at the end to match the scale length
+- **`normalizeZeros`** (boolean): Appends or removes zeros at the beginning/end
+- **`radix`** (string): Character used as decimal separator (e.g., '.' or ',')
+- **`mapToRadix`** (array): Array of characters that should be treated as the radix
+- **`min`** (number): Minimum allowed value
+- **`max`** (number): Maximum allowed value
+- **`autofix`** (boolean): Automatically fix values that exceed min/max bounds
+- **`signed`** (boolean): Allow negative numbers
+
+For more number masking options, see: https://imask.js.org/guide.html#masked-number
+
+#### Pattern Masks
+
+Pattern masks use special characters to define input structure with placeholders and custom definitions.
+
+**Basic Example:**
+```js
+const phoneNumberMask = {
+  mask: "(000) 000-0000"
+};
+```
+
+**Custom Definitions Example:**
+```js
+const customMask = {
+  mask: "AA-0000", // A = letter, 0 = digit
+  definitions: {
+    'A': /[A-Z]/,
+    '0': /\d/
+  }
+};
+```
+
+**Advanced Pattern Example:**
+```js
+const patternMaskWithPlaceholder = {
+  mask: '+{7}(000)000-00-00',
+  lazy: false, // make placeholder always visible
+  placeholderChar: '#' // defaults to '_'
+};
+```
+
+**Secure Input Example:**
+```js
+const secureMask = {
+  mask: '000000',
+  displayChar: '#', // character to display for entered digits
+  lazy: false,
+  overwrite: 'shift'
+};
+```
+
+**Built-in Definitions:**
+- **`0`** - any digit
+- **`a`** - any letter  
+- **`*`** - any character
+- **`[]`** - make input optional (e.g., `000[000]` makes last 3 digits optional)
+- **`{}`** - include fixed part in unmasked value
+- **`` ` ``** - prevent symbols from shifting back
+- **`\\`** - escape character to treat definition chars as fixed (e.g., `\\0` for literal "0")
+
+**Configuration Options:**
+- **`definitions`** (object): Custom character definitions (e.g., `{ '#': /[1-6]/ }`)
+- **`lazy`** (boolean): When false, shows placeholder immediately; when true, shows on focus
+- **`placeholderChar`** (string): Character to use for placeholder (defaults to '_')
+- **`displayChar`** (string): Character to display for entered values (for secure input)
+- **`overwrite`** (string|boolean): Controls overwrite behavior ('shift', true, false)
+
+For more pattern masking options, see: https://imask.js.org/guide.html#masked-pattern
+
+#### Date Masks
+
+Date masks provide structured date input with validation and formatting.
+
+**Example:**
+```js
+const dateMask = {
+  mask: Date,
+  pattern: 'MM/DD/YYYY',
+  min: new Date(1900, 0, 1),
+  max: new Date(2100, 0, 1)
+};
+```
+
+### `useMaskedValue` (optional)
+
+**Type:** `boolean`  
+**Default:** `false`
+
+Controls whether the `onChange` callback receives the masked (formatted) value or the unmasked (raw) value.
+
+- **`false` (default)**: Returns the unmasked value (e.g., "1234567890" for a phone number)
+- **`true`**: Returns the masked value (e.g., "(123) 456-7890" for a phone number)
+
+#### Example:
+
+```js
+// With useMaskedValue=false (default)
+<MaskedField
+  mask={{ mask: "(000) 000-0000" }}
+  onChange={(e) => console.log(e.target.value)} // Logs: "1234567890"
+/>
+
+// With useMaskedValue=true
+<MaskedField
+  mask={{ mask: "(000) 000-0000" }}
+  useMaskedValue={true}
+  onChange={(e) => console.log(e.target.value)} // Logs: "(123) 456-7890"
+/>
+```
+
+<ArgTypes of={MaskedField} />
+
+## Component HTML Structure and Class names
+
+The following HTML is rendered for a MaskedField:
+
+```html
+<div class="mobius mobius-text-field">
+  <label class="mobius-text-field__label">
+    <!-- Label text -->
+  </label>
+  <input class="mobius-text-field__input" type="text" />
+</div>
+```
+
+The MaskedField component extends the TextField component and inherits its CSS classes and structure.

package/src/components/MaskedField/MaskedField.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { MaskedFieldProps } from ".";
+import { MaskedField } from ".";
+import { excludeControls } from "../../utils";
+
+const commaSeparatedNumberMask = {
+  mask: Number,
+  thousandsSeparator: ",",
+  scale: 0,
+  signed: false,
+};
+
+const usPhoneNumberMask = {
+  mask: "(000) 000-0000",
+};
+
+type StoryType = StoryObj<typeof MaskedField>;
+
+const meta: Meta<typeof MaskedField> = {
+  title: "Forms/MaskedField",
+  component: MaskedField,
+  argTypes: excludeControls("className"),
+};
+
+export const PhoneNumber: StoryType = {
+  render: (args: MaskedFieldProps) => (
+    <MaskedField
+      {...args}
+      mask={usPhoneNumberMask}
+      placeholder="Enter phone number"
+      label="Phone Number"
+    />
+  ),
+  args: {
+    mask: usPhoneNumberMask,
+  },
+};
+
+export const CommaSeparatedNumber: StoryType = {
+  render: (args: MaskedFieldProps) => (
+    <MaskedField
+      {...args}
+      mask={commaSeparatedNumberMask}
+      placeholder="Enter number"
+      label="Number"
+    />
+  ),
+  args: {
+    mask: commaSeparatedNumberMask,
+  },
+};
+
+export default meta;

package/src/components/MaskedField/MaskedField.test.tsx

@@ -0,0 +1,350 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MaskedField } from ".";
+
+const commaSeparatedNumberMask = {
+  mask: Number,
+  thousandsSeparator: ",",
+  scale: 0,
+  signed: false,
+};
+
+const usPhoneNumberMask = {
+  mask: "(000) 000-0000",
+};
+
+const WRAPPER_CLASS_NAME = "mobius-text-field";
+const INPUT_CLASS_NAME = "mobius-text-field__input";
+
+describe("MaskedField", () => {
+  it("should render without errors", () => {
+    render(
+      <MaskedField
+        mask={usPhoneNumberMask}
+        label="Phone Number"
+        data-testid="masked-field"
+      />,
+    );
+    expect(screen.getByTestId("masked-field")).toBeInTheDocument();
+  });
+
+  it("should render with correct base class names", () => {
+    const { container } = render(
+      <MaskedField
+        mask={usPhoneNumberMask}
+        label="Phone Number"
+        data-testid="masked-field"
+      />,
+    );
+
+    expect(container.firstChild).toHaveClass("mobius");
+    expect(container.firstChild).toHaveClass(WRAPPER_CLASS_NAME);
+    expect(screen.getByTestId("masked-field")).toHaveClass("mobius");
+    expect(screen.getByTestId("masked-field")).toHaveClass(INPUT_CLASS_NAME);
+  });
+
+  it("should apply phone number mask correctly", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MaskedField
+        mask={usPhoneNumberMask}
+        label="Phone Number"
+        data-testid="masked-field"
+      />,
+    );
+
+    const input = screen.getByTestId("masked-field");
+
+    await user.type(input, "1234567890");
+
+    expect(input).toHaveValue("(123) 456-7890");
+  });
+
+  it("should apply comma-separated number mask correctly", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MaskedField
+        mask={commaSeparatedNumberMask}
+        label="Number"
+        data-testid="masked-field"
+      />,
+    );
+
+    const input = screen.getByTestId("masked-field");
+
+    await user.type(input, "1234567");
+
+    expect(input).toHaveValue("1,234,567");
+  });
+
+  describe("onChange behavior", () => {
+    it("should call onChange with unmasked value by default", async () => {
+      const user = userEvent.setup();
+      const mockOnChange = jest.fn();
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          onChange={mockOnChange}
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      await user.type(input, "1234567890");
+
+      // Should be called with the unmasked value
+      expect(mockOnChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: expect.objectContaining({
+            value: "1234567890",
+          }),
+        }),
+      );
+    });
+
+    it("should call onChange with masked value when useMaskedValue is true", async () => {
+      const user = userEvent.setup();
+      const mockOnChange = jest.fn();
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          onChange={mockOnChange}
+          useMaskedValue={true}
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      await user.type(input, "1234567890");
+
+      // Should be called with the masked value
+      expect(mockOnChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: expect.objectContaining({
+            value: "(123) 456-7890",
+          }),
+        }),
+      );
+    });
+
+    it("should include name in onChange event when provided", async () => {
+      const user = userEvent.setup();
+      const mockOnChange = jest.fn();
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          name="phoneNumber"
+          onChange={mockOnChange}
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      await user.type(input, "123");
+
+      expect(mockOnChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: expect.objectContaining({
+            name: "phoneNumber",
+          }),
+          currentTarget: expect.objectContaining({
+            name: "phoneNumber",
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("controlled component behavior", () => {
+    it("should accept value prop without errors", () => {
+      // This test verifies that the component can accept a value prop
+      // without throwing errors, even if the useIMask hook doesn't
+      // immediately format it
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          value="9876543210"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toBeInTheDocument();
+    });
+
+    it("should work with defaultValue prop", () => {
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          defaultValue="1234567890"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toHaveValue("(123) 456-7890");
+    });
+  });
+
+  describe("accessibility", () => {
+    it("should forward aria-label correctly", () => {
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          aria-label="Custom phone number label"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toHaveAttribute("aria-label", "Custom phone number label");
+    });
+
+    it("should forward aria-describedby correctly", () => {
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          aria-describedby="phone-help"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toHaveAttribute("aria-describedby", "phone-help");
+    });
+  });
+
+  describe("ref forwarding", () => {
+    it("should forward ref to the input element", () => {
+      let inputRef: HTMLInputElement | null = null;
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+          ref={ref => {
+            inputRef = ref;
+          }}
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(inputRef).toBe(input);
+    });
+
+    it("should work with useRef", () => {
+      const TestComponent = () => {
+        const inputRef = React.useRef<HTMLInputElement>(null);
+
+        return (
+          <MaskedField
+            mask={usPhoneNumberMask}
+            label="Phone Number"
+            data-testid="masked-field"
+            ref={inputRef}
+          />
+        );
+      };
+
+      render(<TestComponent />);
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toBeInTheDocument();
+    });
+  });
+
+  describe("custom mask configurations", () => {
+    it("should work with custom mask objects", async () => {
+      const user = userEvent.setup();
+      const customMask = {
+        mask: "000-000",
+        definitions: {
+          "0": /[0-9]/,
+        },
+      };
+
+      render(
+        <MaskedField
+          mask={customMask}
+          label="Custom Code"
+          data-testid="masked-field"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      await user.type(input, "123456");
+
+      expect(input).toHaveValue("123-456");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty input gracefully", () => {
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+      expect(input).toHaveValue("");
+    });
+
+    it("should not call onChange when no onChange handler is provided", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      // Should not throw an error
+      await user.type(input, "123");
+
+      expect(input).toHaveValue("(123");
+    });
+
+    it("should handle partial input correctly", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <MaskedField
+          mask={usPhoneNumberMask}
+          label="Phone Number"
+          data-testid="masked-field"
+        />,
+      );
+
+      const input = screen.getByTestId("masked-field");
+
+      await user.type(input, "123");
+
+      expect(input).toHaveValue("(123");
+    });
+  });
+});

package/src/components/MaskedField/MaskedField.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import type { Ref, RefAttributes } from "react";
+import { forwardRef } from "react";
+import type { ReactMaskOpts } from "react-imask";
+import { useIMask } from "react-imask";
+import type { DOMProps } from "../../types/dom";
+import type { ForwardedRefComponent } from "../../types/components";
+import { TextField, type TextFieldProps } from "../TextField";
+
+export type MaskedFieldElementType = HTMLInputElement;
+
+export interface MaskedFieldProps
+  extends Omit<TextFieldProps, "type">,
+    DOMProps,
+    RefAttributes<MaskedFieldElementType> {
+  /** The mask configuration to apply */
+  mask: ReactMaskOpts;
+  /** Whether to return the masked (formatted) value in onChange. Defaults to false (unmasked value) */
+  useMaskedValue?: boolean;
+}
+
+export type MaskedFieldRef = Ref<MaskedFieldElementType>;
+
+export const MaskedField: ForwardedRefComponent<
+  MaskedFieldProps,
+  MaskedFieldElementType
+> = forwardRef((props: MaskedFieldProps, ref: MaskedFieldRef) => {
+  const {
+    mask,
+    value,
+    defaultValue,
+    useMaskedValue = false,
+    onChange,
+    "aria-describedby": ariaDescribedBy,
+    "aria-label": ariaLabel,
+    ...textFieldProps
+  } = props;
+
+  // Use the useIMask hook to get the mask reference and all value types
+  const { ref: maskRef, value: maskedValue } = useIMask(mask, {
+    defaultValue,
+    onAccept: (value, maskRef) => {
+      // Only trigger onChange when we have a valid masked input
+      if (onChange) {
+        // Determine which value to use based on useMaskedValue
+        const valueToEmit = useMaskedValue ? value : maskRef.unmaskedValue;
+
+        // Create a synthetic event that mimics a ChangeEvent
+        const syntheticEvent = {
+          target: {
+            value: valueToEmit,
+            name: textFieldProps.name,
+          },
+          currentTarget: {
+            value: valueToEmit,
+            name: textFieldProps.name,
+          },
+        } as React.ChangeEvent<HTMLInputElement>;
+
+        onChange(syntheticEvent);
+      }
+    },
+  });
+
+  // Create a composite ref that handles both the mask ref and the forwarded ref
+  const inputRef = (node: HTMLInputElement | null) => {
+    if (maskRef) {
+      maskRef.current = node;
+    }
+    if (ref) {
+      if (typeof ref === "function") {
+        ref(node);
+      } else {
+        ref.current = node;
+      }
+    }
+  };
+
+  return (
+    <TextField
+      {...textFieldProps}
+      ref={inputRef}
+      value={maskedValue}
+      onChange={() => {}} // No-op to satisfy React's controlled component requirement, onChange is handled by the onAccept callback in useIMask
+      aria-describedby={ariaDescribedBy}
+      aria-label={ariaLabel}
+    />
+  );
+});
+
+MaskedField.displayName = "MaskedField";

package/src/components/MaskedField/index.tsx

@@ -0,0 +1 @@
+export * from "./MaskedField";