use-mask-input 3.6.1 → 3.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-mask-input",
-  "version": "3.6.1",
+  "version": "3.7.1",
   "private": false,
   "description": "A react Hook for build elegant input masks. Compatible with React Hook Form",
   "author": "Eduardo Borges<euduardoborges@gmail.com>",
@@ -17,6 +17,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./antd": {
+      "types": "./dist/antd.d.ts",
+      "import": "./dist/antd.js",
+      "require": "./dist/antd.cjs"
     }
   },
   "engines": {
@@ -44,6 +49,7 @@
     "@types/react": ">=17",
     "@types/react-dom": ">=17",
     "@vitest/coverage-v8": "3.2.4",
+    "antd": "^6.2.3",
     "eslint": "^9.35.0",
     "eslint-config-airbnb-extended": "^2.2.0",
     "eslint-import-resolver-typescript": "^4.4.4",

package/src/antd/index.ts

@@ -0,0 +1,9 @@
+import useHookFormMaskAntd from './useHookFormMaskAntd';
+import useMaskInputAntd from './useMaskInputAntd';
+
+export {
+  useHookFormMaskAntd,
+  useMaskInputAntd,
+};
+
+export type { UseHookFormMaskAntdReturn } from './useHookFormMaskAntd';

package/src/antd/useHookFormMaskAntd.spec.ts

@@ -0,0 +1,142 @@
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+import { applyMaskToElement, resolveInputRef } from '../core';
+import useHookFormMaskAntd from './useHookFormMaskAntd';
+
+import type { InputRef } from 'antd';
+import type {
+  FieldValues,
+  UseFormRegister,
+} from 'react-hook-form';
+
+vi.mock('../core', () => ({
+  applyMaskToElement: vi.fn(),
+  resolveInputRef: vi.fn(),
+}));
+
+describe('useHookFormMaskAntd', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a function', () => {
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'test',
+    }));
+
+    const maskedRegister = useHookFormMaskAntd(
+      registerFn as UseFormRegister<FieldValues>,
+    );
+
+    expect(typeof maskedRegister).toBe('function');
+  });
+
+  it('throws when registerFn is missing', () => {
+    const maskedRegister = useHookFormMaskAntd(
+      undefined as unknown as UseFormRegister<FieldValues>,
+    );
+
+    expect(() => maskedRegister('field' as never, '999-999'))
+      .toThrowError('registerFn is required');
+  });
+
+  it('registers field with mask and calls core helpers', () => {
+    const inputElement = document.createElement('input');
+    const prevRef = vi.fn();
+    const registerFn = vi.fn(() => ({
+      ref: prevRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    }));
+
+    vi.mocked(resolveInputRef).mockReturnValue(inputElement);
+
+    const maskedRegister = useHookFormMaskAntd(
+      registerFn as UseFormRegister<FieldValues>,
+    );
+    const options = { placeholder: '_' } as never;
+
+    const result = maskedRegister('phone' as never, '999-999', options);
+
+    expect(registerFn).toHaveBeenCalledWith('phone', options);
+    expect(result.ref).toBeDefined();
+    expect(typeof result.ref).toBe('function');
+
+    const inputRef = { input: inputElement } as unknown as Parameters<
+      ReturnType<typeof useHookFormMaskAntd<FieldValues, never>>
+    >[1];
+
+    result.ref(inputRef as unknown as InputRef);
+
+    expect(resolveInputRef).toHaveBeenCalledWith(inputElement);
+    expect(applyMaskToElement).toHaveBeenCalledWith(
+      inputElement,
+      '999-999',
+      options,
+    );
+    expect(prevRef).toHaveBeenCalledWith(inputElement);
+  });
+
+  it('handles null ref from register', () => {
+    const registerFn = vi.fn(() => ({
+      ref: undefined,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    }));
+
+    const maskedRegister = useHookFormMaskAntd(
+      registerFn as unknown as UseFormRegister<FieldValues>,
+    );
+    const result = maskedRegister('phone' as never, '999-999');
+
+    expect(result.ref).toBeDefined();
+
+    const inputElement = document.createElement('input');
+    vi.mocked(resolveInputRef).mockReturnValue(inputElement);
+
+    const inputRef = { input: inputElement } as unknown as Parameters<
+      ReturnType<typeof useHookFormMaskAntd<FieldValues, never>>
+    >[1];
+
+    result.ref(inputRef as unknown as InputRef);
+
+    expect(applyMaskToElement).toHaveBeenCalled();
+  });
+
+  it('preserves register return properties and defines non-enumerable prevRef', () => {
+    const onChange = vi.fn();
+    const onBlur = vi.fn();
+    const prevRef = vi.fn();
+    const registerFn = vi.fn(() => ({
+      ref: prevRef,
+      onChange,
+      onBlur,
+      name: 'phone',
+    }));
+
+    const maskedRegister = useHookFormMaskAntd(
+      registerFn as UseFormRegister<FieldValues>,
+    );
+    const result = maskedRegister('phone' as never, '999-999');
+
+    expect(result.onChange).toBe(onChange);
+    expect(result.onBlur).toBe(onBlur);
+    expect(result.name).toBe('phone');
+
+    const descriptor = Object.getOwnPropertyDescriptor(result, 'prevRef');
+    expect(descriptor?.enumerable).toBe(false);
+    expect((result as unknown as { prevRef: typeof prevRef }).prevRef)
+      .toBe(prevRef);
+  });
+});

