use-mask-input 3.11.0 → 3.12.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "use-mask-input",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "private": false,
-  "description": "A react Hook for build elegant input masks. Compatible with React Hook Form",
+  "description": "Input masks for React and Vue 3. Works with React Hook Form, TanStack Form, vee-validate, and Ant Design.",
   "license": "MIT",
   "author": "Eduardo Borges<euduardoborges@gmail.com>",
   "type": "module",
@@ -33,6 +33,16 @@
         "types": "./dist/antd.d.cts",
         "default": "./dist/antd.cjs"
       }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/vue.d.mts",
+        "default": "./dist/vue.mjs"
+      },
+      "require": {
+        "types": "./dist/vue.d.cts",
+        "default": "./dist/vue.cjs"
+      }
     }
   },
   "engines": {
@@ -50,11 +60,25 @@
   "peerDependencies": {
     "antd": ">=5",
     "react": ">=17",
-    "react-dom": ">=17"
+    "react-dom": ">=17",
+    "vee-validate": ">=4",
+    "vue": ">=3.4"
   },
   "peerDependenciesMeta": {
     "antd": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vee-validate": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -62,26 +86,46 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/inputmask": "5.0.7",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@vitest/coverage-v8": "4.1.7",
-    "antd": "^6.4.4",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vue/server-renderer": "^3.5.40",
+    "@vue/test-utils": "^2.4.11",
+    "antd": "^6.5.1",
     "inputmask": "5.0.10-beta.61",
     "jsdom": "^29.1.1",
-    "oxlint": "1.66.0",
-    "react-hook-form": "7.75.0",
-    "tsdown": "^0.22.2",
+    "oxlint": "1.74.0",
+    "playwright": "^1.62.0",
+    "react-hook-form": "7.82.0",
+    "tsdown": "^0.22.9",
     "typescript": "~6.0.3",
-    "vitest": "4.1.7"
+    "vee-validate": "^4.15.1",
+    "vitest": "4.1.10",
+    "vue": "^3.5.40"
   },
+  "keywords": [
+    "react",
+    "vue",
+    "react-hook-form",
+    "tanstack-form",
+    "vee-validate",
+    "antd",
+    "input-mask",
+    "input-masking",
+    "vue-mask",
+    "mask"
+  ],
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
     "lint": "oxlint ./src",
-    "test": "vitest --dir ./src --run --coverage",
+    "test": "vitest --project=unit --dir ./src --run --coverage",
+    "test:browser": "vitest --project=browser --run",
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "postbuild": "cp ../../README.md README.md"
+    "postbuild": "node scripts/assert-entry-isolation.mjs && cp ../../README.md README.md"
   }
 }

package/src/@types/inputmask.d.ts

@@ -11,6 +11,12 @@
 
 interface InputmaskInstance {
   unmaskedvalue?: () => string;
+  /** Resolved configuration, after alias defaults are merged with user options. */
+  opts?: Record<string, unknown>;
+  /** Detaches the mask from its element. Used by the Vue directive on unmount. */
+  remove?: () => void;
+  /** Pushes a value through the engine's own validation and formatting. */
+  setValue?: (value: string) => void;
 }
 
 interface HTMLInputElement {

package/src/api/useHookFormMask.ts

@@ -79,11 +79,26 @@ export default function useHookFormMask<
           return _ref;
         };
 
-        nextEntry.stableRef = (
-          nextEntry.latestRHFRef
-            ? flow(applyMaskToRef, (_ref: HTMLElement | null) => nextEntry.latestRHFRef?.(_ref))
-            : applyMaskToRef
-        ) as RefCallback<HTMLElement | null>;
+        // RHF must run first: it writes the field's predefined value onto the
+        // element. If we masked before that, Inputmask would initialise with an
+        // empty buffer and RHF's later value assignment would leave its internal
+        // state out of sync with the DOM, swallowing the first onChange after a
+        // select-all + delete (#193). Masking after RHF seeds Inputmask with the
+        // current value, keeping its buffer in sync from the start.
+        const syncRHFRef = (_ref: HTMLElement | null) => {
+          nextEntry.latestRHFRef?.(_ref);
+          return _ref;
+        };
+
+        const composedRef = nextEntry.latestRHFRef
+          ? flow(syncRHFRef, applyMaskToRef)
+          : applyMaskToRef;
+
+        // React 19 treats a ref callback's return value as a cleanup function,
+        // so the composed callback must return void — never the resolved element.
+        nextEntry.stableRef = ((_ref: HTMLElement | null): void => {
+          composedRef(_ref);
+        }) as RefCallback<HTMLElement | null>;
 
         entry = nextEntry;
         entryCacheRef.current.set(cacheKey, nextEntry);

