# zidane-ui/keybindings

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

## Components

### `FooterHint`

Component.

A footer legend entry: the keys, then what they do (`↑ ↓ Navigate`).

```ts
function FooterHint(props: FooterHintProps): Element
```

**Parameters**

- `props` (`FooterHintProps`): See [`FooterHintProps`](https://zidane.si/docs/reference/ui-keybindings.md#FooterHintProps).

**Returns** `Element`

**Props**

- `className?` (`string`): Classes merged on the root.
- `keys` (`readonly string[]`): The binding specs, each drawn as a small [`KeyHint`](https://zidane.si/docs/reference/ui-keybindings.md#KeyHint).
- `label` (`string`): What they do (`Navigate`).
- `style?` (`CSSProperties`): Styles on the root.

Source: [ui/src/keybindings/KeyHint.tsx:69](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyHint.tsx#L69)

### `KeybindingsProvider`

Component.

Provides a [`KeybindingsHost`](https://zidane.si/docs/reference/ui-keybindings-headless.md#KeybindingsHost) and optional label overrides to the keybindings hooks and components below it.

```ts
function KeybindingsProvider(props: KeybindingsProviderProps): Element
```

**Parameters**

- `props` (`KeybindingsProviderProps`): Provider props: the `host`, optional `labels`, and the `children` to render.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The app.
- `host` (`KeybindingsHost`): Where the user's overrides live.
- `labels?` (`Partial<{ keyHintOr: string }>`): Overrides for the built-in strings. Keys you leave out keep the default English label.

Source: [ui/src/keybindings/KeybindingsProvider.tsx:70](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L70)

### `KeyCommandsProvider`

Component.

Holds a key command registry and fires its handlers on the document, against the bindings of the nearest
`KeybindingsProvider` (the defaults without one). `AppHostProvider` mounts one.

```ts
function KeyCommandsProvider(props: KeyCommandsProviderProps): Element
```

**Parameters**

- `props` (`KeyCommandsProviderProps`): The optional `registry` and the `children`.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The app.
- `registry?` (`KeyCommandRegistry`): The registry to dispatch. Absent: the provider makes its own.

Source: [ui/src/keybindings/KeyCommands.tsx:52](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyCommands.tsx#L52)

### `KeyHint`

Component.

A key binding as keycaps: one `.zg-keycap` per key (`⌘` `K`), macOS glyphs, alternatives quietly separated.

```ts
function KeyHint(props: KeyHintProps): Element
```

**Parameters**

- `props` (`KeyHintProps`): See [`KeyHintProps`](https://zidane.si/docs/reference/ui-keybindings.md#KeyHintProps).

**Returns** `Element`

**Props**

- `className?` (`string`): Classes merged on the root.
- `size?` (`'sm' | 'md'`): `sm` for dense rows (footer hints), `md` (default) for lists.
- `spec` (`string`): The binding spec (`cmd+k`, `ctrl+w | cmd+w`).
- `style?` (`CSSProperties`): Styles on the root.

Source: [ui/src/keybindings/KeyHint.tsx:36](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyHint.tsx#L36)

## Functions

### `bindKeyListeners`

Function.

Listens on the document for the given actions' chords (the dispatcher's rules, see the header) and calls the
handler `read` returns at press time. Returns the function that removes the listeners.

```ts
function bindKeyListeners(
  actions: readonly KeyAction[],
  merged: KeyBindings,
  read: (action: KeyAction) => (() => void) | undefined,
): () => void
```

**Parameters**

- `actions` (`readonly KeyAction[]`): The bound actions, in order: the first matching a chord wins.
- `merged` (`KeyBindings`): The bindings in effect.
- `read` (`(action: KeyAction) => (() => void) | undefined`): The handler of an action now (`undefined`: let the press through).

**Returns** `() => void`

Source: [ui/src/keybindings/KeybindingsProvider.tsx:169](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L169)

### `matchesBinding`

Function.

Whether a key event fires a binding. All declared modifiers must be pressed and no others, so `'o'` does not match
`ctrl+o` and `'ctrl+o'` does not match `ctrl+shift+o`. A spec with alternatives (`ctrl+w | cmd+w`) matches any.

```ts
function matchesBinding(event: KeyboardEvent, spec: string | ParsedBinding): boolean
```

**Parameters**

- `event` (`KeyboardEvent`): The key event.
- `spec` (`string | ParsedBinding`): A spec string, or one parsed chord.

**Returns** `boolean`

Source: [ui/src/keybindings/match.ts:15](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/match.ts#L15)

### `modIsMeta`

Function.

Whether this platform's `mod` is ⌘.

```ts
function modIsMeta(): boolean
```

**Returns** `boolean`

Source: [ui/src/keybindings/press.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/press.ts#L29)

### `pressChord`

Function.

Presses `chord` where focus is. Returns whether a binding took it (a listener called
`preventDefault`). A chord that doesn't parse presses nothing and returns `false`.

```ts
function pressChord(chord: string, options?: PressChordOptions): boolean
```

**Parameters**

- `chord` (`string`): The chord (`'mod+k'`, `'escape'`).
- `options?` (`PressChordOptions`, default `{}`): How to resolve `mod`, and where the key goes.

**Returns** `boolean`

Source: [ui/src/keybindings/press.ts:61](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/press.ts#L61)

### `resolveChord`

Function.

A chord with `mod` resolved: `cmd` on macOS, `ctrl` elsewhere. Other parts stay as written.

```ts
function resolveChord(chord: string, mac?: boolean): string
```

**Parameters**

- `chord` (`string`): The chord (`'mod+shift+k'`).
- `mac?` (`boolean`): Resolve `mod` to `cmd`. Default: this platform's.

**Returns** `string`

Source: [ui/src/keybindings/press.ts:39](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/press.ts#L39)

### `useHelpKey`

Function.

Calls `onOpen` on a bare `?` outside fields. The listener attaches once; both callbacks are read at press time.

```ts
function useHelpKey(onOpen: (() => void) | undefined, blocked?: () => boolean): void
```

**Parameters**

- `onOpen` (`(() => void) | undefined`): Opens the shortcut reference. Absent: nothing listens.
- `blocked?` (`() => boolean`): Whether something else owns input now (a modal is open).

Source: [ui/src/keybindings/useHelpKey.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/useHelpKey.ts#L19)

### `useKeybindings`

Function.

Listens on the document for the bound actions' keys and calls their handlers. Handlers are read at press time,
so a fresh object each render costs nothing; only the set of bound actions decides what is listened for. The
first action (in the caller's order) matching a chord wins.

```ts
function useKeybindings(handlers: KeybindingHandlers): void
```

**Parameters**

- `handlers` (`KeybindingHandlers`): A handler per action to bind.

Source: [ui/src/keybindings/KeybindingsProvider.tsx:120](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L120)

### `useKeybindingsHost`

Function.

The [`KeybindingsHost`](https://zidane.si/docs/reference/ui-keybindings-headless.md#KeybindingsHost) from the nearest [`KeybindingsProvider`](https://zidane.si/docs/reference/ui-keybindings.md#KeybindingsProvider), or `null` outside one (the defaults apply).

```ts
function useKeybindingsHost(): KeybindingsHost | null
```

**Returns** `KeybindingsHost | null`

Source: [ui/src/keybindings/KeybindingsProvider.tsx:79](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L79)

### `useKeybindingsLabels`

Function.

Returns the keybindings components' strings: the defaults merged with any overrides.

```ts
function useKeybindingsLabels(): { keyHintOr: string }
```

**Returns** `{ keyHintOr: string }`

Source: [ui/src/keybindings/useKeybindingsLabels.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/useKeybindingsLabels.ts#L11)

### `useKeyCommandActions`

Function.

The bound actions of the nearest registry, as one space-separated string: re-renders only when the set changes.

```ts
function useKeyCommandActions(): string
```

**Returns** `string`

Source: [ui/src/keybindings/KeyCommands.tsx:116](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyCommands.tsx#L116)

### `useKeyCommandRegistry`

Function.

The registry of the nearest [`KeyCommandsProvider`](https://zidane.si/docs/reference/ui-keybindings.md#KeyCommandsProvider), or `null` outside one.

```ts
function useKeyCommandRegistry(): KeyCommandRegistry | null
```

**Returns** `KeyCommandRegistry | null`

Source: [ui/src/keybindings/KeyCommands.tsx:85](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyCommands.tsx#L85)

### `useKeyCommands`

Function.

Registers handlers with the nearest [`KeyCommandsProvider`](https://zidane.si/docs/reference/ui-keybindings.md#KeyCommandsProvider) for as long as the component is mounted. A fresh
object each render costs nothing: handlers are read at press time. Outside a provider it does nothing.

```ts
function useKeyCommands(commands: KeyCommands): void
```

**Parameters**

- `commands` (`KeyCommands`): A handler per action this part binds.

Source: [ui/src/keybindings/KeyCommands.tsx:95](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyCommands.tsx#L95)

### `useMergedKeybindings`

Function.

The bindings in effect (defaults plus the host's overrides), re-rendering when the overrides change.

```ts
function useMergedKeybindings(): KeyBindings
```

**Returns** `KeyBindings`

Source: [ui/src/keybindings/KeybindingsProvider.tsx:88](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L88)

## Interfaces

### `FooterHintProps`

Interface.

Props for [`FooterHint`](https://zidane.si/docs/reference/ui-keybindings.md#FooterHint).

```ts
interface FooterHintProps
```

**Properties**

- `className?` (`string`): Classes merged on the root.
- `keys` (`readonly string[]`): The binding specs, each drawn as a small [`KeyHint`](https://zidane.si/docs/reference/ui-keybindings.md#KeyHint).
- `label` (`string`): What they do (`Navigate`).
- `style?` (`CSSProperties`): Styles on the root.

Source: [ui/src/keybindings/KeyHint.tsx:53](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyHint.tsx#L53)

### `KeybindingsProviderProps`

Interface.

Props for [`KeybindingsProvider`](https://zidane.si/docs/reference/ui-keybindings.md#KeybindingsProvider).

```ts
interface KeybindingsProviderProps
```

**Properties**

- `children` (`ReactNode`): The app.
- `host` (`KeybindingsHost`): Where the user's overrides live.
- `labels?` (`Partial<{ keyHintOr: string }>`): Overrides for the built-in strings. Keys you leave out keep the default English label.

Source: [ui/src/keybindings/KeybindingsProvider.tsx:56](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L56)

### `KeyCommandsProviderProps`

Interface.

Props for [`KeyCommandsProvider`](https://zidane.si/docs/reference/ui-keybindings.md#KeyCommandsProvider).

```ts
interface KeyCommandsProviderProps
```

**Properties**

- `children` (`ReactNode`): The app.
- `registry?` (`KeyCommandRegistry`): The registry to dispatch. Absent: the provider makes its own.

Source: [ui/src/keybindings/KeyCommands.tsx:37](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyCommands.tsx#L37)

### `KeyHintProps`

Interface.

Props for [`KeyHint`](https://zidane.si/docs/reference/ui-keybindings.md#KeyHint).

```ts
interface KeyHintProps
```

**Properties**

- `className?` (`string`): Classes merged on the root.
- `size?` (`'sm' | 'md'`): `sm` for dense rows (footer hints), `md` (default) for lists.
- `spec` (`string`): The binding spec (`cmd+k`, `ctrl+w | cmd+w`).
- `style?` (`CSSProperties`): Styles on the root.

Source: [ui/src/keybindings/KeyHint.tsx:14](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeyHint.tsx#L14)

### `PressChordOptions`

Interface.

Options of [`pressChord`](https://zidane.si/docs/reference/ui-keybindings.md#pressChord).

```ts
interface PressChordOptions
```

**Properties**

- `mac?` (`boolean`): Resolve `mod` to `cmd`. Default: this platform's.
- `target?` (`EventTarget`): Where the key goes. Default: the focused element, else the body.

Source: [ui/src/keybindings/press.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/press.ts#L47)

## Types

### `KeybindingHandlers`

Type.

A handler per action the caller binds.

```ts
type KeybindingHandlers = KeyCommands
```

Source: [ui/src/keybindings/KeybindingsProvider.tsx:111](https://github.com/Tahul/zidane/blob/main/ui/src/keybindings/KeybindingsProvider.tsx#L111)