numora 2.0.4 → 2.0.5

package/dist/NumoraInput.d.ts

@@ -0,0 +1,67 @@
+import { FormatOn, ThousandStyle } from './types';
+export interface NumoraInputOptions extends Partial<Omit<HTMLInputElement, 'value' | 'defaultValue' | 'onchange'>> {
+    formatOn?: FormatOn;
+    thousandSeparator?: string;
+    thousandStyle?: ThousandStyle;
+    decimalSeparator?: string;
+    decimalMaxLength?: number;
+    decimalMinLength?: number;
+    enableCompactNotation?: boolean;
+    enableNegative?: boolean;
+    enableLeadingZeros?: boolean;
+    rawValueMode?: boolean;
+    onChange?: (value: string) => void;
+    value?: string;
+    defaultValue?: string;
+}
+export declare class NumoraInput {
+    private element;
+    private options;
+    private resolvedOptions;
+    private rawValue;
+    private caretPositionBeforeChange?;
+    constructor(container: HTMLElement, { decimalMaxLength, decimalMinLength, formatOn, thousandSeparator, thousandStyle, decimalSeparator, enableCompactNotation, enableNegative, enableLeadingZeros, rawValueMode, onChange, ...rest }: NumoraInputOptions);
+    private createInputElement;
+    private setupEventListeners;
+    private getResolvedOptions;
+    private buildFormattingOptions;
+    private handleValueChange;
+    private formatValueForDisplay;
+    private handleChange;
+    private handleKeyDown;
+    private handlePaste;
+    private handleFocus;
+    private handleBlur;
+    getValue(): string;
+    setValue(value: string): void;
+    disable(): void;
+    enable(): void;
+    addEventListener(event: string, callback: EventListenerOrEventListenerObject): void;
+    removeEventListener(event: string, callback: EventListenerOrEventListenerObject): void;
+    /**
+     * Returns the underlying HTMLInputElement for direct access.
+     * This allows users to interact with the input as a normal HTMLInputElement.
+     */
+    getElement(): HTMLInputElement;
+    /**
+     * Gets the current value of the input.
+     * In rawValueMode, returns the raw numeric value without formatting.
+     * Otherwise, returns the formatted display value.
+     */
+    get value(): string;
+    /**
+     * Sets the value of the input.
+     * In rawValueMode, the value will be formatted for display.
+     * Otherwise, sets the value directly.
+     */
+    set value(val: string);
+    /**
+     * Gets the value as a number, similar to HTMLInputElement.valueAsNumber.
+     * Returns NaN if the value cannot be converted to a number.
+     */
+    get valueAsNumber(): number;
+    /**
+     * Sets the value from a number, similar to HTMLInputElement.valueAsNumber.
+     */
+    set valueAsNumber(num: number);
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+import { FormatOn, ThousandStyle } from "./types";
+export declare const DEFAULT_DECIMAL_MAX_LENGTH = 2;
+export declare const DEFAULT_DECIMAL_MIN_LENGTH = 0;
+export declare const DEFAULT_FORMAT_ON = FormatOn.Blur;
+export declare const DEFAULT_THOUSAND_SEPARATOR = ",";
+export declare const DEFAULT_THOUSAND_STYLE = ThousandStyle.None;
+export declare const DEFAULT_DECIMAL_SEPARATOR = ".";
+export declare const DEFAULT_ENABLE_COMPACT_NOTATION = false;
+export declare const DEFAULT_ENABLE_NEGATIVE = false;
+export declare const DEFAULT_ENABLE_LEADING_ZEROS = false;
+export declare const DEFAULT_RAW_VALUE_MODE = false;

package/dist/features/compact-notation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Expands compact notation (k, m, b, M, T, Qa, Qi, Sx, Sp, O, N) to full numbers using string manipulation.
+ * Handles formats like: 1k, 1.5m, 2B, 1M, 2.5T, 3Qa (case-insensitive)
+ * Uses string arithmetic to avoid precision loss with large numbers.
+ *
+ * @param value - The string value that may contain compact notation
+ * @returns The expanded numeric string
+ *
+ * @example
+ * expandCompactNotation("1k")     // "1000"
+ * expandCompactNotation("1.5m")   // "1500000"
+ * expandCompactNotation("2B")     // "2000000000"
+ * expandCompactNotation("1M")     // "1000000"
+ * expandCompactNotation("2.5T")   // "2500000000000"
+ * expandCompactNotation("0.5k")   // "500"
+ */
+export declare function expandCompactNotation(value: string): string;

package/dist/features/decimals.d.ts

@@ -0,0 +1,52 @@
+import type { SeparatorOptions, Separators, FormattingOptions } from '@/types';
+/**
+ * Normalizes separator configuration with defaults.
+ *
+ * @param options - Separator configuration options
+ * @returns Normalized separator configuration
+ */
+export declare function getSeparators(options: SeparatorOptions | FormattingOptions | undefined): Separators;
+/**
+ * Converts comma or dot to the configured decimal separator when thousandStyle is None/undefined.
+ * This makes it easier for users to type decimal separators without knowing the exact separator character.
+ *
+ * @param e - The keyboard event
+ * @param inputElement - The input element
+ * @param formattingOptions - Optional formatting options
+ * @param separators - The separator configuration
+ * @returns True if the conversion was handled (event should be prevented), false otherwise
+ */
+export declare function convertCommaOrDotToDecimalSeparatorAndPreventMultimpleDecimalSeparators(e: KeyboardEvent, inputElement: HTMLInputElement, formattingOptions: FormattingOptions | undefined, decimalSeparator: string): boolean;
+/**
+ * Trims a string representation of a number to a maximum number of decimal places.
+ *
+ * @param value - The string to trim.
+ * @param decimalMaxLength - The maximum number of decimal places to allow.
+ * @param decimalSeparator - The decimal separator character to use.
+ * @returns The trimmed string.
+ */
+export declare const trimToDecimalMaxLength: (value: string, decimalMaxLength: number, decimalSeparator?: string) => string;
+/**
+ * Removes extra decimal separators, keeping only the first one.
+ *
+ * @param value - The string value
+ * @param decimalSeparator - The decimal separator character
+ * @returns The string with only the first decimal separator
+ */
+export declare const removeExtraDecimalSeparators: (value: string, decimalSeparator?: string) => string;
+/**
+ * Ensures a numeric string has at least the specified minimum number of decimal places.
+ * Pads with zeros if needed, but does not truncate if more decimals exist.
+ *
+ * @param value - The string value to ensure minimum decimals for
+ * @param minDecimals - The minimum number of decimal places (default: 0, meaning no minimum)
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The string with at least minDecimals decimal places
+ *
+ * @example
+ * ensureMinDecimals("1", 2, ".")      // "1.00"
+ * ensureMinDecimals("1.5", 2, ".")   // "1.50"
+ * ensureMinDecimals("1.123", 2, ".") // "1.123" (doesn't truncate)
+ * ensureMinDecimals("1", 0, ".")      // "1" (no minimum)
+ */
+export declare const ensureMinDecimals: (value: string, minDecimals?: number, decimalSeparator?: string) => string;

package/dist/features/formatting/caret-position-utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Utility functions for setting and managing caret position.
+ * Includes mobile browser workarounds and retry mechanisms.
+ */
+import type { FormattingOptions, CaretPositionInfo, Separators } from '@/types';
+/**
+ * Sets the caret position in an input element.
+ * Includes workaround for Chrome/Safari mobile browser bugs.
+ *
+ * @param el - The input element
+ * @param caretPos - The desired caret position
+ * @returns True if successful, false otherwise
+ */
+export declare function setCaretPosition(el: HTMLInputElement, caretPos: number): boolean;
+/**
+ * Sets caret position with retry mechanism for mobile browsers.
+ * Mobile Chrome sometimes resets the caret position after we set it,
+ * so we retry after a short timeout.
+ *
+ * @param el - The input element
+ * @param caretPos - The desired caret position
+ * @param currentValue - The current input value (for validation)
+ * @returns Timeout ID that can be cleared if needed
+ */
+export declare function setCaretPositionWithRetry(el: HTMLInputElement, caretPos: number, currentValue: string): ReturnType<typeof setTimeout> | null;
+/**
+ * Gets the current caret position from an input element.
+ * Uses max of selectionStart and selectionEnd to handle mobile browser quirks.
+ *
+ * @param el - The input element
+ * @returns The current caret position
+ */
+export declare function getInputCaretPosition(el: HTMLInputElement): number;
+/**
+ * Skips cursor over thousand separator when deleting/backspacing in 'change' mode.
+ * This prevents the cursor from stopping on the separator, making deletion smoother.
+ *
+ * @param e - The keyboard event
+ * @param inputElement - The input element
+ * @param formattingOptions - Optional formatting options
+ */
+export declare function skipOverThousandSeparatorOnDelete(e: KeyboardEvent, inputElement: HTMLInputElement, formattingOptions?: FormattingOptions): void;
+/**
+ * Updates cursor position after value changes, handling both formatted and unformatted values.
+ *
+ * @param target - The input element
+ * @param oldValue - The value before the change
+ * @param newValue - The value after the change
+ * @param oldCursorPosition - The cursor position before the change
+ * @param caretPositionBeforeChange - Optional caret position info from keydown handler
+ * @param separators - Separator configuration
+ * @param formattingOptions - Optional formatting options
+ */
+export declare function updateCursorPosition(target: HTMLInputElement, oldValue: string, newValue: string, oldCursorPosition: number, caretPositionBeforeChange: CaretPositionInfo | undefined, separators: Separators, formattingOptions?: FormattingOptions): void;

package/dist/features/formatting/change-detection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Utilities for detecting changes in input values.
+ * Used to distinguish between different editing operations (Delete vs Backspace, etc.)
+ */
+import type { ChangeRange } from './constants';
+/**
+ * Determines what changed based on caret positions before and after the change.
+ * This is used to distinguish Delete (cursor stays) vs Backspace (cursor moves left).
+ *
+ * @param caretBefore - The caret position info before the change
+ * @param inputValueBefore - The input value before the change
+ * @param inputValueAfter - The input value after the change
+ * @returns Change range information, or undefined if unable to determine
+ *
+ * @example
+ * // Delete key: cursor at 2, endOffset: 1
+ * findChangedRangeFromCaretPositions(
+ *   { selectionStart: 2, selectionEnd: 2, endOffset: 1 },
+ *   "1,234",
+ *   "1,34"
+ * ) // Returns: { start: 2, end: 3, deletedLength: 1, isDelete: true }
+ */
+export declare function findChangedRangeFromCaretPositions(caretBefore: {
+    selectionStart: number;
+    selectionEnd: number;
+    endOffset?: number;
+}, inputValueBefore: string, inputValueAfter: string): ChangeRange | undefined;
+/**
+ * Finds the change range by comparing old and new values.
+ * This is a fallback when caret position info is not available.
+ *
+ * @param oldValue - The value before the change
+ * @param newValue - The value after the change
+ * @returns Change range information, or undefined if unable to determine
+ *
+ * @example
+ * findChangeRange("1,234", "1,34")
+ * // Returns: { start: 2, end: 3, deletedLength: 1, isDelete: true }
+ */
+export declare function findChangeRange(oldValue: string, newValue: string): ChangeRange | undefined;

package/dist/features/formatting/character-equivalence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Character equivalence utilities for cursor position calculation.
+ */
+import type { IsCharacterEquivalent } from './cursor-position';
+/**
+ * Default character equivalence function.
+ * Only considers identical characters as equivalent.
+ */
+export declare const defaultIsCharacterEquivalent: IsCharacterEquivalent;

package/dist/features/formatting/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration for different grouping styles used in number formatting.
+ *
+ * - thousand: Groups by 3 digits (Western style) - 1,234,567
+ * - lakh: First group of 3, then groups of 2 (Indian style) - 12,34,567
+ * - wan: Groups by 4 digits (Chinese style) - 123,4567
+ */
+export declare const GROUPING_CONFIG: {
+    readonly thousand: {
+        readonly size: 3;
+    };
+    readonly lakh: {
+        readonly firstGroup: 3;
+        readonly restGroup: 2;
+    };
+    readonly wan: {
+        readonly size: 4;
+    };
+};
+/**
+ * Interface representing a change range in the input value.
+ * Used to distinguish between Delete and Backspace operations.
+ */
+export interface ChangeRange {
+    start: number;
+    end: number;
+    deletedLength: number;
+    isDelete?: boolean;
+}

package/dist/features/formatting/cursor-boundary.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Caret boundary system for defining editable positions in formatted numeric inputs.
+ * Prevents cursor from being placed in non-editable areas (separators, prefix, suffix).
+ */
+/**
+ * Determines which positions in a formatted value are editable.
+ * Returns a boolean array where true = editable position, false = non-editable.
+ *
+ * @param formattedValue - The formatted string value
+ * @param options - Configuration options
+ * @returns Boolean array indicating editable positions (length = formattedValue.length + 1)
+ *
+ * @example
+ * getCaretBoundary("1,234.56", { thousandSeparator: ",", decimalSeparator: "." })
+ * // Returns: [true, true, false, true, true, true, false, true, true, ...]
+ * //          (editable at positions 0,1,3,4,5,7,8,...)
+ */
+export declare function getCaretBoundary(formattedValue: string, options?: {
+    thousandSeparator?: string;
+    decimalSeparator?: string;
+    prefix?: string;
+    suffix?: string;
+}): boolean[];
+/**
+ * Corrects caret position to be within editable boundaries.
+ * Moves cursor to nearest editable position if current position is non-editable.
+ *
+ * @param value - The formatted string value
+ * @param caretPos - The current caret position
+ * @param boundary - The boundary array from getCaretBoundary()
+ * @param direction - Optional direction to search ('left' or 'right')
+ * @returns Corrected caret position within editable area
+ *
+ * @example
+ * const boundary = getCaretBoundary("1,234", { thousandSeparator: "," });
+ * getCaretPosInBoundary("1,234", 1, boundary, 'right')
+ * // Returns: 2 (moves from separator position to next digit)
+ */
+export declare function getCaretPosInBoundary(value: string, caretPos: number, boundary: boolean[], direction?: 'left' | 'right'): number;

package/dist/features/formatting/cursor-position.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Advanced cursor position calculation for formatted numeric inputs.
+ * Handles cursor preservation during formatting changes, insertion, and deletion operations.
+ */
+import type { ChangeRange } from './constants';
+import { ThousandStyle } from '@/types';
+/**
+ * Type for character equivalence checking.
+ * Returns true if two characters should be considered equivalent for cursor mapping.
+ */
+export type IsCharacterEquivalent = (char1: string, char2: string, context: {
+    oldValue: string;
+    newValue: string;
+    typedRange?: ChangeRange;
+    oldIndex: number;
+    newIndex: number;
+}) => boolean;
+/**
+ * Options for cursor position calculation.
+ */
+export interface CursorPositionOptions {
+    thousandSeparator?: string;
+    decimalSeparator?: string;
+    isCharacterEquivalent?: IsCharacterEquivalent;
+    boundary?: boolean[];
+}
+/**
+ * Calculates the new cursor position after formatting is applied.
+ * Uses digit index mapping to preserve cursor position relative to actual digits,
+ * handling insertion and deletion differently.
+ *
+ * Supports character equivalence for cases where characters are transformed
+ * (e.g., allowed decimal separators normalized to canonical separator).
+ *
+ * @param oldFormattedValue - The formatted value before the change
+ * @param newFormattedValue - The formatted value after formatting
+ * @param oldCursorPosition - The cursor position in the old formatted value
+ * @param separator - The thousand separator character used in formatting
+ * @param _groupStyle - The grouping style used (unused but kept for API compatibility)
+ * @param changeRange - Optional change range info to distinguish Delete vs Backspace
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @param options - Additional options for cursor calculation
+ * @returns The new cursor position in the new formatted value
+ *
+ * @example
+ * // Typing that adds a comma
+ * calculateCursorPositionAfterFormatting("100", "1,000", 3, ",")
+ * // Returns: 5 (cursor after last zero)
+ */
+export declare function calculateCursorPositionAfterFormatting(oldFormattedValue: string, newFormattedValue: string, oldCursorPosition: number, separator: string, _groupStyle: ThousandStyle, changeRange?: ChangeRange, decimalSeparator?: string, options?: CursorPositionOptions): number;

package/dist/features/formatting/digit-counting.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Utilities for counting and locating meaningful digits in formatted numbers.
+ * "Meaningful digits" are actual numeric digits, excluding separators and decimal points.
+ */
+/**
+ * Counts meaningful digits (non-separator, non-decimal) before a position.
+ * This is the core digit counting logic used throughout cursor positioning.
+ *
+ * @param value - The formatted string value
+ * @param position - The position to count up to
+ * @param separator - The thousand separator character
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The count of meaningful digits before the position
+ *
+ * @example
+ * countMeaningfulDigitsBeforePosition("1,234", 3, ",") // Returns: 2 (digits "1" and "2")
+ * countMeaningfulDigitsBeforePosition("1,234.56", 8, ",") // Returns: 6
+ * countMeaningfulDigitsBeforePosition("1.234,56", 8, ".", ",") // Returns: 6
+ */
+export declare function countMeaningfulDigitsBeforePosition(value: string, position: number, separator: string, decimalSeparator?: string): number;
+/**
+ * Finds the position in the string for a specific digit index.
+ * Returns the position AFTER the digit at targetDigitIndex.
+ *
+ * @param value - The formatted string value
+ * @param targetDigitIndex - The zero-based index of the target digit
+ * @param separator - The thousand separator character
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The position after the target digit
+ *
+ * @example
+ * findPositionForDigitIndex("1,234", 2, ",") // Returns: 4 (after digit "3")
+ */
+export declare function findPositionForDigitIndex(value: string, targetDigitIndex: number, separator: string, decimalSeparator?: string): number;
+/**
+ * Finds the position in the string where the digit count equals targetDigitCount.
+ * Returns the position after reaching the target count.
+ *
+ * @param value - The formatted string value
+ * @param targetDigitCount - The target number of digits
+ * @param separator - The thousand separator character
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The position where digit count equals target
+ *
+ * @example
+ * findPositionWithMeaningfulDigitCount("1,234", 3, ",") // Returns: 5 (after "2,3")
+ */
+export declare function findPositionWithMeaningfulDigitCount(value: string, targetDigitCount: number, separator: string, decimalSeparator?: string): number;
+/**
+ * Checks if a position in the string is on a separator character.
+ *
+ * @param value - The formatted string value
+ * @param position - The position to check
+ * @param separator - The thousand separator character
+ * @returns True if the position is on a separator character
+ *
+ * @example
+ * isPositionOnSeparator("1,234", 1, ",") // Returns: true
+ * isPositionOnSeparator("1,234", 2, ",") // Returns: false
+ */
+export declare function isPositionOnSeparator(value: string, position: number, separator: string): boolean;

package/dist/features/formatting/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Numora Formatting Module
+ *
+ * Provides comprehensive number formatting with thousand separators and
+ * sophisticated cursor position preservation for numeric input fields.
+ *
+ * @module formatting
+ */
+export type { ChangeRange } from './constants';
+export { GROUPING_CONFIG } from './constants';
+export { formatWithSeparators, formatNumoraInput } from './thousand-grouping';
+export { calculateCursorPositionAfterFormatting, type CursorPositionOptions, type IsCharacterEquivalent, } from './cursor-position';
+export { findChangedRangeFromCaretPositions, findChangeRange } from './change-detection';
+export { getCaretBoundary, getCaretPosInBoundary } from './cursor-boundary';
+export { setCaretPosition, setCaretPositionWithRetry, getInputCaretPosition, updateCursorPosition, skipOverThousandSeparatorOnDelete } from './caret-position-utils';
+export { countMeaningfulDigitsBeforePosition, findPositionForDigitIndex, findPositionWithMeaningfulDigitCount, isPositionOnSeparator, } from './digit-counting';
+export { formatPercent, formatLargePercent } from './percent';
+export { condenseDecimalZeros } from './subscript-notation';
+export { formatLargeNumber, type FormatLargeNumberOptions } from './large-number';

package/dist/features/formatting/large-number.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Large number formatting utilities for displaying numbers with scale notation (k, M, T, etc.).
+ * These are display-only utilities, not for input formatting.
+ */
+import { ThousandStyle } from '@/types';
+export interface FormatLargeNumberOptions {
+    /** Minimum scale threshold - only apply scale notation above this (default: 0, meaning always apply if applicable) */
+    minScale?: number;
+    /** Under what value should decimals be shown (default: 1000) */
+    decimalsUnder?: number;
+    /** Maximum decimal places to show (default: 2) */
+    decimals?: number;
+    /** Minimum decimal places to show (default: 0) */
+    decimalsMin?: number;
+    /** Show minimum decimals even when value is 0 (default: false) */
+    decimalsMinAppliesToZero?: boolean;
+    /** Placeholder for very large numbers that exceed our scale notation (default: '🔥') */
+    veryLargePlaceholder?: string;
+    /** Decimal separator (default: '.') */
+    decimalSeparator?: string;
+    /** Thousand separator for formatting (optional) */
+    thousandSeparator?: string;
+    /** Thousand grouping style (default: None) */
+    thousandStyle?: ThousandStyle;
+}
+/**
+ * Formats a large number with scale notation (k, M, T, etc.) for display.
+ *
+ * @param value - The numeric string value to format
+ * @param options - Optional formatting options
+ * @returns The formatted string with scale suffix if applicable
+ *
+ * @example
+ * formatLargeNumber("123")        // "123"
+ * formatLargeNumber("1234")        // "1.23k"
+ * formatLargeNumber("1234567")    // "1.23M"
+ * formatLargeNumber("0")          // "0"
+ */
+export declare function formatLargeNumber(value: string, options?: FormatLargeNumberOptions): string;

package/dist/features/formatting/percent.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Percent formatting utilities for displaying numeric values as percentages.
+ * All functions use string arithmetic to avoid precision loss.
+ */
+import { ThousandStyle } from '@/types';
+/**
+ * Formats a decimal value as a percentage string.
+ * Input is expected as a decimal (e.g., 0.01 represents 1%).
+ *
+ * @param value - The numeric string value (as decimal, e.g., "0.01" for 1%)
+ * @param decimals - Number of decimal places to show (default: 2)
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @param thousandSeparator - Optional thousand separator for large percentages
+ * @param thousandStyle - Optional thousand grouping style
+ * @returns The formatted percentage string (e.g., "1.00%")
+ *
+ * @example
+ * formatPercent("0.01", 2)        // "1.00%"
+ * formatPercent("0.1234", 2)      // "12.34%"
+ * formatPercent("1", 0)           // "100%"
+ * formatPercent("0", 2)            // "0%"
+ */
+export declare function formatPercent(value: string, decimals?: number, decimalSeparator?: string, thousandSeparator?: string, thousandStyle?: ThousandStyle): string;
+/**
+ * Formats a large percentage value with scale notation (k, M, T, etc.) for very large percentages.
+ * Input is expected as a decimal (e.g., 0.01 represents 1%).
+ *
+ * @param value - The numeric string value (as decimal, e.g., "0.01" for 1%)
+ * @param decimals - Number of decimal places to show for values under threshold (default: 2)
+ * @param options - Optional formatting options
+ * @returns The formatted percentage string with scale suffix if needed (e.g., "1.23M%")
+ *
+ * @example
+ * formatLargePercent("0.01", 2)           // "1.00%"
+ * formatLargePercent("1000", 2)           // "100000%"
+ * formatLargePercent("1000000", 2)       // "100M%"
+ */
+export declare function formatLargePercent(value: string | null | undefined, decimals?: number, options?: {
+    missingPlaceholder?: string;
+    veryLargePlaceholder?: string;
+    decimalsUnder?: number;
+    decimalSeparator?: string;
+    thousandSeparator?: string;
+    thousandStyle?: ThousandStyle;
+}): string;

package/dist/features/formatting/subscript-notation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Subscript notation utilities for condensing leading decimal zeros.
+ * Converts very small numbers like 0.000001 to 0₆1 for better readability.
+ */
+/**
+ * Condenses leading decimal zeros in a numeric string to subscript notation.
+ * For example: 0.000001 → 0₆1 (meaning 6 leading zeros)
+ *
+ * @param value - The numeric string value to condense
+ * @param maxDecimalDigits - Maximum number of decimal digits to show after condensation
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The condensed string with subscript notation for leading zeros
+ *
+ * @example
+ * condenseDecimalZeros("0.000001", 8)     // "0₆1"
+ * condenseDecimalZeros("0.000123", 8)     // "0₃123"
+ * condenseDecimalZeros("1.000001", 8)     // "1.000001" (no leading zeros to condense)
+ * condenseDecimalZeros("0.123", 8)        // "0.123" (not enough zeros to condense)
+ */
+export declare function condenseDecimalZeros(value: string, maxDecimalDigits?: number, decimalSeparator?: string): string;

package/dist/features/formatting/thousand-grouping.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Number formatting utilities with thousand separators.
+ * Supports multiple grouping styles: thousand (Western), lakh (Indian), wan (Chinese)
+ */
+import type { FormattingOptions, Separators } from '@/types';
+import { ThousandStyle } from '@/types';
+/**
+ * Formats a numeric string with thousand separators based on the specified group style.
+ *
+ * @param value - The numeric string to format (e.g., "1234567")
+ * @param separator - The separator character to use (e.g., ",")
+ * @param groupStyle - The grouping style: 'none' (no separators), 'thousand' (1,234,567), 'lakh' (12,34,567), or 'wan' (123,4567)
+ * @param enableLeadingZeros - Whether to preserve leading zeros
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The formatted string with separators
+ *
+ * @example
+ * formatWithSeparators("1234567", ",", "thousand") // "1,234,567"
+ * formatWithSeparators("1234567", ",", "lakh")     // "12,34,567"
+ * formatWithSeparators("1234567", ",", "wan")      // "123,4567"
+ * formatWithSeparators("1234.56", ",", "thousand", false, '.') // "1,234.56"
+ * formatWithSeparators("1234,56", ",", "thousand", false, ',') // "1,234,56"
+ */
+export declare function formatWithSeparators(value: string, separator: string, groupStyle: ThousandStyle, enableLeadingZeros?: boolean, decimalSeparator?: string): string;
+/**
+ * Applies formatting to the input element if formatting is enabled.
+ *
+ * @param target - The input element
+ * @param sanitizedAndTrimmedValue - The sanitized value to format
+ * @param formattingOptions - Optional formatting options
+ * @param separators - Optional separator configuration
+ * @returns The formatted value, or the original value if formatting is not needed
+ */
+export declare function formatNumoraInput(sanitizedAndTrimmedValue: string, formattingOptions?: FormattingOptions, separators?: Separators): string;

package/dist/features/leading-zeros.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Removes leading zeros from a numeric string while preserving the value "0" itself.
+ * Only removes leading zeros from the integer part, not from decimal values like "0.5".
+ *
+ * @param value - The numeric string to process
+ * @returns The string with leading zeros removed
+ *
+ * @example
+ * removeLeadingZeros("007")     // "7"
+ * removeLeadingZeros("0001")    // "1"
+ * removeLeadingZeros("0")       // "0"
+ * removeLeadingZeros("0.5")     // "0.5"
+ * removeLeadingZeros("-007")    // "-7"
+ * removeLeadingZeros("123")     // "123"
+ * removeLeadingZeros("00.5")    // "0.5"
+ * removeLeadingZeros("-00.5")   // "-0.5"
+ */
+export declare function removeLeadingZeros(value: string): string;

package/dist/features/mobile-keyboard-filtering.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Mobile keyboard artifact filtering utilities.
+ * Handles filtering of unwanted characters that mobile keyboards insert,
+ * such as non-breaking spaces, Unicode whitespace variants, and IME formatting characters.
+ */
+/**
+ * Filters mobile keyboard artifacts from input value.
+ * Removes non-breaking spaces, zero-width spaces, and other Unicode whitespace variants
+ * that mobile keyboards may insert.
+ *
+ * @param value - Input value to filter
+ * @returns Filtered value with mobile keyboard artifacts removed
+ *
+ * @example
+ * filterMobileKeyboardArtifacts("1\u00A0234") // Returns: "1234" (removes non-breaking space)
+ * filterMobileKeyboardArtifacts("1 234") // Returns: "1234" (removes regular space)
+ */
+export declare function filterMobileKeyboardArtifacts(value: string): string;

package/dist/features/non-numeric-characters.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Removes non-numeric characters from a string, preserving the decimal separator.
+ *
+ * @param value - The string to sanitize
+ * @param enableNegative - Whether to allow negative sign
+ * @param decimalSeparator - The decimal separator character (default: '.')
+ * @returns The sanitized string with only numbers and the decimal separator
+ */
+export declare const removeNonNumericCharacters: (value: string, enableNegative?: boolean, decimalSeparator?: string) => string;

package/dist/features/sanitization.d.ts

@@ -0,0 +1,41 @@
+import type { FormattingOptions, Separators } from '@/types';
+/**
+ * Removes all occurrences of thousand separator from a string.
+ * Escapes special regex characters in the separator to ensure safe pattern matching.
+ *
+ * @param value - The string to remove separators from
+ * @param thousandSeparator - The thousand separator character to remove
+ * @returns The string with all thousand separators removed
+ */
+export declare function removeThousandSeparators(value: string, thousandSeparator: string): string;
+export interface SanitizationOptions {
+    enableCompactNotation?: boolean;
+    enableNegative?: boolean;
+    enableLeadingZeros?: boolean;
+    decimalSeparator?: string;
+    thousandSeparator?: string;
+}
+/**
+ * Sanitizes numeric input by:
+ * 0. Filter mobile keyboard artifacts (non-breaking spaces, Unicode whitespace)
+ * 1. Remove thousand separators (formatting, not data)
+ * 2. (Optional) Expanding compact notation (e.g., 1k → 1000)
+ * 3. Expanding scientific notation (e.g., 1.5e-5 → 0.000015)
+ * 4. Removing non-numeric characters
+ * 5. Removing extra decimal points
+ * 6. (Optional) Removing leading zeros
+ *
+ * @param value - The string value to sanitize
+ * @param options - Optional sanitization configuration
+ * @returns The sanitized numeric string
+ */
+export declare const sanitizeNumoraInput: (value: string, options?: SanitizationOptions) => string;
+/**
+ * Builds sanitization options from formatting options and separators.
+ *
+ * @param formattingOptions - Optional formatting options
+ * @param separators - Separator configuration
+ * @param shouldRemoveThousandSeparators - Whether to remove thousand separators
+ * @returns Sanitization options
+ */
+export declare function buildSanitizationOptions(formattingOptions: FormattingOptions | undefined, separators: Separators, shouldRemoveThousandSeparators: boolean): SanitizationOptions;

package/dist/features/scientific-notation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Expands scientific notation to decimal notation using string manipulation only.
+ * Handles formats like: 1.5e-7, 2e+5, 1.23e-4, etc.
+ * Finds and expands scientific notation anywhere in the string.
+ *
+ * @param value - The string value that may contain scientific notation
+ * @returns The expanded decimal string, or original value if not scientific notation
+ */
+export declare function expandScientificNotation(value: string): string;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './NumoraInput';
+export { ThousandStyle, FormatOn } from './types';
+export { handleOnChangeNumoraInput, handleOnPasteNumoraInput, handleOnKeyDownNumoraInput, } from './utils/event-handlers';
+export { formatValue, processAndFormatValue, } from './utils/format-utils';
+export type { FormattingOptions, CaretPositionInfo } from './types';

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export declare enum FormatOn {
+    Blur = "blur",
+    Change = "change"
+}
+export declare enum ThousandStyle {
+    None = "none",
+    Thousand = "thousand",
+    Lakh = "lakh",
+    Wan = "wan"
+}
+export interface FormattingOptions {
+    formatOn?: FormatOn;
+    thousandSeparator?: string;
+    ThousandStyle?: ThousandStyle;
+    enableCompactNotation?: boolean;
+    enableNegative?: boolean;
+    enableLeadingZeros?: boolean;
+    decimalSeparator?: string;
+    decimalMinLength?: number;
+    rawValueMode?: boolean;
+}
+export interface CaretPositionInfo {
+    selectionStart?: number;
+    selectionEnd?: number;
+    endOffset?: number;
+}
+export interface SeparatorOptions {
+    decimalSeparator?: string;
+    thousandSeparator?: string;
+}
+export interface Separators {
+    decimalSeparator: string;
+    thousandSeparator?: string;
+}

package/dist/utils/escape-reg-exp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utility functions used across multiple features.
+ */
+/**
+ * Escapes special regex characters in a string.
+ * This is used when building regex patterns from user-provided separator characters.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string safe for use in regex patterns
+ *
+ * @example
+ * escapeRegExp(".") // Returns: "\\."
+ * escapeRegExp("$") // Returns: "\\$"
+ * escapeRegExp("1,234") // Returns: "1\\,234"
+ */
+export declare function escapeRegExp(str: string): string;

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

@@ -0,0 +1,31 @@
+import { type FormattingOptions, type CaretPositionInfo } from '@/types';
+/**
+ * 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
+ */
+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'.
+ *
+ * @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
+ */
+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): {
+    formatted: string;
+    raw: string;
+};