package/src/api/withMask.ts

@@ -2,6 +2,7 @@
 import inputmask from '../core/inputmask';
 
 import { getMaskOptions } from '../core/maskConfig';
+import { stripMaxLength } from '../core/maskEngine';
 import { getUnmaskedValue, makeMaskCacheKey, setUnmaskedValue } from '../utils';
 import isServer from '../utils/isServer';
 import interopDefaultSync from '../utils/moduleInterop';
@@ -34,6 +35,7 @@ export default function withMask(mask: Mask, options?: Options): UseMaskInputRet
 
     currentInput = input;
     const maskInput = interopDefaultSync(inputmask)(getMaskOptions(mask, options));
+    stripMaxLength(input, mask, options);
     maskInput.mask(input as HTMLElement);
   }) as UseMaskInputReturn;
 

package/src/core/maskEngine.ts

@@ -2,6 +2,7 @@
 import inputmask from './inputmask';
 
 import { getMaskOptions } from './maskConfig';
+import { isHTMLElement } from './elementResolver';
 import { moduleInterop } from '../utils';
 
 import type { Mask, Options } from '../types';
@@ -19,33 +20,6 @@ export function createMaskInstance(mask: Mask, options?: Options): ReturnType<ty
   return inputmaskInstance(getMaskOptions(mask, options));
 }
 
-/**
- * Applies a mask to an input element.
- * If it's not a direct input, searches inside.
- *
- * @param element - The element to apply mask to
- * @param mask - The mask pattern
- * @param options - Optional configuration options
- */
-export function applyMaskToElement(
-  element: HTMLElement | null,
-  mask: Mask,
-  options?: Options,
-): void {
-  if (!element) return;
-
-  const maskInstance = createMaskInstance(mask, options);
-  const inputElement = element.nodeName === 'INPUT'
-    ? element
-    : (element.querySelector('input') as HTMLElement);
-
-  if (inputElement) {
-    maskInstance.mask(inputElement);
-  } else {
-    maskInstance.mask(element);
-  }
-}
-
 /**
  * Formats a raw value using the given mask, without needing a mounted element.
  * Useful for displaying already-persisted (unmasked) values in the UI.
@@ -73,3 +47,58 @@ export function unformatWithMask(value: string, mask: Mask, options?: Options):
   const inputmaskInstance = moduleInterop(inputmask);
   return inputmaskInstance.unmask(value, getMaskOptions(mask, options));
 }
+
+/**
+ * Drops the native `maxlength` when the mask renders characters the user never types.
+ *
+ * A mask like `999.999.999-99` keeps its literals and placeholder in the value, so
+ * `maxlength` counts characters nobody typed: the browser stops accepting keystrokes,
+ * and inputmask copies the attribute into a validator that rejects any buffer longer
+ * than it. Either way the field takes no input at all.
+ *
+ * Open-ended masks (`numeric`, `integer`, `decimal`) render nothing while empty, so
+ * their value only ever holds what was typed and `maxlength` still caps what it says
+ * it caps. Those keep the attribute. Rendering the empty value is what tells the two
+ * apart, since aliases hide their real pattern.
+ *
+ * ponytail: the empty render is a proxy, not a proof. A mask that starts empty but
+ * grows a literal later (`br-bank-agency` gains a `-` at the 6th digit) still loses
+ * that many characters off the cap. Sharpen this only if someone hits it.
+ *
+ * @see https://github.com/eduardoborges/use-mask-input/issues/191
+ * @param element - The element about to be masked
+ * @param mask - The mask pattern about to be applied
+ * @param options - Optional configuration options
+ */
+export function stripMaxLength(element: unknown, mask: Mask, options?: Options): void {
+  if (!isHTMLElement(element) || !element.hasAttribute('maxlength')) return;
+  if (formatWithMask('', mask, options).length === 0) return;
+
+  element.removeAttribute('maxlength');
+}
+
+/**
+ * Applies a mask to an input element.
+ * If it's not a direct input, searches inside.
+ *
+ * @param element - The element to apply mask to
+ * @param mask - The mask pattern
+ * @param options - Optional configuration options
+ */
+export function applyMaskToElement(
+  element: HTMLElement | null,
+  mask: Mask,
+  options?: Options,
+): void {
+  if (!element) return;
+
+  const maskInstance = createMaskInstance(mask, options);
+  const inputElement = element.nodeName === 'INPUT'
+    ? element
+    : (element.querySelector('input') as HTMLElement);
+
+  const target = inputElement ?? element;
+
+  stripMaxLength(target, mask, options);
+  maskInstance.mask(target);
+}

