zidane-ui 9.1.1 → 9.1.3

package/src/keybindings/KeybindingsProvider.tsx

@@ -1,231 +0,0 @@
-/**
- * Puts a `KeybindingsHost` (and optional label overrides) in context, and
- * the global keyboard dispatcher that drives every `KeyAction` against the
- * merged map of `DEFAULT_KEYBINDINGS` and the host's overrides.
- *
- * The dispatcher's rules (parity with the TUI):
- *   - Bindings match exactly: `ctrl+o`, `ctrl+x`, `shift+tab`, …
- *   - Modifier match is strict: `'o'` does NOT fire `ctrl+o`.
- *   - Bare keys are ignored while the user types in an input, textarea,
- *     contenteditable or the code editor (`keyScopeOf`). Combos with a
- *     modifier always fire: the user clearly meant a shortcut.
- *
- * A matched handler's state updates render as a transition: the keydown
- * ends at once and the render yields to the next frame and keys, so a
- * shortcut that redraws much of the window (the side panel, a zoom) never
- * shows as a long frame. The catalog's `urgent` actions (focus moves, the
- * dialogs and the palette, a copy) render before the next key instead.
- * Updates to an external store (`useSyncExternalStore`) render at once
- * either way: React never defers them.
- *
- * Tab keys first: {@link CAPTURE_ACTIONS} match on the way DOWN (capture),
- * before the focused widget sees the press, and stop it there. Embedded
- * widgets read them as plain arrows (the file tree took ⌥⌘→ for → and
- * swallowed it; a terminal would send it to the shell).
- *
- * The first `useKeybindings` under a host reads its overrides once; a
- * `host.refresh()` (a settings panel's Reload) re-attaches every listener
- * with the new specs, without a restart.
- */
-import {
-  createContext,
-  startTransition,
-  useContext,
-  useEffect,
-  useMemo,
-  useReducer,
-  useRef,
-  useSyncExternalStore,
-  type ReactNode,
-} from 'react';
-import { parseBindingSpecs } from 'zidane/chat/pure';
-
-import { LabelsProvider } from '../labels';
-import { DEFAULT_KEYBINDINGS, KEYBINDING_DEF_BY_ACTION, type KeyAction, type KeyBindings } from './headless/catalog';
-import type { KeyCommands } from './headless/commands';
-import type { KeybindingsHost, KeyOverrides } from './headless/host';
-import { bindingAllowedIn, keyScopeOf } from './headless/key-scope';
-import type { KeybindingsLabels } from './headless/labels';
-import { getMergedKeybindings } from './headless/overrides';
-import { loadOnce } from './load-once';
-import { matchesBinding } from './match';
-
-const HostContext = createContext<KeybindingsHost | null>(null);
-
-/** Props for {@link KeybindingsProvider}. */
-export interface KeybindingsProviderProps {
-  /** Where the user's overrides live. */
-  host: KeybindingsHost;
-  /** Overrides for the built-in strings. Keys you leave out keep the default English label. */
-  labels?: Partial<KeybindingsLabels>;
-  /** The app. */
-  children: ReactNode;
-}
-
-/**
- * Provides a {@link KeybindingsHost} and optional label overrides to the keybindings hooks and components below it.
- *
- * @param props - Provider props: the `host`, optional `labels`, and the `children` to render.
- */
-export function KeybindingsProvider({ host, labels, children }: KeybindingsProviderProps) {
-  return (
-    <HostContext.Provider value={host}>
-      <LabelsProvider<KeybindingsLabels> labels={labels}>{children}</LabelsProvider>
-    </HostContext.Provider>
-  );
-}
-
-/** The {@link KeybindingsHost} from the nearest {@link KeybindingsProvider}, or `null` outside one (the defaults apply). */
-export function useKeybindingsHost(): KeybindingsHost | null {
-  return useContext(HostContext);
-}
-
-const noSubscribe = () => () => {};
-const NO_OVERRIDES: KeyOverrides = {};
-const noOverrides = () => NO_OVERRIDES;
-
-/** The bindings in effect (defaults plus the host's overrides), re-rendering when the overrides change. */
-export function useMergedKeybindings(): KeyBindings {
-  const host = useKeybindingsHost();
-  useEffect(() => loadOnce(host), [host]);
-  const read = host?.overrides.get ?? noOverrides;
-  const overrides = useSyncExternalStore(host?.overrides.subscribe ?? noSubscribe, read, read);
-  return useMemo(() => ({ ...DEFAULT_KEYBINDINGS, ...overrides }), [overrides]);
-}
-
-/** Matched before the focused element handles the press (see the header). */
-const CAPTURE_ACTIONS: ReadonlySet<KeyAction> = new Set<KeyAction>(['tabNext', 'tabPrev']);
-
-/**
- * Runs a matched action's handler: as a transition, unless the catalog marks the action `urgent` (see the header).
- *
- * @param action - The matched action.
- * @param handler - Its handler.
- */
-function runKeyHandler(action: KeyAction, handler: () => void): void {
-  if (KEYBINDING_DEF_BY_ACTION[action].urgent) handler();
-  else startTransition(handler);
-}
-
-/** A handler per action the caller binds. */
-export type KeybindingHandlers = KeyCommands;
-
-/**
- * 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.
- *
- * @param handlers - A handler per action to bind.
- */
-export function useKeybindings(handlers: KeybindingHandlers): void {
-  const host = useKeybindingsHost();
-  /*
-   * Subscribe to override changes via a forceUpdate-shaped reducer.
-   * The keydown listener inside the effect closes over `merged` so
-   * a refresh re-attaches with the new specs. Cheap: bindings rarely
-   * change at runtime.
-   */
-  const [tick, bump] = useReducer((n: number) => n + 1, 0);
-  /*
-   * Handlers are read at press time, so a caller handing a fresh object each
-   * render (App's rebuilds whenever the active session changes) neither
-   * re-parses every binding nor detaches and re-attaches the document
-   * listeners. Only the SET of bound actions decides what is listened for.
-   */
-  const handlersRef = useRef(handlers);
-  handlersRef.current = handlers;
-  // In the caller's order: the first action matching a chord wins.
-  const actionsKey = Object.keys(handlers).join(' ');
-
-  useEffect(() => {
-    loadOnce(host);
-    if (!host) return undefined;
-    const unsubscribe = host.overrides.subscribe(() => bump());
-    return () => {
-      unsubscribe();
-    };
-  }, [host]);
-
-  useEffect(
-    () =>
-      bindKeyListeners(
-        actionsKey ? (actionsKey.split(' ') as KeyAction[]) : [],
-        getMergedKeybindings(host),
-        (action) => handlersRef.current[action],
-      ),
-    // `tick` re-runs the effect when the overrides change; the bindings are read inside.
-    [actionsKey, tick, host],
-  );
-}
-
-/**
- * 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.
- *
- * @param actions - The bound actions, in order: the first matching a chord wins.
- * @param merged - The bindings in effect.
- * @param read - The handler of an action now (`undefined`: let the press through).
- */
-export function bindKeyListeners(
-  actions: readonly KeyAction[],
-  merged: KeyBindings,
-  read: (action: KeyAction) => (() => void) | undefined,
-): () => void {
-  // One entry per chord: a binding may list several (`ctrl+w | cmd+w`).
-  const all = actions.flatMap((action) => parseBindingSpecs(merged[action]).map((spec) => ({ action, parsed: spec })));
-
-  const listen = (parsed: typeof all, capture: boolean) => (event: KeyboardEvent) => {
-    /*
-     * Ignore bare-letter shortcuts (without modifiers) when the user is
-     * typing in an editable surface. Combos that include a modifier are
-     * always intentional and bypass this guard.
-     *
-     * `shift` is counted as a modifier here so shifted chords fire
-     * while the prompt has focus. Bare letters typed with shift
-     * (e.g. `A`) still won't match any registered binding so this
-     * doesn't break normal typing: every binding either has an
-     * additional modifier or is bound to a non-letter key.
-     */
-    const hasModifier = event.ctrlKey || event.metaKey || event.altKey || event.shiftKey;
-    const scope = keyScopeOf(event);
-
-    if (!hasModifier && (scope === 'editor' || scope === 'input')) {
-      return;
-    }
-
-    for (const { action, parsed: spec } of parsed) {
-      if (!spec) {
-        continue;
-      }
-
-      if (matchesBinding(event, spec) && bindingAllowedIn(scope, spec, action)) {
-        const handler = read(action);
-
-        if (handler) {
-          event.preventDefault();
-          // Taken on the way down: the focused widget never sees it.
-          if (capture) event.stopPropagation();
-          runKeyHandler(action, handler);
-
-          return;
-        }
-      }
-    }
-  };
-
-  const onCapture = listen(
-    all.filter((b) => CAPTURE_ACTIONS.has(b.action)),
-    true,
-  );
-  const onKey = listen(
-    all.filter((b) => !CAPTURE_ACTIONS.has(b.action)),
-    false,
-  );
-  document.addEventListener('keydown', onCapture, true);
-  document.addEventListener('keydown', onKey);
-
-  return () => {
-    document.removeEventListener('keydown', onCapture, true);
-    document.removeEventListener('keydown', onKey);
-  };
-}

