Keybindings

zidane-ui/keybindings holds the desktop app's keyboard actions: the catalog (every action with its default binding, label and description), a dispatcher that fires your handlers on the document, and KeyHint / FooterHint to draw a binding as keycaps. A KeybindingsHost keeps the user's overrides. The previews below run on a fixture host that rebinds two actions.

Mount it#

import { createBrowserKeybindingsHost } from 'zidane-ui/adapters'
import { KeybindingsProvider, useKeybindings } from 'zidane-ui/keybindings'

const keybindings = createBrowserKeybindingsHost()

function Shortcuts() {
  useKeybindings({ toggleSidebar: () => toggle(), openPalette: () => openPalette() })
  return null
}

export function Root() {
  return (
    <KeybindingsProvider host={keybindings}>
      <Shortcuts />
      <App />
    </KeybindingsProvider>
  )
}

Without a provider the defaults apply. AppHostProvider (zidane-ui/app) puts host.keybindings in a KeybindingsProvider for you.

Register commands#

An app's shortcuts come from many parts: the session on show, the side panel, the zoom. Each part registers its handlers with the key command registry, and one dispatcher fires them. AppHostProvider mounts a KeyCommandsProvider; mount one yourself without it. The desktop app and the web app register the same commands this way, so their shortcuts match.

import { useMemo } from 'react'
import { useAppHost, useConfirm } from 'zidane-ui/app'
import type { ChatSession } from 'zidane-ui/chat/headless'
import { useKeyCommands } from 'zidane-ui/keybindings'
import { usePaletteActions } from 'zidane-ui/palette'
import { createSessionActions, sessionKeyCommands } from 'zidane-ui/session/headless'
import { useWorkspaceKeyCommands } from 'zidane-ui/workspace'

function SessionKeys({ session }: { session: ChatSession | null }) {
  const host = useAppHost()
  const confirm = useConfirm()
  const palette = usePaletteActions()
  const actions = useMemo(() => createSessionActions({ session: host.session, sessions: host.chat?.sessions, confirm }), [host, confirm])
  const panel = useWorkspaceKeyCommands({ scope: !!session, session: !!session })
  useKeyCommands({ ...sessionKeyCommands(actions, session), ...panel, openPalette: palette.toggle })
  return null
}

• Registering re-renders nothing. Handlers are read at press time; the dispatcher re-attaches only when the set of bound actions or the user's overrides change.
• Parts merge in the order they mounted. A later part's handler for an action wins.
• useKeyCommandActions() re-renders only when the set changes. useActionsPaletteSource() (zidane-ui/palette) lists the registered actions in the palette with their chords.
• createKeyCommandRegistry() is the React-free registry, for code outside React.
• useHelpKey(open, blocked) opens your shortcut reference on a bare ?, never while the user types or blocked() says a modal owns input.

How the dispatcher matches#

• A binding matches exactly: 'o' does not fire ctrl+o, and ctrl+o does not fire on ctrl+shift+o.
• A spec may list alternatives: ctrl+w | cmd+w. The grammar is zidane's, so a keybindings.json reads the same in the terminal.
• Bare keys are ignored while the user types in a field or the code editor. keyScopeOf(event) says who owns a key press: editor, input, menu or app. An editor host opts in with data-zg-keyscope="editor".
• In the editor, ctrl plus a letter belongs to the editor (bindingAllowedIn), except closing the tab.
• The tab keys (tabNext, tabPrev) match before the focused widget sees them.
• Handlers are read at press time, so a fresh object each render costs nothing.

matchesBinding(event, spec) is the matcher, for a listener of your own. Punctuation matches by its physical key where a layout types a stand-in.

Pick a host#

getMergedKeybindings(host) and useMergedKeybindings() give the bindings in effect.

Parts#

Test your host#

import { describeKeybindingsHostContract } from 'zidane-ui/keybindings/testing/contract'

describeKeybindingsHostContract('my host', backend => makeHarness(backend), ['save'])