package/src/types/index.ts

@@ -4,35 +4,15 @@ import type {
   UseFormRegisterReturn,
 } from 'react-hook-form';
 
-import type { Options as MaskOptions } from './inputmask.types';
+import type { UnmaskedValueApi } from './mask';
 
 export type { UseFormRegister, UseFormRegisterReturn } from 'react-hook-form';
 
-export type Mask = 'datetime'
-  | 'email'
-  | 'numeric'
-  | 'currency'
-  | 'decimal'
-  | 'integer'
-  | 'percentage'
-  | 'url'
-  | 'ip'
-  | 'mac'
-  | 'ssn'
-  | 'brl-currency'
-  | 'cpf'
-  | 'cnpj'
-  | 'br-bank-account'
-  | 'br-bank-agency'
-  | (string & {})
-  | (string[] & {})
-  | null;
-export type Options = MaskOptions;
-export type Input = HTMLInputElement | HTMLTextAreaElement | HTMLElement;
-
-export interface UnmaskedValueApi {
-  unmaskedValue: () => string;
-}
+// Framework-agnostic types live in ./mask so the Vue entry can import them
+// without pulling this module's react / react-hook-form imports with them.
+export type {
+  Input, Mask, Options, UnmaskedValueApi,
+} from './mask';
 
 export type UseMaskInputReturn = RefCallback<HTMLElement | null> & UnmaskedValueApi;
 

package/src/types/mask.ts

@@ -0,0 +1,37 @@
+import type { Options as MaskOptions } from './inputmask.types';
+
+/**
+ * Framework-agnostic mask types.
+ *
+ * Split out of `./index.ts` so the Vue entry can import them without dragging
+ * in that module's `react` and `react-hook-form` type imports. `./index.ts`
+ * re-exports everything here, so the React-facing surface is unchanged.
+ */
+
+export type Mask = 'datetime'
+  | 'email'
+  | 'numeric'
+  | 'currency'
+  | 'decimal'
+  | 'integer'
+  | 'percentage'
+  | 'url'
+  | 'ip'
+  | 'mac'
+  | 'ssn'
+  | 'brl-currency'
+  | 'cpf'
+  | 'cnpj'
+  | 'br-bank-account'
+  | 'br-bank-agency'
+  | (string & {})
+  | (string[] & {})
+  | null;
+
+export type Options = MaskOptions;
+
+export type Input = HTMLInputElement | HTMLTextAreaElement | HTMLElement;
+
+export interface UnmaskedValueApi {
+  unmaskedValue: () => string;
+}

package/src/vue/applyMask.ts

