Counting and knowing when it's done
Count a number through the values between, tint it as it rises or falls, move several rollers as one, and know when they've landed.
Counting
Given a number as a number, count walks it through every value between the last and the next, each one rolled:
<Roll
value={visitors}
count
format={(n) => n.toLocaleString("en")}
/>It counts on a spring of its own, about a second unless count is the seconds to take, and sent somewhere new mid-count it goes on at the speed it has. Text doesn't count: give the number, and format to write it.
Each number on the way is rounded as the one it's going to is written before format sees it: counting to 1284, format gets whole numbers, and to 6.67, hundredths. So 6.67 to 8 drops its decimals at once and lands on 8, 8 to 6.67 shows them at once, and a toLocaleString never writes 1,039.233.
While it counts, its digits are tabular figures, every digit one width, so the value holds its width as its digits change every frame. tabular={false} keeps the font's own figures.
Trend
trend tints the value a moment as its numbers go up or down, green or red, then lets it fade back to its own colour, as a ticker does. The colours are darkened to read on white; give your own as { up, down }, any CSS colour:
<Roll value={price} trend />
<Roll
value={price}
trend={{ up: "var(--gain)", down: "var(--loss)" }}
/>A change whose numbers didn't move, a word changing beside them, isn't tinted. The tint is a colour, not a motion, so it shows under reduced motion too.
Knowing when it's done
A roller's settled is a promise that resolves once it's at rest on the value it was last given, its count included, and onSettle is called each time it comes to rest:
const total = roll(element, "€24", { onSettle: () => save() });
total.set("€31");
await total.settled; // landedGroups
Rollers in a group move as one. A change to several of them in the same moment staggers across them all, in the page's order, as if they were one value; the group's settled waits for every one of them, and its onSettle is called each time they've all come to rest:
import { roll, rollGroup } from "@cesarvenzac/roll";
const row = rollGroup({ onSettle: () => console.log("landed") });
const price = roll(priceElement, "€8", { group: row });
const total = roll(totalElement, "€24", { group: row });In React, every Roll inside a RollGroup joins it:
import { Roll, RollGroup } from "@cesarvenzac/roll/react";
<RollGroup onSettle={() => setLanded(true)}>
<Roll value={price} /> <Roll value={total} />
</RollGroup>;