@inkra/react 0.2.0 → 0.3.0

package/dist/input-number/index.js

@@ -1,18 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
 import { Button } from '../Button.js';
 import { PencilIcon } from '../PencilIcon.js';
 import { Input } from '../form/Input.js';
 import { useResolvedControlProps } from '../form/controlProps.js';
 import { Tooltip } from '../tooltip/Tooltip.js';
+import { normalizeInputNumberRepeat, resolveInputNumberStep, stepInputNumber, } from './model.js';
 // Lucide Plus / Minus ISC geometry uses the shared pencil renderer.
 const plusPaths = [{ d: 'M5 12h14' }, { d: 'M12 5v14' }];
 const minusPaths = [{ d: 'M5 12h14' }];
 const finiteValue = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
 const format = (value) => String(finiteValue(value) ?? '');
 const numberFromDraft = (draft) => draft === '' ? null : finiteValue(Number(draft));
-export const InputNumber = forwardRef(function InputNumber({ classNames, controls = true, decrementButtonLabel = 'Decrease value', defaultValue, disabled, incrementButtonLabel = 'Increase value', inputMode = 'decimal', max, min, onChange, onValueChange, readOnly, size = 'md', step = 1, textAlign = 'center', value, ...props }, forwardedRef) {
+export const InputNumber = forwardRef(function InputNumber({ classNames, controls = true, decrementButtonLabel = 'Decrease value', defaultValue, disabled, incrementButtonLabel = 'Increase value', inputMode = 'decimal', max, min, onChange, onBlur, onKeyDown, onValueChange, pressAndHold = true, readOnly, repeatDelay = 400, repeatInterval = 80, size = 'md', step = 1, stepModifiers, textAlign = 'center', value, ...props }, forwardedRef) {
     const inputRef = useRef(null);
     const isControlled = value !== undefined;
     const [draft, setDraft] = useState(() => format(isControlled ? value : defaultValue));
@@ -21,6 +22,50 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
     const latest = useRef({ isControlled, value, defaultValue });
     latest.current = { isControlled, value, defaultValue };
     useImperativeHandle(forwardedRef, () => inputRef.current);
+    const holdRef = useRef(null);
+    const timerRef = useRef(undefined);
+    const suppressClickRef = useRef(false);
+    const stopHolding = useCallback(() => {
+        clearTimeout(timerRef.current);
+        timerRef.current = undefined;
+        const hold = holdRef.current;
+        holdRef.current = null;
+        if (hold?.button.hasPointerCapture?.(hold.pointerId)) {
+            try {
+                hold.button.releasePointerCapture(hold.pointerId);
+            }
+            catch { /* The pointer may already be inactive. */ }
+        }
+    }, []);
+    useEffect(() => {
+        const onVisibilityChange = () => { if (document.hidden)
+            stopHolding(); };
+        const onPointerEnd = (event) => {
+            if (event.pointerId === holdRef.current?.pointerId)
+                stopHolding();
+        };
+        const updateModifiers = (event) => {
+            if (holdRef.current)
+                holdRef.current.modifiers = {
+                    shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey,
+                };
+        };
+        window.addEventListener('blur', stopHolding);
+        window.addEventListener('pointerup', onPointerEnd);
+        window.addEventListener('pointercancel', onPointerEnd);
+        window.addEventListener('keydown', updateModifiers);
+        window.addEventListener('keyup', updateModifiers);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            stopHolding();
+            window.removeEventListener('blur', stopHolding);
+            window.removeEventListener('pointerup', onPointerEnd);
+            window.removeEventListener('pointercancel', onPointerEnd);
+            window.removeEventListener('keydown', updateModifiers);
+            window.removeEventListener('keyup', updateModifiers);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [stopHolding]);
     useBrowserLayoutEffect(() => {
         if (isControlled && currentValue !== finiteValue(value))
             setDraft(format(value));
@@ -32,6 +77,7 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
             return;
         let resetTimer;
         const reset = (event) => {
+            stopHolding();
             clearTimeout(resetTimer);
             // Native reset runs after the event; restore the public default, not the latest draft.
             resetTimer = setTimeout(() => {
@@ -45,33 +91,98 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
         };
         form.addEventListener('reset', reset);
         return () => { clearTimeout(resetTimer); form.removeEventListener('reset', reset); };
-    }, [props.form]);
+    }, [props.form, stopHolding]);
     const cannotStep = state.disabled || state.readOnly || step === 'any' || (min !== undefined && max !== undefined && min > max);
     const decreaseDisabled = cannotStep || (currentValue !== null && min !== undefined && currentValue <= min);
     const increaseDisabled = cannotStep || (currentValue !== null && max !== undefined && currentValue >= max);
-    function changeStep(direction) {
+    useBrowserLayoutEffect(() => {
+        const direction = holdRef.current?.direction;
+        if (cannotStep || !controls || !pressAndHold
+            || (direction === 'increment' && increaseDisabled)
+            || (direction === 'decrement' && decreaseDisabled))
+            stopHolding();
+    }, [cannotStep, controls, decreaseDisabled, increaseDisabled, pressAndHold, stopHolding]);
+    function changeStep(direction, modifiers) {
         const input = inputRef.current;
         if (!input || input.matches(':disabled') || input.readOnly || cannotStep)
-            return;
-        const before = input.value;
-        // Native stepping applies the step base and decimal rounding without a custom parser.
-        if (direction === 'increment')
-            input.stepUp();
-        else
-            input.stepDown();
+            return false;
+        const changed = stepInputNumber(input, direction, resolveInputNumberStep(modifiers, stepModifiers));
         input.focus({ preventScroll: true });
-        if (input.value === before)
-            return;
+        if (!changed)
+            return false;
         setDraft(input.value);
         onValueChange?.(Number.isFinite(input.valueAsNumber) ? input.valueAsNumber : null, { reason: direction });
+        return true;
+    }
+    const stepRef = useRef(changeStep);
+    stepRef.current = changeStep;
+    const intervalRef = useRef(repeatInterval);
+    intervalRef.current = repeatInterval;
+    function startHolding(event, direction) {
+        if (event.button !== 0 || !event.isPrimary)
+            return;
+        event.preventDefault();
+        stopHolding();
+        suppressClickRef.current = false;
+        if (!pressAndHold)
+            return;
+        suppressClickRef.current = true;
+        const modifiers = {
+            shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey,
+        };
+        if (!changeStep(direction, modifiers))
+            return;
+        const button = event.currentTarget;
+        if (!button.isConnected || button.disabled)
+            return;
+        holdRef.current = { button, pointerId: event.pointerId, direction, modifiers };
+        try {
+            button.setPointerCapture(event.pointerId);
+        }
+        catch { /* Window listeners retain release handling. */ }
+        const repeat = () => {
+            const hold = holdRef.current;
+            if (!hold || document.hidden || !stepRef.current(hold.direction, hold.modifiers)) {
+                stopHolding();
+                return;
+            }
+            if (holdRef.current)
+                timerRef.current = setTimeout(repeat, normalizeInputNumberRepeat(intervalRef.current, 80, 32));
+        };
+        timerRef.current = setTimeout(repeat, normalizeInputNumberRepeat(repeatDelay, 400, 150));
+    }
+    function buttonEvents(direction) {
+        return {
+            onPointerDown: (event) => startHolding(event, direction),
+            onPointerUp: stopHolding,
+            onPointerCancel: stopHolding,
+            onLostPointerCapture: stopHolding,
+            onBlur: stopHolding,
+            onClick: (event) => {
+                if (event.detail > 0 && suppressClickRef.current) {
+                    suppressClickRef.current = false;
+                    return;
+                }
+                suppressClickRef.current = false;
+                changeStep(direction, event);
+            },
+        };
     }
     const iconSize = size === 'sm' ? 18 : size === 'lg' ? 26 : 22;
     const buttonSize = size === 'sm' ? 'icon-sm' : size === 'lg' ? 'icon-lg' : 'icon';
-    return _jsx(Input, { ...props, ref: inputRef, type: "number", inputMode: inputMode, textAlign: textAlign, clearable: false, size: size, min: min, max: max, step: step, disabled: state.disabled, readOnly: state.readOnly, value: draft, classNames: { ...classNames, root: ['inkra-input-number', classNames?.root].filter(Boolean).join(' ') }, onChange: event => {
+    return _jsx(Input, { ...props, ref: inputRef, type: "number", inputMode: inputMode, textAlign: textAlign, clearable: false, size: size, min: min, max: max, step: step, disabled: state.disabled, readOnly: state.readOnly, value: draft, classNames: { ...classNames, root: ['inkra-input-number', classNames?.root].filter(Boolean).join(' ') }, onBlur: event => { stopHolding(); onBlur?.(event); }, onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || event.nativeEvent.isComposing || (event.key !== 'ArrowUp' && event.key !== 'ArrowDown'))
+                return;
+            if (resolveInputNumberStep(event, stepModifiers) === undefined)
+                return;
+            event.preventDefault();
+            changeStep(event.key === 'ArrowUp' ? 'increment' : 'decrement', event);
+        }, onChange: event => {
             const input = event.currentTarget;
             const nextValue = Number.isFinite(input.valueAsNumber) ? input.valueAsNumber : null;
             setDraft(input.value);
             onChange?.(event);
             onValueChange?.(nextValue, { reason: 'input' });
-        }, startAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: decreaseDisabled, "aria-label": decrementButtonLabel, onPointerDown: event => event.preventDefault(), onClick: () => changeStep('decrement'), children: _jsx(PencilIcon, { paths: minusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: decrementButtonLabel }) })] }) }) }) : undefined, endAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: increaseDisabled, "aria-label": incrementButtonLabel, onPointerDown: event => event.preventDefault(), onClick: () => changeStep('increment'), children: _jsx(PencilIcon, { paths: plusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: incrementButtonLabel }) })] }) }) }) : undefined });
+        }, startAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: decreaseDisabled, "aria-label": decrementButtonLabel, ...buttonEvents('decrement'), children: _jsx(PencilIcon, { paths: minusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: decrementButtonLabel }) })] }) }) }) : undefined, endAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: increaseDisabled, "aria-label": incrementButtonLabel, ...buttonEvents('increment'), children: _jsx(PencilIcon, { paths: plusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: incrementButtonLabel }) })] }) }) }) : undefined });
 });

