use-mask-input 3.7.4 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-mask-input",
-  "version": "3.7.4",
+  "version": "3.9.0",
   "private": false,
   "description": "A react Hook for build elegant input masks. Compatible with React Hook Form",
   "author": "Eduardo Borges<euduardoborges@gmail.com>",
@@ -39,36 +39,26 @@
     "react-dom": ">=17"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.3.2",
-    "@eslint/js": "^9.35.0",
-    "@stylistic/eslint-plugin": "3.1.0",
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/react": "^16.1.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@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",
-    "eslint-plugin-import-x": "^4.16.1",
-    "eslint-plugin-jsx-a11y": "^6.10.2",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^5.2.0",
+    "@types/node": "^25.5.0",
+    "@types/react": ">=19",
+    "@types/react-dom": ">=19",
+    "@vitest/coverage-v8": "4.1.1",
+    "antd": "^6.3.4",
+    "oxlint": "1.57.0",
     "inputmask": "5.0.10-beta.61",
-    "jsdom": "^25.0.1",
-    "react-hook-form": "7.62.0",
-    "tsup": "8.5.0",
-    "typescript": "5.1",
-    "typescript-eslint": "^8.42.0",
-    "vitest": "3.2.4"
+    "jsdom": "^28.1.0",
+    "react-hook-form": "7.72.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9",
+    "vitest": "4.1.1"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "lint": "eslint ./src --ext ts,tsx",
+    "lint": "oxlint ./src",
     "test": "vitest --dir ./src --run --coverage",
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",

package/src/antd/useHookFormMaskAntd.spec.ts

@@ -8,6 +8,8 @@ import {
 } from 'vitest';
 
 import { applyMaskToElement, resolveInputRef } from '../core';
+
+
 import useHookFormMaskAntd from './useHookFormMaskAntd';
 
 import type { InputRef } from 'antd';

package/src/antd/useMaskInputAntd.spec.tsx

