# motion/presence (zidane-ui)

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

## Functions

### `readDurationVar`

Function.

A duration custom property (`200ms`, `0.2s`) in milliseconds; 0 when unset.

```ts
function readDurationVar(name: string, root?: HTMLElement): number
```

**Parameters**

- `name` (`string`): The custom property, such as `--zg-panel-ms`.
- `root?` (`HTMLElement`, default `document.documentElement`): The element to read it from. Defaults to `document.documentElement`.

**Returns** `number`

Source: [ui/src/motion/presence.ts:56](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L56)

### `readExitMs`

Function.

How long a CSS exit plays: the longer of `exit` (transform) and
`fade-out` (opacity). 0 under `off`; the brief fade under `reduced`.
What an `exitMs` waiting on an `exit` / `fade-out` animation passes.

```ts
function readExitMs(): number
```

**Returns** `number`

Source: [ui/src/motion/presence.ts:78](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L78)

### `readMenuExitMs`

Function.

How long a menu's close plays (`menu-exit`, opacity and transform alike): what a menu's `exitMs` passes.

```ts
function readMenuExitMs(): number
```

**Returns** `number`

Source: [ui/src/motion/presence.ts:81](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L81)

### `readMotionMs`

Function.

A named motion's CSS duration (`--zg-motion-<name>-duration`, motion/springs.ts) in ms.

```ts
function readMotionMs(name: string): number
```

**Parameters**

- `name` (`string`): The motion name, such as `settle` or `exit`.

**Returns** `number`

Source: [ui/src/motion/presence.ts:71](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L71)

### `readPanelMs`

Function.

The panel open / close duration token (zeroed by reduced / off motion).

```ts
function readPanelMs(): number
```

**Returns** `number`

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

### `transitionState`

Function.

`open` / `closed` for `[data-state]` transitions: everything but `open` shows the closed look.

```ts
function transitionState(state: PresenceState): 'open' | 'closed'
```

**Parameters**

- `state` (`PresenceState`): The phase from [`usePresence`](https://zidane.si/docs/reference/ui-motion-presence.md#usePresence).

**Returns** `'open' | 'closed'`

Source: [ui/src/motion/presence.ts:88](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L88)

### `usePresence`

Function.

Keeps a node mounted around a CSS transition. It is mounted on the render that opens it,
then goes `entering`, `open`, `closing` for `exitMs` and `closed`. A zero `exitMs` closes at
once, as reduced and off motion want.

```ts
function usePresence(open: boolean, options?: PresenceOptions): Presence
```

**Parameters**

- `open` (`boolean`): Whether the node should be open.
- `options?` (`PresenceOptions`, default `{}`): Whether to mount closed and transition in (`enter`), and how long the exit lasts
  (`exitMs`, in ms or a function read when the close starts), and whose node it is (`key`).

**Returns** `Presence`

Source: [ui/src/motion/presence.ts:99](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L99)

### `useScrollLock`

Function.

Locks page scroll while `active` (menus, dialogs). Counted: with layers
stacked, the page stays locked until the last one lets go, whatever order
they close in, and gets back the styles it had before the first.

```ts
function useScrollLock(active: boolean): void
```

**Parameters**

- `active` (`boolean`): Whether to lock the page scroll.

Source: [ui/src/motion/presence.ts:185](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L185)

## Interfaces

### `Presence`

Interface.

What [`usePresence`](https://zidane.si/docs/reference/ui-motion-presence.md#usePresence) returns.

```ts
interface Presence
```

**Properties**

- `mounted` (`boolean`): Whether the node should be in the tree: true from the render that opens it until its exit
  finishes.
- `state` (`PresenceState`): The current phase. Map it with [`transitionState`](https://zidane.si/docs/reference/ui-motion-presence.md#transitionState) to a `data-state` value.

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

### `PresenceOptions`

Interface.

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

```ts
interface PresenceOptions
```

**Properties**

- `enter?` (`boolean`): Mount closed and transition in. Default false.
- `exitMs?` (`number | (() => number)`): How long `closing` lasts. Default 0.
- `key?` (`string | null`): Whose node it is (a scope's key). A change shows the new state at once: no enter, no exit.

Source: [ui/src/motion/presence.ts:41](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L41)

## Types

### `PresenceState`

Type.

Phase of a [`usePresence`](https://zidane.si/docs/reference/ui-motion-presence.md#usePresence) transition: `entering` (mounted in its closed look, for two frames),
`open`, `closing` (playing its exit) or `closed` (unmounted).

```ts
type PresenceState = 'entering' | 'open' | 'closing' | 'closed'
```

Source: [ui/src/motion/presence.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/motion/presence.ts#L27)