# sequence() (/docs/api/sequence)

> Join several authored states into one seekable timeline of adjacent transitions.

```ts
import { sequence } from 'visdelta/transition';

function sequence(
  states: readonly Visualization[],
  options: SequenceOptions,
): Promise<VisualizationSequence>;
```

`sequence()` prepares a transition for every adjacent pair (`A → B`, `B → C`, …)
and hands off between them at shared endpoints, so the chart host stays mounted
and never shows an empty frame between legs.

Each leg's runtime reads fonts and theme tokens from its actual chart root,
including after that root moves into the visible host. Resizing and reverse
handoffs keep that scope. Preparation uses hidden mounts under `document.body`;
make shared theme tokens available on the document root before initialization.

```ts
const story = await sequence([revenue, profit, ranked, revenue], {
  target: '#chart',
});

story.progress(1.5);            // halfway through profit → ranked
story.play({ duration: 850 });  // from the current position to the end
```

It requires at least two states, all of the same chart type. `SequenceOptions`
accepts the same fields as [`TransitionOptions`](/docs/api/transition#transitionoptions).

## VisualizationSequence [#visualizationsequence]

### VisualizationSequence

| Prop       | Type       | Description                                                                                                                                                                                                      |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `states`   | `array`    | Immutable states in timeline order.                                                                                                                                                                              |
| `value`    | `number`   | Current timeline position. Integers identify authored states.                                                                                                                                                    |
| `progress` | `function` | Display a frame synchronously. Values between integers seek within a leg.                                                                                                                                        |
| `play`     | `function` | Play across adjacent legs. Duration applies to each serial route stage.                                                                                                                                          |
| `pause`    | `function` | Stop owned playback at the current frame.                                                                                                                                                                        |
| `inspect`  | `function` | Inspect the currently mounted leg. Stage positions are local to that leg.                                                                                                                                        |
| `resize`   | `function` | Recompile the active leg for the container's current size/theme. `width` and `height` change the requested canvas size for every leg, as in `TransitionOptions`; a dimension left out keeps its current request. |
| `destroy`  | `function` | Stop playback and remove every prepared leg. The controller cannot be used afterwards.                                                                                                                           |

`value` runs from `0` to `states.length - 1`. Integer values identify authored
states exactly, even when a leg contains generated intermediate stages.

## SequencePlayOptions [#sequenceplayoptions]

### SequencePlayOptions

| Prop        | Type     | Description                                                                                        |
| ----------- | -------- | -------------------------------------------------------------------------------------------------- |
| `duration?` | `number` | Milliseconds for each serial route stage. Defaults to 800.                                         |
| `from?`     | `number` | Timeline position in leg units: 0 is the first state, 1 the second. Defaults to the current value. |
| `to?`       | `number` | Timeline position in leg units: 0 is the first state, 1 the second. Defaults to the last state.    |

Unlike a pair controller, a sequence's `play()` starts from the current value
by default.

## Resizing [#resizing]

A sequence takes the same `width` and `height` as `transition()`: a number of
pixels, or `"auto"` to follow the container. A dimension set to `"auto"` re-fits
the leg on screen when the container changes. Call `resize()` after a theme
change, or to change the requested size for every leg:

```ts
story.resize({ width: 'auto', height: 'auto' });
```

`resize()` recompiles the active leg and keeps the current position; the other
legs pick the new size up when they are shown. A dimension left out keeps its
request.

See [Multi-step stories](/docs/guides/stories) for scroll-driven usage.