@inkra/react 0.6.0 → 0.9.0

package/dist/loading/model.js

@@ -0,0 +1,29 @@
+export function finiteDuration(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : fallback;
+}
+export function normalizeLoadingMax(max) {
+    return typeof max === 'number' && Number.isFinite(max) && max > 0 ? max : 100;
+}
+export function normalizeLoadingProgress(value, max) {
+    if (value == null)
+        return value;
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(max, value));
+}
+export function normalizeTipIndex(index, length) {
+    if (length <= 0)
+        return 0;
+    if (typeof index !== 'number' || !Number.isFinite(index))
+        return 0;
+    return ((Math.trunc(index) % length) + length) % length;
+}
+export function nextTipIndex(current, length, order, random = Math.random) {
+    if (length <= 1)
+        return 0;
+    const normalized = normalizeTipIndex(current, length);
+    if (order === 'sequence')
+        return (normalized + 1) % length;
+    const offset = Math.min(length - 2, Math.max(0, Math.floor(random() * (length - 1))));
+    return (normalized + 1 + offset) % length;
+}

package/dist/masonry/index.d.ts

@@ -0,0 +1,25 @@
+import type { HTMLAttributes, ReactElement, ReactNode, RefAttributes } from 'react';
+import { type MasonryDirection, type MasonryStrategy } from './layout.js';
+export type MasonryKey = string | number | bigint;
+export interface MasonryRenderState<Item> {
+    item: Item;
+    index: number;
+    key: MasonryKey;
+}
+export type MasonryItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'style'>;
+export interface MasonryProps<Item> extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    items: readonly Item[];
+    getItemKey: (item: Item, index: number) => MasonryKey;
+    renderItem: (state: MasonryRenderState<Item>) => ReactNode;
+    getItemProps?: (state: MasonryRenderState<Item>) => MasonryItemProps;
+    columns?: number | 'auto';
+    minColumnWidth?: number;
+    maxColumns?: number;
+    columnGap?: number;
+    rowGap?: number;
+    strategy?: MasonryStrategy;
+    dir?: MasonryDirection;
+    animated?: boolean;
+}
+export declare const Masonry: <Item>(props: MasonryProps<Item> & RefAttributes<HTMLDivElement>) => ReactElement | null;
+export type { MasonryDirection, MasonryStrategy } from './layout.js';

package/dist/masonry/index.js