package/src/keybindings/headless/catalog.ts

@@ -1,360 +0,0 @@
-/**
- * The app's keyboard actions: the catalog (`KEYBINDING_DEFS`, one default
- * spec, label and description per action) and the default map.
- *
- * It shares the TUI's action names and spec grammar, and adds the desktop
- * app's own actions. The grammar (`parseBindingSpec`, aliases, `|`
- * alternatives) is core's, from `zidane/chat/pure`, so a `keybindings.json`
- * parses the same on both surfaces. The user's overrides come from the host
- * (`KeybindingsHost.overrides`); `getMergedKeybindings` layers them over
- * `DEFAULT_KEYBINDINGS`. The DOM matcher is `matchesBinding` (`zidane-ui/keybindings`).
- */
-export { bindingAlternatives, parseBindingSpec, parseBindingSpecs, type ParsedBinding } from 'zidane/chat/pure';
-
-/** Every action a key binding can fire. */
-export type KeyAction =
-  | 'openSettings'
-  | 'openSessionDetails'
-  | 'openModelPicker'
-  | 'openEffortPicker'
-  | 'openTodos'
-  | 'openArtifacts'
-  | 'openMainSession'
-  | 'openUsagePanel'
-  | 'newSession'
-  | 'openKeybindings'
-  | 'openPalette'
-  | 'cancelToolCall'
-  | 'cycleAgent'
-  | 'enterSelectTurnMode'
-  | 'toggleSidebar'
-  | 'sessionGenerateTitle'
-  | 'sessionCompact'
-  | 'sessionExportMarkdown'
-  | 'sessionExportJson'
-  | 'sessionDelete'
-  | 'sessionCopyId'
-  | 'sessionFavorite'
-  | 'zoomIn'
-  | 'zoomOut'
-  | 'zoomReset'
-  | 'panelNext'
-  | 'panelPrev'
-  | 'tabNext'
-  | 'tabPrev'
-  | 'closeTab'
-  | 'toggleTerminal'
-  | 'newTerminal'
-  | 'annotatePage'
-  | 'splitTabRight'
-  | 'splitTabDown';
-
-/** One action of the catalog. */
-export interface KeyBindingDef {
-  /** The action. */
-  action: KeyAction;
-  /** Its default spec (`cmd+k`, `ctrl+w | cmd+w`); `''` for unbound. */
-  default: string;
-  /** Its short name. */
-  label: string;
-  /** What it does. */
-  description: string;
-  /**
-   * Its state updates render before the next key. Without it they render as a transition (`bindKeyListeners`), so a
-   * shortcut that redraws much of the window ends its keydown at once and never holds up a frame or a keystroke. Set
-   * it on an action that moves the focus or opens what the next key goes to (a dialog, the palette, a terminal, a
-   * new chat's composer), since a key typed before that rendered would land where the focus was; and on a copy,
-   * which confirms at once.
-   */
-  urgent?: true;
-}
-
-/** The catalog, in display order. */
-export const KEYBINDING_DEFS: readonly KeyBindingDef[] = [
-  {
-    action: 'openSettings',
-    /*
-     * `cmd+,` is the canonical macOS Settings shortcut — every native
-     * Mac app binds it. Override via `~/.zidane/keybindings.json` if
-     * desired.
-     */
-    default: 'cmd+,',
-    label: 'settings',
-    description: 'open the Settings modal (toggles, theme, keybindings)',
-    urgent: true,
-  },
-  {
-    action: 'openSessionDetails',
-    default: 'ctrl+shift+x',
-    label: 'session',
-    description: 'open the session details modal (rename, export, delete)',
-    urgent: true,
-  },
-  {
-    action: 'openModelPicker',
-    default: 'ctrl+m',
-    label: 'model',
-    description: 'open the cross-provider model picker',
-    urgent: true,
-  },
-  {
-    action: 'openEffortPicker',
-    default: 'ctrl+l',
-    label: 'effort',
-    description: 'open the reasoning-effort picker (when the active model supports it)',
-    urgent: true,
-  },
-  {
-    action: 'openTodos',
-    default: 'ctrl+t',
-    label: 'todos',
-    description: "open the active run's todo list (the agent's `todowrite` checkpoints)",
-  },
-  {
-    action: 'openArtifacts',
-    default: 'ctrl+shift+a',
-    label: 'panel',
-    description: 'toggle the side panel (artifacts the session produced, plus extension panels)',
-  },
-  {
-    action: 'openMainSession',
-    default: 'ctrl+shift+m',
-    label: 'Jump to main session',
-    description: 'jump to (or lazily create) the pinned "Main" orchestration session for the active directory',
-    urgent: true,
-  },
-  {
-    action: 'openUsagePanel',
-    default: 'ctrl+p',
-    label: 'usage',
-    description: 'open the usage panel (rate-limit windows and credits per provider, GitHub API limits)',
-    urgent: true,
-  },
-  {
-    action: 'newSession',
-    default: 'ctrl+n',
-    label: 'new session',
-    description: 'leave the active session and start a fresh one',
-    urgent: true,
-  },
-  {
-    action: 'openKeybindings',
-    default: 'ctrl+y',
-    label: 'keybindings',
-    description: 'open the shortcut reference',
-    urgent: true,
-  },
-  {
-    action: 'openPalette',
-    default: 'cmd+k',
-    label: 'palette',
-    description: 'toggle the command palette: search every action, command, panel, session and setting',
-    urgent: true,
-  },
-  {
-    action: 'cancelToolCall',
-    default: 'ctrl+k',
-    label: 'cancel work',
-    description: 'cancel a running tool call or background task',
-    urgent: true,
-  },
-  {
-    action: 'cycleAgent',
-    /*
-     * `shift+cmd+i` over `shift+tab` — Tab inside the prompt editor
-     * (TipTap) inserts a tab character; trapping shift+tab globally
-     * for an agent cycle would steal the natural shift-tab navigation
-     * the editor + form controls expect. `⇧⌘I` is unclaimed on macOS
-     * and maps cleanly to "switch (I)dentity" mnemonics.
-     */
-    default: 'shift+cmd+i',
-    label: 'cycle agent',
-    description: 'cycle to the next agent profile',
-  },
-  {
-    action: 'enterSelectTurnMode',
-    default: 'ctrl+s',
-    label: 'messages',
-    description: 'enter select-turn mode to navigate previous messages',
-    urgent: true,
-  },
-  {
-    action: 'toggleSidebar',
-    /*
-     * `cmd+b` follows the cross-app convention (VS Code, Notion, Linear,
-     * Slack, …) for show/hide the sidebar. `b` for "bar" / "browse".
-     */
-    default: 'cmd+b',
-    label: 'sidebar',
-    description: 'show or hide the chats sidebar',
-  },
-  /*
-   * Session actions — the TUI binds these to bare letters (`g`, `k`, …)
-   * scoped to its session-details modal. The GUI registers them as
-   * global accelerators (there's no modal-scoped dispatcher here), so
-   * bare letters would misfire whenever focus sits outside an editable
-   * surface. `ctrl+shift+<TUI letter>` keeps the canonical mnemonic
-   * while gating on a deliberate chord.
-   */
-  {
-    action: 'sessionGenerateTitle',
-    default: 'ctrl+shift+t',
-    label: 'generate title',
-    description: 'generate a title for the session via the active provider/model',
-  },
-  {
-    action: 'sessionCompact',
-    default: 'ctrl+shift+k',
-    label: 'compact',
-    description: 'compact older turns via an LLM summary (model still sees everything from the boundary down)',
-  },
-  {
-    action: 'sessionExportMarkdown',
-    default: 'ctrl+shift+e',
-    label: 'export md',
-    description: 'export the session as Markdown under .{prefix}/sessions/',
-  },
-  {
-    action: 'sessionExportJson',
-    default: 'ctrl+shift+j',
-    label: 'export json',
-    description: 'export the session as JSON under .{prefix}/sessions/',
-  },
-  {
-    action: 'sessionDelete',
-    default: 'ctrl+shift+d',
-    label: 'delete',
-    description: 'delete the entire session (confirm dialog)',
-    urgent: true,
-  },
-  {
-    action: 'sessionCopyId',
-    default: 'ctrl+shift+c',
-    label: 'copy id',
-    description: 'copy the full session id to the clipboard',
-    urgent: true,
-  },
-  // Unbound by default: the palette and the row menu reach it; bind one in Settings.
-  {
-    action: 'sessionFavorite',
-    default: '',
-    label: 'favorite',
-    description: 'add the session to favorites, or remove it',
-  },
-  // GUI-only: cycle the side panel's tabs.
-  {
-    action: 'panelNext',
-    default: 'ctrl+shift+]',
-    label: 'next panel',
-    description: 'cycle to the next side-panel tab (opens the panel)',
-  },
-  {
-    action: 'panelPrev',
-    default: 'ctrl+shift+[',
-    label: 'previous panel',
-    description: 'cycle to the previous side-panel tab (opens the panel)',
-  },
-  /*
-   * GUI-only: tabs within whatever holds focus (`tab-scopes.ts`): open files
-   * in Files, changed files in Diffs, terminals; with the focus elsewhere, the
-   * spaces (Spaces on), else the side panel's tabs.
-   */
-  {
-    action: 'tabNext',
-    default: 'cmd+alt+right',
-    label: 'next tab',
-    description:
-      'next tab where the focus is: open file, changed file, terminal; elsewhere the next space (Spaces on) or side-panel tab',
-    urgent: true,
-  },
-  {
-    action: 'tabPrev',
-    default: 'cmd+alt+left',
-    label: 'previous tab',
-    description:
-      'previous tab where the focus is: open file, changed file, terminal; elsewhere the previous space (Spaces on) or side-panel tab',
-    urgent: true,
-  },
-  {
-    action: 'closeTab',
-    default: 'ctrl+w | cmd+w',
-    label: 'close tab',
-    description: 'close the open file in Files, the terminal, or else the active side-panel tab',
-    urgent: true,
-  },
-  // GUI-only: the terminal drawer under the chat (VS Code's chords; `cmd+j` is
-  // VS Code's panel toggle too, and the one that works on every layout).
-  {
-    action: 'toggleTerminal',
-    default: 'ctrl+` | cmd+j',
-    label: 'terminal',
-    description: 'show or hide the terminal drawer under the chat',
-    urgent: true,
-  },
-  {
-    action: 'newTerminal',
-    default: 'ctrl+shift+`',
-    label: 'new terminal',
-    description: "open a new terminal in the session's environment (shows the drawer)",
-    urgent: true,
-  },
-  // GUI-only: annotate mode in the Browser tab (Codex's key), while the tab is on screen.
-  {
-    action: 'annotatePage',
-    default: 'cmd+.',
-    label: 'annotate',
-    description: 'mark elements and areas of the page in the Browser tab for the agent, or stop marking',
-  },
-  // GUI-only: the side panel's tab groups. Split follows VS Code (⌘\ splits the editor).
-  {
-    action: 'splitTabRight',
-    default: 'cmd+\\',
-    label: 'split right',
-    description: "split the side panel's active tab into a new group on the right",
-  },
-  {
-    action: 'splitTabDown',
-    // Not ⇧⌘\: shifted, a US layout reports `|`, which specs read as a separator.
-    default: 'alt+cmd+\\',
-    label: 'split down',
-    description: "split the side panel's active tab into a new group below",
-  },
-  /*
-   * GUI-only: interface size. Persisted through the Appearance store (not
-   * Electron's transient page zoom) so the chosen scale survives relaunch.
-   * `plus` is the physical `=` key; ⌘= is the macOS zoom-in convention.
-   */
-  {
-    action: 'zoomIn',
-    default: 'cmd+plus',
-    label: 'zoom in',
-    description: 'increase the interface size',
-  },
-  {
-    action: 'zoomOut',
-    default: 'cmd+minus',
-    label: 'zoom out',
-    description: 'decrease the interface size',
-  },
-  {
-    action: 'zoomReset',
-    default: 'cmd+0',
-    label: 'reset zoom',
-    description: 'reset the interface size to 100%',
-  },
-];
-
-/** A spec per action. */
-export type KeyBindings = Record<KeyAction, string>;
-
-/** The default spec per action. */
-export const DEFAULT_KEYBINDINGS: KeyBindings = KEYBINDING_DEFS.reduce(
-  (acc, def) => Object.assign(acc, { [def.action]: def.default }),
-  {} as KeyBindings,
-);
-
-/** The catalog by action. */
-export const KEYBINDING_DEF_BY_ACTION: Readonly<Record<KeyAction, KeyBindingDef>> = KEYBINDING_DEFS.reduce(
-  (acc, def) => Object.assign(acc, { [def.action]: def }),
-  {} as Record<KeyAction, KeyBindingDef>,
-);

