ngx-digits-only 1.0.0

package/types/ngx-digits-only.d.ts

@@ -0,0 +1,601 @@
+import * as i0 from '@angular/core';
+import { OnInit, OnChanges, ElementRef, Renderer2, SimpleChanges } from '@angular/core';
+import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors } from '@angular/forms';
+
+/**
+ * digits-only.directive.ts
+ *
+ * A self-contained Angular directive that replicates the key numeric features
+ * of ngx-mask without any external dependency.
+ *
+ * ─── Files in this module ─────────────────────────────────────────────────────
+ *
+ *   digits-only.directive.ts   ← you are here — the Angular directive
+ *   digits-only.regex.ts       ← every RegExp constant with detailed explanations
+ *   digits-only.module.ts       ← NgModule that declares and exports the directive
+ *   eastern-numerals.ts            ← standalone Arabic / Persian → Western digit converter
+ *
+ * ─── Features ─────────────────────────────────────────────────────────────────
+ *
+ *   [digitsOnly]              Selector — add to any <input> element
+ *   [decimalPlaces]           Number of decimal places allowed (default: 0 = integers)
+ *   [thousandSeparator]       Visual grouping character: ',' | '.' | ' ' | '_' | ''
+ *   [prefix]                  Visual prefix shown in input (e.g. '$') — stripped from model
+ *   [suffix]                  Visual suffix shown in input (e.g. '%') — stripped from model
+ *   [allowNegative]           Allow a leading minus sign (default: false)
+ *   [leadingZeros]            Preserve leading zeros like '007' (default: false)
+ *   [maxLength]               Maximum number of raw digits allowed
+ *   [min]                     Minimum numeric value (validation, number mode only)
+ *   [max]                     Maximum numeric value (validation, number mode only)
+ *   [outputType]              'number' (default) | 'string' — type emitted to the model
+ *   [pattern]                 Display-format mask: '0000 0000 0000 0000' or named alias
+ *   [convertEasternNumerals]  Convert Arabic/Persian digits to Western on input (default: true)
+ *
+ * ─── outputType ───────────────────────────────────────────────────────────────
+ *
+ *   'number' (default)
+ *     Model receives:  number | null
+ *     Use for:         prices, quantities, temperatures — values used in arithmetic
+ *     Note:            Leading zeros are lost (007 → 7); values beyond
+ *                      Number.MAX_SAFE_INTEGER may lose precision
+ *
+ *   'string'
+ *     Model receives:  string | null
+ *     Use for:         card numbers, phone numbers, postal codes, SSNs, OTPs —
+ *                      digit strings that are identifiers, not quantities
+ *     Note:            Leading zeros are always preserved; no precision limit
+ *
+ * ─── pattern ──────────────────────────────────────────────────────────────────
+ *
+ *   A mask string made of '0' (digit slot) and any other character (separator).
+ *   Separators are inserted in the display automatically but NEVER reach the model.
+ *   Setting a pattern forces outputType='string' and derives maxLength automatically.
+ *
+ *   Named aliases:
+ *     'card'       →  '0000 0000 0000 0000'   Visa / Mastercard (16 digits)
+ *
+ * ─── convertEasternNumerals ───────────────────────────────────────────────────
+ *
+ *   When true (default), Arabic-Indic (٠١٢٣٤٥٦٧٨٩) and Persian (۰۱۲۳۴۵۶۷۸۹)
+ *   digit characters are silently converted to their Western equivalents before
+ *   any processing.  This allows users on Arabic / Persian keyboards to type
+ *   naturally into any digitsOnly field.
+ *   Set to false only if you specifically need to block Eastern numerals.
+ *
+ * ─── Usage examples ───────────────────────────────────────────────────────────
+ *
+ *   <!-- Integer amount, $ prefix, comma thousands -->
+ *   <input digitsOnly thousandSeparator="," prefix="$" formControlName="salary" />
+ *
+ *   <!-- Decimal price, 2 places -->
+ *   <input digitsOnly [decimalPlaces]="2" thousandSeparator="," formControlName="price" />
+ *
+ *   <!-- Card number with automatic space grouping -->
+ *   <input digitsOnly pattern="card" formControlName="cardNumber" />
+ *
+ *   <!-- Custom pattern -->
+ *   <input digitsOnly pattern="000-00-0000" formControlName="ssn" />
+ *
+ *   <!-- Opt out of Eastern numeral conversion -->
+ *   <input digitsOnly [convertEasternNumerals]="false" formControlName="code" />
+ */
+
+type NamedPattern = 'card';
+declare class digitsOnlyDirective implements ControlValueAccessor, Validator, OnInit, OnChanges {
+    private el;
+    private renderer;
+    private document;
+    /** How many decimal places are allowed. 0 = integers only. Ignored when pattern is set. */
+    decimalPlaces: number;
+    /** Visual grouping character inserted between digit groups. Ignored when pattern is set. */
+    thousandSeparator: '' | ',' | '.' | ' ' | '_';
+    /** Visual text prepended to the displayed value (e.g. '$'). Never reaches the model. */
+    prefix: string;
+    /** Visual text appended to the displayed value (e.g. '%'). Never reaches the model. */
+    suffix: string;
+    /** When true, a leading minus '-' is allowed for negative numbers. */
+    allowNegative: boolean;
+    /** When true, leading zeros (e.g. '007') are preserved in the model value. */
+    leadingZeros: boolean;
+    /** Maximum number of raw digit characters the user may enter. */
+    maxLength: number | null;
+    /** Minimum allowed numeric value. Produces a 'min' validation error when violated. */
+    min: number | null;
+    /** Maximum allowed numeric value. Produces a 'max' validation error when violated. */
+    max: number | null;
+    /**
+     * Controls the JavaScript type emitted to the form model.
+     * 'number' (default) → number | null
+     * 'string'           → string | null
+     * Automatically overridden to 'string' when [pattern] is set.
+     */
+    outputType: 'number' | 'string';
+    /**
+     * When true (default), Arabic-Indic and Persian digit characters typed or
+     * pasted by the user are automatically converted to Western digits 0-9
+     * before any processing happens.
+     *
+     * Safe to leave enabled for all use cases — the conversion only touches
+     * characters in the Unicode ranges U+0660–U+0669 and U+06F0–U+06F9,
+     * which have zero overlap with any ASCII character.
+     */
+    convertEasternNumerals: boolean;
+    /**
+     * Display-format mask string or a named alias (see NamedPattern type).
+     *
+     * Typed as  NamedPattern | (string & {})  so that:
+     *   • Named aliases are autocompleted in IDEs and validated at compile time.
+     *   • Custom raw patterns like '000-0000' are still accepted without error.
+     *
+     * '0' = digit slot, any other char = literal separator auto-inserted in display.
+     * Setting this forces outputType='string' and derives maxLength from slot count.
+     *
+     * @example
+     *   pattern="card"           → '0000 0000 0000 0000'
+     *   pattern="00/00/0000"     → custom date pattern
+     */
+    set pattern(value: NamedPattern | (string & {}));
+    /** Full pattern string after named-alias resolution. Empty string = no pattern. */
+    private _resolvedPattern;
+    /**
+     * The canonical internal value: pure digits (and optional '.' and '-').
+     * No prefix, suffix, separators, or pattern characters ever live here.
+     * Every other method reads or writes this field.
+     */
+    private _rawValue;
+    private _onChange;
+    private _onTouched;
+    private _onValidatorChange;
+    /** True when a format pattern has been set on this input. */
+    private get hasPattern();
+    /**
+     * The set of literal separator characters defined in the current pattern.
+     *
+     * Pattern '(000) 000-0000' → separators: {'(', ')', ' ', '-'}
+     * Pattern '0000 0000'      → separators: {' '}
+     *
+     * Used when stripping decorations back off a displayed value.
+     */
+    private get patternSeparatorChars();
+    /**
+     * The total number of digit slots ('0' characters) in the current pattern.
+     * 'card' pattern has 16 slots; 'expiry' has 4; etc.
+     */
+    private get patternDigitSlotCount();
+    /**
+     * The effective maximum digit length to enforce.
+     * In pattern mode, this is always the slot count (overrides any [maxLength] input).
+     * In non-pattern mode, it comes from the [maxLength] input (may be null = unlimited).
+     */
+    private get effectiveMaxLength();
+    /**
+     * The effective output type.
+     * Pattern mode always emits strings because patterns are for identifiers.
+     * Otherwise respects the [outputType] input.
+     */
+    private get effectiveOutputType();
+    /**
+     * The decimal separator character used in the DISPLAY.
+     * If the thousands separator is '.' (European style), we must use ','
+     * as the decimal character to avoid ambiguity (1.234,56 is valid; 1,234,56 is not).
+     * Otherwise we use the standard '.'.
+     */
+    private get displayDecimalChar();
+    /**
+     * Returns true when the input element (or any of its ancestors) is in
+     * right-to-left mode.
+     *
+     * Detection order:
+     *   1. The input element's own computed `direction` style — this reflects
+     *      any `dir` attribute on the element itself, a CSS `direction` rule,
+     *      or inheritance from a parent element with dir="rtl".
+     *   2. Falls back to false (LTR) if the window / getComputedStyle is
+     *      unavailable (e.g. server-side rendering).
+     *
+     * This is a getter (not a cached field) so it always reflects the current
+     * DOM state, even if the direction changes dynamically at runtime.
+     */
+    private get isRtl();
+    /**
+     * In RTL mode the string stored in the input is prefixed with an LRM mark
+     * so that the bidi algorithm does not reorder digits or separators.
+     * This helper returns the prefix length including the LRM when RTL is active.
+     *
+     * Used wherever we need to know "how many characters before the editable
+     * number portion start" — cursor clamping, minus-key position check, etc.
+     */
+    private get editableStartOffset();
+    /**
+     * The number of characters at the RIGHT end of the display string that
+     * belong to the suffix (LTR) or prefix (RTL) — i.e. characters the cursor
+     * must never move past on the right side.
+     */
+    private get editableEndPadding();
+    constructor(el: ElementRef<HTMLInputElement>, renderer: Renderer2, document: Document);
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    /** Angular calls this when the form model value changes programmatically. */
+    writeValue(value: string | number | null): void;
+    /** Angular calls this to register the function we must call when our value changes. */
+    registerOnChange(fn: (v: number | string | null) => void): void;
+    /** Angular calls this to register the function we must call when the field is touched. */
+    registerOnTouched(fn: () => void): void;
+    /** Angular calls this to enable or disable the input. */
+    setDisabledState(isDisabled: boolean): void;
+    /** Angular calls this to ask whether the current value has any errors. */
+    validate(_control: AbstractControl): ValidationErrors | null;
+    /** Angular calls this to register the function we call when validation rules change. */
+    registerOnValidatorChange(fn: () => void): void;
+    /**
+     * Intercept keydown BEFORE the character lands in the input.
+     * This is our first line of defense — blocking bad keys entirely
+     * so the input event never fires for them.
+     */
+    onKeyDown(event: KeyboardEvent): void;
+    /**
+     * Process input AFTER the character has landed in the input element.
+     * We read the new display value, strip decorations to get raw digits,
+     * apply rules (decimal limits, maxLength, leading zeros), then re-render.
+     */
+    onInput(): void;
+    /**
+     * When the user leaves the field, mark it as touched (triggers validation
+     * display) and clean up any trailing decimal point (e.g. the user typed
+     * '12.' and then tabbed away).
+     */
+    onBlur(): void;
+    /**
+     * Handle paste events manually so we can sanitize the pasted content
+     * before it reaches the input, just like we do for individual keystrokes.
+     */
+    onPaste(event: ClipboardEvent): void;
+    /**
+     * Block drag-and-drop into the field.
+     * Without this a user could drag text from elsewhere and bypass our rules.
+     */
+    onDrop(event: DragEvent): void;
+    /**
+     * Build the value that gets emitted to the Angular form model.
+     *
+     * Pattern / string mode  →  string | null
+     *   ''    → null   (empty field)
+     *   '123' → '123'  (raw digits, leading zeros preserved, no separators)
+     *
+     * Number mode  →  number | null
+     *   ''    → null   (empty field)
+     *   '-'   → null   (user typed a minus but no digits yet)
+     *   '123' → 123
+     *   '1.5' → 1.5
+     *   '-7'  → -7
+     */
+    private buildModelValue;
+    /**
+     * Write the formatted display string back to the <input> DOM element
+     * and try to restore the cursor to a sensible position.
+     *
+     * @param cursorBefore  Cursor position in the display string BEFORE we reformatted
+     * @param lengthBefore  Total display string length BEFORE we reformatted
+     */
+    private refreshDisplay;
+    /**
+     * Apply the display format pattern to the current raw digit string.
+     *
+     * Algorithm:
+     *   Walk through the pattern character by character.
+     *   On '0': consume the next raw digit and add it to the result.
+     *   On anything else: this is a separator — add it ONLY if more digits follow.
+     *   (The "more digits follow" check prevents trailing separators mid-type.)
+     *
+     * Examples:
+     *   pattern '0000 0000 0000 0000', raw '41111111'  →  '4111 1111'
+     *   pattern '(000) 000-0000',      raw '5558675'   →  '(555) 867'
+     *   pattern '00/00',               raw '122'       →  '12/2'
+     */
+    private applyPatternFormatting;
+    /**
+     * Apply thousands separator grouping and decimal character to a raw number string.
+     * Only used in number output mode (not pattern, not string mode).
+     *
+     * Examples (separator=',', decimalChar='.'):
+     *   '1234567'   →  '1,234,567'
+     *   '-9876.50'  →  '-9,876.50'
+     *   '100'       →  '100'
+     */
+    private applyThousandsFormatting;
+    /**
+     * Remove all visual decoration from the displayed input value and return
+     * the bare digit/numeric string ready for internal storage.
+     *
+     * Steps:
+     *   1. Strip prefix from the front
+     *   2. Strip suffix from the back
+     *   3. Remove pattern separators OR thousands separators (depending on mode)
+     *   4. Normalize non-ASCII decimal separator back to '.'
+     *   5. Remove any remaining non-numeric characters
+     */
+    private stripDecorationsFrom;
+    /**
+     * Remove every separator character that the current pattern defines.
+     * For example, pattern '(000) 000-0000' defines '(', ')', ' ', '-' as separators.
+     * This strips all four from the input string, leaving only digits.
+     */
+    private stripPatternSeparatorsFrom;
+    /**
+     * Ensure a raw numeric string has at most one decimal point
+     * and at most [decimalPlaces] digits after it.
+     *
+     * Examples (decimalPlaces=2):
+     *   '12.345'  →  '12.34'
+     *   '1.2.3'   →  '1.23'
+     *   '100'     →  '100'
+     */
+    private enforceDecimalRules;
+    /**
+     * Remove unnecessary leading zeros from the integer part of a numeric string.
+     * Always preserves at least one digit and never touches the decimal part.
+     *
+     * Examples:
+     *   '007'    →  '7'
+     *   '0042'   →  '42'
+     *   '0.5'    →  '0.5'  (leading zero before decimal is correct, don't strip)
+     *   '100'    →  '100'  (no leading zero)
+     *   '-007'   →  '-7'   (handles negative values)
+     */
+    private stripLeadingZeros;
+    /**
+     * Sanitize a pasted string for non-pattern mode.
+     * The characters we keep depend on the current mode:
+     *
+     *   string mode    →  digits only (no dot, no minus; identifiers can't be negative)
+     *   integer number →  digits + optional leading minus
+     *   decimal number →  digits + optional dot + optional leading minus
+     */
+    private sanitizePastedText;
+    /**
+     * Map a cursor position in the formatted DISPLAY string back to an index
+     * in the raw digit string.
+     *
+     * This is needed during paste operations in pattern mode so we know
+     * exactly which digit position the cursor is sitting at.
+     *
+     * Example:
+     *   pattern '(000) 000-0000'
+     *   display '(555) 867'   cursor at position 8 (after '(555) 86')
+     *
+     *   Walking the pattern:
+     *     '('  pos 0 → sep  (adjusted pos 0, raw index still 0)
+     *     '0'  pos 1 → digit (raw index 0)  digit consumed → raw index 1
+     *     '0'  pos 2 → digit (raw index 1)  digit consumed → raw index 2
+     *     '0'  pos 3 → digit (raw index 2)  digit consumed → raw index 3
+     *     ')'  pos 4 → sep
+     *     ' '  pos 5 → sep
+     *     '0'  pos 6 → digit (raw index 3)  digit consumed → raw index 4
+     *     '0'  pos 7 → digit (raw index 4)  digit consumed → raw index 5
+     *   We reached position 8, so raw index = 5  ✔
+     */
+    private mapDisplayCursorToRawIndex;
+    /**
+     * Decide whether a keyboard event is a "control" key that should always
+     * be allowed through without interception.
+     *
+     * Includes:
+     *   - Modifier keys held (Ctrl, Meta/Cmd, Alt) — so Ctrl+C, Ctrl+V, etc. work
+     *   - Navigation keys (arrows, Home, End)
+     *   - Editing keys (Backspace, Delete, Tab, Escape, Enter)
+     */
+    private isControlKey;
+    static ɵfac: i0.ɵɵFactoryDeclaration<digitsOnlyDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<digitsOnlyDirective, "[digitsOnly]", never, { "decimalPlaces": { "alias": "decimalPlaces"; "required": false; }; "thousandSeparator": { "alias": "thousandSeparator"; "required": false; }; "prefix": { "alias": "prefix"; "required": false; }; "suffix": { "alias": "suffix"; "required": false; }; "allowNegative": { "alias": "allowNegative"; "required": false; }; "leadingZeros": { "alias": "leadingZeros"; "required": false; }; "maxLength": { "alias": "maxLength"; "required": false; }; "min": { "alias": "min"; "required": false; }; "max": { "alias": "max"; "required": false; }; "outputType": { "alias": "outputType"; "required": false; }; "convertEasternNumerals": { "alias": "convertEasternNumerals"; "required": false; }; "pattern": { "alias": "pattern"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * eastern-numerals.ts
+ *
+ * A fully standalone, zero-dependency TypeScript utility that converts
+ * Arabic-Indic and Persian/Farsi digit characters to their Western (ASCII)
+ * equivalents.
+ *
+ * ─── Zero dependencies ────────────────────────────────────────────────────────
+ *
+ * This file has NO imports. Copy it into ANY TypeScript or JavaScript project
+ * and use it immediately — Angular, React, Vue, Node.js, plain TS, or a browser
+ * script. Nothing else is required.
+ *
+ * ─── Why this exists ──────────────────────────────────────────────────────────
+ *
+ * Arabic and Persian keyboards — and many mobile IMEs across the Middle East
+ * and South Asia — produce digit characters from a DIFFERENT Unicode block
+ * than the ASCII digits 0–9 most Western software expects:
+ *
+ *   Western / ASCII     0  1  2  3  4  5  6  7  8  9
+ *   Code points         U+0030 ── U+0039
+ *
+ *   Arabic-Indic        ٠  ١  ٢  ٣  ٤  ٥  ٦  ٧  ٨  ٩
+ *   Code points         U+0660 ── U+0669
+ *
+ *   Persian / Farsi     ۰  ۱  ۲  ۳  ۴  ۵  ۶  ۷  ۸  ۹
+ *   Code points         U+06F0 ── U+06F9
+ *
+ * When a user types ١٢٣ on an Arabic keyboard the browser sends those exact
+ * Unicode code points, NOT '123'. Without conversion:
+ *   • /^\d$/ does NOT match them (it only matches U+0030–U+0039)
+ *   • Number('١٢٣') returns NaN
+ *   • parseInt('١٢٣', 10) returns NaN
+ *
+ * ─── Safety guarantee ─────────────────────────────────────────────────────────
+ *
+ * This conversion is completely conflict-free because the Arabic and Persian
+ * digit Unicode blocks have ZERO overlap with:
+ *   • ASCII digits      (U+0030–U+0039)
+ *   • ASCII letters     (U+0041–U+007A)
+ *   • ASCII punctuation (. , - + $ € % @ # etc.)
+ *
+ * Converting ٥ → '5' can NEVER accidentally transform a separator, currency
+ * symbol, or letter into something else. The substitution is exact and
+ * unambiguous.
+ *
+ * ─── What is NOT converted ────────────────────────────────────────────────────
+ *
+ * • Arabic letters ا ب ت ث …      — no Western equivalent, left as-is
+ * • Arabic diacritics (harakat)    — no Western equivalent, left as-is
+ * • Any character outside the two digit blocks described above
+ *
+ * ─── Exports ──────────────────────────────────────────────────────────────────
+ *
+ *   convertEasternDigits(input)   Main conversion — Eastern digits → 0-9
+ *   hasEasternDigits(input)       Quick check — does the string contain any?
+ *   getDigitScript(input)         Identify which script the digits are in
+ *   EASTERN_DIGIT_MAP             Full lookup table (for testing / docs)
+ *   EASTERN_NUMERAL_REGEX         The two RegExp patterns (for advanced use)
+ *
+ * ─── Quick usage ──────────────────────────────────────────────────────────────
+ *
+ *   import { convertEasternDigits } from './eastern-numerals';
+ *
+ *   convertEasternDigits('١٢٣٫٤٥')     // '123.45'
+ *   convertEasternDigits('۶۷۸')        // '678'
+ *   convertEasternDigits('price: ١٠٠') // 'price: 100'  (non-digits untouched)
+ *   convertEasternDigits('123')         // '123'          (already Western)
+ *   convertEasternDigits(null)          // ''
+ */
+/**
+ * Regex patterns used internally by this module.
+ * Also exported so callers can use them directly if needed.
+ *
+ * These are the same patterns documented in digits-only.regex.ts entries
+ * ARABIC_DIGITS, PERSIAN_DIGITS, ARABIC_DECIMAL_COMMA, ARABIC_THOUSANDS_SEPARATOR
+ * but duplicated here so this file remains self-contained.
+ */
+declare const EASTERN_NUMERAL_REGEX: {
+    /**
+     * Matches any Arabic-Indic digit character (U+0660 – U+0669).
+     * These are the digits used on Arabic keyboards: ٠١٢٣٤٥٦٧٨٩
+     * The g flag ensures ALL occurrences in a string are replaced, not just the first.
+     */
+    readonly ARABIC_DIGITS: RegExp;
+    /**
+     * Matches any Persian / Extended Arabic-Indic digit (U+06F0 – U+06F9).
+     * These are the digits used on Persian / Farsi keyboards: ۰۱۲۳۴۵۶۷۸۹
+     * Note: a DIFFERENT Unicode block from Arabic even though they look similar.
+     *   Arabic zero  ٠  =  U+0660
+     *   Persian zero ۰  =  U+06F0  ← different!
+     */
+    readonly PERSIAN_DIGITS: RegExp;
+    /**
+     * Matches the Arabic Decimal Separator ٫ (U+066B).
+     * In Arabic locale this character plays the role of the Western period '.'
+     * as a decimal point. We normalize it to '.' so parseFloat / Number work.
+     */
+    readonly ARABIC_DECIMAL_COMMA: RegExp;
+    /**
+     * Matches the Arabic Thousands Separator ٬ (U+066C).
+     * In Arabic locale this character plays the role of the Western comma ','
+     * as a digit-group separator. We strip it so it doesn't pollute the number.
+     */
+    readonly ARABIC_THOUSANDS_SEPARATOR: RegExp;
+};
+/**
+ * Every Eastern digit character mapped to its Western ASCII equivalent.
+ *
+ * Key   = Eastern character (as it arrives from the keyboard / clipboard)
+ * Value = Western ASCII character it should become
+ *
+ * This map is exported for:
+ *   • Unit tests that want to iterate over every case
+ *   • Documentation / debugging
+ *   • Manual lookups without running a conversion
+ */
+declare const EASTERN_DIGIT_MAP: Readonly<Record<string, string>>;
+/**
+ * Convert all Arabic-Indic and Persian digit characters in a string
+ * to their Western ASCII equivalents (0–9).
+ *
+ * The function runs four passes in order:
+ *   1. Strip Arabic thousands separator ٬ (U+066C)
+ *   2. Convert Arabic decimal comma ٫ (U+066B) → '.'
+ *   3. Convert Arabic-Indic digits ٠-٩ (U+0660–U+0669) → '0'-'9'
+ *   4. Convert Persian digits ۰-۹ (U+06F0–U+06F9) → '0'-'9'
+ *
+ * The function is PURE — it never mutates its input and has no side effects.
+ *
+ * @param input  Any string, number, null, or undefined.
+ *               Numbers are converted via String() first.
+ *               null / undefined / '' all return ''.
+ * @returns      A new string with every Eastern digit replaced by its Western
+ *               equivalent. Non-digit characters are passed through unchanged.
+ *
+ * @example
+ *   convertEasternDigits('١٢٣')           // '123'
+ *   convertEasternDigits('۶۷۸')           // '678'
+ *   convertEasternDigits('١٢٣٫٤٥')       // '123.45'   (decimal comma)
+ *   convertEasternDigits('١٬٢٣٤')        // '1234'     (thousands sep stripped)
+ *   convertEasternDigits('price: ٩٩')    // 'price: 99' (non-digits untouched)
+ *   convertEasternDigits('123')           // '123'       (already Western)
+ *   convertEasternDigits('')              // ''
+ *   convertEasternDigits(null)            // ''
+ *   convertEasternDigits(undefined)       // ''
+ *   convertEasternDigits(42)              // '42'        (number input)
+ */
+declare function convertEasternDigits(input: string | number | null | undefined): string;
+/**
+ * Returns true if the string contains at least one Arabic-Indic or
+ * Persian digit character.
+ *
+ * Useful as a cheap pre-check before calling convertEasternDigits — if this
+ * returns false the string is already all-Western and no conversion is needed.
+ *
+ * @param input  Any string to check.
+ * @returns      true if any Eastern digit is present, false otherwise.
+ *
+ * @example
+ *   hasEasternDigits('١٢٣')    // true   — Arabic
+ *   hasEasternDigits('۴۵۶')   // true   — Persian
+ *   hasEasternDigits('٥0')     // true   — mix of Arabic and Western
+ *   hasEasternDigits('123')    // false  — already Western
+ *   hasEasternDigits('hello')  // false  — no digits at all
+ *   hasEasternDigits('')       // false
+ */
+declare function hasEasternDigits(input: string): boolean;
+/**
+ * Identify which numeral script(s) the string's digits are written in.
+ * Returns one of four values so callers can branch on the exact script
+ * rather than just knowing "something eastern is present".
+ *
+ * @param input  Any string to inspect.
+ * @returns
+ *   'western'  — only ASCII digits 0-9 found (or no digits at all)
+ *   'arabic'   — only Arabic-Indic digits ٠-٩ found
+ *   'persian'  — only Persian digits ۰-۹ found
+ *   'mixed'    — both Eastern script(s) AND/OR Western digits found together
+ *
+ * @example
+ *   getDigitScript('١٢٣')       // 'arabic'
+ *   getDigitScript('۴۵۶')      // 'persian'
+ *   getDigitScript('123')       // 'western'
+ *   getDigitScript('١23')       // 'mixed'   (Arabic + Western)
+ *   getDigitScript('١۴')        // 'mixed'   (Arabic + Persian)
+ *   getDigitScript('hello')     // 'western' (no digits → treated as Western)
+ */
+type DigitScript = 'western' | 'arabic' | 'persian' | 'mixed';
+declare function getDigitScript(input: string): DigitScript;
+/**
+ * Convert a string that may contain Eastern digits to a JavaScript number.
+ * A convenience wrapper around convertEasternDigits + parseFloat.
+ *
+ * Returns NaN for strings that don't represent a valid number
+ * (same contract as parseFloat / Number).
+ *
+ * @param input  A string possibly containing Eastern digits.
+ * @returns      A JavaScript number, or NaN if parsing fails.
+ *
+ * @example
+ *   toWesternNumber('١٢٣')       // 123
+ *   toWesternNumber('١٢٣٫٤٥')   // 123.45
+ *   toWesternNumber('۹٩')        // 99   (mixed Arabic + Persian → still works)
+ *   toWesternNumber('abc')        // NaN
+ *   toWesternNumber('')           // NaN
+ */
+declare function toWesternNumber(input: string | null | undefined): number;
+
+export { EASTERN_DIGIT_MAP, EASTERN_NUMERAL_REGEX, convertEasternDigits, digitsOnlyDirective, getDigitScript, hasEasternDigits, toWesternNumber };
+export type { DigitScript, NamedPattern };