@@ -0,0 +1,227 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createElement as _createElement } from "react";
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
+import { calculateMasonryLayout, normalizeMasonryColumnCount, normalizeMasonrySpacing, } from './layout.js';
+function classes(...values) {
+    return values.filter(Boolean).join(' ');
+}
+function internalItemKey(key) {
+    return `${typeof key}:${String(key)}`;
+}
+function assignRef(ref, value) {
+    if (typeof ref === 'function')
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+function cssPixels(value) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function samePositions(current, next) {
+    if (current.size !== next.length)
+        return false;
+    return next.every(position => {
+        const existing = current.get(position.key);
+        return existing !== undefined
+            && existing.column === position.column
+            && Math.abs(existing.x - position.x) < 0.25
+            && Math.abs(existing.y - position.y) < 0.25
+            && Math.abs(existing.width - position.width) < 0.25
+            && Math.abs(existing.height - position.height) < 0.25;
+    });
+}
+function emptyLayout(signature) {
+    return { signature, columnCount: 1, height: 0, positions: new Map(), ready: false };
+}
+function MasonryInner({ animated = true, className, columnGap = 16, columns = 'auto', dir, getItemKey, getItemProps, items, maxColumns, minColumnWidth = 240, renderItem, role, rowGap = 16, strategy = 'shortest', style, ...props }, forwardedRef) {
+    const rootRef = useRef(null);
+    const itemRefs = useRef(new Map());
+    const frameRef = useRef(null);
+    const safeColumnGap = normalizeMasonrySpacing(columnGap, 16);
+    const safeRowGap = normalizeMasonrySpacing(rowGap, 16);
+    const safeMinColumnWidth = Number.isFinite(minColumnWidth) && minColumnWidth > 0
+        ? minColumnWidth
+        : 240;
+    const safeMaxColumns = maxColumns === undefined
+        ? undefined
+        : Number.isFinite(maxColumns)
+            ? normalizeMasonryColumnCount(maxColumns)
+            : undefined;
+    const fixedColumns = columns === 'auto' ? undefined : normalizeMasonryColumnCount(columns);
+    const entries = useMemo(() => {
+        const next = items.map((item, index) => {
+            const key = getItemKey(item, index);
+            return { item, index, key, internalKey: internalItemKey(key) };
+        });
+        const keys = new Set();
+        for (const entry of next) {
+            if (keys.has(entry.internalKey)) {
+                throw new Error(`Masonry item keys must be unique. Received duplicate key: ${String(entry.key)}`);
+            }
+            keys.add(entry.internalKey);
+        }
+        return next;
+    }, [getItemKey, items]);
+    const signature = useMemo(() => JSON.stringify([
+        fixedColumns ?? 'auto',
+        safeMinColumnWidth,
+        safeMaxColumns ?? null,
+        safeColumnGap,
+        safeRowGap,
+        strategy,
+        dir ?? null,
+    ]), [
+        dir,
+        fixedColumns,
+        safeColumnGap,
+        safeMaxColumns,
+        safeMinColumnWidth,
+        safeRowGap,
+        strategy,
+    ]);
+    const [layout, setLayout] = useState(() => emptyLayout(signature));
+    const effectiveLayout = layout.signature === signature ? layout : emptyLayout(signature);
+    const ready = effectiveLayout.ready && entries.every(entry => effectiveLayout.positions.has(entry.internalKey));
+    const setRootRef = useCallback((node) => {
+        rootRef.current = node;
+        assignRef(forwardedRef, node);
+    }, [forwardedRef]);
+    const setItemRef = useCallback((key, node) => {
+        if (node)
+            itemRefs.current.set(key, node);
+        else
+            itemRefs.current.delete(key);
+    }, []);
+    const updateLayout = useCallback(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const rootStyle = getComputedStyle(root);
+        const paddingLeft = cssPixels(rootStyle.paddingLeft);
+        const paddingRight = cssPixels(rootStyle.paddingRight);
+        const paddingTop = cssPixels(rootStyle.paddingTop);
+        const paddingBottom = cssPixels(rootStyle.paddingBottom);
+        const borderTop = cssPixels(rootStyle.borderTopWidth);
+        const borderBottom = cssPixels(rootStyle.borderBottomWidth);
+        const containerWidth = root.clientWidth - paddingLeft - paddingRight;
+        if (!Number.isFinite(containerWidth) || containerWidth <= 0)
+            return;
+        const measuredItems = [];
+        for (const entry of entries) {
+            const node = itemRefs.current.get(entry.internalKey);
+            if (!node)
+                return;
+            measuredItems.push({
+                key: entry.internalKey,
+                height: node.offsetHeight,
+            });
+        }
+        const resolvedDirection = dir
+            ?? (rootStyle.direction === 'rtl' ? 'rtl' : 'ltr');
+        const next = calculateMasonryLayout({
+            containerWidth,
+            items: measuredItems,
+            columns: fixedColumns,
+            minColumnWidth: safeMinColumnWidth,
+            maxColumns: safeMaxColumns,
+            columnGap: safeColumnGap,
+            rowGap: safeRowGap,
+            strategy,
+            direction: resolvedDirection,
+        });
+        const positions = next.positions.map(position => ({
+            ...position,
+            x: position.x + paddingLeft,
+            y: position.y + paddingTop,
+        }));
+        const contentBlockSize = next.height;
+        const blockSize = rootStyle.boxSizing === 'border-box'
+            ? borderTop + paddingTop + contentBlockSize + paddingBottom + borderBottom
+            : contentBlockSize;
+        setLayout(current => current.signature === signature
+            && current.ready
+            && current.columnCount === next.columnCount
+            && Math.abs(current.height - blockSize) < 0.25
+            && samePositions(current.positions, positions)
+            ? current
+            : {
+                signature,
+                columnCount: next.columnCount,
+                height: blockSize,
+                positions: new Map(positions.map(position => [position.key, position])),
+                ready: true,
+            });
+    }, [
+        dir,
+        entries,
+        fixedColumns,
+        safeColumnGap,
+        safeMaxColumns,
+        safeMinColumnWidth,
+        safeRowGap,
+        signature,
+        strategy,
+    ]);
+    const scheduleLayout = useCallback(() => {
+        if (frameRef.current !== null || typeof window === 'undefined')
+            return;
+        frameRef.current = window.requestAnimationFrame(() => {
+            frameRef.current = null;
+            updateLayout();
+        });
+    }, [updateLayout]);
+    useBrowserLayoutEffect(() => {
+        if (layout.signature === signature)
+            return;
+        setLayout(emptyLayout(signature));
+    }, [layout.signature, signature]);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return undefined;
+        const observer = typeof ResizeObserver === 'undefined'
+            ? null
+            : new ResizeObserver(scheduleLayout);
+        observer?.observe(root);
+        itemRefs.current.forEach(node => observer?.observe(node));
+        if (!observer)
+            window.addEventListener('resize', scheduleLayout);
+        scheduleLayout();
+        return () => {
+            observer?.disconnect();
+            window.removeEventListener('resize', scheduleLayout);
+            if (frameRef.current !== null) {
+                window.cancelAnimationFrame(frameRef.current);
+                frameRef.current = null;
+            }
+        };
+    }, [entries, scheduleLayout, signature]);
+    useEffect(() => {
+        const fonts = typeof document === 'undefined' ? undefined : document.fonts;
+        if (!fonts?.addEventListener)
+            return undefined;
+        fonts.addEventListener('loadingdone', scheduleLayout);
+        return () => fonts.removeEventListener('loadingdone', scheduleLayout);
+    }, [scheduleLayout]);
+    const rootStyle = {
+        ...style,
+        '--inkra-masonry-column-gap': `${safeColumnGap}px`,
+        '--inkra-masonry-columns': fixedColumns ?? 1,
+        '--inkra-masonry-min-column-width': `${safeMinColumnWidth}px`,
+        '--inkra-masonry-row-gap': `${safeRowGap}px`,
+        blockSize: ready ? `${effectiveLayout.height}px` : style?.blockSize,
+    };
+    return _jsx("div", { ...props, className: classes('inkra-masonry', className), "data-animated": animated || undefined, "data-columns": ready ? effectiveLayout.columnCount : undefined, "data-layout": ready ? 'ready' : 'fallback', "data-mode": fixedColumns === undefined ? 'adaptive' : 'fixed', "data-strategy": strategy, dir: dir, ref: setRootRef, role: role, style: rootStyle, children: entries.map(entry => {
+            const state = entry;
+            const itemProps = getItemProps?.(state) ?? {};
+            const { className: itemClassName, role: itemRole, ...nativeItemProps } = itemProps;
+            const position = ready ? effectiveLayout.positions.get(entry.internalKey) : undefined;
+            return _createElement("div", { ...nativeItemProps, "aria-posinset": role === 'list' ? entry.index + 1 : undefined, "aria-setsize": role === 'list' ? entries.length : undefined, className: classes('inkra-masonry__item', itemClassName), "data-column": position?.column, "data-index": entry.index, "data-masonry-key": String(entry.key), "data-positioned": position ? '' : undefined, key: entry.internalKey, ref: node => setItemRef(entry.internalKey, node), role: itemRole ?? (role === 'list' ? 'listitem' : undefined), style: position ? {
+                    inlineSize: `${position.width}px`,
+                    transform: `translate3d(${position.x}px, ${position.y}px, 0)`,
+                } : undefined }, renderItem(state));
+        }) });
+}
+export const Masonry = forwardRef(MasonryInner);

