bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/dist/components/BbNumberInput/numberDisplay.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Q60.25 (owner 2026-10-07): BbNumberInput shows its number the locale's way
+ * while the user types. This is the engine, pure and DOM-free: the component
+ * keeps a canonical `raw` string, edits only that, and paints `formatRaw(raw)`.
+ *
+ * - `raw` is `-?\d*(\.\d*)?`: period decimal, no grouping. It is the only
+ *   thing edited; the caret lives in it and is projected onto the display.
+ * - Two parsers (plans/reviews/q60-25-number-display, GROK-INGEST 1–2): the
+ *   KEYSTROKE reducer (`applyEdit`) sees one typed fragment and applies the
+ *   owner's rule — any typed `,` or `.` starts the decimals, with Q51.2's
+ *   key-by-key reclassify — and `readText` re-reads text that may be a
+ *   painted number (paste, drop, undo, restore, autofill, an outside
+ *   `el.value` write): a legal number in this locale is read strictly, the
+ *   locale's way; anything else by Q51.2 on the whole fragment.
+ */
+/** The marks of one locale, read from `Intl` (CLDR). */
+export interface NumberSymbols {
+    /** The BCP 47 tag the symbols come from. */
+    tag: string;
+    /** The decimal mark (`,` in it, `.` in en). */
+    decimal: string;
+    /** The grouping mark (`.` in it, U+202F in fr, U+2019 in de-CH); '' when none. */
+    group: string;
+    /** Digits in the last group (3) and in the groups before it (2 in hi-IN). */
+    primary: number;
+    secondary: number;
+    /** Groups an integer-digit string, or `null` for ungrouped symbols. */
+    groupInt: ((digits: string) => string) | null;
+    /**
+     * What a negative number starts with: `-`, or `LRM -` in the right-to-left
+     * locales (ar, he, fa, ur), whose minus would otherwise paint on the right
+     * of the digits in a `dir="rtl"` field (CURRENCY-SPEC § 2.12).
+     */
+    minusPrefix: string;
+}
+/** Period decimal and no grouping: `disableFormatting` with a `minPrecision`. */
+export declare const PLAIN_SYMBOLS: NumberSymbols;
+/**
+ * The marks of a locale tag. `useGrouping` is the STRING `'auto'` (owner
+ * 2026-10-07: grouping follows each locale, so it shows `1000` and then
+ * `10.000`): `true` means `'always'` in current engines and the locale's rule
+ * in older ones. Digits are always `latn`. With a `currency`, the marks money
+ * is written with: CLDR gives de-AT (`€ 1.234,50`, a space otherwise) and
+ * fr-CH (`1 234.50 CHF`, a comma otherwise) their own.
+ */
+export declare const numberSymbolsOf: (tag: string, currency?: string) => NumberSymbols;
+/** The fraction digits a currency is written with. */
+export interface CurrencyDigits {
+    min: number;
+    max: number;
+}
+/**
+ * A currency's own fraction digits, from `Intl` (ISO 4217 via CLDR): 2 for EUR
+ * and USD, 0 for JPY, 3 for KWD. `null` for a code `Intl` refuses (`'EURO'`),
+ * so the field keeps its plain defaults.
+ */
+export declare const currencyDigitsOf: (currency: string, tag: string) => CurrencyDigits | null;
+/**
+ * One character as the engine reads it: NFKC (full-width digits from a CJK
+ * IME become ASCII), any other decimal digit (Arabic-Indic, Devanagari, …)
+ * mapped to ASCII, and the minus look-alikes to `-`.
+ */
+export declare const normalizeChar: (ch: string) => string;
+export interface DisplayOptions {
+    /** Fraction digits always shown, padded with placeholder zeros. */
+    minPrecision: number;
+}
+export interface Display {
+    text: string;
+    /** `positions[i]`: where `raw[i]` sits in `text`. */
+    positions: number[];
+    /**
+     * With a currency or unit: `[start, end)` of the numeric span in `text`
+     * (the digits, group marks, decimal and padding), the shell around it.
+     */
+    hole?: [number, number];
+    /** With a currency or unit: the shell's text, to tell when it changes. */
+    shell?: string;
+}
+/**
+ * The display of a raw string: sign, the integer grouped by the locale (an
+ * integer part with a leading zero stays verbatim — `005` while the user edits
+ * it), the locale decimal, the fraction VERBATIM (Intl never sees it: no
+ * 3-digit rounding, and `10,` / `1,50` survive), then placeholder zeros up to
+ * `minPrecision`.
+ */
+export declare const formatRaw: (raw: string, symbols: NumberSymbols, options: DisplayOptions) => Display;
+/**
+ * The display offset of a raw caret: right after `raw[k - 1]`. With a shell,
+ * the caret before the first digit is the hole's start (after a prefix, and
+ * after the minus wherever the locale paints it); `0` on a negative value is
+ * before the minus.
+ */
+export declare const displayIndexOf: (display: Display, k: number) => number;
+/** The raw caret of a display offset: the raw characters before it. */
+export declare const rawIndexOf: (display: Display, offset: number) => number;
+/**
+ * Where a caret may rest: a display offset moved off the shell onto the
+ * nearest edge of the numeric span (never before a negative value's minus).
+ * Without a shell, the offset as it is.
+ */
+export declare const snapOffset: (display: Display, offset: number) => number;
+/**
+ * A non-collapsed display range that holds no raw character and lies on the
+ * shell (`€` selected in `12,00 €`): a delete over it changes nothing
+ * (CURRENCY-SPEC § 2.4). Inside the number, an empty raw range is a group
+ * mark, and a delete there takes the digit beyond it, as always.
+ */
+export declare const isShellOnly: (display: Display, from: number, to: number) => boolean;
+/** A field's currency or unit, already checked by `Intl`. */
+export interface Affix {
+    tag: string;
+    kind: 'currency' | 'unit';
+    code: string;
+}
+/**
+ * The affix of a field: `currency` first (both set: currency wins), `null`
+ * when neither is set or `Intl` refuses the code (`'EURO'`, `'kilograms'`):
+ * the field then shows a plain number.
+ */
+export declare const affixOf: (tag: string, currency?: string, unit?: string) => Affix | null;
+/**
+ * `formatRaw` inside the affix's shell. Empty stays empty (the placeholder
+ * shows) and a lone `-` paints bare until a digit comes; any other value gets
+ * the full shell, the minus in the locale's slot as ASCII `-`.
+ */
+export declare const formatAffixed: (raw: string, symbols: NumberSymbols, options: DisplayOptions, affix: Affix | null) => Display;
+/**
+ * Text read back into a currency / unit field (a paste, an undo, a restore)
+ * without this field's shell: its symbol or unit removed as a whole token
+ * (`kr.` goes, a group dot stays), bidi marks and the spaces around it gone.
+ * The merged `readText` then reads the number.
+ */
+export declare const stripAffix: (text: string, affix: Affix | null) => string;
+/**
+ * What a screen reader hears at rest: the amount spelled out
+ * (`1,234.56 euros`, `20 kilograms`), from the raw value at rest.
+ */
+export declare const spokenAffixed: (raw: string, minPrecision: number, affix: Affix) => string;
+/**
+ * A number as raw: period decimal, no grouping, never an exponent (`1e21`,
+ * `1e-7` print in full), at most `maxPrecision` fraction digits, no `-0`.
+ */
+export declare const rawOfNumber: (value: number, maxPrecision: number) => string;
+/**
+ * The number a raw string holds: `null` when empty, `undefined` while it holds
+ * no digit yet (`-`: the last valid value stands), else the number (`10.` is
+ * 10, `-0` is 0).
+ */
+export declare const valueOfRaw: (raw: string) => number | null | undefined;
+/**
+ * A legal formatted number in this locale, read the locale's way: group marks
+ * only where the locale puts them (lakh sizes included, any space for a
+ * space-grouping locale, any apostrophe for de-CH), the decimal mark as the
+ * decimal. Group positions only — not the minimum grouping digits, so it's
+ * `1.000` reads 1000 although it shows `1000`. `null` when the text is not one.
+ */
+export declare const parseLocaleText: (text: string, symbols: NumberSymbols) => string | null;
+/**
+ * Q51.2, today's forgiving reading of a whole fragment: both `.` and `,`
+ * present — the LAST one is the decimal, the rest group; one kind repeated —
+ * it groups; a single one — the decimal. Space- and apostrophe-like marks and
+ * the Arabic group mark group; the Arabic decimal mark is a decimal. A minus
+ * counts only before the first digit.
+ */
+export declare const parseLooseText: (text: string) => string;
+/**
+ * Text that may be a painted number — a paste, a drop, an undo, a restored
+ * or autofilled value, an outside `el.value` write: the number inside it
+ * (`numericCore`), then strict when it is a legal number in this locale,
+ * Q51.2 otherwise. A currency / unit field strips its shell first
+ * (`stripAffix`).
+ */
+export declare const readText: (text: string, symbols: NumberSymbols) => string;
+export interface EditState {
+    raw: string;
+    /** The key (`,` or `.`) that made the current decimal; '' when none or unknown. */
+    decChar: string;
+    /** A key the user has shown to mean grouping; '' when none. */
+    groupChar: string;
+}
+export interface EditOptions {
+    maxPrecision: number;
+    minPrecision: number;
+    /** The live clamp; `min` waits for blur / Enter. */
+    max: number;
+    /**
+     * The key a decimal set from outside counts as (owner Q6: as if the user
+     * had typed what the field shows): the locale's mark when it is `,` or `.`.
+     */
+    localeKey: string;
+}
+export type Edit = {
+    type: 'insert';
+    start: number;
+    end: number;
+    text: string;
+} | {
+    type: 'paste';
+    start: number;
+    end: number;
+    raw: string;
+} | {
+    type: 'deleteBackward';
+    start: number;
+    end: number;
+} | {
+    type: 'deleteForward';
+    start: number;
+    end: number;
+} | {
+    type: 'deleteToStart';
+    start: number;
+    end: number;
+} | {
+    type: 'deleteToEnd';
+    start: number;
+    end: number;
+};
+export interface EditResult extends EditState {
+    caret: number;
+    /** The edit changed nothing (a rejected keystroke). */
+    rejected: boolean;
+}
+/**
+ * One edit on the raw value. Selection ranges are raw indices. Deletes act on
+ * raw characters only — a group mark is never one, so Backspace after `1.|000`
+ * takes the `1`. With `minPrecision`, deleting a fraction digit inside the
+ * padded region turns it back into a `0` without shifting the rest, and the
+ * caret steps over the decimal mark instead of deleting it.
+ */
+export declare const applyEdit: (state: EditState, edit: Edit, options: EditOptions) => EditResult;
+/**
+ * With `minPrecision` the display always shows the decimal mark (`12` paints
+ * `12,00`), so raw holds it too (`12.`): a value set from outside, a typed
+ * `12` and a typed `12,` are then one state, and every key, caret and delete
+ * treats the painted mark and placeholders alike (war-room 82a72d539).
+ */
+export declare const withPaddedMark: (raw: string, minPrecision: number) => string;
+/**
+ * What the field shows at rest — on blur, and for a value set from outside:
+ * the number rebuilt from the model, so useless digits go (`1,50` → `1,5`,
+ * `10,` → `10`, `007` → `7`, `-0` → `0`), never rounded, trailing zeros kept
+ * down to `minPrecision`.
+ */
+export declare const rawAtRest: (value: number | null | undefined, maxPrecision: number) => string;
+/**
+ * Which span a regroup write replaces: the minimal changed range, or from the
+ * first change to the end. Internal (not package API): the screen-reader pass
+ * picks one (`100` → `1.000` minimally inserts `.0`, which may be read as
+ * "point zero"), so it stays switchable and the war-room caret suite runs
+ * under both (GROK-INGEST 9).
+ */
+export declare const writeStrategy: {
+    span: 'minimal' | 'tail';
+};