package/dist/input-number/model.d.ts

@@ -0,0 +1,13 @@
+export interface InputNumberStepModifier {
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    step: number;
+}
+export type InputNumberModifierState = Pick<KeyboardEvent, 'shiftKey' | 'altKey' | 'ctrlKey' | 'metaKey'>;
+export type InputNumberStepDirection = 'increment' | 'decrement';
+export declare const defaultInputNumberStepModifiers: readonly InputNumberStepModifier[];
+export declare function resolveInputNumberStep(modifiers: InputNumberModifierState, rules?: readonly InputNumberStepModifier[]): number | undefined;
+export declare function normalizeInputNumberRepeat(value: number | undefined, fallback: number, minimum: number): number;
+export declare function stepInputNumber(input: HTMLInputElement, direction: InputNumberStepDirection, modifierStep?: number): boolean;

package/dist/input-number/model.js

@@ -0,0 +1,50 @@
+export const defaultInputNumberStepModifiers = [
+    { shiftKey: true, step: 10 },
+];
+export function resolveInputNumberStep(modifiers, rules = defaultInputNumberStepModifiers) {
+    return rules.find(rule => Number.isFinite(rule.step) && rule.step > 0
+        && Boolean(rule.shiftKey) === modifiers.shiftKey
+        && Boolean(rule.altKey) === modifiers.altKey
+        && Boolean(rule.ctrlKey) === modifiers.ctrlKey
+        && Boolean(rule.metaKey) === modifiers.metaKey)?.step;
+}
+export function normalizeInputNumberRepeat(value, fallback, minimum) {
+    return value === undefined || !Number.isFinite(value)
+        ? fallback
+        : Math.min(60000, Math.max(minimum, value));
+}
+export function stepInputNumber(input, direction, modifierStep) {
+    const before = input.value;
+    const min = input.min === '' ? -Infinity : Number(input.min);
+    const max = input.max === '' ? Infinity : Number(input.max);
+    if (input.disabled || input.readOnly || input.step === 'any' || min > max)
+        return false;
+    if ((direction === 'increment' && input.valueAsNumber >= max)
+        || (direction === 'decrement' && input.valueAsNumber <= min))
+        return false;
+    if (modifierStep === undefined) {
+        if (direction === 'increment')
+            input.stepUp();
+        else
+            input.stepDown();
+    }
+    else {
+        // A detached native input anchors the step base at the current value, so
+        // modifier steps are absolute deltas without floating-point arithmetic.
+        const probe = input.cloneNode(false);
+        probe.removeAttribute('min');
+        probe.removeAttribute('max');
+        probe.step = String(modifierStep);
+        probe.defaultValue = before || '0';
+        probe.value = before;
+        if (direction === 'increment')
+            probe.stepUp();
+        else
+            probe.stepDown();
+        const next = probe.valueAsNumber;
+        if (!Number.isFinite(next))
+            return false;
+        input.value = String(Math.min(Number.isFinite(max) ? max : Infinity, Math.max(Number.isFinite(min) ? min : -Infinity, next)));
+    }
+    return before !== input.value;
+}