@@ -47,7 +47,7 @@ describe('useMaskInputAntd', () => {
     const inputElement = document.createElement('input');
     vi.mocked(inputmask).mockReturnValue({
       mask: vi.fn(),
-    } as unknown as Inputmask.Instance);
+    } as any);
 
     const { result, rerender } = renderHook(
       () => useMaskInputAntd({ mask: '999-999' }),
@@ -66,7 +66,7 @@ describe('useMaskInputAntd', () => {
     const inputElement = document.createElement('input');
     vi.mocked(inputmask).mockReturnValue({
       mask: vi.fn(),
-    } as unknown as Inputmask.Instance);
+    } as any);
 
     const { result, rerender } = renderHook(
       () => useMaskInputAntd({
@@ -89,7 +89,7 @@ describe('useMaskInputAntd', () => {
     const register = vi.fn();
     vi.mocked(inputmask).mockReturnValue({
       mask: vi.fn(),
-    } as unknown as Inputmask.Instance);
+    } as any);
 
     const { result, rerender } = renderHook(
       () => useMaskInputAntd({

package/src/api/index.ts

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

package/src/api/useHookFormMask.spec.ts

@@ -1,4 +1,4 @@
-import { renderHook } from '@testing-library/react';
+import { act, renderHook } from '@testing-library/react';
 import inputmask from 'inputmask';
 import {
   beforeEach,
@@ -50,7 +50,7 @@ describe('useHookFormMask', () => {
       name: 'phone',
     }));
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const { result } = renderHook(
       () => useHookFormMask(registerFn as UseFormRegister<FieldValues>),
@@ -68,7 +68,7 @@ describe('useHookFormMask', () => {
 
   it('merges register options with mask options', () => {
     const registerFn = makeRegisterFn('phone');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result } = renderHook(
       () => useHookFormMask(registerFn as UseFormRegister<FieldValues>),
@@ -80,7 +80,7 @@ describe('useHookFormMask', () => {
 
   it('works with alias masks', () => {
     const registerFn = makeRegisterFn('cpf');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result } = renderHook(
       () => useHookFormMask(registerFn as UseFormRegister<FieldValues>),
@@ -92,7 +92,7 @@ describe('useHookFormMask', () => {
 
   it('works with array masks', () => {
     const registerFn = makeRegisterFn('phone');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result } = renderHook(
       () => useHookFormMask(registerFn as UseFormRegister<FieldValues>),
@@ -190,6 +190,53 @@ describe('useHookFormMask', () => {
     expect(refBefore).not.toBe(refAfter);
   });
 
+  it('calls the latest RHF ref with the element after re-render (reset() regression)', async () => {
+    // Simulate react-hook-form's reset() behaviour: it clears _fields and
+    // returns a brand-new ref callback from register() on the next render.
+    // The cached stable ref must still forward to the new RHF ref so that
+    // RHF's internal T()/Z() logic can sync the DOM value to the reset value.
+    const input = document.createElement('input');
+    const refFn1 = vi.fn();
+    const refFn2 = vi.fn(); // "new" ref returned after reset()
+
+    const makeRegisterReturn = (ref: ReturnType<typeof vi.fn>) => ({
+      ref,
+      prevRef: vi.fn(),
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    });
+
+    let currentRef = refFn1;
+    const registerFn = vi.fn(() => makeRegisterReturn(currentRef));
+
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
+
+    // Mimic a real component: the registration function is called on every
+    // render (which is what triggers the queue-push logic for reset support).
+    const { result, rerender } = renderHook(
+      () => {
+        const registerWithMask = useHookFormMask(registerFn as UseFormRegister<FieldValues>);
+        return registerWithMask('phone', '999-999');
+      },
+    );
+
+    // Mount the element – stable cached ref is called once
+    result.current.ref?.(input);
+    expect(refFn1).toHaveBeenCalledWith(input);
+
+    // Simulate reset(): register() now returns a different ref (refFn2)
+    currentRef = refFn2;
+
+    await act(async () => {
+      rerender();
+    });
+
+    // After the re-render + useLayoutEffect, the new RHF ref must have been
+    // called with the stored element so RHF can re-register it and sync values.
+    expect(refFn2).toHaveBeenCalledWith(input);
+  });
+
   it('defines prevRef as a non-enumerable property', () => {
     const prevRef = vi.fn();
     const registerFn = vi.fn(() => ({

package/src/api/useHookFormMask.ts

@@ -1,4 +1,4 @@
-import { useMemo } from 'react';
+import { useLayoutEffect, useMemo, useRef } from 'react';
 
 import { applyMaskToElement } from '../core';
 import { flow, makeMaskCacheKey, setPrevRef } from '../utils';
@@ -12,6 +12,13 @@ import type {
 
 import type { Mask, Options, UseHookFormMaskReturn } from '../types';
 
+interface CacheEntry {
+  stableRef: RefCallback<HTMLElement | null>;
+  element: HTMLElement | null;
+  latestRHFRef?: RefCallback<HTMLElement | null>;
+  syncedRHFRef?: RefCallback<HTMLElement | null>;
+}
+
 /**
  * Creates a masked version of React Hook Form's register function.
  * Takes react-hook-form's register and adds automatic masking. Like an upgrade.
@@ -25,9 +32,26 @@ export default function useHookFormMask<
   T extends FieldValues, D extends RegisterOptions,
 >(registerFn: UseFormRegister<T>): ((fieldName: Path<T>, mask: Mask, options?: (
   D & Options) | Options | D) => UseHookFormMaskReturn<T>) {
-  //
+  const entryCacheRef = useRef(new Map<string, CacheEntry>());
+
+  useLayoutEffect(() => {
+    entryCacheRef.current.forEach((entry) => {
+      const currentEntry = entry;
+      if (!currentEntry.element || !currentEntry.latestRHFRef) return;
+
+      // After reset(), RHF gives us a new ref callback. React won't call it
+      // because our outward ref identity stays stable, so we replay it here.
+      if (currentEntry.latestRHFRef !== currentEntry.syncedRHFRef) {
+        currentEntry.latestRHFRef(currentEntry.element);
+        currentEntry.syncedRHFRef = currentEntry.latestRHFRef;
+      }
+    });
+  });
+
   return useMemo(() => {
-    const refCache = new Map<string, RefCallback<HTMLElement | null>>();
+    // registerFn identity changed, so drop cached refs bound to the previous
+    // register lifecycle.
+    entryCacheRef.current = new Map<string, CacheEntry>();
 
     return (fieldName: Path<T>, mask: Mask, options?: (
       D & Options) | Options | D): UseHookFormMaskReturn<T> => {
@@ -38,20 +62,36 @@ export default function useHookFormMask<
 
       const cacheKey = makeMaskCacheKey(fieldName, mask);
 
-      if (!refCache.has(cacheKey)) {
+      let entry = entryCacheRef.current.get(cacheKey);
+      if (!entry) {
+        const nextEntry: CacheEntry = {
+          element: null,
+          latestRHFRef: ref,
+          syncedRHFRef: undefined,
+          stableRef: null as unknown as RefCallback<HTMLElement | null>,
+        };
+
         const applyMaskToRef = (_ref: HTMLElement | null) => {
+          nextEntry.element = _ref;
           if (_ref) applyMaskToElement(_ref, mask, options as Options);
           return _ref;
         };
-        refCache.set(
-          cacheKey,
-          (ref ? flow(applyMaskToRef, ref) : applyMaskToRef) as RefCallback<HTMLElement | null>,
-        );
+
+        nextEntry.stableRef = (
+          nextEntry.latestRHFRef
+            ? flow(applyMaskToRef, (_ref: HTMLElement | null) => nextEntry.latestRHFRef?.(_ref))
+            : applyMaskToRef
+        ) as RefCallback<HTMLElement | null>;
+
+        entry = nextEntry;
+        entryCacheRef.current.set(cacheKey, nextEntry);
+      } else {
+        entry.latestRHFRef = ref;
       }
 
       const result = {
         ...registerReturn,
-        ref: refCache.get(cacheKey),
+        ref: entry.stableRef,
       } as UseHookFormMaskReturn<T>;
 
       setPrevRef(result, ref);

package/src/api/useMaskInput.spec.tsx

@@ -43,7 +43,7 @@ describe('useMaskInput', () => {
 
   it('handles direct input element', () => {
     const input = document.createElement('input');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -59,7 +59,7 @@ describe('useMaskInput', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -76,7 +76,7 @@ describe('useMaskInput', () => {
     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);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -91,7 +91,7 @@ describe('useMaskInput', () => {
 
   it('handles invalid element in ref', () => {
     const invalidRef = { current: 'not an element' };
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -106,7 +106,7 @@ describe('useMaskInput', () => {
     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);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -121,7 +121,7 @@ describe('useMaskInput', () => {
 
   it('handles wrapper without input inside', () => {
     const wrapper = document.createElement('div');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -136,7 +136,7 @@ describe('useMaskInput', () => {
 
   it('works with custom options', () => {
     const input = document.createElement('input');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({
       mask: '999-999',
@@ -154,7 +154,7 @@ describe('useMaskInput', () => {
 
   it('works with alias masks', () => {
     const input = document.createElement('input');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: 'cpf' }));
 
@@ -170,7 +170,7 @@ describe('useMaskInput', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({
       mask: '999-999',
@@ -188,7 +188,7 @@ describe('useMaskInput', () => {
 
   it('handles textarea element', () => {
     const textarea = document.createElement('textarea');
-    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 
@@ -205,7 +205,7 @@ describe('useMaskInput', () => {
     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);
+    vi.mocked(inputmask).mockReturnValue({ mask: vi.fn() } as any);
 
     const { result, rerender } = renderHook(() => useMaskInput({ mask: '999-999' }));
 

package/src/api/useTanStackFormMask.ts

@@ -0,0 +1,24 @@
+import { useMemo } from 'react';
+
+import withTanStackFormMask from './withTanStackFormMask';
+
+import type { Mask, Options, TanStackFormInputProps, UseTanStackFormMaskReturn } from '../types';
+
+/**
+ * Creates a helper to mask TanStack Form-compatible input props.
+ * Designed for objects returned by field.getInputProps().
+ */
+export default function useTanStackFormMask(): <T extends TanStackFormInputProps>(
+  mask: Mask,
+  inputProps: T,
+  options?: Options,
+) => UseTanStackFormMaskReturn<T> {
+  return useMemo(
+    () => <T extends TanStackFormInputProps>(
+      mask: Mask,
+      inputProps: T,
+      options?: Options,
+    ): UseTanStackFormMaskReturn<T> => withTanStackFormMask(inputProps, mask, options),
+    [],
+  );
+}

package/src/api/withHookFormMask.spec.ts

@@ -7,7 +7,7 @@ import {
 import withHookFormMask from './withHookFormMask';
 
 import type { RefCallback } from 'react';
-import type { FieldValues, UseFormRegisterReturn } from 'react-hook-form';
+import type { FieldValues } from 'react-hook-form';
 
 import type { UseHookFormMaskReturn } from '../types';
 
@@ -33,7 +33,7 @@ describe('withHookFormMask', () => {
       name: 'phone',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, '999-999');
 
@@ -55,7 +55,7 @@ describe('withHookFormMask', () => {
       name: 'phone',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, '999-999');
     result.ref?.(input);
@@ -74,7 +74,7 @@ describe('withHookFormMask', () => {
       name: 'phone',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, '999-999');
     result.ref?.(input);
@@ -93,7 +93,7 @@ describe('withHookFormMask', () => {
       name: 'cpf',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, 'cpf');
     result.ref?.(input);
@@ -112,7 +112,7 @@ describe('withHookFormMask', () => {
       name: 'phone',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, '999-999', { placeholder: '_' });
     result.ref?.(input);
@@ -145,7 +145,7 @@ describe('withHookFormMask', () => {
       name: 'phone',
     };
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const result = withHookFormMask(register, '999-999');
     result.ref?.(null as unknown as HTMLElement);

package/src/api/withMask.spec.ts

@@ -29,7 +29,7 @@ describe('withMask', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask('999-999');
     refCallback(input);
@@ -39,7 +39,7 @@ describe('withMask', () => {
 
   it('does nothing if input is null', () => {
     const maskFn = vi.fn();
-    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask('999-999');
     refCallback(null);
@@ -50,7 +50,7 @@ describe('withMask', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask(null);
     refCallback(input);
@@ -61,7 +61,7 @@ describe('withMask', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask('999-999', { placeholder: '_' });
     refCallback(input);
@@ -72,7 +72,7 @@ describe('withMask', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask('cpf');
     refCallback(input);
@@ -83,7 +83,7 @@ describe('withMask', () => {
   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);
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
 
     const refCallback = withMask(['999-999', '9999-9999']);
     refCallback(input);

package/src/api/withTanStackFormMask.spec.ts

@@ -0,0 +1,76 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+import withTanStackFormMask from './withTanStackFormMask';
+
+import type { TanStackFormInputProps } from '../types';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+describe('withTanStackFormMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns masked input props with stable structure', () => {
+    const inputProps: TanStackFormInputProps = {
+      name: 'cpf',
+      ref: vi.fn(),
+      onBlur: vi.fn(),
+      onChange: vi.fn(),
+      value: '',
+    };
+
+    const result = withTanStackFormMask(inputProps, 'cpf');
+
+    expect(typeof result.ref).toBe('function');
+    expect(result.onBlur).toBe(inputProps.onBlur);
+    expect(result.onChange).toBe(inputProps.onChange);
+    expect(result.name).toBe('cpf');
+  });
+
+  it('applies mask when ref callback receives an input', () => {
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as any);
+
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const inputProps: TanStackFormInputProps = {
+      name: 'phone',
+      ref: originalRef,
+      onBlur: vi.fn(),
+      onChange: vi.fn(),
+      value: '',
+    };
+
+    const result = withTanStackFormMask(inputProps, '(99) 99999-9999');
+    result.ref(input);
+
+    expect(maskFn).toHaveBeenCalled();
+    expect(originalRef).toHaveBeenCalledWith(input);
+  });
+
+  it('keeps ref cache stable for same ref and mask', () => {
+    const originalRef = vi.fn();
+    const inputProps: TanStackFormInputProps = {
+      name: 'cpf',
+      ref: originalRef,
+      onBlur: vi.fn(),
+      onChange: vi.fn(),
+      value: '',
+    };
+
+    const first = withTanStackFormMask(inputProps, 'cpf');
+    const second = withTanStackFormMask(inputProps, 'cpf');
+
+    expect(first.ref).toBe(second.ref);
+  });
+});

package/src/api/withTanStackFormMask.ts

@@ -0,0 +1,64 @@
+import { applyMaskToElement } from '../core';
+import { flow, makeMaskCacheKey, setPrevRef } from '../utils';
+
+import type { RefCallback } from 'react';
+
+import type {
+  Mask, Options, TanStackFormInputProps, UseTanStackFormMaskReturn,
+} from '../types';
+
+const refCache = new WeakMap<
+  RefCallback<HTMLElement | null>,
+  Map<string, RefCallback<HTMLElement | null>>
+>();
+
+/**
+ * Enhances TanStack Form-compatible input props with mask support.
+ * Works with objects returned by field.getInputProps().
+ */
+export default function withTanStackFormMask<T extends TanStackFormInputProps>(
+  inputProps: T,
+  mask: Mask,
+  options?: Options,
+): UseTanStackFormMaskReturn<T> {
+  const { ref } = inputProps;
+
+  if (!ref) {
+    const result = {
+      ...inputProps,
+      ref: ((input: HTMLElement | null) => {
+        if (input) applyMaskToElement(input, mask, options);
+      }) as RefCallback<HTMLElement | null>,
+    } as unknown as UseTanStackFormMaskReturn<T>;
+
+    setPrevRef(result, ref);
+    return result;
+  }
+
+  if (!refCache.has(ref)) {
+    refCache.set(ref, new Map());
+  }
+
+  const maskCache = refCache.get(ref);
+  const cacheKey = makeMaskCacheKey(inputProps.name ?? '', mask);
+
+  if (!maskCache?.has(cacheKey)) {
+    const applyMaskToRef = (_ref: HTMLElement | null) => {
+      if (_ref) applyMaskToElement(_ref, mask, options);
+      return _ref;
+    };
+
+    maskCache?.set(
+      cacheKey,
+      flow(applyMaskToRef, ref) as RefCallback<HTMLElement | null>,
+    );
+  }
+
+  const result = {
+    ...inputProps,
+    ref: maskCache?.get(cacheKey),
+  } as unknown as UseTanStackFormMaskReturn<T>;
+
+  setPrevRef(result, ref);
+  return result;
+}