# liveFrame

> Live results for a text control rendered inside a frame: once typing pauses, the frame is pointed at the address for the control's value and reloaded.

```ts
import { liveFrame } from "@sdxc/ui/mixins";
```

Reloads the host's frame from `src(value)` once typing pauses, and at once on
LIVE_FRAME_RELOAD_EVENT, which a consumer dispatches after changing the value or
anything else `src` reads. A value whose address the frame already shows settles in place.

## Signature

```ts
liveFrame(options: LiveFrame.Options): MixinDescriptor<HTMLInputElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options` | `LiveFrame.Options` |  |

## Examples

```tsx
<input name="q" mix={[liveFrame({ src: (q) => `/frames/search?q=${encodeURIComponent(q)}` })]} />
```

```tsx
input.value = ""; input.dispatchEvent(new Event(LIVE_FRAME_RELOAD_EVENT));
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/mixins` too.

### LiveFrameEvent

Dispatched on a liveFrame host as a reload moves through its states. Only the reload
for the newest value settles, so an answer to an older value never ends a newer wait.

#### Signature

```ts
new LiveFrameEvent(init: { state: LiveFrame.State; src: string })
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `state` | `readonly LiveFrame.State` |  |
| `src` | `readonly string` | The address the frame is loading or showing. |

### LIVE_FRAME_RELOAD_EVENT

DOM event type a consumer dispatches on a liveFrame host to reload it at once.

#### Signature

```ts
const LIVE_FRAME_RELOAD_EVENT = "ui:live-frame-reload"
```

### LiveFrame.Options

Configuration for liveFrame.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `src` | `(value: string) => string` | The frame address for a value, read each time the frame reloads. |
| `debounce?` | `number` |  |
| `slowAfter?` | `number` |  |

### LiveFrame.State

Where a reload stands: `pending` once the value moves past what the frame shows, `slow`
once that has lasted past `slowAfter`, `loading` just before the frame is replaced, and
`settled` once the frame shows the newest value.

#### Signature

```ts
type LiveFrame.State = "pending" | "slow" | "loading" | "settled"
```

One of `"pending"`, `"slow"`, `"loading"`, `"settled"`.