@@ -0,0 +1,99 @@
+import { applyMaskToElement } from '../core';
+import { makeMaskCacheKey } from '../utils';
+import isServer from '../utils/isServer';
+
+import type { Mask, Options, VueMaskBinding, VueMaskConfig } from './types';
+
+type MaskedElement = HTMLElement & {
+  inputmask?: { remove?: () => void };
+};
+
+/**
+ * Single implementation both Vue surfaces route through, so the directive and
+ * the composable cannot drift apart on what a given mask means.
+ */
+
+function isConfig(binding: VueMaskBinding): binding is VueMaskConfig {
+  return (
+    typeof binding === 'object'
+    && binding !== null
+    && !Array.isArray(binding)
+    && 'mask' in binding
+  );
+}
+
+/** Unpacks the two accepted binding shapes into a mask and its options. */
+export function normalizeBinding(binding: VueMaskBinding): {
+  mask: Mask;
+  options?: Options;
+} {
+  if (isConfig(binding)) {
+    return { mask: binding.mask, options: binding.options };
+  }
+
+  return { mask: binding as Mask };
+}
+
+/**
+ * Shallow equality over mask options.
+ *
+ * ponytail: shallow on purpose. An options object mutated in place, or one
+ * holding functions, won't compare equal-then-changed correctly — but deep
+ * comparison on every re-render is exactly the cost this guard exists to
+ * avoid. Documented as "replace options, don't mutate them".
+ */
+function sameOptions(a?: Options, b?: Options): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+
+  const keysA = Object.keys(a) as (keyof Options)[];
+  const keysB = Object.keys(b) as (keyof Options)[];
+  if (keysA.length !== keysB.length) return false;
+
+  return keysA.every((key) => Object.is(a[key], b[key]));
+}
+
+/**
+ * True when two bindings mean the same mask, so an unrelated re-render doesn't
+ * rebuild Inputmask's buffer and drop the caret to the end mid-typing.
+ *
+ * Compares structurally, not by identity: an inline `v-mask-input="{ mask: 'cpf' }"`
+ * allocates a fresh object every render and would otherwise never look equal.
+ */
+export function sameBinding(a: VueMaskBinding, b: VueMaskBinding): boolean {
+  const left = normalizeBinding(a);
+  const right = normalizeBinding(b);
+
+  if (makeMaskCacheKey('', left.mask) !== makeMaskCacheKey('', right.mask)) {
+    return false;
+  }
+
+  return sameOptions(left.options, right.options);
+}
+
+/**
+ * Applies a binding's mask to an already-resolved element.
+ *
+ * A null mask is not merely "do nothing": it has to tear down whatever mask is
+ * already on the element. A binding is reactive, so `v-mask-input="on ? 'cpf' : null"`
+ * turns the mask off, and simply returning early would leave the element still
+ * formatting as a CPF.
+ *
+ * @param element - The element to mask
+ * @param binding - Mask, or `{ mask, options }`
+ */
+export default function applyMask(
+  element: HTMLElement | null,
+  binding: VueMaskBinding,
+): void {
+  if (isServer || !element) return;
+
+  const { mask, options } = normalizeBinding(binding);
+
+  if (mask === null || mask === undefined) {
+    (element as MaskedElement).inputmask?.remove?.();
+    return;
+  }
+
+  applyMaskToElement(element, mask, options);
+}

package/src/vue/directive.ts

@@ -0,0 +1,59 @@
+import applyMask, { sameBinding } from './applyMask';
+import resolveVueElement from './resolveVueElement';
+
+import type { ObjectDirective } from 'vue';
+
+import type { VueMaskBinding } from './types';
+
+type MaskedElement = HTMLElement & {
+  inputmask?: { remove?: () => void };
+};
+
+/**
+ * `v-mask-input` — the only thing in the Vue entry that applies a mask.
+ *
+ * Getting real lifecycle hooks is why this, and not the composable, is the
+ * primitive: the React surface has no equivalent of `unmounted`, which is why
+ * it never tears Inputmask down.
+ *
+ * Note there is no `v-model` handling here, and none is needed. Inputmask
+ * replaces the element's `value` property with its own accessor, so `v-model`
+ * reads and writes through the engine rather than around it — including
+ * returning the unmasked value under `autoUnmask`.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { vMaskInput } from 'use-mask-input/vue'
+ * </script>
+ *
+ * <template>
+ *   <input v-mask-input="'cpf'" />
+ *   <input v-mask-input="{ mask: 'currency', options: { prefix: 'R$ ' } }" />
+ * </template>
+ * ```
+ */
+const vMaskInput: ObjectDirective<HTMLElement, VueMaskBinding> = {
+  mounted(el, binding) {
+    applyMask(resolveVueElement(el), binding.value);
+  },
+
+  updated(el, binding) {
+    // Every parent re-render lands here. Re-masking an unchanged binding would
+    // rebuild the buffer and send the caret to the end while the user types.
+    if (sameBinding(binding.value, binding.oldValue as VueMaskBinding)) return;
+
+    applyMask(resolveVueElement(el), binding.value);
+  },
+
+  unmounted(el) {
+    const target = resolveVueElement(el) as MaskedElement | null;
+    target?.inputmask?.remove?.();
+  },
+
+  // Without this, @vue/server-renderer warns about an unhandled custom
+  // directive. There is nothing to render server-side.
+  getSSRProps: () => ({}),
+};
+
+export default vMaskInput;

package/src/vue/index.ts

@@ -0,0 +1,13 @@
+export { default as vMaskInput } from './directive';
+export { default as useMaskInput } from './useMaskInput';
+
+export { formatWithMask, unformatWithMask } from '../core';
+
+export type {
+  Mask,
+  MaskRefTarget,
+  Options,
+  UseMaskInputReturn,
+  VueMaskBinding,
+  VueMaskConfig,
+} from './types';

package/src/vue/resolveVueElement.ts

