numora 1.0.4 → 2.0.1

package/README.md

@@ -1,6 +1,7 @@
 # numora
 
 [![npm version](https://img.shields.io/npm/v/numora.svg)](https://www.npmjs.com/package/numora)
+[![npm downloads](https://img.shields.io/npm/dm/numora.svg)](https://www.npmjs.com/package/numora)
 
 A lightweight, framework-agnostic numeric input library for handling currency and decimal inputs in **financial/DeFi** applications. Built with TypeScript and designed for modern web applications with:
 
@@ -11,63 +12,272 @@ A lightweight, framework-agnostic numeric input library for handling currency an
 
 ## Demo
 
-Check out the [live demo](https://numora.netlify.app/) to see Numora in action.
+Check out the [live demo](https://numora.xyz/) to see Numora in action.
 
 ## Features
 
-- Validates and sanitizes numeric input
-- Limits decimal places
-- Handles paste events
-- Converts commas to dots
-- Prevents multiple decimal points
-- Customizable with various options
-- Framework-agnostic core with adapters for popular frameworks
+| Feature | Description |
+|---------|-------------|
+| **⭐️ Zero Dependencies** | No external dependencies, minimal bundle size |
+| **⭐️ Framework Agnostic** | Works with any framework or vanilla JavaScript |
+| **Decimal Precision Control** | Configure minimum and maximum decimal places (`decimalMinLength`, `decimalMaxLength`) |
+| **Minimum Decimal Places** | Automatically pad values with zeros to ensure minimum decimal places (e.g., `"1"` with `decimalMinLength: 2` becomes `"1.00"`) |
+| **Thousand Separators** | Customizable thousand separators with multiple grouping styles (`Thousand`, `Lakh`, `Wan`, `None`) |
+| **Custom Decimal Separator** | Support for different decimal separators (e.g., `.` or `,`) |
+| **Format on Blur/Change** | Choose when to apply formatting: `on blur (clean editing)` or `on change (real-time)` |
+| **Compact Notation Expansion** | When enabled, expands compact notation during paste/setValue (e.g., `"1k"` → `"1000"`, `"1.5m"` → `"1500000"`, `"2B"` → `"2000000000"`) |
+| **Scientific Notation Expansion** | Always automatically expands scientific notation (e.g., `"1.5e-7"` → `"0.00000015"`, `"2e+5"` → `"200000"`) |
+| **Negative Number Support** | Optional support for negative numbers with `enableNegative` |
+| **Leading Zeros Support** | Control leading zero behavior with `enableLeadingZeros` |
+| **Raw Value Mode** | Get unformatted numeric values while displaying formatted values |
+| **Paste Event Handling** | Intelligent paste handling with automatic sanitization, formatting, and cursor positioning |
+| **Cursor Position Preservation** | Smart cursor positioning that works with thousand separators, even during formatting |
+| **Thousand Separator Skipping** | On delete/backspace, cursor automatically skips over thousand separators for better UX |
+| **Mobile Keyboard Optimization** | Automatic `inputmode="decimal"` for mobile numeric keyboards |
+| **Mobile Keyboard Filtering** | Automatically filters non-breaking spaces and Unicode whitespace artifacts from mobile keyboards |
+| **Non-numeric Character Filtering** | Automatic removal of invalid characters |
+| **Comma/Dot Conversion** | When `thousandStyle` is `None`, typing comma or dot automatically converts to the configured `decimalSeparator` |
+| **Character Equivalence** | Automatic conversion of commas to dots (or custom decimal separator) for easier input |
+| **Sanitization** | Comprehensive input sanitization for security and data integrity |
+| **TypeScript Support** | Full TypeScript definitions included |
+
+## Display Formatting Utilities
+
+Numora also exports utility functions for formatting numbers for display (outside of the input component):
+
+| Utility | Description | Example |
+|---------|-------------|---------|
+| `formatPercent` | Format decimal values as percentages | `formatPercent("0.01", 2)` → `"1.00%"` |
+| `formatLargePercent` | Format large percentages with scale notation (k, M, T, etc.) | `formatLargePercent("1000", 2)` → `"100000%"` |
+| `formatLargeNumber` | Format large numbers with scale notation | `formatLargeNumber("1234")` → `"1.23k"` |
+| `condenseDecimalZeros` | Condense leading decimal zeros to subscript notation | `condenseDecimalZeros("0.000001", 8)` → `"0₆1"` |
+
+These utilities use string arithmetic to avoid floating-point precision issues.
+
+## 📊 Comparison
+
+| Feature | Numora | react-number-format | Native Number Input |
+|---------|--------|---------------------|---------------------|
+| **Framework Support** | ✅ All frameworks | ❌ React only | ✅ All frameworks |
+| **Dependencies** | ✅ Zero | ⚠️ React required | ✅ Zero |
+| **Raw Value Mode** | ✅ Yes | ⚠️ Limited | ❌ No |
+| **Comma/Dot Conversion** | ✅ Yes | ⚠️ Limited | ❌ No |
+| **Scientific Notation** | ✅ Auto-expand | ❌ No | ❌ No |
+| **Display Formatting Utils** | ✅ Yes | ❌ No | ❌ No |
+| **Compact Notation** | ✅ Auto-expand | ❌ No | ❌ No |
+| **Mobile Support** | ✅ Yes | ✅ Yes | ⚠️ Limited |
+| **Decimal Precision Control** | ✅ Yes | ✅ Yes | ❌ Limited |
+| **Thousand Separators** | ✅ Customizable | ✅ Yes | ❌ No |
+| **Custom Decimal Separator** | ✅ Yes | ✅ Yes | ❌ No (always `.`) |
+| **Formatting Options** | ✅ Blur/Change modes | ✅ Multiple modes | ❌ No |
+| **Cursor Preservation** | ✅ Advanced | ✅ Basic | ❌ N/A |
+| **TypeScript Support** | ✅ Yes | ✅ Yes | ⚠️ Partial |
+| **Paste Handling** | ✅ Intelligent | ✅ Yes | ⚠️ Basic |
+| **Grouping Styles** | ✅ Thousand/Lakh/Wan | ✅ Thousand/Lakh/Wan | ❌ No |
+| **Leading Zeros Control** | ✅ Yes | ✅ Yes | ❌ No |
 
 ## Installation
 
 ```bash
 npm install numora
 # or
-yarn add numora
+bun add numora
 # or
 pnpm add numora
 ```
 
 ## Usage
 
+### Basic Example
+
 ```typescript
-import { NumericInput } from 'numora';
+import { NumoraInput } from 'numora';
 
 // Get the container element where you want to mount the input
 const container = document.querySelector('#my-input-container');
 
-// Create a new NumericInput instance
-const numericInput = new NumericInput(container, {
-  maxDecimals: 2,
+// Create a new NumoraInput instance
+const numoraInput = new NumoraInput(container, {
+  decimalMaxLength: 2,
   onChange: (value) => {
     console.log('Value changed:', value);
-    // Do something with the value
   },
-  // ... all other input properties you want
+});
+```
+
+### Advanced Example
+
+```typescript
+import { NumoraInput, FormatOn, ThousandStyle } from 'numora';
+
+const container = document.querySelector('#my-input-container');
+
+const numoraInput = new NumoraInput(container, {
+  // Decimal options
+  decimalMaxLength: 18,
+  decimalMinLength: 2, // Pads with zeros: "1" becomes "1.00"
+  decimalSeparator: '.',
+
+  // Thousand separator options
+  thousandSeparator: ',',
+  thousandStyle: ThousandStyle.Thousand,
+  formatOn: FormatOn.Change, // or FormatOn.Blur
+
+  // Additional features
+  enableCompactNotation: true, // Expands "1k" → "1000" on paste/setValue
+  enableNegative: false,
+  enableLeadingZeros: false,
+  rawValueMode: true, // Get unformatted values in onChange
+
+  // Standard input properties
+  placeholder: 'Enter amount',
+  className: 'numora-input',
+
+  // Event handler
+  onChange: (value) => {
+    console.log('Raw value:', value); // Unformatted if rawValueMode is true
+    console.log('Display value:', numoraInput.value); // Formatted display value
+    console.log('As number:', numoraInput.valueAsNumber); // Parsed as number
+  },
+});
+```
+
+### Compact Notation Example
+
+```typescript
+import { NumoraInput } from 'numora';
+
+const container = document.querySelector('#my-input-container');
+
+const numoraInput = new NumoraInput(container, {
+  enableCompactNotation: true,
+  onChange: (value) => {
+    console.log('Value:', value);
+  },
+});
+
+// When user pastes "1.5k" or you call setValue("1.5k")
+// It automatically expands to "1500"
+numoraInput.setValue('1.5k'); // Display: "1,500" (if thousand separator enabled)
+```
+
+### Scientific Notation Example
+
+```typescript
+import { NumoraInput } from 'numora';
+
+const container = document.querySelector('#my-input-container');
+
+const numoraInput = new NumoraInput(container, {
+  decimalMaxLength: 18,
+  onChange: (value) => {
+    console.log('Value:', value);
+  },
+});
+
+// Scientific notation is ALWAYS automatically expanded
+// User can paste "1.5e-7" and it becomes "0.00000015"
+// User can paste "2e+5" and it becomes "200000"
+```
+
+### Comma/Dot Conversion Example
+
+```typescript
+import { NumoraInput, ThousandStyle } from 'numora';
+
+const container = document.querySelector('#my-input-container');
+
+const numoraInput = new NumoraInput(container, {
+  decimalSeparator: ',', // European format
+  thousandStyle: ThousandStyle.None, // Required for comma/dot conversion
+  decimalMaxLength: 2,
+});
+
+// When thousandStyle is None:
+// - User types "." → automatically converted to ","
+// - User types "," → automatically converted to ","
+// This makes it easier for users without knowing the exact separator
+```
+
+### Using Display Formatting Utilities
+
+```typescript
+import { formatPercent, formatLargePercent, formatLargeNumber, condenseDecimalZeros } from 'numora';
+
+// Format as percentage
+const percent = formatPercent('0.01', 2); // "1.00%"
+const largePercent = formatLargePercent('1000', 2); // "100000%"
+
+// Format large numbers with scale notation
+const large = formatLargeNumber('1234567'); // "1.23M"
+const small = formatLargeNumber('1234'); // "1.23k"
+
+// Condense decimal zeros
+const condensed = condenseDecimalZeros('0.000001', 8); // "0₆1"
+const condensed2 = condenseDecimalZeros('0.000123', 8); // "0₃123"
+```
+
+### Programmatic Value Control
+
+```typescript
+// Get the current value
+const currentValue = numoraInput.getValue();
+// or
+const currentValue = numoraInput.value;
+
+// Set a new value
+numoraInput.setValue('1234.56');
+// or
+numoraInput.value = '1234.56';
+
+// Set from a number
+numoraInput.valueAsNumber = 1234.56;
+
+// Get as a number
+const numericValue = numoraInput.valueAsNumber;
+
+// Enable/disable the input
+numoraInput.disable();
+numoraInput.enable();
+
+// Access the underlying HTMLInputElement
+const inputElement = numoraInput.getElement();
+inputElement.addEventListener('focus', () => {
+  console.log('Input focused');
 });
 ```
 
 ## Options
 
-The NumericInput constructor accepts the following options:
+The NumoraInput constructor accepts the following options:
+
 | Option | Type | Default | Description |
-| --------------- | -------- | --------- | -------------------------------------------------------- |
-| maxDecimals | number | 2 | Maximum number of decimal places allowed |
-| onChange | function | undefined | Callback function that runs when the input value changes |
-| supports all input properties | - | - | - |
+|--------|------|---------|-------------|
+| `decimalMaxLength` | `number` | `2` | Maximum number of decimal places allowed |
+| `decimalMinLength` | `number` | `0` | Minimum number of decimal places (pads with zeros) |
+| `decimalSeparator` | `string` | `'.'` | Character used as decimal separator |
+| `thousandSeparator` | `string` | `','` | Character used as thousand separator (set to empty string to disable) |
+| `thousandStyle` | `ThousandStyle` | `ThousandStyle.None` | Grouping style: `Thousand`, `Lakh`, `Wan`, or `None` |
+| `formatOn` | `FormatOn` | `FormatOn.Blur` | When to apply formatting: `Blur` or `Change` |
+| `enableCompactNotation` | `boolean` | `false` | Enable expansion of compact notation (e.g., "1k" → "1000") on paste/setValue |
+| `enableNegative` | `boolean` | `false` | Allow negative numbers |
+| `enableLeadingZeros` | `boolean` | `false` | Allow leading zeros before decimal point |
+| `rawValueMode` | `boolean` | `false` | Return unformatted values in `onChange` callback |
+| `onChange` | `(value: string) => void` | `undefined` | Callback function that runs when the input value changes |
+| `value` | `string` | `undefined` | Initial value (controlled mode) |
+| `defaultValue` | `string` | `undefined` | Initial default value (uncontrolled mode) |
+
+All standard HTMLInputElement properties are also supported (e.g., `placeholder`, `className`, `disabled`, `id`, etc.).
+
+**Note:** Scientific notation expansion (e.g., `"1.5e-7"` → `"0.00000015"`) always happens automatically and is not configurable.
 
 ## Framework Adapters
 
 Numora is also available for popular frameworks:
 
-- React: `numora-react` (in progress)
-- Vue: `numora-vue` (in progress)
-- Svelte: `numora`
+- **React**: [`numora-react`](../react/README.md) - React component wrapper
+- **Vue**: Coming soon
+- **Svelte**: Use the core package directly
 
 ## License
 

package/dist/NumoraInput.d.ts

@@ -0,0 +1,72 @@
+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;
+    /**
+     * Extracts and stores the raw numeric value from a formatted value.
+     * Gets the raw value from the data attribute set by event handlers, or extracts it from formatted value.
+     */
+    private updateRawValue;
+    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;