# motion/roll (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/motion/roll.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx).

## Components

### `RollingText`

Component.

Text whose changed characters roll like an odometer: up when the value
grows, down when it shrinks. Unchanged characters hold still, so a
counter ticking `3.51k` → `3.52k` moves one digit. The formatting stays
whatever the caller renders (`3.51k`, `$42.057`, `12s`); pass `value` so
the direction follows the number rather than the characters. Wrap in
`SmoothWidth` when the length can change.

```ts
function RollingText(props: RollingTextProps): Element
```

**Parameters**

- `props` (`RollingTextProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the wrapping element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `text` (`string`): The formatted text to show. Characters that differ from the previous text roll.
- `value?` (`number`): The number behind `text`. When given, the roll goes down if it fell and up otherwise;
  without it, it always rolls up.

Source: [ui/src/motion/roll.tsx:64](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx#L64)

## Functions

### `readRollMs`

Function.

How long one roll plays, read off the motion vars: the longer of the enter (`settle`, `fade`) and the exit.

```ts
function readRollMs(): number
```

**Returns** `number`

Source: [ui/src/motion/roll.tsx:12](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx#L12)

### `rollCells`

Function.

Per-character diff for [`RollingText`](https://zidane.si/docs/reference/ui-motion-roll.md#RollingText), aligned from the RIGHT so the
units stay in their column when the number grows a digit (`9.99k` →
`10.0k`). Each cell is the new character plus the one it replaces:
`null` when unchanged, `''` when the column is new.

```ts
function rollCells(prev: string, next: string): { char: string; from: string | null }[]
```

**Parameters**

- `prev` (`string`): The text before the change.
- `next` (`string`): The text after the change.

**Returns** `{ char: string; from: string | null }[]`: One cell per character of `next`.

Source: [ui/src/motion/roll.tsx:30](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx#L30)

## Interfaces

### `RollingTextProps`

Interface.

Props for [`RollingText`](https://zidane.si/docs/reference/ui-motion-roll.md#RollingText).

```ts
interface RollingTextProps
```

**Properties**

- `className?` (`string`): Extra classes on the wrapping element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `text` (`string`): The formatted text to show. Characters that differ from the previous text roll.
- `value?` (`number`): The number behind `text`. When given, the roll goes down if it fell and up otherwise;
  without it, it always rolls up.

Source: [ui/src/motion/roll.tsx:40](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx#L40)

## Types

### `RollDirection`

Type.

Direction characters roll in [`RollingText`](https://zidane.si/docs/reference/ui-motion-roll.md#RollingText): `up` when the value grows, `down` when it
shrinks.

```ts
type RollDirection = 'up' | 'down'
```

Source: [ui/src/motion/roll.tsx:18](https://github.com/Tahul/zidane/blob/main/ui/src/motion/roll.tsx#L18)