package/src/antd/useHookFormMaskAntd.ts

@@ -0,0 +1,57 @@
+import { applyMaskToElement, resolveInputRef } from '../core';
+
+import type { InputRef } from 'antd';
+import type { RefCallback } from 'react';
+import type {
+  FieldValues, Path,
+  RegisterOptions,
+  UseFormRegister,
+} from 'react-hook-form';
+
+import type { Mask, Options, UseHookFormMaskReturn } from '../types';
+
+export type UseHookFormMaskAntdReturn<T extends FieldValues> = Omit<
+  UseHookFormMaskReturn<T>,
+  'ref'
+> & { ref: RefCallback<InputRef | null> };
+
+/**
+ * Ant Design version of useHookFormMask.
+ * Creates a masked register that works with Ant Design Input (ref receives InputRef).
+ *
+ * @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 for Ant Design Input
+ */
+export default function useHookFormMaskAntd<
+  T extends FieldValues, D extends RegisterOptions,
+>(registerFn: UseFormRegister<T>) {
+  return (fieldName: Path<T>, mask: Mask, options?: (
+    D & Options) | Options | D): UseHookFormMaskAntdReturn<T> => {
+    if (!registerFn) throw new Error('registerFn is required');
+
+    const registerReturn = registerFn(fieldName, options as Options);
+    const { ref } = registerReturn as UseHookFormMaskReturn<T>;
+
+    const refWithMask: RefCallback<InputRef | null> = (inputRef) => {
+      const element = inputRef ? resolveInputRef(inputRef.input) : null;
+      if (element) applyMaskToElement(element, mask, options as Options);
+      if (ref) ref(element);
+    };
+
+    const result = {
+      ...registerReturn,
+      ref: refWithMask,
+    } as UseHookFormMaskAntdReturn<T>;
+
+    Object.defineProperty(result, 'prevRef', {
+      value: ref,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+
+    return result;
+  };
+}

package/src/antd/useMaskInputAntd-server.spec.tsx

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

package/src/antd/useMaskInputAntd.spec.tsx

@@ -0,0 +1,109 @@
+import { act, renderHook } from '@testing-library/react';
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+import useMaskInputAntd from './useMaskInputAntd';
+
+import type { InputRef } from 'antd';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+vi.mock('../utils/isServer', () => ({
+  default: false,
+}));
+
+describe('useMaskInputAntd', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a ref callback function', () => {
+    const { result } = renderHook(() => useMaskInputAntd({ mask: '999-999' }));
+    expect(typeof result.current).toBe('function');
+  });
+
+  it('handles null input ref', () => {
+    const { result } = renderHook(() => useMaskInputAntd({ mask: '999-999' }));
+
+    act(() => {
+      result.current(null);
+    });
+
+    expect(result.current).toBeDefined();
+  });
+
+  it('applies mask to element when given InputRef with input element', () => {
+    const inputElement = document.createElement('input');
+    vi.mocked(inputmask).mockReturnValue({
+      mask: vi.fn(),
+    } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(
+      () => useMaskInputAntd({ mask: '999-999' }),
+    );
+
+    act(() => {
+      result.current({ input: inputElement } as unknown as InputRef);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('works with custom options', () => {
+    const inputElement = document.createElement('input');
+    vi.mocked(inputmask).mockReturnValue({
+      mask: vi.fn(),
+    } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(
+      () => useMaskInputAntd({
+        mask: '999-999',
+        options: { placeholder: '_' },
+      }),
+    );
+
+    act(() => {
+      result.current({ input: inputElement } as unknown as InputRef);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+
+  it('accepts register option and applies mask', () => {
+    const inputElement = document.createElement('input');
+    const register = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({
+      mask: vi.fn(),
+    } as unknown as Inputmask.Instance);
+
+    const { result, rerender } = renderHook(
+      () => useMaskInputAntd({
+        mask: '999-999',
+        register,
+      }),
+    );
+
+    act(() => {
+      result.current({ input: inputElement } as unknown as InputRef);
+    });
+
+    rerender();
+
+    expect(inputmask).toHaveBeenCalled();
+  });
+});

package/src/antd/useMaskInputAntd.ts

@@ -0,0 +1,77 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import {
+  createMaskInstance, findInputElement, isHTMLElement, resolveInputRef,
+} from '../core';
+import isServer from '../utils/isServer';
+
+import type { InputRef } from 'antd';
+
+import type { 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 useMaskInputAntd(props: UseMaskInputOptions): (
+  input: InputRef | null
+) => void {
+  const { mask, register, options } = props;
+  const ref = useRef<InputRef | null>(null);
+  const maskInput = useMemo(
+    () => (isServer ? null : createMaskInstance(mask, options)),
+    [mask, options],
+  );
+
+  const refCallback = useCallback((input: InputRef | null) => {
+    if (!input) {
+      ref.current = null;
+      return;
+    }
+
+    ref.current = resolveInputRef(input.input) as unknown as InputRef;
+  }, []);
+
+  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/useMaskInput.ts

@@ -1,4 +1,9 @@
-import { useEffect, useMemo, useRef } from 'react';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
 
 import {
   createMaskInstance, findInputElement, isHTMLElement, resolveInputRef,
@@ -26,15 +31,20 @@ interface UseMaskInputOptions {
 export default function useMaskInput(props: UseMaskInputOptions): ((input: Input | null) => void) {
   const { mask, register, options } = props;
   const ref = useRef<HTMLInputElement | null>(null);
-  const maskInput = useMemo(() => createMaskInstance(mask, options), [mask, options]);
+  const maskInput = useMemo(
+    () => (isServer ? null : createMaskInstance(mask, options)),
+    [mask, options],
+  );
 
-  if (isServer) {
-    return (): void => {
-      // server doesn't have dom, so just do nothing
-    };
-  }
+  const refCallback = useCallback((input: Input | null): void => {
+    if (!input) {
+      ref.current = null;
+      return;
+    }
+
+    ref.current = resolveInputRef(input);
+  }, []);
 
-  // eslint-disable-next-line react-hooks/rules-of-hooks
   useEffect(() => {
     if (isServer || !ref.current) return;
 
@@ -44,21 +54,20 @@ export default function useMaskInput(props: UseMaskInputOptions): ((input: Input
 
     const inputElement = findInputElement(ref.current);
 
-    if (inputElement && isHTMLElement(inputElement)) {
+    if (maskInput && inputElement && isHTMLElement(inputElement)) {
       maskInput.mask(inputElement);
     }
 
     if (register && isHTMLElement(ref.current)) {
       register(ref.current);
     }
-  }, [mask, register, options, maskInput, ref]);
+  }, [mask, register, options, maskInput]);
 
-  return (input: Input | null): void => {
-    if (!input) {
-      ref.current = null;
-      return;
-    }
+  if (isServer) {
+    return (): void => {
+      // server doesn't have dom, so just do nothing
+    };
+  }
 
-    ref.current = resolveInputRef(input);
-  };
+  return refCallback;
 }

package/src/core/elementResolver.ts

@@ -41,7 +41,7 @@ export function findInputElement(element: unknown): HTMLElement | null {
   }
 
   try {
-    const inputElement = element.querySelector('input') ?? element.querySelector('textarea');
+    const inputElement = element.querySelector('input, textarea');
 
     if (inputElement && isHTMLElement(inputElement)) {
       return inputElement;

package/src/core/maskConfig.ts

@@ -2,6 +2,34 @@
 import type { Mask, Options } from '../types';
 import type { Options as InputmaskOptions } from '../types/inputmask.types';
 
+/** Base config for built-in mask aliases. Merged with user options in getMaskOptions. */
+const ALIAS_MASKS: Record<string, InputmaskOptions> = {
+  datetime: { alias: 'datetime' },
+  email: { alias: 'email', placeholder: '' },
+  numeric: { alias: 'numeric', placeholder: '' },
+  currency: { alias: 'currency', prefix: '$ ', placeholder: '' },
+  decimal: { alias: 'decimal', placeholder: '' },
+  integer: { alias: 'integer', placeholder: '' },
+  percentage: { alias: 'percentage', placeholder: ' %', suffix: ' %' },
+  url: { alias: 'url', placeholder: 'https://' },
+  ip: { alias: 'ip' },
+  mac: { alias: 'mac' },
+  ssn: { alias: 'ssn' },
+  'brl-currency': {
+    alias: 'currency',
+    prefix: 'R$ ',
+    placeholder: '0,00',
+    displayFormat: 'currency',
+    radixPoint: ',',
+    autoUnmask: true,
+  },
+  cpf: { mask: '999.999.999-99', placeholder: '___.___.___-__' },
+  cnpj: {
+    mask: ['A|9{2}.A|9{3}.A|9{3}/A|9{4}-9{2}'],
+    placeholder: '__.___.___/____-__',
+  },
+};
+
 /**
  * Converts mask and options into Inputmask configuration.
  * Has some ready aliases to make life easier.
@@ -17,84 +45,9 @@ export function getMaskOptions(mask?: Mask, _options?: Options): Options {
   };
   if (!mask) return options;
 
-  const masks: Record<string, InputmaskOptions> = {
-    datetime: {
-      alias: 'datetime',
-      ...options,
-    },
-    email: {
-      alias: 'email',
-      placeholder: '',
-      ...options,
-    },
-    numeric: {
-      alias: 'numeric',
-      placeholder: '',
-      ...options,
-    },
-    currency: {
-      alias: 'currency',
-      prefix: '$ ',
-      placeholder: '',
-      ...options,
-    },
-    decimal: {
-      alias: 'decimal',
-      placeholder: '',
-      ...options,
-    },
-    integer: {
-      alias: 'integer',
-      placeholder: '',
-      ...options,
-    },
-    percentage: {
-      alias: 'percentage',
-      placeholder: ' %',
-      suffix: ' %',
-      ...options,
-    },
-    url: {
-      alias: 'url',
-      placeholder: 'https://',
-      ...options,
-    },
-    ip: {
-      alias: 'ip',
-      ...options,
-    },
-    mac: {
-      alias: 'mac',
-      ...options,
-    },
-    ssn: {
-      alias: 'ssn',
-      ...options,
-    },
-
-    // alias for brazilians <3
-    'brl-currency': {
-      alias: 'currency',
-      prefix: 'R$ ',
-      placeholder: '0,00',
-      displayFormat: 'currency',
-      radixPoint: ',',
-      autoUnmask: true,
-      ...options,
-    },
-    cpf: {
-      mask: '999.999.999-99',
-      placeholder: '___.___.___-__',
-      ...options,
-    },
-    cnpj: {
-      mask: ['A|9{2}.A|9{3}.A|9{3}/A|9{4}-9{2}'],
-      placeholder: '__.___.___/____-__',
-      ...options,
-    },
-  };
-
-  if (typeof mask === 'string' && masks[mask]) return masks[mask];
+  if (typeof mask === 'string' && ALIAS_MASKS[mask]) {
+    return { ...ALIAS_MASKS[mask], ...options } as Options;
+  }
 
   return {
     mask,