use-mask-input 3.6.0 → 3.7.0

package/src/api/useHookFormMask.ts

@@ -0,0 +1,56 @@
+import { applyMaskToElement } from '../core';
+import { flow } from '../utils';
+
+import type { RefCallback } from 'react';
+import type {
+  FieldValues, Path,
+  RegisterOptions,
+  UseFormRegister,
+} from 'react-hook-form';
+
+import type { Mask, Options, UseHookFormMaskReturn } from '../types';
+
+/**
+ * Creates a masked version of React Hook Form's register function.
+ * Takes react-hook-form's register and adds automatic masking. Like an upgrade.
+ *
+ * @template T - The form data type
+ * @template D - The register options type
+ * @param registerFn - The register function from useForm hook
+ * @returns A function that registers a field with mask support
+ */
+export default function useHookFormMask<
+  T extends FieldValues, D extends RegisterOptions,
+>(registerFn: UseFormRegister<T>) {
+  return (fieldName: Path<T>, mask: Mask, options?: (
+    D & Options) | Options | D): UseHookFormMaskReturn<T> => {
+    if (!registerFn) throw new Error('registerFn is required');
+
+    const registerReturn = registerFn(fieldName, options as Options);
+    const { ref } = registerReturn as UseHookFormMaskReturn<T>;
+
+    const applyMaskToRef = (_ref: HTMLElement | null) => {
+      if (_ref) applyMaskToElement(_ref, mask, options as Options);
+      return _ref;
+    };
+
+    const refWithMask = ref
+      ? flow(applyMaskToRef, ref)
+      : applyMaskToRef;
+
+    const result = {
+      ...registerReturn,
+      ref: refWithMask as RefCallback<HTMLElement | null>,
+    } as UseHookFormMaskReturn<T>;
+
+    // change prevRef to non-enumerable
+    Object.defineProperty(result, 'prevRef', {
+      value: ref,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+
+    return result;
+  };
+}

package/src/api/useMaskInput-server.spec.tsx

@@ -0,0 +1,30 @@
+import { act, renderHook } from '@testing-library/react';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+vi.mock('../utils/isServer', () => ({
+  default: true,
+}));
+
+describe('useMaskInput server-side', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+  });
+
+  it('returns no-op function on server', async () => {
+    const { default: useMaskInput } = await import('./useMaskInput');
+    const { result } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    expect(typeof result.current).toBe('function');
+
+    act(() => {
+      result.current(document.createElement('input'));
+    });
+
+    // should do nothing on server
+    expect(result.current).toBeDefined();
+  });
+});

package/src/api/useMaskInput.spec.tsx