package/dist/utils/format-utils.d.ts

@@ -0,0 +1,28 @@
+import { type FormattingOptions } from '@/types';
+/**
+ * Processes and formats a numeric input value by sanitizing, trimming decimals, and applying formatting.
+ * This is a pure function that doesn't require DOM elements or events.
+ *
+ * @param rawValue - The raw input value to process
+ * @param decimalMaxLength - Maximum number of decimal places allowed
+ * @param formattingOptions - Optional formatting options
+ * @param shouldRemoveThousandSeparators - Whether to remove thousand separators during sanitization (default: determined by formatOn)
+ * @returns Object with formatted value and raw value (raw value is the value before formatting)
+ */
+export declare function processAndFormatValue(rawValue: string, decimalMaxLength: number, formattingOptions?: FormattingOptions, shouldRemoveThousandSeparators?: boolean): {
+    formatted: string;
+    raw: string;
+};
+/**
+ * Formats a value for display using the provided formatting options.
+ * This is a pure function that can be used without DOM events.
+ *
+ * @param value - The value to format
+ * @param decimalMaxLength - Maximum number of decimal places allowed
+ * @param formattingOptions - Optional formatting options
+ * @returns Object with formatted value and raw value
+ */
+export declare function formatValue(value: string, decimalMaxLength: number, formattingOptions?: FormattingOptions): {
+    formatted: string;
+    raw: string;
+};

