numora 1.0.4 → 2.0.0

package/README.md

@@ -36,14 +36,14 @@ pnpm add numora
 ## Usage
 
 ```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
@@ -54,10 +54,10 @@ const numericInput = new NumericInput(container, {
 
 ## 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 |
+| decimalMaxLength | number | 2 | Maximum number of decimal places allowed |
 | onChange | function | undefined | Callback function that runs when the input value changes |
 | supports all input properties | - | - | - |
 

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;

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;