@@ -0,0 +1,220 @@
+import { act, renderHook } from '@testing-library/react';
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+import useMaskInput from './useMaskInput';
+import * as core from '../core';
+
+import type { Input } from '../types';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+vi.mock('../utils/isServer', () => ({
+  default: false,
+}));
+
+describe('useMaskInput', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a ref callback function', () => {
+    const { result } = renderHook(() => useMaskInput({ mask: '999-999' }));
+    expect(typeof result.current).toBe('function');
+  });
+
+  it('handles null input', () => {
+    const { result } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(null);
+    });
+
+    expect(result.current).toBeDefined();
+  });
+
+  it('handles direct input element', () => {
+    const input = document.createElement('input');
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(input);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('handles ref object', () => {
+    const input = document.createElement('input');
+    const ref = { current: input };
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(ref as unknown as Input);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('handles wrapper element with input inside', () => {
+    const wrapper = document.createElement('div');
+    const input = document.createElement('input');
+    wrapper.appendChild(input);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(wrapper);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('handles invalid element in ref', () => {
+    const invalidRef = { current: 'not an element' };
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(invalidRef as unknown as Input);
+    });
+
+    expect(result.current).toBeDefined();
+  });
+
+  it('handles element that is not HTMLElement in useEffect', () => {
+    vi.spyOn(core, 'isHTMLElement').mockReturnValueOnce(false);
+
+    const invalidElement = { nodeType: 1 } as unknown as Input;
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(invalidElement as unknown as Input);
+    });
+
+    rerender();
+
+    expect(result.current).toBeDefined();
+  });
+
+  it('handles wrapper without input inside', () => {
+    const wrapper = document.createElement('div');
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(wrapper);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('works with custom options', () => {
+    const input = document.createElement('input');
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({
+      mask: '999-999',
+      options: { placeholder: '_' },
+    }));
+
+    act(() => {
+      result.current(input);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('works with alias masks', () => {
+    const input = document.createElement('input');
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: 'cpf' }));
+
+    act(() => {
+      result.current(input);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('calls register callback when provided', () => {
+    const input = document.createElement('input');
+    const register = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({
+      mask: '999-999',
+      register,
+    }));
+
+    act(() => {
+      result.current(input);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('handles textarea element', () => {
+    const textarea = document.createElement('textarea');
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(textarea);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('handles case where findInputElement returns valid element', () => {
+    const wrapper = document.createElement('div');
+    const input = document.createElement('input');
+    wrapper.appendChild(input);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
+
+    act(() => {
+      result.current(wrapper);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+});

package/src/api/useMaskInput.ts

@@ -0,0 +1,73 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import {
+  createMaskInstance, findInputElement, isHTMLElement, resolveInputRef,
+} from '../core';
+import isServer from '../utils/isServer';
+
+import type { Input, Mask, Options } from '../types';
+
+interface UseMaskInputOptions {
+  mask: Mask;
+  register?: (element: HTMLElement) => void;
+  options?: Options;
+}
+
+/**
+ * React hook for applying input masks to form elements.
+ * Works with Ant Design and other wrapped components too.
+ *
+ * @param props - Configuration object
+ * @param props.mask - The mask pattern to apply
+ * @param props.register - Optional callback that receives the element
+ * @param props.options - Optional mask configuration options
+ * @returns A ref callback function to attach to the input element
+ */
+export default function useMaskInput(props: UseMaskInputOptions): ((input: Input | null) => void) {
+  const { mask, register, options } = props;
+  const ref = useRef<HTMLInputElement | null>(null);
+  const maskInput = useMemo(
+    () => (isServer ? null : createMaskInstance(mask, options)),
+    [mask, options],
+  );
+
+  const refCallback = useCallback((input: Input | null): void => {
+    if (!input) {
+      ref.current = null;
+      return;
+    }
+
+    ref.current = resolveInputRef(input);
+  }, []);
+
+  useEffect(() => {
+    if (isServer || !ref.current) return;
+
+    if (!isHTMLElement(ref.current)) {
+      return;
+    }
+
+    const inputElement = findInputElement(ref.current);
+
+    if (maskInput && inputElement && isHTMLElement(inputElement)) {
+      maskInput.mask(inputElement);
+    }
+
+    if (register && isHTMLElement(ref.current)) {
+      register(ref.current);
+    }
+  }, [mask, register, options, maskInput]);
+
+  if (isServer) {
+    return (): void => {
+      // server doesn't have dom, so just do nothing
+    };
+  }
+
+  return refCallback;
+}

package/src/api/withHookFormMask.spec.ts

@@ -0,0 +1,155 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+import withHookFormMask from './withHookFormMask';
+
+import type { RefCallback } from 'react';
+import type { FieldValues, UseFormRegisterReturn } from 'react-hook-form';
+
+import type { UseHookFormMaskReturn } from '../types';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+describe('withHookFormMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns register object with masked ref', () => {
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+
+    expect(result.ref).toBeDefined();
+    expect(typeof result.ref).toBe('function');
+    expect(result.onChange).toBe(register.onChange);
+    expect(result.onBlur).toBe(register.onBlur);
+    expect(result.name).toBe(register.name);
+  });
+
+  it('applies mask when ref is called', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('calls original ref after applying mask', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      ref: originalRef,
+      prevRef: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+    result.ref?.(input);
+
+    expect(originalRef).toHaveBeenCalled();
+  });
+
+  it('works with alias masks', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      ref: originalRef,
+      prevRef: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'cpf',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, 'cpf');
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('works with custom options', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999', { placeholder: '_' });
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('handles null ref gracefully', () => {
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: null as unknown as RefCallback<HTMLElement | null>,
+      ref: null as unknown as RefCallback<HTMLElement | null>,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+
+    const result = withHookFormMask(register, '999-999');
+    expect(result.ref).toBeNull();
+    expect(result.onChange).toBe(register.onChange);
+    expect(result.onBlur).toBe(register.onBlur);
+  });
+
+  it('handles null input in ref callback', () => {
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+    result.ref?.(null as unknown as HTMLElement);
+
+    expect(maskFn).not.toHaveBeenCalled();
+  });
+});

package/src/api/withHookFormMask.ts

@@ -0,0 +1,54 @@
+/* eslint-disable no-nested-ternary */
+import { applyMaskToElement } from '../core';
+import { flow } from '../utils';
+
+import type { RefCallback } from 'react';
+import type { FieldValues } from 'react-hook-form';
+
+import type {
+  Mask, Options, UseFormRegisterReturn, UseHookFormMaskReturn,
+} from '../types';
+
+/**
+ * Enhances a React Hook Form register return object with mask support.
+ * Takes an already registered field and adds mask to it.
+ * Useful when you registered the field before.
+ *
+ * @param register - The register return object from React Hook Form
+ * @param mask - The mask pattern to apply
+ * @param options - Optional mask configuration options
+ * @returns A new register return object with mask applied
+ */
+export default function withHookFormMask(
+  register: UseFormRegisterReturn,
+  mask: Mask,
+  options?: Options,
+): UseHookFormMaskReturn<FieldValues> {
+  const { ref } = register as UseHookFormMaskReturn<FieldValues>;
+
+  const applyMaskToRef = (_ref: HTMLElement | null) => {
+    if (_ref) applyMaskToElement(_ref, mask, options);
+    return _ref;
+  };
+
+  const refWithMask = ref === null
+    ? null
+    : ref
+      ? flow(applyMaskToRef, ref)
+      : null;
+
+  const result = {
+    ...register,
+    ref: refWithMask as RefCallback<HTMLElement | null>,
+  } as UseHookFormMaskReturn<FieldValues>;
+
+  // change prevRef to non-enumerable
+  Object.defineProperty(result, 'prevRef', {
+    value: ref,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  return result;
+}

package/src/api/withMask.spec.ts

@@ -0,0 +1,93 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach, describe, expect, it, vi,
+} from 'vitest';
+
+import withMask from './withMask';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+vi.mock('../utils/isServer', () => ({
+  default: false,
+}));
+
+describe('withMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a function', () => {
+    const result = withMask('999-999');
+    expect(typeof result).toBe('function');
+  });
+
+  it('applies mask to input element', () => {
+    const input = document.createElement('input');
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask('999-999');
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  it('does nothing if input is null', () => {
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask('999-999');
+    refCallback(null);
+
+    expect(maskFn).not.toHaveBeenCalled();
+  });
+
+  it('does nothing if mask is null', () => {
+    const input = document.createElement('input');
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask(null);
+    refCallback(input);
+
+    expect(maskFn).not.toHaveBeenCalled();
+  });
+
+  it('applies mask with custom options', () => {
+    const input = document.createElement('input');
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask('999-999', { placeholder: '_' });
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  it('works with alias masks', () => {
+    const input = document.createElement('input');
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask('cpf');
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  it('works with array masks', () => {
+    const input = document.createElement('input');
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask(['999-999', '9999-9999']);
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+});

package/src/api/withMask.ts

@@ -0,0 +1,25 @@
+/* eslint-disable import-x/no-extraneous-dependencies */
+import inputmask from 'inputmask';
+
+import { getMaskOptions } from '../core/maskConfig';
+import isServer from '../utils/isServer';
+import interopDefaultSync from '../utils/moduleInterop';
+
+import type { Input, Mask, Options } from '../types';
+
+/**
+ * Higher-order function that creates a ref callback for applying input masks.
+ * Simple function to apply mask via ref. No hooks, no drama.
+ *
+ * @param mask - The mask pattern to apply
+ * @param options - Optional mask configuration options
+ * @returns A ref callback function that applies the mask
+ */
+export default function withMask(mask: Mask, options?: Options) {
+  return (input: Input | null): void => {
+    if (isServer || mask === null || !input) return;
+
+    const maskInput = interopDefaultSync(inputmask)(getMaskOptions(mask, options));
+    maskInput.mask(input as HTMLElement);
+  };
+}