package/dist/masonry/layout.d.ts

@@ -0,0 +1,35 @@
+export type MasonryStrategy = 'shortest' | 'sequential';
+export type MasonryDirection = 'ltr' | 'rtl';
+export interface MasonryLayoutItem {
+    key: string;
+    height: number;
+}
+export interface MasonryLayoutOptions {
+    containerWidth: number;
+    items: readonly MasonryLayoutItem[];
+    columns?: number;
+    minColumnWidth?: number;
+    maxColumns?: number;
+    columnGap?: number;
+    rowGap?: number;
+    strategy?: MasonryStrategy;
+    direction?: MasonryDirection;
+}
+export interface MasonryLayoutPosition {
+    key: string;
+    column: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MasonryLayoutResult {
+    columnCount: number;
+    columnWidth: number;
+    height: number;
+    positions: readonly MasonryLayoutPosition[];
+}
+export declare function normalizeMasonrySpacing(value: number | undefined, fallback?: number): number;
+export declare function normalizeMasonryColumnCount(value: number | undefined, fallback?: number): number;
+export declare function resolveMasonryColumnCount({ columns, containerWidth, columnGap, maxColumns, minColumnWidth, }: Pick<MasonryLayoutOptions, 'columns' | 'containerWidth' | 'columnGap' | 'maxColumns' | 'minColumnWidth'>): number;
+export declare function calculateMasonryLayout(options: MasonryLayoutOptions): MasonryLayoutResult;

package/dist/masonry/layout.js

@@ -0,0 +1,67 @@
+const DEFAULT_MIN_COLUMN_WIDTH = 240;
+const MAX_COLUMN_COUNT = 100;
+export function normalizeMasonrySpacing(value, fallback = 0) {
+    return Number.isFinite(value) ? Math.max(0, value) : fallback;
+}
+export function normalizeMasonryColumnCount(value, fallback = 1) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(MAX_COLUMN_COUNT, Math.max(1, Math.floor(value)));
+}
+export function resolveMasonryColumnCount({ columns, containerWidth, columnGap = 0, maxColumns, minColumnWidth = DEFAULT_MIN_COLUMN_WIDTH, }) {
+    if (columns !== undefined)
+        return normalizeMasonryColumnCount(columns);
+    const width = Number.isFinite(containerWidth) ? Math.max(0, containerWidth) : 0;
+    const gap = normalizeMasonrySpacing(columnGap);
+    const minimum = Number.isFinite(minColumnWidth) && minColumnWidth > 0
+        ? minColumnWidth
+        : DEFAULT_MIN_COLUMN_WIDTH;
+    const available = Math.max(0, width + gap);
+    const adaptive = Math.max(1, Math.floor(available / (minimum + gap)));
+    return Math.min(adaptive, normalizeMasonryColumnCount(maxColumns, MAX_COLUMN_COUNT));
+}
+export function calculateMasonryLayout(options) {
+    const containerWidth = Number.isFinite(options.containerWidth)
+        ? Math.max(0, options.containerWidth)
+        : 0;
+    const columnGap = normalizeMasonrySpacing(options.columnGap);
+    const rowGap = normalizeMasonrySpacing(options.rowGap);
+    const requestedColumnCount = resolveMasonryColumnCount({
+        columns: options.columns,
+        containerWidth,
+        columnGap,
+        maxColumns: options.maxColumns,
+        minColumnWidth: options.minColumnWidth,
+    });
+    const columnCount = options.columns === undefined && options.items.length > 0
+        ? Math.min(requestedColumnCount, options.items.length)
+        : requestedColumnCount;
+    const effectiveColumnGap = columnCount > 1
+        ? Math.min(columnGap, containerWidth / (columnCount - 1))
+        : 0;
+    const columnWidth = Math.max(0, (containerWidth - effectiveColumnGap * (columnCount - 1)) / columnCount);
+    const columnHeights = Array.from({ length: columnCount }, () => 0);
+    const strategy = options.strategy ?? 'shortest';
+    const direction = options.direction ?? 'ltr';
+    const positions = options.items.map((item, index) => {
+        let column = strategy === 'shortest' ? 0 : index % columnCount;
+        if (strategy === 'shortest') {
+            for (let candidate = 1; candidate < columnCount; candidate += 1) {
+                if (columnHeights[candidate] < columnHeights[column])
+                    column = candidate;
+            }
+        }
+        const height = Number.isFinite(item.height) ? Math.max(0, item.height) : 0;
+        const y = columnHeights[column] === 0 ? 0 : columnHeights[column] + rowGap;
+        const logicalX = column * (columnWidth + effectiveColumnGap);
+        const x = direction === 'rtl' ? containerWidth - columnWidth - logicalX : logicalX;
+        columnHeights[column] = y + height;
+        return { key: item.key, column, x, y, width: columnWidth, height };
+    });
+    return {
+        columnCount,
+        columnWidth,
+        height: Math.max(0, ...columnHeights),
+        positions,
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { RollingMotionColumn } from './rolling.js';
+export declare function RollingValue({ columns, progress, direction }: {
+    columns: RollingMotionColumn[];
+    progress: number;
+    direction: 'up' | 'down';
+}): import("react").JSX.Element;

package/dist/number-ticker/RollingValue.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PencilText } from '../PencilText.js';
+import { rollMix } from './rolling.js';
+export function RollingValue({ columns, progress, direction }) {
+    return _jsx("span", { className: "inkra-number-ticker__reels", dir: "ltr", "data-direction": direction, children: columns.map(column => {
+            const width = rollMix(column.fromWidth, column.toWidth, progress);
+            return _jsx("span", { className: "inkra-number-ticker__column", "data-place": column.key, "data-digit": column.digit || undefined, "data-departing": column.target === '' || undefined, style: column.digit ? { width: `${width}ch` } : { gridTemplateColumns: `${width}fr` }, children: _jsx("span", { className: "inkra-number-ticker__column-inner", children: column.faces.map(face => _jsx("span", { className: "inkra-number-ticker__face", "data-face": face.text === column.target ? 'to' : 'from', style: { transform: column.digit ? `translateY(${rollMix(face.fromOffset, face.toOffset, progress) * 100}%)` : undefined,
+                            opacity: rollMix(face.fromOpacity, face.toOpacity, progress) }, children: _jsx(PencilText, { seed: `ticker-reel-${column.key}-${face.text}`, children: face.text }) }, face.text)) }) }, column.key);
+        }) });
+}

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

@@ -1,5 +1,7 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 import type { NumberTickerCompact, NumberTickerCompactOptions, NumberTickerFormatOptions, NumberTickerLocale, NumberTickerValue } from './model.js';
+export type NumberTickerAnimation = 'count' | 'roll';
+export type NumberTickerRollDirection = 'auto' | 'up' | 'down';
 export interface NumberTickerRenderDetails {
     animating: boolean;
     formattedValue: string;
@@ -19,6 +21,8 @@ export interface NumberTickerProps extends Omit<ComponentPropsWithoutRef<'span'>
     renderValue?: (value: NumberTickerValue, details: NumberTickerRenderDetails) => ReactNode;
     getValueLabel?: (value: NumberTickerValue, formattedValue: string) => string;
     animate?: boolean;
+    animation?: NumberTickerAnimation;
+    rollDirection?: NumberTickerRollDirection;
     duration?: number;
     easing?: (progress: number) => number;
     showDelta?: boolean;

package/dist/number-ticker/index.js

@@ -5,6 +5,8 @@ import { PencilText } from '../PencilText.js';
 import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
 import { canAnimateTickerValue, createNumberFormatter, createTickerFormatter, easeOutCubic, formatDerivedTickerDelta, formatTickerValue, interpolateTickerValue, tickerValueChanged, subtractTickerValues, tickerValueKey, } from './model.js';
 import { ExactDecimal } from './precision.js';
+import { RollingValue } from './RollingValue.js';
+import { createRollingMotion, rollingTokens, sameRollingTokens } from './rolling.js';
 function usePrefersReducedMotion() {
     const [reduced, setReduced] = useState(false);
     useBrowserLayoutEffect(() => {
@@ -24,7 +26,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, compact = false, compactOptions, deltaDuration = 1600, deltaFormatOptions, duration = 420, easing = easeOutCubic, formatOptions, getValueLabel, locale: localeProp, prefix, renderDelta, renderValue, showDelta = false, suffix, value, ...props }, forwardedRef) {
+export const NumberTicker = forwardRef(function NumberTicker({ animate = true, animation = 'count', className, compact = false, compactOptions, deltaDuration = 1600, deltaFormatOptions, duration = 420, easing = easeOutCubic, formatOptions, getValueLabel, locale: localeProp, prefix, renderDelta, renderValue, rollDirection = 'auto', showDelta = false, suffix, value, ...props }, forwardedRef) {
     const { locale: inheritedLocale } = useInkraLocale();
     const locale = localeProp ?? inheritedLocale;
     const rootRef = useRef(null);
@@ -36,6 +38,9 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
     const [announcedValue, setAnnouncedValue] = useState(value);
     const [animating, setAnimating] = useState(false);
     const [delta, setDelta] = useState(null);
+    const [roll, setRoll] = useState(null);
+    const [rollProgress, setRollProgress] = useState(1);
+    const rollFrameRef = useRef(null);
     const reducedMotion = usePrefersReducedMotion();
     const localeKey = Array.isArray(locale) ? locale.join('\u0000') : locale;
     const formatOptionsKey = JSON.stringify(formatOptions ?? {});
@@ -45,6 +50,14 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
     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);
+    const rollRequested = animation === 'roll' && !renderValue;
+    const finalTokens = useMemo(() => rollRequested ? rollingTokens(formatter.formatToParts(value)) : [], [formatter, value, rollRequested]);
+    // Keep exact large values readable without creating thousands of painted reels.
+    const useRoll = rollRequested && finalTokens.length <= 128;
+    const settledTokensRef = useRef(finalTokens);
+    const previousFormatterRef = useRef(formatter);
+    const previousUseRollRef = useRef(useRoll);
+    const columns = useMemo(() => roll?.columns ?? createRollingMotion(finalTokens, finalTokens, 'up'), [roll, finalTokens]);
     useBrowserLayoutEffect(() => {
         const previousTarget = targetRef.current;
         targetRef.current = value;
@@ -72,22 +85,53 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
                 && typeof window.matchMedia === 'function'
                 && window.matchMedia('(prefers-reduced-motion: reduce)').matches);
         const from = displayedRef.current;
-        if (!animate || reduceImmediately || !canAnimateTickerValue(from, value, duration)) {
+        const formatChanged = previousFormatterRef.current !== formatter;
+        previousFormatterRef.current = formatter;
+        const modeChanged = previousUseRollRef.current !== useRoll;
+        previousUseRollRef.current = useRoll;
+        if (!animate || reduceImmediately || formatChanged || modeChanged
+            || (useRoll && !rollFrameRef.current && sameRollingTokens(settledTokensRef.current, finalTokens))
+            || (rollRequested && (!useRoll || settledTokensRef.current.length > 128))
+            || !canAnimateTickerValue(from, value, duration)) {
             displayedRef.current = value;
             setDisplayedValue(value);
             setAnnouncedValue(value);
             setAnimating(false);
+            setRoll(null);
+            setRollProgress(1);
+            settledTokensRef.current = finalTokens;
+            rollFrameRef.current = null;
             return undefined;
         }
+        if (useRoll) {
+            const direction = rollDirection === 'auto'
+                ? (new ExactDecimal(String(value)).gt(String(from)) ? 'up' : 'down') : rollDirection;
+            const nextColumns = createRollingMotion(settledTokensRef.current, finalTokens, direction, rollFrameRef.current ?? undefined);
+            setRoll({ columns: nextColumns, direction });
+            setRollProgress(0);
+            rollFrameRef.current = { columns: nextColumns, progress: 0 };
+        }
+        else {
+            setRoll(null);
+            rollFrameRef.current = null;
+        }
         let startTime = null;
         setAnimating(true);
         const tick = (time) => {
             if (startTime === null)
                 startTime = time;
             const progress = Math.min(1, Math.max(0, (time - startTime) / duration));
-            const next = interpolateTickerValue(from, value, easing(progress));
+            const eased = easing(progress);
+            const bounded = Number.isFinite(eased) ? Math.min(1, Math.max(0, eased)) : progress;
+            const next = interpolateTickerValue(from, value, bounded);
             displayedRef.current = next;
-            setDisplayedValue(next);
+            if (useRoll) {
+                setRollProgress(bounded);
+                if (rollFrameRef.current)
+                    rollFrameRef.current.progress = bounded;
+            }
+            else
+                setDisplayedValue(next);
             if (progress < 1) {
                 frameRef.current = requestAnimationFrame(tick);
             }
@@ -97,6 +141,10 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
                 setDisplayedValue(value);
                 setAnnouncedValue(value);
                 setAnimating(false);
+                setRoll(null);
+                setRollProgress(1);
+                settledTokensRef.current = finalTokens;
+                rollFrameRef.current = null;
             }
         };
         frameRef.current = requestAnimationFrame(tick);
@@ -106,7 +154,7 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
                 frameRef.current = null;
             }
         };
-    }, [animate, deltaDuration, duration, easing, reducedMotion, showDelta, value]);
+    }, [animate, deltaDuration, duration, easing, reducedMotion, showDelta, value, useRoll, rollRequested, rollDirection, formatter]);
     useEffect(() => () => {
         if (frameRef.current !== null)
             cancelAnimationFrame(frameRef.current);
@@ -120,7 +168,7 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
         .filter(Boolean).join(' ');
     const accessibleLabel = getValueLabel?.(announcedValue, announcedFormattedValue) ?? defaultAccessibleLabel;
     const valueContent = renderValue?.(displayedValue, { animating, formattedValue })
-        ?? (animating
+        ?? (useRoll ? _jsx(RollingValue, { columns: columns, progress: roll ? rollProgress : 1, direction: roll?.direction ?? 'up' }) : animating
             ? _jsx("span", { className: "inkra-number-ticker__native-value", children: formattedValue })
             : _jsx(PencilText, { seed: `number-ticker-${finalFormattedValue}`, children: finalFormattedValue }));
     const deltaContent = delta === null ? null : (() => {
@@ -133,6 +181,6 @@ export const NumberTicker = forwardRef(function NumberTicker({ animate = true, c
     })();
     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": 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 })] });
+    return _jsxs("span", { ...props, className: classes, ref: rootRef, "data-animating": animating || undefined, "data-animation": animation, 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, numberTickerUnits, } from './model.js';

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

@@ -0,0 +1,35 @@
+export interface RollingToken {
+    key: string;
+    text: string;
+    digit: boolean;
+}
+export declare function sameRollingTokens(from: readonly RollingToken[], to: readonly RollingToken[]): boolean;
+export interface RollingColumn {
+    key: string;
+    from: string;
+    to: string;
+    digit: boolean;
+}
+export interface RollingFace {
+    text: string;
+    fromOffset: number;
+    toOffset: number;
+    fromOpacity: number;
+    toOpacity: number;
+}
+export interface RollingMotionColumn {
+    key: string;
+    digit: boolean;
+    target: string;
+    fromWidth: number;
+    toWidth: number;
+    faces: RollingFace[];
+}
+export interface RollingFrame {
+    columns: RollingMotionColumn[];
+    progress: number;
+}
+export declare const rollMix: (from: number, to: number, progress: number) => number;
+export declare function createRollingMotion(from: RollingToken[], to: RollingToken[], direction: 'up' | 'down', previous?: RollingFrame): RollingMotionColumn[];
+export declare function rollingTokens(parts: Intl.NumberFormatPart[]): RollingToken[];
+export declare function rollingColumns(from: RollingToken[], to: RollingToken[]): RollingColumn[];