package/dist/utils/input-pattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Builds an input pattern that allows optional negative sign and a single custom decimal separator.
+ * The separator is escaped so any character can be safely used.
+ */
+export declare function getNumoraPattern(decimalSeparator: string, enableNegative: boolean): string;

package/dist/validation.d.ts

@@ -0,0 +1,20 @@
+import { FormatOn } from './types';
+import { ThousandStyle } from './types';
+export interface NumoraInputValidationOptions {
+    decimalMaxLength?: number;
+    decimalMinLength?: number;
+    formatOn?: FormatOn;
+    thousandSeparator?: string;
+    thousandStyle?: ThousandStyle;
+    decimalSeparator?: string;
+    enableCompactNotation?: boolean;
+    enableNegative?: boolean;
+    enableLeadingZeros?: boolean;
+    rawValueMode?: boolean;
+    onChange?: (value: string) => void;
+}
+/**
+ * Validates all NumoraInput constructor parameters.
+ * Throws descriptive errors for invalid values.
+ */
+export declare function validateNumoraInputOptions(options: NumoraInputValidationOptions): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numora",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Precision-first numeric input library for DeFi and financial applications",
   "homepage": "https://numora.xyz/",
   "main": "dist/index.js",
@@ -61,7 +61,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "vite build && tsc --emitDeclarationOnly",
+    "build": "vite build & tsc --emitDeclarationOnly",
     "test": "vitest run",
     "dev": "vite build --watch"
   }