use-mask-input 3.6.0 → 3.7.0

package/src/core/elementResolver.spec.ts

@@ -0,0 +1,175 @@
+import {
+  describe, expect, it, vi,
+} from 'vitest';
+
+import { findInputElement, isHTMLElement, resolveInputRef } from './elementResolver';
+
+import type { Input } from '..';
+
+describe('elementResolver', () => {
+  describe('isHTMLElement', () => {
+    it('returns true for valid HTMLElement', () => {
+      const element = document.createElement('div');
+      expect(isHTMLElement(element)).toBe(true);
+    });
+
+    it('returns false for null', () => {
+      expect(isHTMLElement(null)).toBe(false);
+    });
+
+    it('returns false for undefined', () => {
+      expect(isHTMLElement(undefined)).toBe(false);
+    });
+
+    it('returns false for string', () => {
+      expect(isHTMLElement('string')).toBe(false);
+    });
+
+    it('returns false for number', () => {
+      expect(isHTMLElement(123)).toBe(false);
+    });
+
+    it('returns false for object without nodeType', () => {
+      expect(isHTMLElement({})).toBe(false);
+    });
+
+    it('returns false for object without querySelector', () => {
+      expect(isHTMLElement({ nodeType: 1 })).toBe(false);
+    });
+
+    it('returns false for object with non-function querySelector', () => {
+      expect(isHTMLElement({ nodeType: 1, querySelector: 'not a function' })).toBe(false);
+    });
+  });
+
+  describe('findInputElement', () => {
+    it('returns null for null', () => {
+      expect(findInputElement(null)).toBe(null);
+    });
+
+    it('returns null for undefined', () => {
+      expect(findInputElement(undefined)).toBe(null);
+    });
+
+    it('returns input element directly if it is an INPUT', () => {
+      const input = document.createElement('input');
+      expect(findInputElement(input)).toBe(input);
+    });
+
+    it('returns textarea element directly if it is a TEXTAREA', () => {
+      const textarea = document.createElement('textarea');
+      expect(findInputElement(textarea)).toBe(textarea);
+    });
+
+    it('finds input inside wrapper element', () => {
+      const wrapper = document.createElement('div');
+      const input = document.createElement('input');
+      wrapper.appendChild(input);
+      expect(findInputElement(wrapper)).toBe(input);
+    });
+
+    it('finds textarea inside wrapper element', () => {
+      const wrapper = document.createElement('div');
+      const textarea = document.createElement('textarea');
+      wrapper.appendChild(textarea);
+      expect(findInputElement(wrapper)).toBe(textarea);
+    });
+
+    it('returns null if no input found inside wrapper', () => {
+      const wrapper = document.createElement('div');
+      const span = document.createElement('span');
+      wrapper.appendChild(span);
+      expect(findInputElement(wrapper)).toBe(null);
+    });
+
+    it('returns null for invalid element', () => {
+      expect(findInputElement('not an element')).toBe(null);
+    });
+
+    it('handles querySelector error gracefully', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+        querySelector: vi.fn(() => {
+          throw new Error('querySelector error');
+        }),
+      };
+      expect(findInputElement(element)).toBe(null);
+    });
+
+    it('handles element without querySelector method', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+      };
+      expect(findInputElement(element)).toBe(null);
+    });
+
+    it('handles element with non-function querySelector', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+        querySelector: 'not a function',
+      };
+      expect(findInputElement(element)).toBe(null);
+    });
+
+    it('handles element where querySelector is not in element', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+      };
+      // element doesn't have querySelector property
+      expect(findInputElement(element)).toBe(null);
+    });
+
+    it('handles querySelector returning null', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+        querySelector: vi.fn(() => null),
+      };
+      expect(findInputElement(element)).toBe(null);
+    });
+
+    it('handles querySelector returning non-HTMLElement', () => {
+      const element = {
+        nodeType: 1,
+        nodeName: 'DIV',
+        querySelector: vi.fn(() => 'not an element'),
+      };
+      expect(findInputElement(element)).toBe(null);
+    });
+  });
+
+  describe('resolveInputRef', () => {
+    it('returns null for null', () => {
+      expect(resolveInputRef(null)).toBe(null);
+    });
+
+    it('returns element for direct HTMLElement', () => {
+      const input = document.createElement('input');
+      expect(resolveInputRef(input)).toBe(input);
+    });
+
+    it('returns element from ref object with current', () => {
+      const input = document.createElement('input');
+      const ref = { current: input };
+      expect(resolveInputRef(ref as unknown as Input)).toBe(input);
+    });
+
+    it('returns null for ref object with null current', () => {
+      const ref = { current: null } as unknown as Input;
+      expect(resolveInputRef(ref)).toBe(null);
+    });
+
+    it('returns null for ref object with invalid current', () => {
+      const ref = { current: 'not an element' } as unknown as Input;
+      expect(resolveInputRef(ref)).toBe(null);
+    });
+
+    it('returns null for invalid input type', () => {
+      expect(resolveInputRef('not an element' as unknown as Input)).toBe(null);
+    });
+  });
+});

