# Roll: How it rolls

> Digits that keep their places and turn the way the number went, everything else rolling over, on springs that carry on.

Source: https://cesarvenzac.com/roll/docs/rolling

Roll compares the value it shows with the next, character by character, and turns only the characters that change. At rest the value is plain text; while it rolls, each changing character gets a cell of its own.

## Digits keep their places

A number's digits are matched by their place, not their position in the text. The units stay the units: 9 becoming 10 turns the 9 to 0 while a 1 rolls in on its left, 9:59 becoming 10:00 keeps its colon where it is, and 1,234 becoming 999 lets the 1 and its comma roll away from where they stand.

- A fraction is read from its mark, so €8 becoming €6.67 turns the 8 back to a 6 and rolls .67 in after it.
- Thousands are told from decimals: "12,345", "1.234.567" and "1 234,5" are each read as they're meant.
- Each number in a value keeps its own places: "3/12", "1:05:30".
- What isn't part of a number, a currency sign, a unit, a word, keeps its place beside the number it's next to: what comes before the first number counted back from it, so a sign that comes and goes leaves the currency where it is, and what comes after a number counted on from it. A value with no number goes letter by letter from its start.

## The way the number went

Each digit turns forward as its number counts up (7, 8, 9, 0) and back as it counts down, never the long way round. The way is read from the numbers themselves, fractions and signs included: €8 to €6.40 is down, −3° to −5° is down, 9:59 to 10:00 is up. `way` sets it instead, `"up"` or `"down"`, for every character.

## Everything else rolls over

A sign, a letter, a word's letters in their places: the old one leaves and the new one comes in, from below going up, as a split-flap board's flaps fall. A character that comes or goes rolls in or out where it stands, its width growing from nothing or shrinking to it.

### Reels

With `reels`, letters, or any symbols you give in order, turn through every symbol between rather than rolling over:

```tsx
import { DIGITS, LOWERCASE, UPPERCASE } from "@cesarvenzac/roll";

<Roll value={day} reels={[DIGITS, UPPERCASE, LOWERCASE]} />;
<Roll value={suit} reels={["♠♥♦♣"]} />;
```

A reel goes round, and every symbol on it turns the value's way: forward unless the numbers say otherwise or `way` does, so a word's letters all go the same way, as a split-flap board's do. `reels` replaces the default, `[DIGITS]`: keep `DIGITS` in it for numbers to turn.

## Icons

A node rolls over as one: give `roll` an SVG, or `Roll` any element. Name it with `label`, or it's read by its own `aria-label`, `title` or text.

## Springs

Every turn is a spring: `duration` is about how long it takes to come to rest (0.6 seconds unless said) and `bounce` how far it goes past and comes back, from 0, none, to 1. A spring from still starts as an ease-out does, quick and settling, never slow to leave.

Interrupted, it goes on. A character sent somewhere else mid-turn carries on from where it is at the speed it has, then comes home as quickly as a fresh turn would: a number changing faster than it can turn never stutters or starts over.

## Stagger

The characters of a change start one after another, `stagger` seconds apart (0.03 unless said), from the `start` of the value unless `staggerFrom` says the `end` or the `center`. However many there are, the last starts within a quarter of a second of the first. A character already turning goes on at once.

## Widths

Characters keep the width the font gives them, so no tabular figures are needed: a column eases to the next character's width as it turns, and what follows the value moves with it. Every width eases at once, on one curve, so the value's own width only ever moves one way.

## Roll's docs

- [Overview](https://cesarvenzac.com/roll.md): Text that rolls as it changes: digits turn like an odometer's and keep their places, letters and icons roll over.
- [Getting started](https://cesarvenzac.com/roll/docs/getting-started.md): Install Roll and give it a value to show: in React, in any page, as an element, in Svelte or in Vue.
- [How it rolls](https://cesarvenzac.com/roll/docs/rolling.md): Digits that keep their places and turn the way the number went, everything else rolling over, on springs that carry on.
- [Looks and effects](https://cesarvenzac.com/roll/docs/looks.md): A flat strip, a drum, a cube, a rolling circle, a tipping square or a swap in place, in any direction, faded, scaled or blurred as it goes.
- [Counting and knowing when it's done](https://cesarvenzac.com/roll/docs/numbers.md): 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.
- [In the page](https://cesarvenzac.com/roll/docs/page.md): What assistive tech hears, what reduced motion gets, how to style it, how it's drawn on a server, and what it costs.
- [API reference](https://cesarvenzac.com/roll/docs/api.md): Every function, component and type the package exports, entry by entry: the core, React, the element, Svelte and Vue.
