use-mask-input 3.6.0 → 3.7.0

package/package.json

@@ -1,28 +1,33 @@
 {
   "name": "use-mask-input",
-  "version": "3.6.0",
+  "version": "3.7.0",
+  "private": false,
   "description": "A react Hook for build elegant input masks. Compatible with React Hook Form",
   "author": "Eduardo Borges<euduardoborges@gmail.com>",
   "type": "module",
-  "repository": "https://github.com/eduardoborges/use-mask-input",
+  "repository": {
+    "url": "https://github.com/eduardoborges/use-mask-input"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.tsx",
   "exports": {
     ".": {
       "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": {
     "node": ">=16",
     "npm": ">=7"
   },
-  "scripts": {
-    "build": "./scripts.sh build",
-    "dev": "./scripts.sh dev",
-    "lint": "./scripts.sh lint",
-    "test": "./scripts.sh test",
-    "prepare": "./scripts.sh prepare"
-  },
   "files": [
     "dist",
     "src",
@@ -36,18 +41,15 @@
   "devDependencies": {
     "@eslint/compat": "^1.3.2",
     "@eslint/js": "^9.35.0",
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/commit-analyzer": "13.0.1",
-    "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "11.0.5",
-    "@semantic-release/npm": "12.0.2",
-    "@semantic-release/release-notes-generator": "14.0.3",
     "@stylistic/eslint-plugin": "3.1.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
     "@types/inputmask": "5.0.7",
     "@types/node": "22",
     "@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",
@@ -56,16 +58,20 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "inputmask": "5.0.10-beta.61",
+    "jsdom": "^25.0.1",
     "react-hook-form": "7.62.0",
-    "read-pkg": "9.0.1",
-    "semantic-release": "24.2.7",
-    "simple-git-hooks": "2.13.1",
     "tsup": "8.5.0",
     "typescript": "5.1",
     "typescript-eslint": "^8.42.0",
     "vitest": "3.2.4"
   },
-  "simple-git-hooks": {
-    "pre-commit": "npm run lint && npm run test && npm run build"
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint ./src --ext ts,tsx",
+    "test": "vitest --dir ./src --run --coverage",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "postbuild": "cp ../../README.md README.md"
   }
-}
+}

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';
+
+vi.mock('../core', () => ({
+  applyMaskToElement: vi.fn(),
+  resolveInputRef: vi.fn(),
+}));
+
+import { applyMaskToElement, resolveInputRef } from '../core';
+import useHookFormMaskAntd from './useHookFormMaskAntd';
+
+import type {
+  FieldValues,
+  UseFormRegister,
+} from 'react-hook-form';
+
+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);
+
+    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);
+
+    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,36 @@
+import { act, renderHook } from '@testing-library/react';
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+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 unknown as { input: HTMLElement });
+    });
+
+    // should do nothing on server
+    expect(result.current).toBeDefined();
+  });
+});
+

package/src/antd/useMaskInputAntd.spec.tsx

@@ -0,0 +1,108 @@
+import { act, renderHook } from '@testing-library/react';
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+vi.mock('../utils/isServer', () => ({
+  default: false,
+}));
+
+import useMaskInputAntd from './useMaskInputAntd';
+
+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 { input: HTMLElement });
+    });
+
+    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 { input: HTMLElement });
+    });
+
+    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 { input: HTMLElement });
+    });
+
+    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/index.ts

@@ -0,0 +1,4 @@
+export { default as useMaskInput } from './useMaskInput';
+export { default as useHookFormMask } from './useHookFormMask';
+export { default as withMask } from './withMask';
+export { default as withHookFormMask } from './withHookFormMask';

package/src/api/useHookFormMask.spec.ts

@@ -0,0 +1,146 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+import useHookFormMask from './useHookFormMask';
+
+import type { FieldValues, UseFormRegister } from 'react-hook-form';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+describe('useHookFormMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a function', () => {
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      prevRef: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'test',
+    }));
+
+    const maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    expect(typeof maskedRegister).toBe('function');
+  });
+
+  it('registers field with mask', () => {
+    const input = document.createElement('input');
+    const refCallback = vi.fn();
+    const registerFn = vi.fn(() => ({
+      ref: refCallback,
+      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 maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    const result = maskedRegister('phone', '999-999');
+
+    expect(registerFn).toHaveBeenCalledWith('phone', undefined);
+    expect(result.ref).toBeDefined();
+    expect(typeof result.ref).toBe('function');
+
+    // call the ref callback
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('merges register options with mask options', () => {
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      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 maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    maskedRegister('phone', '999-999', { required: true });
+
+    expect(registerFn).toHaveBeenCalledWith('phone', { required: true });
+  });
+
+  it('works with alias masks', () => {
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      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 maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    const result = maskedRegister('cpf', 'cpf');
+
+    expect(result.ref).toBeDefined();
+  });
+
+  it('works with array masks', () => {
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      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 maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    const result = maskedRegister('phone', ['999-999', '9999-9999']);
+
+    expect(result.ref).toBeDefined();
+  });
+
+  it('preserves all register return properties', () => {
+    const onChange = vi.fn();
+    const onBlur = vi.fn();
+    const registerFn = vi.fn(() => ({
+      ref: vi.fn(),
+      prevRef: vi.fn(),
+      onChange,
+      onBlur,
+      name: 'phone',
+    }));
+
+    const maskedRegister = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+    const result = maskedRegister('phone', '999-999');
+
+    expect(result.onChange).toBe(onChange);
+    expect(result.onBlur).toBe(onBlur);
+    expect(result.name).toBe('phone');
+  });
+
+  it('handles null ref from register', () => {
+    const registerFn = vi.fn(() => ({
+      ref: undefined,
+      prevRef: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    }));
+
+    const maskedRegister = useHookFormMask(registerFn as unknown as UseFormRegister<FieldValues>);
+    const result = maskedRegister('phone', '999-999');
+
+    expect(result.ref).toBeDefined();
+  });
+});