raqam 0.3.1 → 0.4.0

package/dist/core.d.cts

@@ -1,297 +1,5 @@
-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). `knownValue` overrides
-     * the parsed value when `val` is a formatted string that cannot be reversed
-     * (compact "2.5K", scientific, unit notation).
-     */
-    setInputValue: (val: string, knownValue?: number | null) => void;
-    /** Directly set the numeric value (triggers format + onChange) */
-    setNumberValue: (val: number | null) => void;
-    /** Format + clamp on blur — call from onBlur. Returns the committed numeric value. */
-    commit: () => number | null;
-    /** 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;
-    /**
-     * Fires only when the value is committed — i.e. on blur, or when the user
-     * presses Enter — after formatting and clamping have been applied.
-     * `reason` is `"blur"` for focus loss and `"keyboard"` for Enter.
-     * Reach for this (instead of `onChange`) when you only care about the final,
-     * settled value: persisting it, validating server-side, firing a request, etc.
-     */
-    onValueCommitted?: (value: number | null, details: {
-        reason: "blur" | "keyboard";
-    }) => void;
-}
-interface NumberFieldAria {
-    /**
-     * Props for the label element. Includes a `ref` callback that registers the
-     * label's presence with the hook — spread it onto whatever element you render
-     * as the label (built-in `<NumberField.Label>` or a custom primitive) so the
-     * input/group keep their `aria-labelledby` wiring and avoid dangling refs.
-     */
-    labelProps: React.LabelHTMLAttributes<HTMLLabelElement> & {
-        ref?: React.RefCallback<HTMLElement>;
-    };
-    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;
-}
-
-/**
- * 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;
+import { L as LocaleInfo, F as FormatResult, P as ParseResult, D as DigitBlock, C as CaretBoundary } from './types-B2ZqkJI-.cjs';
+export { a as ChangeReason, b as NumberFieldAria, c as NumberFieldRootProps, N as NumberFieldState, R as RenderProp, f as StateRenderFn, U as UseNumberFieldProps, g as UseNumberFieldStateOptions } from './types-B2ZqkJI-.cjs';
 
 interface FormatterOptions {
     locale?: string;
@@ -326,6 +34,14 @@ interface Parser {
     parse(input: string): ParseResult;
     isIntermediate(input: string): boolean;
     getLocaleInfo(): LocaleInfo;
+    /**
+     * Strip formatting affordances (grouping separators, currency symbol, prefix/
+     * suffix, percent sign…) from `input`, returning the bare numeric string
+     * (ASCII digits, an optional leading "-", and at most one "."). Trailing zeros
+     * the user typed are preserved. Useful for deriving a precision-preserving raw
+     * value from a formatted display string.
+     */
+    strip(input: string): string;
 }
 /**
  * Create a locale-aware parser. Separator characters are extracted from
@@ -333,6 +49,21 @@ interface Parser {
  */
 declare function createParser(opts?: ParserOptions): Parser;
 
+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;
+
 /**
  * Build a boolean array of length `formattedValue.length + 1`.
  * `true`  → cursor may rest at this position.
@@ -366,4 +97,46 @@ declare function getCaretBoundary(formattedValue: string, info: LocaleInfo): Car
  */
 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 };
+/**
+ * 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;
+};
+
+export { CaretBoundary, DigitBlock, FormatResult, type Formatter, type FormatterOptions, type LocaleConfig, LocaleInfo, ParseResult, type Parser, type ParserOptions, computeNewCursorPosition, createFormatter, createParser, getCaretBoundary, normalizeDigits, presets, registerLocale };