@simplybusiness/mobius 6.1.2 → 6.2.0

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";

package/src/components/index.tsx

@@ -45,3 +45,4 @@ export * from "./Title";
 export * from "./Trust";
 export * from "./ExpandableText";
 export * from "./VisuallyHidden";
+export * from "./MaskedField";