package/src/core/elementResolver.ts

@@ -0,0 +1,84 @@
+import type { Input } from '../types';
+
+/**
+ * Checks if an element is a valid DOM element (or at least looks like one).
+ *
+ * @param element - The element to check
+ * @returns True if it's a valid HTMLElement
+ */
+export function isHTMLElement(element: unknown): element is HTMLElement {
+  return (
+    element !== null
+    && typeof element === 'object'
+    && 'nodeType' in element
+    && 'querySelector' in element
+    && typeof (element as HTMLElement).querySelector === 'function'
+  );
+}
+
+/**
+ * Finds the actual input element from various component structures.
+ * Finds the actual input inside wrappers (ant design, etc). Like a detective.
+ *
+ * @param element - The element to search in
+ * @returns The found input element or null
+ */
+export function findInputElement(element: unknown): HTMLElement | null {
+  if (!element) return null;
+
+  if (!isHTMLElement(element)) {
+    return null;
+  }
+
+  // if it's already an input or textarea, return it directly
+  if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {
+    return element;
+  }
+
+  // tries to find input inside the wrapper
+  if (!('querySelector' in element) || typeof element.querySelector !== 'function') {
+    return null;
+  }
+
+  try {
+    const inputElement = element.querySelector('input, textarea');
+
+    if (inputElement && isHTMLElement(inputElement)) {
+      return inputElement;
+    }
+  } catch {
+    // if it errors, return null and move on
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves React refs to a valid HTMLInputElement.
+ * Handles ref objects and direct DOM elements.
+ *
+ * @param input - The input reference to resolve
+ * @returns A valid HTMLInputElement or null
+ */
+export function resolveInputRef(input: Input | null): HTMLInputElement | null {
+  if (!input) {
+    return null;
+  }
+
+  // react ref objects
+  if (typeof input === 'object' && 'current' in input) {
+    const refValue = (input as { current: HTMLElement | null }).current;
+    if (isHTMLElement(refValue)) {
+      return refValue as HTMLInputElement;
+    }
+    return null;
+  }
+
+  // direct dom elements
+  if (isHTMLElement(input)) {
+    return input as HTMLInputElement;
+  }
+
+  return null;
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './elementResolver';
+export * from './maskEngine';
+export * from './maskConfig';

package/src/core/maskConfig.spec.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+
+import { getMaskOptions } from './maskConfig';
+
+describe('maskConfig', () => {
+  describe('getMaskOptions', () => {
+    it('returns default options when no mask is provided', () => {
+      const options = getMaskOptions();
+      expect(options).toEqual({
+        jitMasking: false,
+      });
+    });
+
+    it('merges custom options with defaults', () => {
+      const options = getMaskOptions(undefined, { placeholder: '_' });
+      expect(options).toEqual({
+        jitMasking: false,
+        placeholder: '_',
+      });
+    });
+
+    it('returns options for datetime mask', () => {
+      const options = getMaskOptions('datetime');
+      expect(options).toEqual({
+        alias: 'datetime',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for email mask', () => {
+      const options = getMaskOptions('email');
+      expect(options).toEqual({
+        alias: 'email',
+        placeholder: '',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for numeric mask', () => {
+      const options = getMaskOptions('numeric');
+      expect(options).toEqual({
+        alias: 'numeric',
+        placeholder: '',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for currency mask', () => {
+      const options = getMaskOptions('currency');
+      expect(options).toEqual({
+        alias: 'currency',
+        prefix: '$ ',
+        placeholder: '',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for decimal mask', () => {
+      const options = getMaskOptions('decimal');
+      expect(options).toEqual({
+        alias: 'decimal',
+        placeholder: '',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for integer mask', () => {
+      const options = getMaskOptions('integer');
+      expect(options).toEqual({
+        alias: 'integer',
+        placeholder: '',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for percentage mask', () => {
+      const options = getMaskOptions('percentage');
+      expect(options).toEqual({
+        alias: 'percentage',
+        placeholder: ' %',
+        suffix: ' %',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for url mask', () => {
+      const options = getMaskOptions('url');
+      expect(options).toEqual({
+        alias: 'url',
+        placeholder: 'https://',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for ip mask', () => {
+      const options = getMaskOptions('ip');
+      expect(options).toEqual({
+        alias: 'ip',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for mac mask', () => {
+      const options = getMaskOptions('mac');
+      expect(options).toEqual({
+        alias: 'mac',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for ssn mask', () => {
+      const options = getMaskOptions('ssn');
+      expect(options).toEqual({
+        alias: 'ssn',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for brl-currency mask', () => {
+      const options = getMaskOptions('brl-currency');
+      expect(options).toEqual({
+        alias: 'currency',
+        prefix: 'R$ ',
+        placeholder: '0,00',
+        displayFormat: 'currency',
+        radixPoint: ',',
+        autoUnmask: true,
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for cpf mask', () => {
+      const options = getMaskOptions('cpf');
+      expect(options).toEqual({
+        mask: '999.999.999-99',
+        placeholder: '___.___.___-__',
+        jitMasking: false,
+      });
+    });
+
+    it('returns options for cnpj mask', () => {
+      const options = getMaskOptions('cnpj');
+      expect(options).toEqual({
+        mask: ['A|9{2}.A|9{3}.A|9{3}/A|9{4}-9{2}'],
+        placeholder: '__.___.___/____-__',
+        jitMasking: false,
+      });
+    });
+
+    it('returns custom mask string', () => {
+      const options = getMaskOptions('999-999');
+      expect(options).toEqual({
+        mask: '999-999',
+        jitMasking: false,
+      });
+    });
+
+    it('returns custom mask array', () => {
+      const mask = ['999-999', '9999-9999'];
+      const options = getMaskOptions(mask);
+      expect(options).toEqual({
+        mask,
+        jitMasking: false,
+      });
+    });
+
+    it('merges custom options with alias options', () => {
+      const options = getMaskOptions('cpf', { placeholder: '___' });
+      expect(options).toEqual({
+        mask: '999.999.999-99',
+        placeholder: '___',
+        jitMasking: false,
+      });
+    });
+
+    it('handles null mask', () => {
+      const options = getMaskOptions(null);
+      expect(options).toEqual({
+        jitMasking: false,
+      });
+    });
+  });
+});

package/src/core/maskConfig.ts

@@ -0,0 +1,56 @@
+/* eslint-disable import-x/prefer-default-export */
+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.
+ *
+ * @param mask - The mask pattern or alias
+ * @param _options - Optional configuration options
+ * @returns Inputmask configuration object
+ */
+export function getMaskOptions(mask?: Mask, _options?: Options): Options {
+  const options: Options = {
+    jitMasking: false,
+    ..._options,
+  };
+  if (!mask) return options;
+
+  if (typeof mask === 'string' && ALIAS_MASKS[mask]) {
+    return { ...ALIAS_MASKS[mask], ...options } as Options;
+  }
+
+  return {
+    mask,
+    ...options,
+  };
+}

package/src/core/maskEngine.spec.ts

@@ -0,0 +1,108 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach, describe, expect, it, vi,
+} from 'vitest';
+
+import { applyMaskToElement, createMaskInstance } from './maskEngine';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+describe('maskEngine', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('createMaskInstance', () => {
+    it('creates mask instance with string mask', () => {
+      const instance = createMaskInstance('999-999');
+      expect(inputmask).toHaveBeenCalled();
+      expect(instance).toBeDefined();
+    });
+
+    it('creates mask instance with alias', () => {
+      const instance = createMaskInstance('cpf');
+      expect(inputmask).toHaveBeenCalled();
+      expect(instance).toBeDefined();
+    });
+
+    it('creates mask instance with options', () => {
+      const instance = createMaskInstance('999-999', { placeholder: '_' });
+      expect(inputmask).toHaveBeenCalled();
+      expect(instance).toBeDefined();
+    });
+
+    it('creates mask instance with array mask', () => {
+      const instance = createMaskInstance(['999-999', '9999-9999']);
+      expect(inputmask).toHaveBeenCalled();
+      expect(instance).toBeDefined();
+    });
+  });
+
+  describe('applyMaskToElement', () => {
+    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);
+
+      applyMaskToElement(input, '999-999');
+
+      expect(maskFn).toHaveBeenCalledWith(input);
+    });
+
+    it('applies mask to textarea element', () => {
+      const textarea = document.createElement('textarea');
+      const maskFn = vi.fn();
+      vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+      applyMaskToElement(textarea, '999-999');
+
+      expect(maskFn).toHaveBeenCalledWith(textarea);
+    });
+
+    it('finds and applies mask to input inside wrapper', () => {
+      const wrapper = document.createElement('div');
+      const input = document.createElement('input');
+      wrapper.appendChild(input);
+      const maskFn = vi.fn();
+      vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+      applyMaskToElement(wrapper, '999-999');
+
+      expect(maskFn).toHaveBeenCalledWith(input);
+    });
+
+    it('applies mask to wrapper if no input found inside', () => {
+      const wrapper = document.createElement('div');
+      const maskFn = vi.fn();
+      vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+      applyMaskToElement(wrapper, '999-999');
+
+      expect(maskFn).toHaveBeenCalledWith(wrapper);
+    });
+
+    it('does nothing if element is null', () => {
+      const maskFn = vi.fn();
+      vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+      applyMaskToElement(null as unknown as HTMLElement, '999-999');
+
+      expect(maskFn).not.toHaveBeenCalled();
+    });
+
+    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);
+
+      applyMaskToElement(input, '999-999', { placeholder: '_' });
+
+      expect(maskFn).toHaveBeenCalledWith(input);
+    });
+  });
+});

package/src/core/maskEngine.ts

@@ -0,0 +1,47 @@
+/* eslint-disable import-x/no-extraneous-dependencies */
+import inputmask from 'inputmask';
+
+import { getMaskOptions } from './maskConfig';
+import { moduleInterop } from '../utils';
+
+import type { Mask, Options } from '../types';
+
+/**
+ * Creates a mask instance with the given mask and options.
+ * Like a factory, but simpler.
+ *
+ * @param mask - The mask pattern
+ * @param options - Optional configuration options
+ * @returns A mask instance
+ */
+export function createMaskInstance(mask: Mask, options?: Options): Inputmask.Instance {
+  const inputmaskInstance = moduleInterop(inputmask);
+  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);
+  }
+}

package/src/index.tsx

@@ -1,7 +1,14 @@
-export { default as withHookFormMask } from './withHookFormMask';
-export { default as withMask } from './withMask';
-export { default as useHookFormMask } from './useHookFormMask';
-export { default as useMaskInput } from './useMaskInput';
+export {
+  useHookFormMask,
+  useMaskInput,
+  withHookFormMask,
+  withMask,
+} from './api';
+
 export type {
-  Mask, Options, UseFormRegister, UseFormRegisterReturn,
+  Input,
+  Mask,
+  Options,
+  UseFormRegister,
+  UseFormRegisterReturn,
 } from './types';

package/src/{types.ts → types/index.ts}

@@ -1,3 +1,9 @@
+import type { RefCallback } from 'react';
+import type {
+  FieldValues, Path,
+  UseFormRegisterReturn,
+} from 'react-hook-form';
+
 import type { Options as MaskOptions } from './inputmask.types';
 
 export type { UseFormRegister, UseFormRegisterReturn } from 'react-hook-form';
@@ -21,3 +27,10 @@ export type Mask = 'datetime'
   | null;
 export type Options = MaskOptions;
 export type Input = HTMLInputElement | HTMLTextAreaElement | HTMLElement;
+
+export interface UseHookFormMaskReturn<
+  T extends FieldValues,
+> extends UseFormRegisterReturn<Path<T>> {
+  ref: RefCallback<HTMLElement | null>;
+  prevRef: RefCallback<HTMLElement | null>;
+}