raqam 0.2.0

package/dist/core.d.cts

@@ -0,0 +1,351 @@
+interface LocaleInfo {
+    /** Decimal separator for this locale (e.g. "." en-US, "," de-DE, "٫" fa-IR) */
+    decimalSeparator: string;
+    /** Grouping (thousands) separator (e.g. "," en-US, "." de-DE, "٬" fa-IR) */
+    groupingSeparator: string;
+    /** Minus sign character (usually "-" but can differ) */
+    minusSign: string;
+    /** Locale's representation of "0" (e.g. "0" for Latin, "۰" for Persian) */
+    zero: string;
+    /** Whether this is an RTL locale */
+    isRTL: boolean;
+}
+interface FormatResult {
+    formatted: string;
+    parts: Intl.NumberFormatPart[];
+}
+interface ParseResult {
+    /** The parsed number, or null if empty / un-parseable */
+    value: number | null;
+    /** True for valid numbers */
+    isValid: boolean;
+    /**
+     * True for valid-but-incomplete input that must not be reformatted yet:
+     * "-", "1.", "1.0", "1.00", etc.
+     */
+    isIntermediate: boolean;
+}
+/**
+ * boolean[] of length formattedValue.length + 1.
+ * true  → cursor may rest at this index
+ * false → cursor must not rest here (e.g. inside a thousands separator)
+ */
+type CaretBoundary = boolean[];
+/** Unicode codepoint range [start, end] inclusive representing a digit block */
+type DigitBlock = readonly [number, number];
+interface UseNumberFieldStateOptions {
+    /** Controlled numeric value */
+    value?: number | null;
+    /** Uncontrolled default value */
+    defaultValue?: number | null;
+    /** Fires on every meaningful value change */
+    onChange?: (value: number | null) => void;
+    /** BCP 47 locale tag (default: browser locale) */
+    locale?: string;
+    /** Full Intl.NumberFormatOptions — currency, percent, decimal, etc. */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** Minimum allowed value */
+    minValue?: number;
+    /** Maximum allowed value */
+    maxValue?: number;
+    /** Step amount for increment/decrement (default: 1) */
+    step?: number;
+    /** Large step — Shift+Arrow / PageUp/Down (default: step * 10) */
+    largeStep?: number;
+    /** Small step — Meta/Ctrl+Arrow (default: step * 0.1) */
+    smallStep?: number;
+    /** Allow negative values (default: true) */
+    allowNegative?: boolean;
+    /** Allow decimal values (default: true) */
+    allowDecimal?: boolean;
+    /** Override maximumFractionDigits from formatOptions */
+    maximumFractionDigits?: number;
+    /** Override minimumFractionDigits from formatOptions */
+    minimumFractionDigits?: number;
+    /** Always show exactly maximumFractionDigits decimal places */
+    fixedDecimalScale?: boolean;
+    /** When clamping happens (default: "blur") */
+    clampBehavior?: "blur" | "strict" | "none";
+    /** Apply live formatting while typing (default: true) */
+    liveFormat?: boolean;
+    /** Arbitrary prefix string (e.g. "$") */
+    prefix?: string;
+    /** Arbitrary suffix string (e.g. " تومان") */
+    suffix?: string;
+    /** Disable the field */
+    disabled?: boolean;
+    /** Make the field read-only */
+    readOnly?: boolean;
+    /** Mark the field as required */
+    required?: boolean;
+    /**
+     * Allow values outside min/max to be typed and committed without clamping.
+     * Useful when server-side validation handles clamping.
+     * When true, aria-invalid is set when value is out of range.
+     * default: false
+     */
+    allowOutOfRange?: boolean;
+    /**
+     * Custom validation function. Called on every value change.
+     * - Return `true` or `null`/`undefined` → valid
+     * - Return `false` → invalid (aria-invalid set, no error message)
+     * - Return a `string` → invalid with that string as the error message
+     */
+    validate?: (value: number | null) => boolean | string | null | undefined;
+    /**
+     * Fires with the raw unformatted string the user typed, preserving full
+     * decimal precision before JS float conversion. Useful for financial apps
+     * that need arbitrary-precision string arithmetic.
+     * Fires alongside `onChange`.
+     */
+    onRawChange?: (rawValue: string | null) => void;
+    /**
+     * Custom format function. When provided, replaces the built-in Intl.NumberFormat
+     * formatter for display purposes. Also used for initial display value.
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Custom parse function. When provided, replaces the built-in locale-aware parser.
+     * Must return `{ value: number | null, isIntermediate: boolean }`.
+     */
+    parseValue?: (input: string) => {
+        value: number | null;
+        isIntermediate: boolean;
+    };
+}
+interface NumberFieldState {
+    /** The display string shown in the input */
+    inputValue: string;
+    /** The parsed numeric value (null for empty/invalid) */
+    numberValue: number | null;
+    /**
+     * The raw string value exactly as the user typed it (before formatting).
+     * Preserves full decimal precision — useful for financial arbitrary-precision math.
+     */
+    rawValue: string | null;
+    /** Whether increment is currently possible */
+    canIncrement: boolean;
+    /** Whether decrement is currently possible */
+    canDecrement: boolean;
+    /** Whether the ScrubArea is currently being dragged */
+    isScrubbing: boolean;
+    /** Update the isScrubbing state (called by useScrubArea) */
+    setIsScrubbing: (val: boolean) => void;
+    /** Whether the input is currently focused */
+    isFocused: boolean;
+    /** Update the isFocused state (called by useNumberField) */
+    setIsFocused: (val: boolean) => void;
+    /** Current validation state — 'valid' if no validate prop, or based on validate result */
+    validationState: "valid" | "invalid";
+    /** Error message from validate() if it returned a string, otherwise null */
+    validationError: string | null;
+    /** Internal: set the reason for the next onChange call (used by useNumberField) */
+    _setLastChangeReason: (reason: ChangeReason) => void;
+    /** Internal: read the current change reason (used by NumberField.Root) */
+    _getLastChangeReason: () => ChangeReason;
+    /** Update display string (triggers parse + onChange) */
+    setInputValue: (val: string) => void;
+    /** Directly set the numeric value (triggers format + onChange) */
+    setNumberValue: (val: number | null) => void;
+    /** Format + clamp on blur — call from onBlur */
+    commit: () => void;
+    /** Increment by step */
+    increment: (amount?: number) => void;
+    /** Decrement by step */
+    decrement: (amount?: number) => void;
+    /** Jump to maxValue */
+    incrementToMax: () => void;
+    /** Jump to minValue */
+    decrementToMin: () => void;
+    /** Raw options (for hooks that need them) */
+    options: UseNumberFieldStateOptions;
+}
+/** Reason for a value change — propagated through onValueChange details */
+type ChangeReason = "input" | "clear" | "blur" | "paste" | "keyboard" | "increment" | "decrement" | "wheel" | "scrub";
+interface UseNumberFieldProps extends UseNumberFieldStateOptions {
+    /** Visible label text (used for aria-label fallback) */
+    label?: string;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    "aria-labelledby"?: string;
+    /** Form field name — renders a hidden input */
+    name?: string;
+    /** id for the input element */
+    id?: string;
+    /** Enable mouse-wheel increment/decrement */
+    allowMouseWheel?: boolean;
+    /**
+     * Controls what is placed in the clipboard on copy/cut.
+     * - 'formatted' (default): browser-native copy of display string
+     * - 'raw': numberValue as a plain JS number string (e.g. "1234.56")
+     * - 'number': alias for 'raw'
+     */
+    copyBehavior?: "formatted" | "raw" | "number";
+    /** Milliseconds before press-and-hold repeat starts (default: 400) */
+    stepHoldDelay?: number;
+    /** Initial milliseconds between repeats during press-and-hold (default: 200) */
+    stepHoldInterval?: number;
+    onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void;
+    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+}
+interface NumberFieldAria {
+    labelProps: React.LabelHTMLAttributes<HTMLLabelElement>;
+    groupProps: React.HTMLAttributes<HTMLDivElement>;
+    inputProps: React.InputHTMLAttributes<HTMLInputElement>;
+    hiddenInputProps: React.InputHTMLAttributes<HTMLInputElement> | null;
+    incrementButtonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+    decrementButtonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+    descriptionProps: React.HTMLAttributes<HTMLElement>;
+    errorMessageProps: React.HTMLAttributes<HTMLElement>;
+}
+type StateRenderFn = (props: Record<string, unknown>, state: NumberFieldState) => React.ReactElement;
+type RenderProp = React.ReactElement | StateRenderFn;
+interface NumberFieldRootProps extends UseNumberFieldProps {
+    children?: React.ReactNode;
+    /** CSS class for the root wrapper div */
+    className?: string;
+    /** Inline style for the root wrapper div */
+    style?: React.CSSProperties;
+    /** Fires on every meaningful value change */
+    onValueChange?: (value: number | null, details: {
+        reason: ChangeReason;
+        formattedValue: string;
+        event?: React.SyntheticEvent;
+    }) => void;
+    /** Fires only on commit (blur, Enter) */
+    onValueCommitted?: (value: number | null, details: {
+        reason: "blur" | "keyboard";
+    }) => void;
+}
+
+/**
+ * Format presets — named Intl.NumberFormatOptions configurations for common
+ * number input patterns. Use these as the `formatOptions` prop value.
+ *
+ * @example
+ * import { presets } from 'raqam'
+ * <NumberField.Root formatOptions={presets.currency('USD')} />
+ * <NumberField.Root formatOptions={presets.percent} />
+ * <NumberField.Root formatOptions={presets.compact} />
+ */
+declare const presets: {
+    /** Currency with standard sign display. Shorthand for `{ style:'currency', currency:code }`. */
+    readonly currency: (code: string) => Intl.NumberFormatOptions;
+    /**
+     * Accounting currency — negatives shown as `(1,234.56)` instead of `-$1,234.56`.
+     * Requires the accounting format parser fix (built-in to raqam).
+     */
+    readonly accounting: (code: string) => Intl.NumberFormatOptions;
+    /** Percentage — formats 0.42 as "42%" */
+    readonly percent: Intl.NumberFormatOptions;
+    /** Compact short — "1.2K", "3.4M" */
+    readonly compact: Intl.NumberFormatOptions;
+    /** Compact long — "1.2 thousand", "3.4 million" */
+    readonly compactLong: Intl.NumberFormatOptions;
+    /** Scientific notation — "1.234E3" */
+    readonly scientific: Intl.NumberFormatOptions;
+    /** Engineering notation — exponents always multiples of 3 */
+    readonly engineering: Intl.NumberFormatOptions;
+    /** Integer — no decimal places */
+    readonly integer: Intl.NumberFormatOptions;
+    /**
+     * Financial — always exactly 2 decimal places (fixed scale).
+     * Combine with `fixedDecimalScale` prop for strict display.
+     */
+    readonly financial: Intl.NumberFormatOptions;
+    /**
+     * Unit — shorthand for `{ style:'unit', unit:unitCode }`.
+     * @example presets.unit('kilometer-per-hour') → { style:'unit', unit:'kilometer-per-hour' }
+     */
+    readonly unit: (unit: string) => Intl.NumberFormatOptions;
+};
+
+interface LocaleConfig {
+    /** Extra digit block ranges to register */
+    digitBlocks?: DigitBlock[];
+}
+/**
+ * Register additional digit blocks (called by locale plugins as a side effect).
+ * Duplicate ranges are silently ignored.
+ */
+declare function registerLocale(config: LocaleConfig): void;
+/**
+ * Normalise any Unicode decimal digit in `input` to its ASCII equivalent (0–9).
+ * Non-digit characters pass through unchanged.
+ */
+declare function normalizeDigits(input: string): string;
+
+interface FormatterOptions {
+    locale?: string;
+    formatOptions?: Intl.NumberFormatOptions;
+    prefix?: string;
+    suffix?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    fixedDecimalScale?: boolean;
+}
+interface Formatter {
+    format(value: number): string;
+    formatToParts(value: number): Intl.NumberFormatPart[];
+    getLocaleInfo(): LocaleInfo;
+    formatResult(value: number): FormatResult;
+}
+/**
+ * Create a formatter instance. Intl.NumberFormat is cached — safe to call
+ * on every render.
+ */
+declare function createFormatter(opts: FormatterOptions): Formatter;
+
+interface ParserOptions {
+    locale?: string;
+    formatOptions?: Intl.NumberFormatOptions;
+    allowNegative?: boolean;
+    allowDecimal?: boolean;
+    prefix?: string;
+    suffix?: string;
+}
+interface Parser {
+    parse(input: string): ParseResult;
+    isIntermediate(input: string): boolean;
+    getLocaleInfo(): LocaleInfo;
+}
+/**
+ * Create a locale-aware parser. Separator characters are extracted from
+ * Intl.NumberFormat — never hardcoded.
+ */
+declare function createParser(opts?: ParserOptions): Parser;
+
+/**
+ * Build a boolean array of length `formattedValue.length + 1`.
+ * `true`  → cursor may rest at this position.
+ * `false` → cursor must snap away (sits inside a formatting-only character
+ *            such as a grouping separator or a currency prefix).
+ *
+ * Rules:
+ *  - Start and end positions are always valid.
+ *  - A position immediately AFTER a grouping separator is invalid (the
+ *    cursor would look like it's between two digits but moving left would
+ *    skip the comma).
+ *  - A position immediately BEFORE a grouping separator is valid.
+ */
+declare function getCaretBoundary(formattedValue: string, info: LocaleInfo): CaretBoundary;
+/**
+ * Compute the new cursor position in `newFormatted` that corresponds
+ * semantically to `oldCursor` in `oldInput`.
+ *
+ * Algorithm (3 stages from the spec):
+ *
+ * 1. Count accepted characters before `oldCursor` in `oldInput`.
+ * 2. Adjust for backspace-over-separator edge case.
+ * 3. Walk `newFormatted` to find the position where the same count of
+ *    accepted chars precede it; snap to the nearest valid boundary.
+ *
+ * @param oldInput     The raw string the user just typed into (pre-format)
+ * @param oldCursor    selectionStart captured from the native event
+ * @param newFormatted The formatted string we're about to display
+ * @param info         Locale separators
+ * @param inputType    e.nativeEvent.inputType (optional — for backspace detection)
+ */
+declare function computeNewCursorPosition(oldInput: string, oldCursor: number, newFormatted: string, info: LocaleInfo, inputType?: string): number;
+
+export { type CaretBoundary, type ChangeReason, type DigitBlock, type FormatResult, type Formatter, type FormatterOptions, type LocaleConfig, type LocaleInfo, type NumberFieldAria, type NumberFieldRootProps, type NumberFieldState, type ParseResult, type Parser, type ParserOptions, type RenderProp, type StateRenderFn, type UseNumberFieldProps, type UseNumberFieldStateOptions, computeNewCursorPosition, createFormatter, createParser, getCaretBoundary, normalizeDigits, presets, registerLocale };