react-input-mask-format 2.0.0 → 2.2.0

package/README.md

@@ -4,10 +4,26 @@
 [![npm downloads](https://img.shields.io/npm/dm/react-input-mask-format.svg)](https://www.npmjs.com/package/react-input-mask-format)
 [![CI](https://github.com/Temirtator/react-input-mask-format/actions/workflows/ci.yml/badge.svg)](https://github.com/Temirtator/react-input-mask-format/actions/workflows/ci.yml)
 
-Input masking component for React. Made with attention to UX.
+General-purpose input masking for React — dates, phone numbers, cards, custom
+tokens, and a growing set of ready-made country packs (Kazakhstan ships first).
+Made with attention to UX.
 
 A maintained fork of [react-input-mask](https://github.com/sanniassin/react-input-mask).
 
+## What's new in 2.2
+
+- `useMask` hook — mask your own `<input>` with no wrapper component, see [useMask hook](#usemask-hook)
+- `react-input-mask-format/number` — numeric & currency masking, a lightweight `react-number-format` alternative, see [Numeric & currency](#numeric--currency--react-input-mask-formatnumber)
+
+### 2.1
+
+- `transform` prop (`uppercase` / `lowercase` / custom) — see [transform](#transform)
+- Custom tokens via RegExp `formatChars` + shipped `extendedFormatChars` (`A`, `Я`, `#`)
+- `react-input-mask-format/presets` — `card` + Kazakhstan pack (phone, IIN, BIN, IBAN, plate, postal)
+- `react-input-mask-format/validators` — `isValidIin`, `isValidBin`, `isValidKzIban`, `luhn`
+
+All additive — no migration needed.
+
 ## Why this fork
 
 The original `react-input-mask` has been unmaintained since 2021. This fork is:
@@ -45,6 +61,8 @@ function DateInput(props) {
 |                            Name                            |                Type                | Default | Description |
 | :---------------------------------------------------------: | :--------------------------------: | :-----: | :--- |
 |                    **[`mask`](#mask)**                     | `{String\|Array<String, RegExp>}`  |         | Mask format |
+|                    **[`transform`](#transform)**                    | `{"uppercase"\|"lowercase"\|Function}` |         | Normalize each entered character before it's tested against the mask |
+| **[`formatChars`](#custom-tokens-formatchars-and-extendedformatchars)** | `{Object<String, RegExp>}` |         | Custom mask tokens beyond the default `9`, `a`, `*` |
 |          **[`maskPlaceholder`](#maskplaceholder)**          |             `{String}`             |   `_`   | Placeholder to cover unfilled parts of the mask |
 |           **[`alwaysShowMask`](#alwaysshowmask)**           |            `{Boolean}`             | `false` | Whether mask prefix and placeholder should be displayed when input is empty and has no focus |
 | **[`beforeMaskedStateChange`](#beforemaskedstatechange)** |            `{Function}`            |         | Function to modify value and selection before applying mask |
@@ -79,6 +97,151 @@ const mask = [firstLetter, digit, letter, " ", digit, letter, digit];
 return <InputMask mask={mask} />;
 ```
 
+### `transform`
+
+Normalize every entered character. Runs before the mask test, so an uppercase-only
+class accepts lowercase typing; runs before `beforeMaskedStateChange`.
+
+```jsx
+<InputMask mask="aaaaaa" transform="uppercase" />           // "abc" → "ABC"
+<InputMask mask={[/[A-Z]/, /[A-Z]/]} transform="uppercase" />
+<InputMask mask="9a9a" transform={(char, position) => char} />
+```
+
+Values: `"uppercase"`, `"lowercase"`, or `(char, position) => char` (must be pure).
+
+### Custom tokens (`formatChars`) and `extendedFormatChars`
+
+Define your own mask tokens by mapping a character to a `RegExp`:
+
+```jsx
+import InputMask, { extendedFormatChars } from "react-input-mask-format";
+
+// roll your own
+<InputMask mask="ww-ww" formatChars={{ w: /[a-z]/ }} />
+
+// or use the shipped extended set: A (uppercase), Я (Cyrillic incl. Kazakh), # (hex)
+<InputMask mask="AAA-###" formatChars={extendedFormatChars} />
+```
+
+The default tokens (`9`, `a`, `*`) are unchanged. Passing string values (`{ w: "[a-z]" }`)
+still works but is deprecated — pass `RegExp` values.
+
+## Presets
+
+Ready-made mask configs. Import what you need and spread it — tree-shakeable, and the
+core bundle carries none of it.
+
+```jsx
+import InputMask from "react-input-mask-format";
+import { kzPhone, kzIban } from "react-input-mask-format/presets";
+
+<InputMask {...kzPhone} value={phone} onChange={onChange} />
+<InputMask {...kzIban} value={iban} onChange={onChange} />
+```
+
+Presets are a country-agnostic system; Kazakhstan is the first (flagship) country pack —
+PRs adding other countries are welcome.
+
+| export | mask | example |
+| --- | --- | --- |
+| `card` | `9999 9999 9999 9999` | `4242 4242 4242 4242` |
+| `kzPhone` | `+7 (799) 999-99-99` | `+7 (701) 234-56-78` |
+| `kzIin` | `999999999999` | `901010123458` |
+| `kzBin` | `999999999999` | `150340004984` |
+| `kzIban` | `KZ99 999* **** **** ****` (uppercase) | `KZ86 125K ZT50 0410 0100` |
+| `kzPlate` | `123 ABC 02` (letters `ABCEHKMNOPTXY`, uppercase) | `123 ABC 02` |
+| `kzPostal` | `999999` | `050000` |
+
+## Validators
+
+Optional checksum validators, separate entry point, zero-deps. Accept raw or formatted
+input; return `false` on empty/invalid.
+
+```jsx
+import { isValidIin, isValidBin, isValidKzIban, luhn } from "react-input-mask-format/validators";
+
+isValidIin("901010123458");                 // KZ IIN/BIN mod-11 checksum
+isValidKzIban("KZ86 125K ZT50 0410 0100");  // ISO 7064 MOD-97
+luhn("4242 4242 4242 4242");                // card Luhn
+```
+
+## `useMask` hook
+
+Mask your own `<input>` with no wrapper component. `useMask` returns a ref
+callback:
+
+```tsx
+import { useMask } from "react-input-mask-format";
+
+function Phone() {
+  const ref = useMask({ mask: "+7 (999) 999-99-99", maskPlaceholder: "_" });
+  return <input ref={ref} name="phone" />;
+}
+```
+
+`useMask` is **uncontrolled**: attach it to an input you don't drive with a
+React `value` prop, and read the masked value through your own `onChange` (it
+fires with the masked value) or on form submit. For a controlled component,
+use `<InputMask>`.
+
+Options: `mask`, `maskPlaceholder`, `alwaysShowMask`, `formatChars`,
+`transform`, `beforeMaskedStateChange`.
+
+## Numeric & currency — `react-input-mask-format/number`
+
+A separate, tree-shakeable entry for formatting numbers, currency, and
+percentages. Prop names match `react-number-format`, so migration is mostly a
+find-and-replace of the import.
+
+```tsx
+import { NumberFormat } from "react-input-mask-format/number";
+
+function Amount() {
+  const [value, setValue] = React.useState<number>();
+  return (
+    <NumberFormat
+      value={value ?? ""}
+      onValueChange={({ floatValue }) => setValue(floatValue)}
+      thousandSeparator="," decimalScale={2} fixedDecimalScale prefix="$ "
+      allowNegative
+    />
+  );
+}
+```
+
+`onValueChange` receives `{ value, formattedValue, floatValue }`:
+
+```txt
+typing "1234.5"  →  value "1234.5"  formattedValue "$ 1,234.50"  floatValue 1234.5
+```
+
+Options: `thousandSeparator` (`true` → `,`, or a custom string),
+`decimalSeparator` (default `.`), `decimalScale` (truncates, no rounding),
+`fixedDecimalScale`, `prefix`, `suffix`, `allowNegative` (default `true`),
+`allowLeadingZeros`, and `isAllowed(values) => boolean` (reject an edit, e.g.
+for min/max).
+
+There is also a ref hook and the pure helpers:
+
+```tsx
+import { useNumberFormat, formatNumber, parseNumber } from "react-input-mask-format/number";
+
+const ref = useNumberFormat({ thousandSeparator: " ", decimalScale: 2, prefix: "$ " });
+// <input ref={ref} />
+
+formatNumber(1234.5, { thousandSeparator: ",", decimalScale: 2, fixedDecimalScale: true }); // "1,234.50"
+```
+
+### Migrating from react-number-format
+
+`NumberFormat`'s props (`thousandSeparator`, `decimalSeparator`, `decimalScale`,
+`fixedDecimalScale`, `prefix`, `suffix`, `allowNegative`, `allowLeadingZeros`,
+`isAllowed`, `onValueChange`) mirror `react-number-format`'s `NumericFormat`.
+The main differences: `decimalScale` **truncates** rather than rounds while
+typing, and this package ships a single `NumberFormat` (no separate
+`PatternFormat` — use the mask engine / `<InputMask>` for pattern masks).
+
 ### `maskPlaceholder`
 
 ```jsx

package/dist/chunk-CEZXZ7IJ.js

@@ -0,0 +1,42 @@
+// src/utils/input.ts
+function setInputSelection(input, start, end) {
+  if (end === void 0) {
+    end = start;
+  }
+  input.setSelectionRange(start, end);
+}
+function getInputSelection(input) {
+  const start = input.selectionStart;
+  const end = input.selectionEnd;
+  return {
+    start,
+    end,
+    length: (end != null ? end : 0) - (start != null ? start : 0)
+  };
+}
+function isInputFocused(input) {
+  const inputDocument = input.ownerDocument;
+  return inputDocument.hasFocus() && inputDocument.activeElement === input;
+}
+
+// src/set-native-value.ts
+function setNativeValue(input, value) {
+  const descriptor = Object.getOwnPropertyDescriptor(
+    HTMLInputElement.prototype,
+    "value"
+  );
+  const setter = descriptor && descriptor.set;
+  if (setter) {
+    setter.call(input, value);
+  } else {
+    input.value = value;
+  }
+}
+
+export {
+  setInputSelection,
+  getInputSelection,
+  isInputFocused,
+  setNativeValue
+};
+//# sourceMappingURL=chunk-CEZXZ7IJ.js.map

package/dist/chunk-CEZXZ7IJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/input.ts","../src/set-native-value.ts"],"sourcesContent":["import type { Selection } from \"../types\";\n\nexport function setInputSelection(\n  input: HTMLInputElement,\n  start: number,\n  end?: number\n): void {\n  if (end === undefined) {\n    end = start;\n  }\n  input.setSelectionRange(start, end);\n}\n\nexport function getInputSelection(input: HTMLInputElement): Required<Selection> {\n  const start = input.selectionStart;\n  const end = input.selectionEnd;\n\n  return {\n    start,\n    end,\n    length: (end ?? 0) - (start ?? 0)\n  };\n}\n\nexport function isInputFocused(input: HTMLInputElement): boolean {\n  const inputDocument = input.ownerDocument;\n  return inputDocument.hasFocus() && inputDocument.activeElement === input;\n}\n","// Write to input.value through the native prototype setter so React's\n// internal value tracker stays stale. The user's keystroke `input` event then\n// bubbles into React's root listener, which sees masked value != stale tracker\n// and fires the consumer's onChange with the masked value. Using the tracked\n// (React-wrapped) setter instead would suppress that onChange.\nexport function setNativeValue(input: HTMLInputElement, value: string): void {\n  const descriptor = Object.getOwnPropertyDescriptor(\n    HTMLInputElement.prototype,\n    \"value\"\n  );\n  const setter = descriptor && descriptor.set;\n  if (setter) {\n    setter.call(input, value);\n  } else {\n    input.value = value;\n  }\n}\n"],"mappings":";AAEO,SAAS,kBACd,OACA,OACA,KACM;AACN,MAAI,QAAQ,QAAW;AACrB,UAAM;AAAA,EACR;AACA,QAAM,kBAAkB,OAAO,GAAG;AACpC;AAEO,SAAS,kBAAkB,OAA8C;AAC9E,QAAM,QAAQ,MAAM;AACpB,QAAM,MAAM,MAAM;AAElB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,SAAS,oBAAO,MAAM,wBAAS;AAAA,EACjC;AACF;AAEO,SAAS,eAAe,OAAkC;AAC/D,QAAM,gBAAgB,MAAM;AAC5B,SAAO,cAAc,SAAS,KAAK,cAAc,kBAAkB;AACrE;;;ACtBO,SAAS,eAAe,OAAyB,OAAqB;AAC3E,QAAM,aAAa,OAAO;AAAA,IACxB,iBAAiB;AAAA,IACjB;AAAA,EACF;AACA,QAAM,SAAS,cAAc,WAAW;AACxC,MAAI,QAAQ;AACV,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B,OAAO;AACL,UAAM,QAAQ;AAAA,EAChB;AACF;","names":[]}

package/dist/index.cjs

@@ -30,10 +30,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.tsx
 var src_exports = {};
 __export(src_exports, {
-  default: () => src_default
+  default: () => src_default,
+  defaultFormatChars: () => defaultFormatChars,
+  extendedFormatChars: () => extendedFormatChars,
+  useMask: () => useMask
 });
 module.exports = __toCommonJS(src_exports);
-var import_react2 = __toESM(require("react"), 1);
+var import_react3 = __toESM(require("react"), 1);
 
 // src/hooks.ts
 var import_react = require("react");
@@ -265,6 +268,12 @@ var defaultFormatChars = {
   a: /[A-Za-z]/,
   "*": /[A-Za-z0-9]/
 };
+var extendedFormatChars = {
+  ...defaultFormatChars,
+  A: /[A-Z]/,
+  "\u042F": /[А-Яа-яЁёӘәҒғҚқҢңӨөҰұҮүҺһІі]/,
+  "#": /[0-9A-Fa-f]/
+};
 
 // src/validate-props.ts
 function warnDev(condition, message) {
@@ -491,13 +500,14 @@ var MaskUtils = class {
       if (position >= mask.length) {
         return value;
       }
-      const isAllowed = this.isCharacterAllowedAtPosition(character, position);
+      const transformedCharacter = this.transform && this.isPositionEditable(position) ? this.transform(character, position) : character;
+      const isAllowed = this.isCharacterAllowedAtPosition(transformedCharacter, position);
       const isEditable = this.isPositionEditable(position);
       const nextEditablePosition = this.getRightEditablePosition(position);
-      const isNextPlaceholder = maskPlaceholder && nextEditablePosition ? character === maskPlaceholder[nextEditablePosition] : null;
+      const isNextPlaceholder = maskPlaceholder && nextEditablePosition ? transformedCharacter === maskPlaceholder[nextEditablePosition] : null;
       const valueBefore = value.slice(0, position);
       if (isAllowed || !isEditable) {
-        const insertedCharacter = isAllowed ? character : mask[position];
+        const insertedCharacter = isAllowed ? transformedCharacter : mask[position];
         value = valueBefore + insertedCharacter;
       }
       if (!isAllowed && !isEditable && !isNextPlaceholder) {
@@ -592,6 +602,7 @@ var MaskUtils = class {
       };
     };
     this.maskOptions = parseMask(options);
+    this.transform = options.transform;
   }
 };
 
@@ -609,15 +620,22 @@ function resolveMaskPlaceholder(maskPlaceholder, maskChar) {
   }
   return maskChar;
 }
-function toRegExpFormatChars(formatChars) {
+function normalizeFormatChars(formatChars) {
   if (!formatChars) {
-    return void 0;
+    return { formatChars: void 0, hasLegacyString: false };
   }
   const result = {};
+  let hasLegacyString = false;
   for (const key of Object.keys(formatChars)) {
-    result[key] = new RegExp(formatChars[key]);
+    const value = formatChars[key];
+    if (typeof value === "string") {
+      hasLegacyString = true;
+      result[key] = new RegExp(value);
+    } else {
+      result[key] = value;
+    }
   }
-  return result;
+  return { formatChars: result, hasLegacyString };
 }
 function createBeforeMaskedStateChangeAdapter(beforeMaskedValueChange, maskOptions) {
   return ({ previousState, currentState, nextState }) => {
@@ -631,14 +649,243 @@ function createBeforeMaskedStateChangeAdapter(beforeMaskedValueChange, maskOptio
   };
 }
 
+// src/utils/transform.ts
+function resolveTransform(transform) {
+  if (!transform) {
+    return void 0;
+  }
+  if (transform === "uppercase") {
+    return (char) => char.toUpperCase();
+  }
+  if (transform === "lowercase") {
+    return (char) => char.toLowerCase();
+  }
+  if (typeof transform === "function") {
+    return transform;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    console.error(
+      `react-input-mask-format: invalid transform "${String(
+        transform
+      )}", expected "uppercase" | "lowercase" | (char, position) => char`
+    );
+  }
+  return void 0;
+}
+
+// src/use-mask.ts
+var import_react2 = require("react");
+
+// src/set-native-value.ts
+function setNativeValue(input, value) {
+  const descriptor = Object.getOwnPropertyDescriptor(
+    HTMLInputElement.prototype,
+    "value"
+  );
+  const setter = descriptor && descriptor.set;
+  if (setter) {
+    setter.call(input, value);
+  } else {
+    input.value = value;
+  }
+}
+
+// src/bind-mask.ts
+var IS_JSDOM = typeof navigator !== "undefined" && navigator.userAgent.includes("jsdom");
+function createMaskController(maskUtils, options) {
+  let input = null;
+  let lastValue = "";
+  let lastSelection = { start: null, end: null };
+  function getInputState() {
+    return { value: input.value, selection: getInputSelection(input) };
+  }
+  function getLastInputState() {
+    return { value: lastValue, selection: lastSelection };
+  }
+  function setInputState({ value, selection }) {
+    setNativeValue(input, value);
+    lastValue = value;
+    if (input && isInputFocused(input) && selection.start !== null && selection.end !== null) {
+      setInputSelection(input, selection.start, selection.end);
+      lastSelection = getInputSelection(input);
+    } else {
+      lastSelection = selection;
+    }
+    if (IS_JSDOM) {
+      const resyncValue = value;
+      const resyncSelection = selection;
+      queueMicrotask(() => {
+        if (!input || input.value !== resyncValue) return;
+        input.value = resyncValue;
+        if (isInputFocused(input) && resyncSelection.start !== null && resyncSelection.end !== null) {
+          setInputSelection(input, resyncSelection.start, resyncSelection.end);
+        }
+      });
+    }
+  }
+  function handleInput() {
+    const currentState = getInputState();
+    const previousState = getLastInputState();
+    let nextState = maskUtils.processChange(currentState, previousState);
+    if (options.beforeMaskedStateChange) {
+      nextState = options.beforeMaskedStateChange({ currentState, previousState, nextState });
+    }
+    setInputState(nextState);
+  }
+  function handleFocus() {
+    const currentValue = getInputState().value;
+    if (!maskUtils.isValueFilled(currentValue)) {
+      const newValue = maskUtils.formatValue(currentValue);
+      const newSelection = maskUtils.getDefaultSelectionForValue(newValue);
+      let nextState = { value: newValue, selection: newSelection };
+      if (options.beforeMaskedStateChange) {
+        nextState = options.beforeMaskedStateChange({ currentState: getInputState(), nextState });
+      }
+      setInputState(nextState);
+      defer(() => {
+        if (input && isInputFocused(input)) {
+          setInputSelection(input, lastSelection.start, lastSelection.end);
+        }
+      });
+    }
+  }
+  function handleBlur() {
+    const lastValueOnBlur = getLastInputState().value;
+    if (!options.alwaysShowMask && maskUtils.isValueEmpty(lastValueOnBlur)) {
+      let nextState = { value: "", selection: { start: null, end: null } };
+      if (options.beforeMaskedStateChange) {
+        nextState = options.beforeMaskedStateChange({ currentState: getInputState(), nextState });
+      }
+      setInputState(nextState);
+    }
+  }
+  function handleMouseDown(event) {
+    if (!input) return;
+    const { value } = getInputState();
+    const inputDocument = getElementDocument(input);
+    if (!isInputFocused(input) && !maskUtils.isValueFilled(value)) {
+      const mouseDownX = event.clientX;
+      const mouseDownY = event.clientY;
+      const mouseDownTime = (/* @__PURE__ */ new Date()).getTime();
+      const mouseUpHandler = (mouseUpEvent) => {
+        inputDocument.removeEventListener("mouseup", mouseUpHandler);
+        if (!input || !isInputFocused(input)) return;
+        const deltaX = Math.abs(mouseUpEvent.clientX - mouseDownX);
+        const deltaY = Math.abs(mouseUpEvent.clientY - mouseDownY);
+        const axisDelta = Math.max(deltaX, deltaY);
+        const timeDelta = (/* @__PURE__ */ new Date()).getTime() - mouseDownTime;
+        if (axisDelta <= 10 && timeDelta <= 200 || axisDelta <= 5 && timeDelta <= 300) {
+          const newSelection = maskUtils.getDefaultSelectionForValue(lastValue);
+          if (newSelection.start !== null && newSelection.end !== null) {
+            setInputSelection(input, newSelection.start, newSelection.end);
+            lastSelection = getInputSelection(input);
+          }
+        }
+      };
+      inputDocument.addEventListener("mouseup", mouseUpHandler);
+    }
+  }
+  function bind(el) {
+    input = el;
+    lastValue = el.value;
+    lastSelection = getInputSelection(el);
+    const formatted = maskUtils.formatValue(el.value);
+    if (!maskUtils.isValueEmpty(formatted) || options.alwaysShowMask) {
+      setNativeValue(el, formatted);
+      lastValue = formatted;
+    }
+    el.addEventListener("input", handleInput);
+    el.addEventListener("focus", handleFocus);
+    el.addEventListener("blur", handleBlur);
+    el.addEventListener("mousedown", handleMouseDown);
+  }
+  function unbind() {
+    if (input) {
+      input.removeEventListener("input", handleInput);
+      input.removeEventListener("focus", handleFocus);
+      input.removeEventListener("blur", handleBlur);
+      input.removeEventListener("mousedown", handleMouseDown);
+    }
+    input = null;
+  }
+  function update(nextMaskUtils, nextOptions) {
+    maskUtils = nextMaskUtils;
+    options = nextOptions;
+  }
+  return { bind, unbind, update };
+}
+
+// src/use-mask.ts
+function useMask(options) {
+  const {
+    mask,
+    maskPlaceholder: maskPlaceholderProp,
+    alwaysShowMask = false,
+    formatChars,
+    transform,
+    beforeMaskedStateChange: beforeMaskedStateChangeProp,
+    beforeMaskedValueChange
+  } = options;
+  if (beforeMaskedValueChange !== void 0) {
+    warnDeprecatedOnce(
+      "beforeMaskedValueChange",
+      "beforeMaskedValueChange is deprecated, use beforeMaskedStateChange."
+    );
+  }
+  const resolvedPlaceholder = resolveMaskPlaceholder(maskPlaceholderProp, void 0);
+  const maskPlaceholder = resolvedPlaceholder === void 0 ? "_" : resolvedPlaceholder;
+  const { formatChars: normalizedFormatChars, hasLegacyString } = normalizeFormatChars(formatChars);
+  if (hasLegacyString) {
+    warnDeprecatedOnce(
+      "formatChars",
+      "string values in formatChars are deprecated, pass RegExp values instead."
+    );
+  }
+  const maskUtils = new MaskUtils({
+    mask: mask != null ? mask : null,
+    maskPlaceholder,
+    formatChars: normalizedFormatChars,
+    transform: resolveTransform(transform)
+  });
+  let beforeMaskedStateChange = beforeMaskedStateChangeProp;
+  if (!beforeMaskedStateChange && beforeMaskedValueChange) {
+    const v2MaskOptions = {
+      mask: mask != null ? mask : void 0,
+      maskChar: maskPlaceholder,
+      alwaysShowMask,
+      formatChars: formatChars != null ? formatChars : { "9": "[0-9]", a: "[A-Za-z]", "*": "[A-Za-z0-9]" },
+      permanents: maskUtils.maskOptions.permanents
+    };
+    beforeMaskedStateChange = createBeforeMaskedStateChangeAdapter(beforeMaskedValueChange, v2MaskOptions);
+  }
+  const controllerOptions = { alwaysShowMask, beforeMaskedStateChange };
+  const controllerRef = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    var _a;
+    (_a = controllerRef.current) == null ? void 0 : _a.update(maskUtils, controllerOptions);
+  });
+  return (0, import_react2.useCallback)((el) => {
+    var _a;
+    if (el) {
+      const controller = createMaskController(maskUtils, controllerOptions);
+      controller.bind(el);
+      controllerRef.current = controller;
+    } else {
+      (_a = controllerRef.current) == null ? void 0 : _a.unbind();
+      controllerRef.current = null;
+    }
+  }, []);
+}
+
 // src/index.tsx
-var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forwardedRef) {
+var InputMask = (0, import_react3.forwardRef)(function InputMask2(props, forwardedRef) {
   const {
     alwaysShowMask = false,
     children,
     mask,
     maskPlaceholder: maskPlaceholderProp,
     beforeMaskedStateChange: beforeMaskedStateChangeProp,
+    transform,
     maskChar,
     formatChars,
     beforeMaskedValueChange,
@@ -647,9 +894,6 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
   if (maskChar !== void 0) {
     warnDeprecatedOnce("maskChar", "maskChar is deprecated, use maskPlaceholder instead. See migration guide: https://github.com/Temirtator/react-input-mask-format#migrating-from-react-input-mask");
   }
-  if (formatChars !== void 0) {
-    warnDeprecatedOnce("formatChars", "formatChars is deprecated, prefer an array mask with RegExps. See migration guide: https://github.com/Temirtator/react-input-mask-format#migrating-from-react-input-mask");
-  }
   if (beforeMaskedValueChange !== void 0) {
     warnDeprecatedOnce("beforeMaskedValueChange", "beforeMaskedValueChange is deprecated, use beforeMaskedStateChange. See migration guide: https://github.com/Temirtator/react-input-mask-format#migrating-from-react-input-mask");
   }
@@ -657,10 +901,18 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
   const maskPlaceholder = resolvedPlaceholder === void 0 ? "_" : resolvedPlaceholder;
   validateMaxLength(props);
   validateMaskPlaceholder({ ...props, maskPlaceholder });
+  const { formatChars: normalizedFormatChars, hasLegacyString } = normalizeFormatChars(formatChars);
+  if (hasLegacyString) {
+    warnDeprecatedOnce(
+      "formatChars",
+      'string values in formatChars are deprecated, pass RegExp values instead (e.g. { "#": /[0-9]/ }). See migration guide: https://github.com/Temirtator/react-input-mask-format#migrating-from-react-input-mask'
+    );
+  }
   const maskUtils = new MaskUtils({
     mask,
     maskPlaceholder,
-    formatChars: toRegExpFormatChars(formatChars)
+    formatChars: normalizedFormatChars,
+    transform: resolveTransform(transform)
   });
   let beforeMaskedStateChange = beforeMaskedStateChangeProp;
   if (!beforeMaskedStateChange && beforeMaskedValueChange) {
@@ -809,7 +1061,7 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
     renderValue = newValue;
   }
   const lastSelection = getLastInputState().selection;
-  (0, import_react2.useLayoutEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     if (isMasked && isControlled) {
       setInputState({
         ...getLastInputState(),
@@ -817,7 +1069,7 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
       });
     }
   });
-  (0, import_react2.useLayoutEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     if (!isMasked) {
       return;
     }
@@ -874,10 +1126,16 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
   };
   if (children) {
     validateChildren(props, children);
-    return import_react2.default.cloneElement(children, inputProps);
+    return import_react3.default.cloneElement(children, inputProps);
   }
-  return /* @__PURE__ */ import_react2.default.createElement("input", { ...inputProps });
+  return /* @__PURE__ */ import_react3.default.createElement("input", { ...inputProps });
 });
 InputMask.displayName = "InputMask";
 var src_default = InputMask;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defaultFormatChars,
+  extendedFormatChars,
+  useMask
+});
 //# sourceMappingURL=index.cjs.map