use-mask-input 3.6.0 → 3.6.1

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "use-mask-input",
-  "version": "3.6.0",
+  "version": "3.6.1",
+  "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",
@@ -16,13 +23,6 @@
     "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,13 +36,9 @@
   "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",
@@ -56,16 +52,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/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();
+  });
+});

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,64 @@
+import { 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(() => createMaskInstance(mask, options), [mask, options]);
+
+  if (isServer) {
+    return (): void => {
+      // server doesn't have dom, so just do nothing
+    };
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  useEffect(() => {
+    if (isServer || !ref.current) return;
+
+    if (!isHTMLElement(ref.current)) {
+      return;
+    }
+
+    const inputElement = findInputElement(ref.current);
+
+    if (inputElement && isHTMLElement(inputElement)) {
+      maskInput.mask(inputElement);
+    }
+
+    if (register && isHTMLElement(ref.current)) {
+      register(ref.current);
+    }
+  }, [mask, register, options, maskInput, ref]);
+
+  return (input: Input | null): void => {
+    if (!input) {
+      ref.current = null;
+      return;
+    }
+
+    ref.current = resolveInputRef(input);
+  };
+}