package/dist/number-ticker/index.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-import type { NumberTickerLocale } from './model.js';
+import type { NumberTickerCompact, NumberTickerCompactOptions, NumberTickerFormatOptions, NumberTickerLocale, NumberTickerValue } from './model.js';
 export interface NumberTickerRenderDetails {
     animating: boolean;
     formattedValue: string;
@@ -9,21 +9,23 @@ export interface NumberTickerDeltaDetails {
     formattedDelta: string;
 }
 export interface NumberTickerProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'prefix'> {
-    value: number;
+    value: NumberTickerValue;
     locale?: NumberTickerLocale;
-    formatOptions?: Intl.NumberFormatOptions;
+    formatOptions?: NumberTickerFormatOptions;
+    compact?: NumberTickerCompact;
+    compactOptions?: NumberTickerCompactOptions;
     prefix?: ReactNode;
     suffix?: ReactNode;
-    renderValue?: (value: number, details: NumberTickerRenderDetails) => ReactNode;
-    getValueLabel?: (value: number, formattedValue: string) => string;
+    renderValue?: (value: NumberTickerValue, details: NumberTickerRenderDetails) => ReactNode;
+    getValueLabel?: (value: NumberTickerValue, formattedValue: string) => string;
     animate?: boolean;
     duration?: number;
     easing?: (progress: number) => number;
     showDelta?: boolean;
     deltaDuration?: number;
-    deltaFormatOptions?: Intl.NumberFormatOptions;
-    renderDelta?: (delta: number, details: NumberTickerDeltaDetails) => ReactNode;
+    deltaFormatOptions?: NumberTickerFormatOptions;
+    renderDelta?: (delta: NumberTickerValue, details: NumberTickerDeltaDetails) => ReactNode;
 }
 export declare const NumberTicker: import("react").ForwardRefExoticComponent<NumberTickerProps & import("react").RefAttributes<HTMLSpanElement>>;
-export { createNumberFormatter, easeOutCubic, formatTickerDelta, formatTickerValue, interpolateTickerValue, } from './model.js';
-export type { NumberTickerLocale } from './model.js';
+export { createNumberFormatter, easeOutCubic, formatTickerDelta, formatTickerValue, interpolateTickerValue, numberTickerUnits, } from './model.js';
+export type { NumberTickerCompact, NumberTickerCompactOptions, NumberTickerFormatOptions, NumberTickerLocale, NumberTickerUnit, NumberTickerValue } from './model.js';

package/dist/number-ticker/index.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState, } from 'react';
 import { PencilText } from '../PencilText.js';
 import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
