react-input-mask-format 2.1.0 → 2.3.0

package/README.md

@@ -10,7 +10,16 @@ Made with attention to UX.
 
 A maintained fork of [react-input-mask](https://github.com/sanniassin/react-input-mask).
 
-## What's new in 2.1
+## What's new in 2.3
+
+- `react-input-mask-format/time` — HH:MM (24h) masked input with clamping, see [Time](#time--react-input-mask-formattime)
+
+### 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`, `Я`, `#`)
@@ -161,6 +170,135 @@ 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).
+
+## Time — `react-input-mask-format/time`
+
+A separate, tree-shakeable entry for formatting times in 24-hour format (HH:MM).
+
+```tsx
+import { TimeFormat, useTimeFormat, formatTime } from "react-input-mask-format/time";
+
+// controlled component
+<TimeFormat value={time} onValueChange={(v) => setTime(v.value)} />
+
+// bring-your-own input (e.g. a design-system Input)
+const ref = useTimeFormat({ onValueChange: (v) => setTime(v.value) });
+<input ref={ref} />
+
+formatTime("2999"); // "23:59"
+```
+
+`onValueChange` receives `{ value, formattedValue, hours, minutes }`:
+
+```txt
+typing "1234"  →  value "12:34"  formattedValue "12:34"  hours 12  minutes 34
+typing "12"    →  value ""       formattedValue "12:"     hours 12  minutes undefined
+```
+
+`value` remains empty until both hours and minutes are complete. The canonical
+`value` always uses `:` as the separator, regardless of the display `separator`
+option.
+
+**Clamping**: When hours are complete (two digits), they're clamped to ≤23.
+When minutes are complete, they're clamped to ≤59. A single digit is never
+clamped.
+
+Because an incomplete time has an empty canonical `value`, a controlled parent
+that resets `value` to `""` won't visibly clear a partially-typed field; to
+force-clear it, remount the input with a changed React `key`.
+
+Options: `separator` (default `:`).
+
+There is also a ref hook and the pure helpers:
+
+```tsx
+import { useTimeFormat, formatTime, parseTime } from "react-input-mask-format/time";
+
+const ref = useTimeFormat({ separator: ":" });
+// <input ref={ref} />
+
+formatTime("2999", { separator: ":" }); // "23:59"
+parseTime("14:30");                      // { value: "14:30", formattedValue: "14:30", hours: 14, minutes: 30 }
+```
+
+**Reserved for a later minor release**: seconds (HH:MM:SS) and 12-hour format
+with AM/PM.
+
 ### `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

@@ -32,10 +32,11 @@ var src_exports = {};
 __export(src_exports, {
   default: () => src_default,
   defaultFormatChars: () => defaultFormatChars,
-  extendedFormatChars: () => extendedFormatChars
+  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");
@@ -672,8 +673,212 @@ function resolveTransform(transform) {
   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,
@@ -856,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(),
@@ -864,7 +1069,7 @@ var InputMask = (0, import_react2.forwardRef)(function InputMask2(props, forward
       });
     }
   });
-  (0, import_react2.useLayoutEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     if (!isMasked) {
       return;
     }
@@ -921,15 +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
+  extendedFormatChars,
+  useMask
 });
 //# sourceMappingURL=index.cjs.map