package/src/keybindings/headless/commands.ts

@@ -1,77 +0,0 @@
-/**
- * The key command registry: the handlers an app's parts register for the
- * catalog's actions, merged into the one map the dispatcher and the palette
- * read. Each part holds a slot and replaces its handlers as its state
- * changes; nothing re-renders for it. Readers that care which actions are
- * bound (the dispatcher re-attaching, the palette listing them) compare
- * `actions()`: handler identities change on every update, the set rarely.
- */
-import type { Readable } from '../../chat/headless/store';
-import type { KeyAction } from './catalog';
-
-/** A handler per action. */
-export type KeyCommands = Partial<Record<KeyAction, () => void>>;
-
-/** One part's handlers in a {@link KeyCommandRegistry}. */
-export interface KeyCommandSlot {
-  /** Replaces this part's handlers. */
-  set(commands: KeyCommands): void;
-  /** Removes this part's handlers. */
-  dispose(): void;
-}
-
-/** The merged handlers of every registered part. */
-export interface KeyCommandRegistry extends Readable<KeyCommands> {
-  /**
-   * Adds a part. Parts merge in the order they registered: an action an earlier part binds keeps its place, a later
-   * part's handler for it wins.
-   *
-   * @param commands - The part's first handlers.
-   */
-  register(commands?: KeyCommands): KeyCommandSlot;
-  /** The bound actions, in merge order (the first action matching a chord wins). One string per set: compare it. */
-  actions(): string;
-}
-
-/** A registry with no parts: what the dispatcher reads until something registers. */
-export function createKeyCommandRegistry(): KeyCommandRegistry {
-  const slots: { commands: KeyCommands }[] = [];
-  const listeners = new Set<() => void>();
-  let merged: KeyCommands = {};
-  let actions = '';
-
-  const update = () => {
-    const next: KeyCommands = {};
-    for (const slot of slots) Object.assign(next, slot.commands);
-    merged = next;
-    actions = Object.keys(next).join(' ');
-    for (const listener of [...listeners]) listener();
-  };
-
-  return {
-    get: () => merged,
-    actions: () => actions,
-    subscribe(onChange) {
-      listeners.add(onChange);
-      return () => listeners.delete(onChange);
-    },
-    register(commands = {}) {
-      const slot = { commands };
-      slots.push(slot);
-      update();
-      return {
-        set(next) {
-          if (next === slot.commands) return;
-          slot.commands = next;
-          update();
-        },
-        dispose() {
-          const at = slots.indexOf(slot);
-          if (at < 0) return;
-          slots.splice(at, 1);
-          update();
-        },
-      };
-    },
-  };
-}