-import { canAnimateTickerValue, createNumberFormatter, easeOutCubic, formatTickerDelta, formatTickerValue, interpolateTickerValue, tickerValueChanged, } from './model.js';
+import { canAnimateTickerValue, createNumberFormatter, createTickerFormatter, easeOutCubic, formatDerivedTickerDelta, formatTickerValue, interpolateTickerValue, tickerValueChanged, subtractTickerValues, tickerValueKey, } from './model.js';
+import { ExactDecimal } from './precision.js';
 function usePrefersReducedMotion() {
     const [reduced, setReduced] = useState(false);
     useBrowserLayoutEffect(() => {
@@ -22,7 +23,7 @@ function lettering(content, seed) {
 function accessibleAffix(content) {
     return typeof content === 'string' || typeof content === 'number' ? String(content) : '';
 }
-export const NumberTicker = forwardRef(function NumberTicker({ animate = true, className, deltaDuration = 1600, deltaFormatOptions, duration = 420, easing = easeOutCubic, formatOptions, getValueLabel, locale, prefix, renderDelta, renderValue, showDelta = false, suffix, value, ...props }, forwardedRef) {
+export const NumberTicker = forwardRef(function NumberTicker({ animate = true, className, compact = false, compactOptions, deltaDuration = 1600, deltaFormatOptions, duration = 420, easing = easeOutCubic, formatOptions, getValueLabel, locale, prefix, renderDelta, renderValue, showDelta = false, suffix, value, ...props }, forwardedRef) {
     const rootRef = useRef(null);
     const frameRef = useRef(null);
     const deltaTimerRef = useRef(null);
@@ -35,15 +36,17 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
     const reducedMotion = usePrefersReducedMotion();
     const localeKey = Array.isArray(locale) ? locale.join('\u0000') : locale;
     const formatOptionsKey = JSON.stringify(formatOptions ?? {});
+    const compactOptionsKey = tickerValueKey(compactOptions ?? {});
     const deltaFormatOptionsKey = JSON.stringify(deltaFormatOptions ?? formatOptions ?? {});
-    const formatter = useMemo(() => createNumberFormatter(locale, formatOptions), [localeKey, formatOptionsKey]);
-    const deltaFormatter = useMemo(() => createNumberFormatter(locale, deltaFormatOptions ?? formatOptions), [localeKey, deltaFormatOptionsKey]);
+    const formatter = useMemo(() => createTickerFormatter(locale, formatOptions, compact, compactOptions), [localeKey, formatOptionsKey, compact, compactOptionsKey]);
+    const deltaFormatter = useMemo(() => createTickerFormatter(locale, deltaFormatOptions ?? formatOptions, compact, compactOptions), [localeKey, deltaFormatOptionsKey, compact, compactOptionsKey]);
+    const announcementFormatter = useMemo(() => createNumberFormatter(locale, compact ? { ...formatOptions, notation: 'standard' } : formatOptions), [localeKey, formatOptionsKey, compact]);
     useImperativeHandle(forwardedRef, () => rootRef.current);
     useBrowserLayoutEffect(() => {
         const previousTarget = targetRef.current;
         targetRef.current = value;
-        if (showDelta && tickerValueChanged(previousTarget, value) && Number.isFinite(previousTarget) && Number.isFinite(value)) {
-            const nextDelta = value - previousTarget;
+        if (showDelta && tickerValueChanged(previousTarget, value)) {
+            const nextDelta = subtractTickerValues(value, previousTarget);
             setDelta(nextDelta);
             if (deltaTimerRef.current !== null)
                 clearTimeout(deltaTimerRef.current);
@@ -109,7 +112,7 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
     }, []);
     const formattedValue = formatTickerValue(formatter, displayedValue);
     const finalFormattedValue = formatTickerValue(formatter, value);
-    const announcedFormattedValue = formatTickerValue(formatter, announcedValue);
+    const announcedFormattedValue = formatTickerValue(announcementFormatter, announcedValue);
     const defaultAccessibleLabel = [accessibleAffix(prefix), announcedFormattedValue, accessibleAffix(suffix)]
         .filter(Boolean).join(' ');
     const accessibleLabel = getValueLabel?.(announcedValue, announcedFormattedValue) ?? defaultAccessibleLabel;
@@ -118,15 +121,15 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
             ? _jsx("span", { className: "inkra-number-ticker__native-value", children: formattedValue })
             : _jsx(PencilText, { seed: `number-ticker-${finalFormattedValue}`, children: finalFormattedValue }));
     const deltaContent = delta === null ? null : (() => {
-        const formattedDelta = formatTickerDelta(deltaFormatter, delta);
+        const formattedDelta = formatDerivedTickerDelta(deltaFormatter, delta);
         const details = {
-            direction: delta < 0 ? 'decrease' : 'increase',
+            direction: new ExactDecimal(String(delta)).lt(0) ? 'decrease' : 'increase',
             formattedDelta,
         };
         return renderDelta?.(delta, details) ?? _jsx(PencilText, { seed: `number-ticker-delta-${formattedDelta}`, children: formattedDelta });
     })();
     const classes = ['inkra-number-ticker', animating && 'inkra-number-ticker--animating', className]
         .filter(Boolean).join(' ');
-    return _jsxs("span", { ...props, className: classes, ref: rootRef, "data-animating": animating || undefined, children: [_jsxs("span", { "aria-hidden": "true", className: "inkra-number-ticker__visual", children: [prefix !== undefined && _jsx("span", { className: "inkra-number-ticker__prefix", children: lettering(prefix, 'number-ticker-prefix') }), _jsx("span", { className: "inkra-number-ticker__value", children: valueContent }), suffix !== undefined && _jsx("span", { className: "inkra-number-ticker__suffix", children: lettering(suffix, 'number-ticker-suffix') }), deltaContent !== null && _jsx("span", { className: "inkra-number-ticker__delta", "data-direction": delta < 0 ? 'decrease' : 'increase', children: deltaContent })] }), _jsx("span", { className: "inkra-number-ticker__announcement", "aria-atomic": "true", "aria-live": "polite", children: accessibleLabel })] });
+    return _jsxs("span", { ...props, className: classes, ref: rootRef, "data-animating": animating || undefined, children: [_jsxs("span", { "aria-hidden": "true", className: "inkra-number-ticker__visual", children: [prefix !== undefined && _jsx("span", { className: "inkra-number-ticker__prefix", children: lettering(prefix, 'number-ticker-prefix') }), _jsx("span", { className: "inkra-number-ticker__value", children: valueContent }), suffix !== undefined && _jsx("span", { className: "inkra-number-ticker__suffix", children: lettering(suffix, 'number-ticker-suffix') }), deltaContent !== null && _jsx("span", { className: "inkra-number-ticker__delta", "data-direction": new ExactDecimal(String(delta)).lt(0) ? 'decrease' : 'increase', children: deltaContent })] }), _jsx("span", { className: "inkra-number-ticker__announcement", "aria-atomic": "true", "aria-live": "polite", children: accessibleLabel })] });
 });
-export { createNumberFormatter, easeOutCubic, formatTickerDelta, formatTickerValue, interpolateTickerValue, } from './model.js';
+export { createNumberFormatter, easeOutCubic, formatTickerDelta, formatTickerValue, interpolateTickerValue, numberTickerUnits, } from './model.js';

package/dist/number-ticker/model.d.ts

@@ -1,8 +1,41 @@
+import { tickerDecimal } from './precision.js';
+import type { NumberTickerValue } from './precision.js';
+export { subtractTickerValues, tickerValueKey } from './precision.js';
+export type { NumberTickerValue } from './precision.js';
 export type NumberTickerLocale = string | readonly string[];
-export declare function createNumberFormatter(locale?: NumberTickerLocale, options?: Intl.NumberFormatOptions): Intl.NumberFormat;
-export declare function formatTickerValue(formatter: Intl.NumberFormat, value: number): string;
-export declare function formatTickerDelta(formatter: Intl.NumberFormat, delta: number): string;
+export type NumberTickerCompact = boolean | 'en' | 'zh';
+export interface NumberTickerFormatOptions extends Intl.NumberFormatOptions {
+    roundingMode?: 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven';
+}
+export interface NumberTickerUnit {
+    factor: NumberTickerValue;
+    label: string;
+    /** Absolute display magnitude required to enter this unit. */
+    threshold?: NumberTickerValue;
+}
+export interface NumberTickerCompactOptions {
+    units?: readonly NumberTickerUnit[];
+    minUnit?: string;
+    maxUnit?: string;
+    separator?: string;
+    promotionThreshold?: NumberTickerValue;
+    promoteAfterRounding?: boolean;
+    overflow?: 'unit' | 'scientific';
+}
+export declare const numberTickerUnits: Readonly<Record<'en' | 'zh', readonly NumberTickerUnit[]>>;
+type TickerFormatter = {
+    format(value: NumberTickerValue): string;
+    formatToParts(value: NumberTickerValue): Intl.NumberFormatPart[];
+    formatDecimal(value: ReturnType<typeof tickerDecimal>): Intl.NumberFormatPart[];
+};
+export declare function createNumberFormatter(locale?: NumberTickerLocale, options?: NumberTickerFormatOptions): Intl.NumberFormat;
+export declare function createTickerFormatter(locale?: NumberTickerLocale, options?: NumberTickerFormatOptions, compact?: NumberTickerCompact, compactOptions?: NumberTickerCompactOptions): TickerFormatter;
+export declare function formatTickerValue(formatter: TickerFormatter | Intl.NumberFormat, value: NumberTickerValue): string;
+export declare function formatTickerDelta(formatter: TickerFormatter | Intl.NumberFormat, delta: NumberTickerValue): string;
+export declare function formatDerivedTickerDelta(formatter: TickerFormatter, delta: NumberTickerValue): string;
 export declare function interpolateTickerValue(from: number, to: number, progress: number): number;
-export declare function tickerValueChanged(previous: number, next: number): boolean;
-export declare function canAnimateTickerValue(from: number, to: number, duration: number): boolean;
+export declare function interpolateTickerValue(from: bigint, to: bigint, progress: number): bigint;
+export declare function interpolateTickerValue(from: NumberTickerValue, to: NumberTickerValue, progress: number): NumberTickerValue;
+export declare function tickerValueChanged(previous: NumberTickerValue, next: NumberTickerValue): boolean;
+export declare function canAnimateTickerValue(from: NumberTickerValue, to: NumberTickerValue, duration: number): boolean;
 export declare function easeOutCubic(progress: number): number;

package/dist/number-ticker/model.js

@@ -1,29 +1,158 @@
+import { ExactDecimal, formatExactParts, tickerDecimal } from './precision.js';
+export { subtractTickerValues, tickerValueKey } from './precision.js';
+export const numberTickerUnits = {
+    en: ['K', 'M', 'B', 'T', 'Qa', 'Qi', 'Sx', 'Sp', 'Oc', 'No', 'Dc']
+        .map((label, index) => ({ label, factor: Number(`1e${(index + 1) * 3}`) })),
+    zh: [{ label: '千', factor: 1e3 }, ...['万', '亿', '兆', '京', '垓', '秭', '穰', '沟', '涧', '正', '载', '极', '恒河沙', '阿僧祇', '那由他', '不可思议', '无量大数']
+            .map((label, index) => ({ label, factor: Number(`1e${(index + 1) * 4}`) }))],
+};
 export function createNumberFormatter(locale = 'en-US', options) {
-    return new Intl.NumberFormat(locale, options);
+    const formatter = new Intl.NumberFormat(locale, options);
+    if (options?.roundingMode && options.roundingMode !== 'halfExpand' && !('roundingMode' in formatter.resolvedOptions())) {
+        throw new RangeError('NumberTicker roundingMode requires Intl.NumberFormat rounding support');
+    }
+    return formatter;
+}
+export function createTickerFormatter(locale = 'en-US', options, compact = false, compactOptions = {}) {
+    if (!compact || options?.notation === 'scientific' || options?.notation === 'engineering') {
+        const native = createNumberFormatter(locale, options);
+        const formatToParts = (value) => formatExactParts(native, value);
+        return { formatToParts, formatDecimal: value => formatExactParts(native, value), format: value => formatToParts(value).map(part => part.value).join('') };
+    }
+    const precision = {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: Math.max(1, options?.minimumFractionDigits ?? 0),
+        ...options,
+        notation: 'standard',
+    };
+    const formatter = createNumberFormatter(locale, precision);
+    const language = compact === true
+        ? (formatter.resolvedOptions().locale.startsWith('zh') ? 'zh' : 'en')
+        : compact;
+    const multiplier = tickerDecimal(compactOptions.promotionThreshold ?? 1);
+    if (!multiplier.gt(0) || !multiplier.isFinite())
+        throw new RangeError('promotionThreshold must be positive and finite');
+    const supplied = [...(compactOptions.units ?? numberTickerUnits[language])]
+        .map(unit => ({ ...unit, factor: tickerDecimal(unit.factor), threshold: unit.threshold === undefined ? undefined : tickerDecimal(unit.threshold) }))
+        .sort((a, b) => a.factor.cmp(b.factor));
+    const labels = new Set();
+    let previousFactor = tickerDecimal(1);
+    let previousThreshold = tickerDecimal(0);
+    for (const unit of supplied) {
+        const threshold = unit.threshold ?? unit.factor.times(multiplier);
+        if (!unit.label.trim() || labels.has(unit.label) || !unit.factor.isFinite() || unit.factor.lte(previousFactor)
+            || !threshold.isFinite() || threshold.lte(previousThreshold)) {
+            throw new RangeError('Compact units need unique nonempty labels, increasing finite factors > 1 and positive increasing thresholds');
+        }
+        labels.add(unit.label);
+        previousFactor = unit.factor;
+        previousThreshold = threshold;
+    }
+    const units = [{ factor: tickerDecimal(1), label: '', threshold: undefined }, ...supplied];
+    const indexFor = (label, fallback) => {
+        if (label === undefined)
+            return fallback;
+        const index = units.findIndex(unit => unit.label === label);
+        if (index < 0)
+            throw new RangeError(`Unknown compact unit: ${label}`);
+        return index;
+    };
+    const minIndex = indexFor(compactOptions.minUnit, 0);
+    const maxIndex = indexFor(compactOptions.maxUnit, units.length - 1);
+    if (minIndex > maxIndex)
+        throw new RangeError('minUnit must not exceed maxUnit');
+    const thresholdFor = (index) => units[index].threshold ?? units[index].factor.times(multiplier);
+    const last = units[maxIndex];
+    const overflowThreshold = maxIndex + 1 < units.length ? thresholdFor(maxIndex + 1)
+        : thresholdFor(maxIndex).times(maxIndex > 0 ? last.factor.div(units[maxIndex - 1].factor) : 1000);
+    const overflow = compactOptions.overflow ?? (compactOptions.maxUnit !== undefined ? 'unit' : 'scientific');
+    const scientific = createNumberFormatter(locale, { ...precision, notation: 'scientific' });
+    const rounding = createNumberFormatter('en-US', {
+        ...precision, style: 'decimal', numberingSystem: 'latn', useGrouping: false,
+    });
+    const percentScale = options?.style === 'percent' ? 100 : 1;
+    const formatDecimal = (exact) => {
+        if (!exact.isFinite())
+            return formatExactParts(formatter, exact);
+        let index = minIndex;
+        const reaches = (threshold) => {
+            if (compactOptions.promoteAfterRounding === false)
+                return exact.abs().times(percentScale).gte(threshold);
+            const scaled = exact.div(units[index].factor).times(percentScale);
+            const rounded = formatExactParts(rounding, scaled).map(part => part.value).join('');
+            return new ExactDecimal(rounded).abs().times(units[index].factor).gte(threshold);
+        };
+        while (index < maxIndex) {
+            if (!reaches(thresholdFor(index + 1)))
+                break;
+            index++;
+        }
+        if (index === maxIndex && overflow === 'scientific' && reaches(overflowThreshold))
+            return formatExactParts(scientific, exact);
+        const { factor, label } = units[index];
+        const parts = formatExactParts(formatter, exact.div(factor));
+        if (label) {
+            let insertion = parts.length;
+            while (insertion > 0 && !['integer', 'fraction'].includes(parts[insertion - 1].type))
+                insertion--;
+            const separator = compactOptions.separator ?? ' ';
+            parts.splice(insertion, 0, ...(separator ? [{ type: 'literal', value: separator }] : []), { type: 'compact', value: label });
+        }
+        return parts;
+    };
+    const formatToParts = (value) => formatDecimal(tickerDecimal(value));
+    return { formatToParts, formatDecimal, format: value => formatToParts(value).map(part => part.value).join('') };
 }
 export function formatTickerValue(formatter, value) {
-    return formatter.format(value);
+    return formatter instanceof Intl.NumberFormat ? formatExactParts(formatter, value).map(part => part.value).join('') : formatter.format(value);
 }
 export function formatTickerDelta(formatter, delta) {
-    const sign = delta > 0 ? '+' : delta < 0 ? '\u2212' : '';
-    const magnitude = formatter.formatToParts(Math.abs(delta))
+    const exact = tickerDecimal(delta);
+    return formatDecimalDelta(formatter, exact);
+}
+// Deltas are derived from validated inputs and can legitimately exceed input bounds.
+export function formatDerivedTickerDelta(formatter, delta) {
+    return formatDecimalDelta(formatter, new ExactDecimal(String(delta)));
+}
+function formatDecimalDelta(formatter, exact) {
+    const sign = exact.gt(0) ? '+' : exact.lt(0) ? '\u2212' : '';
+    const magnitude = (formatter instanceof Intl.NumberFormat ? formatExactParts(formatter, exact) : formatter.formatDecimal(exact))
         .filter(part => part.type !== 'plusSign' && part.type !== 'minusSign')
+        .filter(part => part.type !== 'literal' || !/^[()]$/.test(part.value))
         .map(part => part.value)
         .join('');
     return `${sign}${magnitude}`;
 }
 export function interpolateTickerValue(from, to, progress) {
-    if (!Number.isFinite(from) || !Number.isFinite(to))
+    if (!tickerDecimal(from).isFinite() || !tickerDecimal(to).isFinite())
         return to;
-    const boundedProgress = Math.min(1, Math.max(0, progress));
-    return from + (to - from) * boundedProgress;
+    const boundedProgress = Number.isFinite(progress) ? Math.min(1, Math.max(0, progress)) : 1;
+    if (boundedProgress === 0)
+        return from;
+    if (boundedProgress === 1)
+        return to;
+    if (typeof from === 'number' && typeof to === 'number') {
+        const distance = to - from;
+        return Number.isFinite(distance) ? from + distance * boundedProgress
+            : from * (1 - boundedProgress) + to * boundedProgress;
+    }
+    const start = tickerDecimal(from);
+    const next = start.plus(tickerDecimal(to).minus(start).times(String(boundedProgress)));
+    return typeof from === 'bigint' && typeof to === 'bigint' ? BigInt(next.trunc().toFixed(0)) : next.toString();
 }
 export function tickerValueChanged(previous, next) {
-    return !Object.is(previous, next);
+    if (Object.is(previous, next))
+        return false;
+    const before = tickerDecimal(previous);
+    const after = tickerDecimal(next);
+    return !before.eq(after) || (before.isZero() && before.isNegative() !== after.isNegative());
 }
 export function canAnimateTickerValue(from, to, duration) {
-    return Number.isFinite(from)
-        && Number.isFinite(to)
+    const start = tickerDecimal(from);
+    const end = tickerDecimal(to);
+    return start.isFinite() && end.isFinite()
+        && typeof from === typeof to
+        && (typeof to === 'number' || (Math.max(start.sd(), end.sd(), Math.abs(start.e - end.e)) <= 512))
         && Number.isFinite(duration)
         && duration > 0
         && tickerValueChanged(from, to);

package/dist/number-ticker/precision.d.ts

@@ -0,0 +1,7 @@
+import { Decimal } from 'decimal.js';
+export type NumberTickerValue = number | bigint | string;
+export declare const ExactDecimal: typeof Decimal;
+export declare function tickerDecimal(value: NumberTickerValue): Decimal;
+export declare function tickerValueKey(value: unknown): string;
+export declare function formatExactParts(formatter: Intl.NumberFormat, value: NumberTickerValue | Decimal): Intl.NumberFormatPart[];
+export declare function subtractTickerValues(next: NumberTickerValue, previous: NumberTickerValue): NumberTickerValue | null;