@@ -0,0 +1,34 @@
+import { findInputElement, isHTMLElement } from '../core/elementResolver';
+
+import type { MaskRefTarget } from './types';
+
+/**
+ * Resolves whatever Vue hands us into the element that should carry the mask.
+ *
+ * A directive always receives a DOM element. A `:ref` on a component receives
+ * the component's public instance instead, so the element has to be dug out of
+ * `$el` first. Either way the existing `findInputElement` does the final
+ * wrapper search, which is the same code path that makes Ant Design work on the
+ * React side.
+ *
+ * Fragment-root components resolve to `null` on purpose: their `$el` is a text
+ * anchor node, and Vue itself refuses this case for directives
+ * ("Runtime directive used on component with non-element root node"). Walking
+ * up to `parentElement` could just as easily find a sibling input as the
+ * intended one.
+ *
+ * @param target - Element, component public instance, or null
+ * @returns The element to mask, or null if there isn't one
+ */
+export default function resolveVueElement(target: MaskRefTarget): HTMLElement | null {
+  if (!target) return null;
+
+  if (isHTMLElement(target)) {
+    return findInputElement(target);
+  }
+
+  const { $el } = target as { $el?: unknown };
+  if (!isHTMLElement($el)) return null;
+
+  return findInputElement($el);
+}

package/src/vue/types.ts

@@ -0,0 +1,35 @@
+import type { Mask, Options } from '../types/mask';
+
+export type { Mask, Options } from '../types/mask';
+
+/** Object form of the directive binding, for when options are needed. */
+export interface VueMaskConfig {
+  mask: Mask;
+  options?: Options;
+}
+
+/**
+ * Everything `v-mask-input` accepts. A bare mask covers the common case;
+ * the object form adds options.
+ */
+export type VueMaskBinding = Mask | VueMaskConfig;
+
+/**
+ * What Vue hands a `:ref` callback: a DOM element for a native tag, or the
+ * component's public instance for a component. `$el` is typed loosely because
+ * a fragment-root component exposes a text anchor node there, not an element.
+ */
+export type MaskRefTarget = Element | { $el?: unknown } | null;
+
+export interface UseMaskInputReturn {
+  /** Bind with `:ref="maskRef"`. */
+  maskRef: (target: MaskRefTarget) => void;
+  /**
+   * Current unmasked value. Call this from event handlers and imperative code.
+   *
+   * NOT reactive: `{{ unmaskedValue() }}` in a template renders once and never
+   * updates, because reading the DOM registers no reactive dependency. For a
+   * value the template should track, bind `v-model` with `autoUnmask: true`.
+   */
+  unmaskedValue: () => string;
+}

package/src/vue/useMaskInput.ts

@@ -0,0 +1,56 @@
+import applyMask from './applyMask';
+import resolveVueElement from './resolveVueElement';
+import { getUnmaskedValue } from '../utils';
+import isServer from '../utils/isServer';
+
+import type {
+  MaskRefTarget, Mask, Options, UseMaskInputReturn,
+} from './types';
+
+/**
+ * Composable form, for imperative use and for reading the raw value when
+ * `autoUnmask` is off.
+ *
+ * Narrower than the directive on purpose: wrapper components (PrimeVue,
+ * Element Plus, Ant Design Vue) are already covered by `v-mask-input`, because
+ * Vue applies directives to a component's root element and the mask engine
+ * searches inside it. Reach for this when you need `unmaskedValue()` or a ref
+ * you can hold.
+ *
+ * @param mask - The mask pattern or alias
+ * @param options - Optional mask configuration options
+ * @returns A ref callback to bind, and an unmasked-value accessor
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useMaskInput } from 'use-mask-input/vue'
+ * const { maskRef, unmaskedValue } = useMaskInput('cpf')
+ * function submit() { console.log(unmaskedValue()) }
+ * </script>
+ *
+ * <template><input :ref="maskRef" /></template>
+ * ```
+ */
+export default function useMaskInput(mask: Mask, options?: Options): UseMaskInputReturn {
+  if (isServer) {
+    return {
+      maskRef: () => {
+        // server doesn't have dom, so just do nothing
+      },
+      unmaskedValue: () => '',
+    };
+  }
+
+  let element: HTMLElement | null = null;
+
+  const maskRef = (target: MaskRefTarget): void => {
+    element = resolveVueElement(target);
+    applyMask(element, { mask, options });
+  };
+
+  return {
+    maskRef,
+    unmaskedValue: () => getUnmaskedValue(element),
+  };
+}