# terminal/TerminalProvider (zidane-ui/terminal)

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

## Components

### `TerminalProvider`

Component.

Provides the terminal store and the app's actions to the terminal components below it.

```ts
function TerminalProvider(props: TerminalProviderProps): Element
```

**Parameters**

- `props` (`TerminalProviderProps`): Provider props: the `host` or `store`, the app's `actions`, `enabled`, `waiting`, `symbolsFontUrl`, `labels` and the `children`.

**Returns** `Element`

**Props**

- `actions?` (`TerminalAppActions`): What only the app can do (open links, add to chat, settings). Keep it stable: a new object re-renders every view.
- `children` (`ReactNode`): The app.
- `enabled?` (`boolean`): `false` removes the drawer and its toggle (terminals turned off). Default: true.
- `labels?` (`Partial<TerminalLabels>`): Overrides for the built-in strings. Keys you leave out keep the default English label.
- `symbolsFontUrl?` (`string`): Where the app serves the Nerd Font symbols face (`SYMBOLS_FONT`), loaded before a terminal measures its cells.
- `waiting?` (`TerminalWaiting | null`): Set while the link to what runs terminals is coming up or down: the unavailable state says so.

Source: [ui/src/terminal/TerminalProvider.tsx:122](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L122)

## Functions

### `useOptionalTerminalStore`

Function.

The [`TerminalStore`](https://zidane.si/docs/reference/ui-terminal-headless.md#TerminalStore) from the nearest [`TerminalProvider`](https://zidane.si/docs/reference/ui-terminal-terminal-provider.md#TerminalProvider), or `null` outside one (an app without terminals).

```ts
function useOptionalTerminalStore(): TerminalStore | null
```

**Returns** `TerminalStore | null`

Source: [ui/src/terminal/TerminalProvider.tsx:149](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L149)

### `useScopeTerminals`

Function.

A scope's terminals (state, active terminal, error, agent badge), re-rendering when they change.

```ts
function useScopeTerminals(scope: TerminalScope | null): ScopeTerminals
```

**Parameters**

- `scope` (`TerminalScope | null`): The scope, or `null` for none.

**Returns** `ScopeTerminals`

Source: [ui/src/terminal/TerminalProvider.tsx:178](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L178)

### `useTerminalActions`

Function.

The app's actions from the nearest [`TerminalProvider`](https://zidane.si/docs/reference/ui-terminal-terminal-provider.md#TerminalProvider).

```ts
function useTerminalActions(): TerminalAppActions
```

**Returns** `TerminalAppActions`

Source: [ui/src/terminal/TerminalProvider.tsx:154](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L154)

### `useTerminalLayout`

Function.

A scope's terminal layout (drawer, order, agent filter), re-rendering when it changes. Tells the
layouts the scope is shown (`TerminalLayouts.show`) once per scope.

```ts
function useTerminalLayout(scope: TerminalScope): TerminalLayout
```

**Parameters**

- `scope` (`TerminalScope`): The scope.

**Returns** `TerminalLayout`

Source: [ui/src/terminal/TerminalProvider.tsx:194](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L194)

### `useTerminalsEnabled`

Function.

Whether terminals are on (`TerminalProvider`'s `enabled`).

```ts
function useTerminalsEnabled(): boolean
```

**Returns** `boolean`

Source: [ui/src/terminal/TerminalProvider.tsx:164](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L164)

### `useTerminalStore`

Function.

The [`TerminalStore`](https://zidane.si/docs/reference/ui-terminal-headless.md#TerminalStore) from the nearest [`TerminalProvider`](https://zidane.si/docs/reference/ui-terminal-terminal-provider.md#TerminalProvider). Throws outside one.

```ts
function useTerminalStore(): TerminalStore
```

**Returns** `TerminalStore`

Source: [ui/src/terminal/TerminalProvider.tsx:144](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L144)

## Interfaces

### `TerminalAppActions`

Interface.

What only the app can do for the terminal components. Each one left out hides what needs it.

```ts
interface TerminalAppActions
```

**Properties**

- `drawerProps?` (`Readonly<Record<string, string | number | boolean>>`): Extra attributes for the drawer's root (a focus region's marker).
- `addToChat?` (`(scope: TerminalScope, excerpt: TerminalExcerpt) => void`): Adds a selection to the scope's chat. Absent: no Add to chat.
- `canAddToChat?` (`(scope: TerminalScope) => boolean`): Whether the scope has a chat to add to now (read when a menu opens). Absent: always, given `addToChat`.
- `openFile?` (`(scope: TerminalScope, path: string, event: MouseEvent, at?: { column?: number; line: number }) => void`): Opens a file a terminal printed (absolute path, optional 1-based position). Absent: paths don't link.
- `openSettings?` (`() => void`): Opens the app's settings where terminals are turned on (the unavailable state's button). Absent: no button.
- `openUrl?` (`(scope: TerminalScope, url: string, external: boolean, cwd: string) => void`): Opens a web link a terminal printed; `external`: ⌘/Ctrl-click asked for the system browser.
  `cwd`: where the terminal's paths resolve (`''` when they are not this machine's). Absent: a new window.
- `registerTabScope?` (`(element: HTMLElement, handlers: TerminalTabHandlers) => () => void`): Registers keyboard handlers on a terminal area's root element. Returns the unregister.
- `remoteName?` (`(scope: TerminalScope) => string | null`): The machine the scope's terminals run on when it is not this one: their files don't link, their loopback links don't open.

Source: [ui/src/terminal/TerminalProvider.tsx:49](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L49)

### `TerminalExcerpt`

Interface.

A selection of a terminal's output, to add to the chat.

```ts
interface TerminalExcerpt
```

**Properties**

- `endLine` (`number`): Last buffer line of the selection (1-based).
- `label` (`string`): The terminal's label (`Terminal 1`).
- `startLine` (`number`): First buffer line of the selection (1-based).
- `text` (`string`): The selected text.

Source: [ui/src/terminal/TerminalProvider.tsx:29](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L29)

### `TerminalTabHandlers`

Interface.

Keyboard handlers a terminal area registers on its root (`TerminalAppActions.registerTabScope`).

```ts
interface TerminalTabHandlers
```

**Properties**

- `close` (`() => boolean`): Closes the active terminal. False when there was none (whatever holds the area closes instead).
- `step` (`(direction: -1 | 1) => boolean`): Activates the next (`1`) or previous (`-1`) terminal. False when there was nothing to move to.

Source: [ui/src/terminal/TerminalProvider.tsx:41](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L41)

## Types

### `TerminalProviderProps`

Type.

Props for [`TerminalProvider`](https://zidane.si/docs/reference/ui-terminal-terminal-provider.md#TerminalProvider): a `host` (the provider creates the store) or a `store` the app created.

```ts
type TerminalProviderProps = ({ host: TerminalHost; store?: never } | { host?: never; store: TerminalStore }) & { actions?: TerminalAppActions; children: ReactNode; enabled?: boolean; labels?: Partial<TerminalLabels>; symbolsFontUrl?: string; waiting?: TerminalWaiting | null }
```

Source: [ui/src/terminal/TerminalProvider.tsx:91](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L91)

### `TerminalWaiting`

Type.

Why there are no terminals for a while: the link to what runs them is coming up, or down.

```ts
type TerminalWaiting = 'connecting' | 'unreachable'
```

Source: [ui/src/terminal/TerminalProvider.tsx:72](https://github.com/Tahul/zidane/blob/main/ui/src/terminal/TerminalProvider.tsx#L72)