numora 3.5.0 → 4.0.0

package/dist/types.d.ts

@@ -8,15 +8,62 @@ export declare enum ThousandStyle {
     Lakh = "lakh",
     Wan = "wan"
 }
+/**
+ * Named constants for the W3C InputEvent `inputType` strings used by NumoraInput's
+ * beforeinput/input handlers. Defined as an `as const` object (not a TS `enum`) to
+ * avoid a runtime artifact and to stay tree-shakable.
+ *
+ * Reference for the full set of `inputType` values:
+ *   - MDN: https://developer.mozilla.org/en-US/docs/Web/API/InputEvent/inputType
+ *   - W3C Input Events spec: https://w3c.github.io/input-events/
+ */
+export declare const InputType: {
+    readonly InsertText: "insertText";
+    readonly InsertFromPaste: "insertFromPaste";
+    readonly InsertFromDrop: "insertFromDrop";
+    readonly DeleteContentBackward: "deleteContentBackward";
+    readonly DeleteContentForward: "deleteContentForward";
+    readonly DeleteByCut: "deleteByCut";
+    readonly DeleteByDrag: "deleteByDrag";
+    readonly DeleteSoftLineBackward: "deleteSoftLineBackward";
+    readonly DeleteHardLineBackward: "deleteHardLineBackward";
+    readonly DeleteSoftLineForward: "deleteSoftLineForward";
+    readonly DeleteHardLineForward: "deleteHardLineForward";
+    readonly HistoryUndo: "historyUndo";
+    readonly HistoryRedo: "historyRedo";
+};
+export type InputType = (typeof InputType)[keyof typeof InputType];
 export interface FormattingOptions {
     formatOn?: FormatOn;
     thousandSeparator?: string;
-    ThousandStyle?: ThousandStyle;
+    thousandStyle?: ThousandStyle;
     enableCompactNotation?: boolean;
     enableNegative?: boolean;
     enableLeadingZeros?: boolean;
+    /**
+     * When true, a bare leading decimal separator gets a `0` prepended (`.5` → `0.5`,
+     * `-.5` → `-0.5`). Useful for currency-style fields where leading-decimal entry is
+     * common but `0.` form is the canonical representation.
+     */
+    autoAddLeadingZero?: boolean;
     decimalSeparator?: string;
+    decimalMaxLength?: number;
     decimalMinLength?: number;
+    /**
+     * Maximum length of the raw (unformatted) value. Counts digits, the decimal separator,
+     * and a leading `-`. Thousand separators are NOT counted. Applied at the end of the
+     * sanitization pipeline and enforced at keystroke time so the user cannot type past it.
+     *
+     * Do not also pass `maxLength` as a native HTML attribute - that one counts formatted
+     * characters (commas included) and would double-count.
+     */
+    maxLength?: number;
+    /**
+     * Custom keystroke/paste validator. Called with the post-sanitization raw value the
+     * input would have after the user's action. Return false to reject the edit (no value
+     * change, no onChange fires, undo history is untouched).
+     */
+    isAllowed?: (rawValue: string) => boolean;
     rawValueMode?: boolean;
 }
 export interface CaretPositionInfo {

package/dist/utils/event-handlers.d.ts

@@ -1,45 +1,60 @@
 import { type FormattingOptions, type CaretPositionInfo } from '@/types';
 /**
- * Handles the beforeinput event to format the value before it is applied to the DOM.
+ * Outcome of `handleOnBeforeInputNumoraInput`. Pure: the helper does not mutate the
+ * input or the event. The caller decides what to do based on the variant:
  *
- * Returns null for paste events so the dedicated paste handler can process them.
+ * - `handled`: caller should preventDefault, write `formatted` to the input via an
+ *   undo-preserving write, set caret to `cursorPos`, and notify listeners.
+ * - `reject`: caller should preventDefault. The input value is left untouched.
+ * - `skip`: caller should NOT preventDefault. Includes paste/drop (handled by the
+ *   dedicated paste listener) and any unrecognized inputType.
+ */
+export type BeforeInputResult = {
+    type: 'handled';
+    formatted: string;
+    raw: string;
+    cursorPos: number;
+} | {
+    type: 'reject';
+} | {
+    type: 'skip';
+};
+/**
+ * Computes the formatted value, raw value, and target cursor position for a
+ * `beforeinput` event without mutating the input or the event.
+ *
+ * Callers are responsible for `preventDefault()` and applying the result to the DOM.
  *
  * @param e - The InputEvent (beforeinput)
  * @param decimalMaxLength - The maximum number of decimal places allowed
  * @param formattingOptions - Optional formatting options
- * @returns Object with formatted and raw values, or null if the event should be handled natively
+ * @returns A tagged result describing what the caller should do
  */
-export declare function handleOnBeforeInputNumoraInput(e: InputEvent, decimalMaxLength: number, formattingOptions?: FormattingOptions): {
-    formatted: string;
-    raw: string;
-} | null;
+export declare function handleOnBeforeInputNumoraInput(e: InputEvent, decimalMaxLength: number, formattingOptions?: FormattingOptions): BeforeInputResult;
 /**
- * Handles the keydown event to prevent the user from entering a second decimal point.
- * Also tracks selection info for Delete/Backspace keys to enable proper cursor positioning.
- * In 'change' mode with formatting, skips cursor over thousand separators on delete/backspace.
- *
- * @param e - The keyboard event triggered by the input.
- * @param formattingOptions - Optional formatting options for separator skipping
- * @returns Caret position info if Delete/Backspace was pressed, undefined otherwise
+ * Skips the cursor over thousand separators on Delete/Backspace and returns the caret
+ * info the change handler needs to disambiguate Delete-forward (`endOffset: 1`) from
+ * Backspace or non-deletion keys (`endOffset: 0`). Returns undefined for keys that
+ * aren't Delete/Backspace so the caller can null out the stored caret info.
  */
 export declare function handleOnKeyDownNumoraInput(e: KeyboardEvent, formattingOptions?: FormattingOptions): CaretPositionInfo | undefined;
 /**
- * Handles the input change event to ensure the value does not exceed the maximum number of decimal places,
- * replaces commas with dots, and removes invalid non-numeric characters.
- * Also handles cursor positioning for Delete/Backspace keys.
- * Optionally formats with thousand separators in real-time if formatOn is 'change'.
+ * Outcome of `handleOnPasteNumoraInput`. The caller always calls preventDefault on the
+ * paste event; the variant says whether to apply a write or leave the input untouched.
  *
- * @param e - The event triggered by the input.
- * @param decimalMaxLength - The maximum number of decimal places allowed.
- * @param caretPositionBeforeChange - Optional caret position info from keydown handler
- * @param formattingOptions - Optional formatting options for real-time formatting
- * @returns Object with formatted value and raw value
+ * - `handled`: write `formatted` via an undo-preserving write, set caret to `cursorPos`.
+ * - `reject`: do nothing further (input is unchanged).
  */
-export declare function handleOnChangeNumoraInput(e: Event, decimalMaxLength: number, caretPositionBeforeChange?: CaretPositionInfo, formattingOptions?: FormattingOptions): {
-    formatted: string;
-    raw: string;
-};
-export declare function handleOnPasteNumoraInput(e: ClipboardEvent, decimalMaxLength: number, formattingOptions?: FormattingOptions): {
+export type PasteResult = {
+    type: 'handled';
     formatted: string;
     raw: string;
+    cursorPos: number;
+} | {
+    type: 'reject';
 };
+/**
+ * Computes the formatted value and cursor position for a paste event without mutating
+ * the input or the event. The caller owns `preventDefault()` and the DOM write.
+ */
+export declare function handleOnPasteNumoraInput(e: ClipboardEvent, decimalMaxLength: number, formattingOptions?: FormattingOptions): PasteResult;

package/dist/utils/regex-cache.d.ts

@@ -9,32 +9,5 @@
  * @param pattern - The regex pattern string
  * @param flags - Optional regex flags (default: 'g')
  * @returns A cached RegExp object
- *
- * @example
- * // Instead of: new RegExp(escapeRegExp(separator), 'g')
- * getCachedRegex(escapeRegExp(separator), 'g')
  */
 export declare function getCachedRegex(pattern: string, flags?: string): RegExp;
-/**
- * Gets a cached RegExp for a separator character.
- * Handles escaping of special regex characters automatically.
- *
- * @param separator - The separator character to match
- * @param flags - Optional regex flags (default: 'g')
- * @returns A cached RegExp object that matches the separator
- *
- * @example
- * getCachedSeparatorRegex(',') // Returns cached /,/g
- * getCachedSeparatorRegex('.') // Returns cached /\./g (escaped)
- */
-export declare function getCachedSeparatorRegex(separator: string, flags?: string): RegExp;
-/**
- * Clears the regex cache.
- * Useful for testing or when separator configuration changes significantly.
- */
-export declare function clearRegexCache(): void;
-/**
- * Gets the current size of the regex cache.
- * Useful for debugging and monitoring.
- */
-export declare function getRegexCacheSize(): number;

package/dist/utils/set-numora-input-value.d.ts

@@ -0,0 +1,32 @@
+import type { FormattingOptions } from '@/types';
+export interface SetNumoraInputValueOptions {
+    /** Maximum number of decimal places. Defaults to `DEFAULT_DECIMAL_MAX_LENGTH`. */
+    maxDecimals?: number;
+    /** Formatting options (separators, locale, etc.). */
+    formattingOptions?: FormattingOptions;
+    /**
+     * When true (default), routes the write through `setRangeText` so the browser's
+     * undo/redo history stays intact. Set to false only when the new value should *replace*
+     * the entire undo history (e.g. form reset).
+     */
+    undoable?: boolean;
+    /**
+     * When true (default), dispatches a synthetic `input` event after the write so React's
+     * `_valueTracker` and other listeners stay in sync.
+     */
+    dispatchEvent?: boolean;
+}
+/**
+ * Programmatically sets the value of a Numora-managed `<input>` element.
+ *
+ * Use this when you have a direct DOM reference (e.g. `ref.current` in React) and want
+ * to apply a value without going through React's controlled-state machinery. The helper
+ * formats the value through the same pipeline used by typing, preserves the undo stack
+ * by default, and dispatches a synthetic `input` event so listeners see the change.
+ *
+ * @returns The formatted display string and the raw numeric string actually written.
+ */
+export declare function setNumoraInputValue(el: HTMLInputElement, value: string, options?: SetNumoraInputValueOptions): {
+    formatted: string;
+    raw: string;
+};

package/dist/validation.d.ts

@@ -9,6 +9,9 @@ export interface NumoraInputValidationOptions {
     enableCompactNotation?: boolean;
     enableNegative?: boolean;
     enableLeadingZeros?: boolean;
+    autoAddLeadingZero?: boolean;
+    maxLength?: number;
+    isAllowed?: (rawValue: string) => boolean;
     rawValueMode?: boolean;
     onChange?: (value: string) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numora",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Framework-agnostic numeric input library for DeFi and financial apps",
   "homepage": "https://numora.xyz/",
   "main": "dist/index.js",