# Flow

Headless, unstyled viewport that shows one step of a multi-step flow at a time, keeping the outgoing step mounted, inert and `aria-hidden` until its exit transition ends. Measures the active step into `--cl-flow-step-height` on the root. `useFlowAutoFocus` marks what a step focuses when it enters, and `useFlowStepActive` is `false` inside an exiting step.

## Use for

- the base for a styled component that swaps screens on one surface
- focusing a field when a step of a multi-step flow enters
- knowing whether content sits in an exiting step

## Practices

- Don't: Use the primitive in a feature. Use the styled `Flow` from `src/components/flow` instead, as the Views guide says (`mosaic guides inspect views`).
- Do: List every controller state a screen covers in one `Flow.Step` `ids`, such as its pending and error states, so moving between them does not transition.
- Do: Attach `useFlowAutoFocus()` to the field a step should focus when it enters.
- Do: Style `Flow.Root` with `overflow: clip`, not `hidden`, so focusing a sliding step cannot scroll it.
- Do: Transition the root height only under `data-transitioning`, so a resize inside the active step is not animated twice.

## API reference

### Flow.Root

Renders a `div`, or the `render` element. Carries `data-initial` through the first measured frame, `data-transitioning` from a step change until its own `height` transition ends, and `data-height-change` of `grow` or `shrink`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The active controller state. The step whose `ids` include it is shown. |
| `direction` | `FlowDirection` | `1` | `1` forward or `-1` back. Each step exposes it as `--cl-flow-transition-direction`. |

### Flow.Step

Renders while active or exiting, with `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`. An exiting step keeps the children of its last active render. The first active step gets no `data-starting-style`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ids` | `readonly string[]` |  | The controller states this step shows for. |

## Examples

### Two steps

```tsx
<Flow.Root value={status} direction={direction}>
  <Flow.Step ids={['password', 'password-pending']}>
    <PasswordView />
  </Flow.Step>
  <Flow.Step ids={['code', 'code-pending']}>
    <CodeView />
  </Flow.Step>
</Flow.Root>
```
