use-mask-input 3.6.0 → 3.6.1

package/src/api/withHookFormMask.spec.ts

@@ -0,0 +1,155 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach,
+  describe, expect, it, vi,
+} from 'vitest';
+
+import withHookFormMask from './withHookFormMask';
+
+import type { RefCallback } from 'react';
+import type { FieldValues, UseFormRegisterReturn } from 'react-hook-form';
+
+import type { UseHookFormMaskReturn } from '../types';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+describe('withHookFormMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns register object with masked ref', () => {
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+
+    expect(result.ref).toBeDefined();
+    expect(typeof result.ref).toBe('function');
+    expect(result.onChange).toBe(register.onChange);
+    expect(result.onBlur).toBe(register.onBlur);
+    expect(result.name).toBe(register.name);
+  });
+
+  it('applies mask when ref is called', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('calls original ref after applying mask', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      ref: originalRef,
+      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 result = withHookFormMask(register, '999-999');
+    result.ref?.(input);
+
+    expect(originalRef).toHaveBeenCalled();
+  });
+
+  it('works with alias masks', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      ref: originalRef,
+      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 result = withHookFormMask(register, 'cpf');
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('works with custom options', () => {
+    const input = document.createElement('input');
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999', { placeholder: '_' });
+    result.ref?.(input);
+
+    expect(maskFn).toHaveBeenCalled();
+  });
+
+  it('handles null ref gracefully', () => {
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: null as unknown as RefCallback<HTMLElement | null>,
+      ref: null as unknown as RefCallback<HTMLElement | null>,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+
+    const result = withHookFormMask(register, '999-999');
+    expect(result.ref).toBeNull();
+    expect(result.onChange).toBe(register.onChange);
+    expect(result.onBlur).toBe(register.onBlur);
+  });
+
+  it('handles null input in ref callback', () => {
+    const originalRef = vi.fn();
+    const register: UseHookFormMaskReturn<FieldValues> = {
+      prevRef: vi.fn(),
+      ref: originalRef,
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      name: 'phone',
+    };
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const result = withHookFormMask(register, '999-999');
+    result.ref?.(null as unknown as HTMLElement);
+
+    expect(maskFn).not.toHaveBeenCalled();
+  });
+});

package/src/api/withHookFormMask.ts

@@ -0,0 +1,54 @@
+/* eslint-disable no-nested-ternary */
+import { applyMaskToElement } from '../core';
+import { flow } from '../utils';
+
+import type { RefCallback } from 'react';
+import type { FieldValues } from 'react-hook-form';
+
+import type {
+  Mask, Options, UseFormRegisterReturn, UseHookFormMaskReturn,
+} from '../types';
+
+/**
+ * Enhances a React Hook Form register return object with mask support.
+ * Takes an already registered field and adds mask to it.
+ * Useful when you registered the field before.
+ *
+ * @param register - The register return object from React Hook Form
+ * @param mask - The mask pattern to apply
+ * @param options - Optional mask configuration options
+ * @returns A new register return object with mask applied
+ */
+export default function withHookFormMask(
+  register: UseFormRegisterReturn,
+  mask: Mask,
+  options?: Options,
+): UseHookFormMaskReturn<FieldValues> {
+  const { ref } = register as UseHookFormMaskReturn<FieldValues>;
+
+  const applyMaskToRef = (_ref: HTMLElement | null) => {
+    if (_ref) applyMaskToElement(_ref, mask, options);
+    return _ref;
+  };
+
+  const refWithMask = ref === null
+    ? null
+    : ref
+      ? flow(applyMaskToRef, ref)
+      : null;
+
+  const result = {
+    ...register,
+    ref: refWithMask as RefCallback<HTMLElement | null>,
+  } as UseHookFormMaskReturn<FieldValues>;
+
+  // change prevRef to non-enumerable
+  Object.defineProperty(result, 'prevRef', {
+    value: ref,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+
+  return result;
+}

package/src/api/withMask.spec.ts

@@ -0,0 +1,93 @@
+import inputmask from 'inputmask';
+import {
+  beforeEach, describe, expect, it, vi,
+} from 'vitest';
+
+import withMask from './withMask';
+
+vi.mock('inputmask', () => ({
+  default: vi.fn((options) => ({
+    mask: vi.fn(),
+    options,
+  })),
+}));
+
+vi.mock('../utils/isServer', () => ({
+  default: false,
+}));
+
+describe('withMask', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a function', () => {
+    const result = withMask('999-999');
+    expect(typeof result).toBe('function');
+  });
+
+  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);
+
+    const refCallback = withMask('999-999');
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  it('does nothing if input is null', () => {
+    const maskFn = vi.fn();
+    vi.mocked(inputmask).mockReturnValue({ mask: maskFn } as unknown as Inputmask.Instance);
+
+    const refCallback = withMask('999-999');
+    refCallback(null);
+
+    expect(maskFn).not.toHaveBeenCalled();
+  });
+
+  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);
+
+    const refCallback = withMask(null);
+    refCallback(input);
+
+    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);
+
+    const refCallback = withMask('999-999', { placeholder: '_' });
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  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);
+
+    const refCallback = withMask('cpf');
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+
+  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);
+
+    const refCallback = withMask(['999-999', '9999-9999']);
+    refCallback(input);
+
+    expect(maskFn).toHaveBeenCalledWith(input);
+  });
+});

package/src/api/withMask.ts

@@ -0,0 +1,25 @@
+/* eslint-disable import-x/no-extraneous-dependencies */
+import inputmask from 'inputmask';
+
+import { getMaskOptions } from '../core/maskConfig';
+import isServer from '../utils/isServer';
+import interopDefaultSync from '../utils/moduleInterop';
+
+import type { Input, Mask, Options } from '../types';
+
+/**
+ * Higher-order function that creates a ref callback for applying input masks.
+ * Simple function to apply mask via ref. No hooks, no drama.
+ *
+ * @param mask - The mask pattern to apply
+ * @param options - Optional mask configuration options
+ * @returns A ref callback function that applies the mask
+ */
+export default function withMask(mask: Mask, options?: Options) {
+  return (input: Input | null): void => {
+    if (isServer || mask === null || !input) return;
+
+    const maskInput = interopDefaultSync(inputmask)(getMaskOptions(mask, options));
+    maskInput.mask(input as HTMLElement);
+  };
+}

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') ?? element.querySelector('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';