# motion/springs (zidane-ui)

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

## Functions

### `applyMotionVars`

Function.

Write the motion switches and every `--zg-motion-*` / `--zg-panel-*` var
on `root` (usually `<html>`): what an app calls when its motion settings
change, so it never copies the curves. Returns the vars written.

```ts
function applyMotionVars(
  root: HTMLElement,
  prefs: MotionPrefs,
  options?: ApplyMotionOptions,
): Record<string, string>
```

**Parameters**

- `root` (`HTMLElement`): The element to write to, usually `document.documentElement`.
- `prefs` (`MotionPrefs`): The motion level and spring switch to apply.
- `options?` (`ApplyMotionOptions`, default `{}`): See [`ApplyMotionOptions`](https://zidane.si/docs/reference/ui-motion-springs.md#ApplyMotionOptions).

**Returns** `Record<string, string>`

Source: [ui/src/motion/springs.ts:297](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L297)

### `cssMotionVars`

Function.

`--zg-motion-<name>-duration` / `-ease` for every motion and for `hover`,
for CSS that stays CSS. Below `full`, movement is 0ms; fades stay a brief
tween under `reduced`; `off` zeroes everything.

```ts
function cssMotionVars(prefs: MotionPrefs): Record<string, string>
```

**Parameters**

- `prefs` (`MotionPrefs`): The live motion level and spring switch.

**Returns** `Record<string, string>`: A map of custom property names to values.

Source: [ui/src/motion/springs.ts:230](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L230)

### `currentMotionPrefs`

Function.

Both switches, read off `<html>` for imperative code.

```ts
function currentMotionPrefs(): MotionPrefs
```

**Returns** `MotionPrefs`

Source: [ui/src/motion/springs.ts:388](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L388)

### `currentMotionTransition`

Function.

Non-hook read for imperative animations (`animate()`, scroll glides).

```ts
function currentMotionTransition(name: MotionName, visualDuration?: number): Transition
```

**Parameters**

- `name` (`MotionName`): The motion to resolve.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`

Source: [ui/src/motion/springs.ts:400](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L400)

### `currentWithFade`

Function.

Non-hook `withFade`, for `animate()` calls that move and fade one element.

```ts
function currentWithFade(name: MotionName, visualDuration?: number): Transition
```

**Parameters**

- `name` (`MotionName`): The movement motion to use.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`

Source: [ui/src/motion/springs.ts:411](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L411)

### `fadeTransition`

Function.

The fade curve for opacity / colour: `fade`, or `fade-out` for an exit.

```ts
function fadeTransition(prefs: MotionPrefs, exit?: boolean): Transition
```

**Parameters**

- `prefs` (`MotionPrefs`): The live motion level and spring switch.
- `exit?` (`boolean`, default `false`): Use the leaving curve, `fade-out`, instead of `fade`.

**Returns** `Transition`: The transition for opacity and colour.

Source: [ui/src/motion/springs.ts:175](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L175)

### `menuTransition`

Function.

A menu's open (`menu`) or close (`menu-exit`) transition: one tween for
scale / position, with the enter's opacity on the same curve but shorter
(`MENU_FADE_RATIO`) so the surface is solid before it finishes growing.
Reduced: an opacity-only 80ms tween (pair it with no transform). Off: instant.

```ts
function menuTransition(prefs: MotionPrefs, exit?: boolean): Transition
```

**Parameters**

- `prefs` (`MotionPrefs`): The live motion level and spring switch.
- `exit?` (`boolean`, default `false`): Use the close transition, `menu-exit`, instead of `menu`.

**Returns** `Transition`: The transition for a menu's scale and position, with a shorter opacity curve on enter.

Source: [ui/src/motion/springs.ts:189](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L189)

### `motionTransition`

Function.

The motion transition for `name` under `prefs`. `visualDuration` overrides
the spec's duration (seconds; the panel slider), scaling the tween too.

```ts
function motionTransition(
  name: MotionName,
  prefs: MotionPrefs,
  visualDuration?: number,
): Transition
```

**Parameters**

- `name` (`MotionName`): The motion to resolve.
- `prefs` (`MotionPrefs`): The live motion level and spring switch.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`: A `motion` transition: instant when off, a short fade when reduced, otherwise a spring
or tween.

Source: [ui/src/motion/springs.ts:156](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L156)

### `motionVars`

Function.

Every motion custom property for `prefs`: the named curves, hover and the panels.

```ts
function motionVars(prefs: MotionPrefs, panelMs?: number): Record<string, string>
```

**Parameters**

- `prefs` (`MotionPrefs`): The live motion level and spring switch.
- `panelMs?` (`number`, default `DEFAULT_PANEL_MS`): The panel spring's perceived duration, in ms.

**Returns** `Record<string, string>`: A map of custom property names to values.

Source: [ui/src/motion/springs.ts:276](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L276)

### `panelMotionVars`

Function.

`--zg-panel-ms` / `--zg-panel-ease` for the layout panels (sidebar, side
panel, terminal drawer, tree column). They animate width / height in CSS
(a JS tween would re-lay out the chat column every frame), on the `panel`
spring sized by the user's slider: `panelMs` is the spring's perceived
duration; `--zg-panel-ms` becomes its settle time, which is also what
`usePresence` (`readPanelMs`) waits before unmounting a closed panel.

```ts
function panelMotionVars(panelMs: number, prefs: MotionPrefs): Record<string, string>
```

**Parameters**

- `panelMs` (`number`): The panel spring's perceived duration, in ms. Zero or less makes panels instant.
- `prefs` (`MotionPrefs`): The live motion level and spring switch.

**Returns** `Record<string, string>`: `--zg-panel-ms` and `--zg-panel-ease`.

Source: [ui/src/motion/springs.ts:262](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L262)

### `useMenuTransition`

Function.

`menuTransition` under the live preferences.

```ts
function useMenuTransition(exit?: boolean): Transition
```

**Parameters**

- `exit?` (`boolean`, default `false`): Use the close transition instead of the open one.

**Returns** `Transition`

Source: [ui/src/motion/springs.ts:355](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L355)

### `useMotionPrefs`

Function.

Both switches, live.

```ts
function useMotionPrefs(): MotionPrefs
```

**Returns** `MotionPrefs`

Source: [ui/src/motion/springs.ts:335](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L335)

### `useMotionTransition`

Function.

`motionTransition(name)` under the live preferences.

```ts
function useMotionTransition(name: MotionName, visualDuration?: number): Transition
```

**Parameters**

- `name` (`MotionName`): The motion to resolve.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`

Source: [ui/src/motion/springs.ts:346](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L346)

### `useSprings`

Function.

Spring animations on (`html[data-springs]` is not `off`).

```ts
function useSprings(): boolean
```

**Returns** `boolean`

Source: [ui/src/motion/springs.ts:330](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L330)

### `useTabExit`

Function.

A closing tab's `exit`, for every tab strip (tabs in an `AnimatePresence initial={false}`):
it folds to nothing on `settle` as it fades out, so the tabs after it flow left from where
they were. None with motion reduced or off: the tab goes at once and the rest close up.

```ts
function useTabExit(): TargetAndTransition | undefined
```

**Returns** `TargetAndTransition | undefined`

Source: [ui/src/motion/springs.ts:375](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L375)

### `useWithFade`

Function.

`withFade(name)` under the live preferences.

```ts
function useWithFade(name: MotionName, visualDuration?: number): Transition
```

**Parameters**

- `name` (`MotionName`): The movement motion to use.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`

Source: [ui/src/motion/springs.ts:366](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L366)

### `withFade`

Function.

`name`'s transition for movement, with every `FADE_KEYS` value on the
fade curve (`fade-out` when `name` is an exit): spring the transform,
fade the opacity. Pass it as a motion component's `transition`.

```ts
function withFade(
  name: MotionName,
  prefs: MotionPrefs,
  visualDuration?: number,
): Transition
```

**Parameters**

- `name` (`MotionName`): The movement motion to use.
- `prefs` (`MotionPrefs`): The live motion level and spring switch.
- `visualDuration?` (`number`): Overrides the motion's duration, in seconds, for example from the panel
  slider. A value of 0 or less is instant.

**Returns** `Transition`: The movement transition with opacity and colour keys on the fade curve.

Source: [ui/src/motion/springs.ts:206](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L206)

## Constants

### `DEFAULT_PANEL_MS`

Constant.

The panel slider's default (ms): the `panel` spring's perceived duration.

```ts
const DEFAULT_PANEL_MS = 200
```

Source: [ui/src/motion/springs.ts:115](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L115)

### `FADE_KEYS`

Constant.

The values `withFade` puts on the fade curve: never sprung, whatever moves around them.

```ts
const FADE_KEYS: readonly ['opacity', 'color', 'backgroundColor', 'borderColor', 'fill', 'stroke', 'filter', 'backdropFilter']
```

Source: [ui/src/motion/springs.ts:132](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L132)

### `HOVER_MOTION`

Constant.

Hover / press colour feedback: one short tween, the same with springs on or off.

```ts
const HOVER_MOTION: { duration: number; ease: readonly [0.4, 0, 0.2, 1] }
```

Source: [ui/src/motion/springs.ts:112](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L112)

### `INSTANT`

Constant.

Instant: what every motion resolves to with motion off.

```ts
const INSTANT: Transition
```

Source: [ui/src/motion/springs.ts:126](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L126)

### `MENU_FADE_RATIO`

Constant.

A menu's enter opacity lands ahead of its scale: \~100ms of the 140ms `menu`.

```ts
const MENU_FADE_RATIO = 0.7
```

Source: [ui/src/motion/springs.ts:106](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L106)

### `MOTION_NAMES`

Constant.

Every [`MotionName`](https://zidane.si/docs/reference/ui-motion-springs.md#MotionName), in the order of [`MOTIONS`](https://zidane.si/docs/reference/ui-motion-springs.md#MOTIONS).

```ts
const MOTION_NAMES: MotionName[]
```

Source: [ui/src/motion/springs.ts:109](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L109)

### `MOTIONS`

Constant.

The curve of every [`MotionName`](https://zidane.si/docs/reference/ui-motion-springs.md#MotionName): its spring (when it has one), tween duration in
seconds and easing.

```ts
const MOTIONS: Readonly<Record<MotionName, MotionSpec>>
```

Source: [ui/src/motion/springs.ts:92](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L92)

### `REDUCED_FADE`

Constant.

Reduced motion: a short fade; transforms jump (MotionConfig `reducedMotion`).

```ts
const REDUCED_FADE: Transition
```

Source: [ui/src/motion/springs.ts:129](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L129)

## Interfaces

### `ApplyMotionOptions`

Interface.

Options of [`applyMotionVars`](https://zidane.si/docs/reference/ui-motion-springs.md#applyMotionVars).

```ts
interface ApplyMotionOptions
```

**Properties**

- `attributes?` (`boolean`): Also write `data-motion` / `data-springs`. Default true; false when the attributes are the input.
- `panelMs?` (`number`): The panel slider (ms). Default `DEFAULT_PANEL_MS`.

Source: [ui/src/motion/springs.ts:281](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L281)

### `MotionPrefs`

Interface.

The two switches that pick what plays: the motion level and whether movement springs.

```ts
interface MotionPrefs
```

**Properties**

- `level` (`MotionLevel`): Motion level. `off` is instant, `reduced` keeps brief fades, `full` plays all motion.
- `springs` (`boolean`): Whether movement uses springs. When off, it uses the tween twins.

Source: [ui/src/motion/springs.ts:118](https://github.com/Tahul/zidane/blob/main/ui/src/motion/springs.ts#L118)

## Types

### `MotionName`

Type.

Name of a motion in the design system's vocabulary. `snap`, `pop`, `panel`, `slide` and
`settle` are movement that springs; `exit` is a fast straight exit; `fade` and `fade-out` are
the opacity curves for entering and leaving; `menu` and `menu-exit` are the menu tweens.

```ts
type MotionName =
  | 'snap'
  | 'pop'
  | 'panel'
  | 'slide'
  | 'settle'
  | 'exit'
  | 'fade'
  | 'fade-out'
  | 'menu'
  | 'menu-exit'
```

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