zidane-ui 9.0.4 → 9.1.3

package/src/keybindings/headless/fixture-host.ts

@@ -1,51 +0,0 @@
-/**
- * A `KeybindingsHost` held in memory, for docs, demos, galleries and tests.
- */
-import type { KeybindingsHost } from './host';
-import { createKeybindingOverrides } from './overrides';
-
-/** Options of {@link createFixtureKeybindingsHost}. */
-export interface FixtureKeybindingsOptions {
-  /** The stored overrides (action → spec; unknown actions are dropped on read). Default: none. */
-  overrides?: Readonly<Record<string, string>>;
-  /** Offer `save`. Default: true. */
-  editable?: boolean;
-}
-
-/** Changes the stored overrides from outside. */
-export interface FixtureKeybindingsControl {
-  /** The stored map now. */
-  stored(): Readonly<Record<string, string>>;
-  /** The file changed on disk (the next `refresh` reads it). */
-  store(overrides: Readonly<Record<string, string>>): void;
-}
-
-/** An in-memory {@link KeybindingsHost} and its control. */
-export type FixtureKeybindingsHost = KeybindingsHost & { control: FixtureKeybindingsControl };
-
-/**
- * Creates a {@link KeybindingsHost} held in memory.
- *
- * @param options - The stored overrides, and whether they can be saved.
- */
-export function createFixtureKeybindingsHost(options: FixtureKeybindingsOptions = {}): FixtureKeybindingsHost {
-  let stored: Readonly<Record<string, string>> = { ...options.overrides };
-  const state = createKeybindingOverrides(async () => stored);
-  return {
-    ...state,
-    ...(options.editable === false
-      ? {}
-      : {
-          save: async (next: Readonly<Record<string, string>>) => {
-            stored = { ...next };
-            await state.refresh();
-          },
-        }),
-    control: {
-      stored: () => stored,
-      store(next) {
-        stored = { ...next };
-      },
-    },
-  };
-}

package/src/keybindings/headless/host.ts

@@ -1,29 +0,0 @@
-/**
- * The keybindings host: where the user's overrides of the default bindings
- * live. An app implements it once (the desktop app over IPC and
- * `~/.zidane/keybindings.json`, a web app over `localStorage` with
- * `createBrowserKeybindingsHost`) and hands it to `KeybindingsProvider` (or
- * `AppHost.keybindings`). Without a host the defaults apply.
- *
- * `overrides` and `refresh` are required; leaving another member out hides
- * what needs it (no `save`: the bindings are edited elsewhere).
- */
-import type { Readable } from '../../chat/headless/store';
-import type { KeyAction } from './catalog';
-
-/** The user's specs per action, over the defaults. Only known actions with a non-empty spec. */
-export type KeyOverrides = Readonly<Partial<Record<KeyAction, string>>>;
-
-/** The keybindings host. */
-export interface KeybindingsHost {
-  /** The overrides: `{}` until read. */
-  overrides: Readable<KeyOverrides>;
-  /** Reads the overrides again and tells subscribers. Never rejects: missing or unreadable reads as none. */
-  refresh(): Promise<void>;
-  /** Replaces the overrides (action → spec), then reads them back. Absent: read-only. */
-  save?(overrides: Readonly<Record<string, string>>): Promise<void>;
-  /** Opens the file the overrides live in with the user's editor. Absent: no such file. */
-  openInEditor?(): Promise<void>;
-  /** Where the overrides live, to show (a path). Absent: not shown. */
-  location?(): Promise<string>;
-}

package/src/keybindings/headless/index.ts

@@ -1,13 +0,0 @@
-/**
- * `zidane-ui/keybindings/headless`: the React-free half of the keybindings
- * area. The action catalog and default bindings, the `KeybindingsHost`
- * interface, the overrides model (`createKeybindingOverrides`,
- * `getMergedKeybindings`), the key command registry
- * (`createKeyCommandRegistry`), key ownership (`keyScopeOf`) and the labels.
- */
-export * from './catalog';
-export * from './commands';
-export * from './host';
-export * from './overrides';
-export * from './key-scope';
-export * from './labels';

package/src/keybindings/headless/key-scope.ts

@@ -1,91 +0,0 @@
-/**
- * Who owns a key press. One answer for every global keydown listener so
- * the app never fights a text surface:
- *
- *   'editor'  the code editor (pierre, in a shadow root: the event target is
- *             the host element, so tag checks alone miss it). Hosts opt in
- *             with `data-zg-keyscope="editor"`.
- *   'input'   a native text field or contenteditable (the composer).
- *   'menu'    an open menu / listbox / dialog owning its own arrows.
- *   'app'     nothing focused that wants the keys.
- *
- * Resolved from `composedPath()`, which pierces shadow roots.
- */
-import type { ParsedBinding } from 'zidane/chat/pure';
-
-/** Who owns a key press: the code editor, a text field, an open menu, or the app. */
-export type KeyScope = 'editor' | 'input' | 'menu' | 'app';
-
-/** The attribute an editor host sets (`data-zg-keyscope="editor"`) to own its keys. */
-export const KEYSCOPE_ATTR = 'data-zg-keyscope';
-
-const MENU_SELECTOR = '[role="menu"], [role="listbox"], [role="dialog"], [data-radix-popper-content-wrapper]';
-
-/**
- * Who owns a key press, from its composed path.
- *
- * @param event - The key event.
- */
-export function keyScopeOf(event: Event): KeyScope {
-  // The editor's own content is contenteditable, so an inner-first tag
-  // check would report 'input' before reaching the host. An opted-in
-  // editor host anywhere on the path wins.
-  let inner: KeyScope | null = null;
-  for (const node of event.composedPath()) {
-    if (!(node instanceof HTMLElement)) continue;
-    if (node.getAttribute(KEYSCOPE_ATTR) === 'editor') return 'editor';
-    if (inner) continue;
-    const tag = node.tagName;
-    if (tag === 'INPUT' || tag === 'TEXTAREA' || node.isContentEditable) inner = 'input';
-    else if (node.matches(MENU_SELECTOR)) inner = 'menu';
-  }
-  return inner ?? 'app';
-}
-
-/**
- * True when the key press belongs to a surface the user is typing in.
- *
- * @param event - The key event.
- */
-export function isTypingTarget(event: Event): boolean {
-  const scope = keyScopeOf(event);
-  return scope === 'editor' || scope === 'input';
-}
-
-/** Tags that take typed input; a focused webview or iframe owns its own keys. */
-const TYPING_TAGS: ReadonlySet<string> = new Set(['INPUT', 'TEXTAREA', 'SELECT', 'WEBVIEW', 'IFRAME']);
-
-/**
- * True when the focused element takes the user's typing, so moving focus
- * would swallow keystrokes. Walks into shadow roots (the editor's host is
- * `document.activeElement` while its inner content holds the caret).
- */
-export function isTypingFocused(): boolean {
-  let el: Element | null = document.activeElement;
-  while (el) {
-    if (el instanceof HTMLElement) {
-      if (el.closest(`[${KEYSCOPE_ATTR}="editor"]`) || el.isContentEditable || TYPING_TAGS.has(el.tagName)) return true;
-    }
-    el = el.shadowRoot?.activeElement ?? null;
-  }
-  return false;
-}
-
-/**
- * Whether an app-level binding may fire under `scope`. In the editor,
- * `ctrl+<letter>` without shift belongs to the editor (movement and
- * editing chords); everything with shift, meta or a non-letter key is an
- * app intent (settings, panels, zoom).
- *
- * @param scope - Who owns the press.
- * @param spec - The binding.
- * @param action - The binding's action (`closeTab` fires everywhere).
- */
-export function bindingAllowedIn(scope: KeyScope, spec: ParsedBinding, action?: string): boolean {
-  if (scope !== 'editor') return true;
-  // Closing the tab is an app intent wherever focus is (ctrl+w by default,
-  // which a shell would take as delete-word: the user chose closing).
-  if (action === 'closeTab') return true;
-  const bareCtrlLetter = spec.ctrl && !spec.shift && !spec.meta && !spec.alt && /^[a-z]$/i.test(spec.name);
-  return !bareCtrlLetter;
-}

package/src/keybindings/headless/labels.ts

@@ -1,14 +0,0 @@
-/**
- * The keybindings components' strings. One flat dictionary an app overrides
- * with `<LabelsProvider>` or the `labels` prop of `KeybindingsProvider`.
- * Keys you leave out keep the default English label.
- */
-
-/** The default English strings of the keybindings components. */
-export const DEFAULT_KEYBINDINGS_LABELS = {
-  /** Between two alternative chords of one binding (`⌃W or ⌘W`). */
-  keyHintOr: 'or',
-};
-
-/** The shape of the keybindings label dictionary. */
-export type KeybindingsLabels = typeof DEFAULT_KEYBINDINGS_LABELS;

package/src/keybindings/headless/overrides.ts

@@ -1,64 +0,0 @@
-/**
- * The overrides model every `KeybindingsHost` shares: read the stored map,
- * keep the known actions, announce it, and layer it over the defaults.
- */
-import { writable, type Readable } from '../../chat/headless/store';
-import { DEFAULT_KEYBINDINGS, type KeyAction, type KeyBindings } from './catalog';
-import type { KeyOverrides } from './host';
-
-/**
- * The known actions of a stored map, each with a non-empty spec. Entries a future build wrote are dropped, so the
- * matcher never parses them.
- *
- * @param raw - What was stored (anything).
- */
-export function filterOverrides(raw: unknown): KeyOverrides {
-  const next = raw && typeof raw === 'object' ? (raw as Record<string, unknown>) : undefined;
-  const filtered: Partial<Record<KeyAction, string>> = {};
-  for (const action of Object.keys(DEFAULT_KEYBINDINGS) as KeyAction[]) {
-    const spec = next?.[action];
-    if (typeof spec === 'string' && spec.trim()) {
-      filtered[action] = spec;
-    }
-  }
-  return filtered;
-}
-
-/** A host's overrides store and the read that fills it. */
-export interface KeybindingOverridesState {
-  /** The overrides: `{}` until read. */
-  overrides: Readable<KeyOverrides>;
-  /** Reads them, keeps the known actions and announces them (also when unchanged). A failed read is none. */
-  refresh(): Promise<void>;
-}
-
-/**
- * The overrides store over a read: what a host's `overrides` and `refresh` are.
- *
- * @param read - Reads the stored map (rejects or answers nothing when there is none).
- */
-export function createKeybindingOverrides(read: () => Promise<unknown>): KeybindingOverridesState {
-  const store = writable<KeyOverrides>({});
-  return {
-    overrides: store,
-    async refresh() {
-      let next: KeyOverrides;
-      try {
-        next = filterOverrides(await read());
-      } catch {
-        // No overrides file, or not ready: the defaults. The file is opt-in and missing is the common case.
-        next = {};
-      }
-      store.set(next);
-    },
-  };
-}
-
-/**
- * The bindings in effect: `DEFAULT_KEYBINDINGS` with the host's overrides on top.
- *
- * @param host - The host whose overrides apply; none: the defaults.
- */
-export function getMergedKeybindings(host?: { overrides: Readable<KeyOverrides> } | null): KeyBindings {
-  return { ...DEFAULT_KEYBINDINGS, ...host?.overrides.get() };
-}

package/src/keybindings/index.ts

@@ -1,14 +0,0 @@
-/**
- * `zidane-ui/keybindings`: key bindings over a `KeybindingsHost`.
- * `KeybindingsProvider` and the global dispatcher `useKeybindings`, the key
- * command registry (`KeyCommandsProvider`, `useKeyCommands`), `useHelpKey`,
- * `useMergedKeybindings`, the DOM matcher `matchesBinding`, and `KeyHint` /
- * `FooterHint` to show a binding as keycaps. The React-free model (catalog,
- * overrides, key ownership) is `zidane-ui/keybindings/headless`.
- */
-export * from './KeybindingsProvider';
-export * from './KeyCommands';
-export * from './useHelpKey';
-export * from './KeyHint';
-export * from './match';
-export * from './useKeybindingsLabels';

package/src/keybindings/load-once.ts

@@ -1,11 +0,0 @@
-import type { KeybindingsHost } from './headless/host';
-
-/** Hosts whose overrides were read once already (by the first dispatcher under them). */
-const loaded = new WeakSet<KeybindingsHost>();
-
-/** Reads a host's overrides the first time a dispatcher under it mounts. Internal: not exported from the entry. */
-export function loadOnce(host: KeybindingsHost | null): void {
-  if (!host || loaded.has(host)) return;
-  loaded.add(host);
-  void host.refresh();
-}

package/src/keybindings/match.ts

@@ -1,48 +0,0 @@
-/**
- * Matches a DOM `KeyboardEvent` against a binding spec.
- */
-import { canonicalKeyName, parseBindingSpecs, type ParsedBinding } from 'zidane/chat/pure';
-
-import { PUNCTUATION_CODES, typesStandIn } from '../components/keyboard-layout';
-
-/**
- * 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.
- *
- * @param event - The key event.
- * @param spec - A spec string, or one parsed chord.
- */
-export function matchesBinding(event: KeyboardEvent, spec: string | ParsedBinding): boolean {
-  if (typeof spec === 'string') {
-    return parseBindingSpecs(spec).some((parsed) => matchesBinding(event, parsed));
-  }
-  const parsed = spec;
-
-  if (parsed.ctrl !== event.ctrlKey) {
-    return false;
-  }
-
-  if (parsed.shift !== event.shiftKey) {
-    return false;
-  }
-
-  if (parsed.alt !== event.altKey) {
-    return false;
-  }
-
-  if (parsed.meta !== event.metaKey) {
-    return false;
-  }
-
-  return canonicalKeyName(event.key) === parsed.name || matchesPhysicalKey(event, parsed.name);
-}
-
-/**
- * A punctuation key by its physical position (`event.code`), for layouts
- * where it types a stand-in there (`typesStandIn`, the rule keycap labels
- * share). Decided by the event alone, so a keypress matches the same way
- * every time; the keyboard layout map only labels keycaps.
- */
-function matchesPhysicalKey(event: KeyboardEvent, name: string): boolean {
-  return PUNCTUATION_CODES[name]?.includes(event.code) === true && typesStandIn(event.key);
-}

package/src/keybindings/testing/contract.ts

@@ -1,139 +0,0 @@
-/**
- * What every `KeybindingsHost` implementation does alike, as a vitest suite: the in-memory fixture
- * (`createFixtureKeybindingsHost`), the browser one (`createBrowserKeybindingsHost`), the desktop app's.
- *
- * An implementation's test calls {@link describeKeybindingsHostContract} with a harness factory. The
- * contract hands it a {@link KeybindingsHostContractBackend}: the overrides stored (or none at all).
- * The harness builds the host over a backend that holds them, and returns a
- * {@link KeybindingsHostContractControl} that reads the backend and changes it from outside (the user
- * edited the file). The capabilities list says which optional members the host offers: the suite
- * checks the others are left out (undefined, never a throwing stub) and skips what needs them.
- *
- *   describeKeybindingsHostContract('createBrowserKeybindingsHost', (backend) => ({ host, control }), [
- *     'save',
- *   ]);
- */
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import { DEFAULT_KEYBINDINGS } from '../headless/catalog';
-import type { KeybindingsHost } from '../headless/host';
-import { getMergedKeybindings } from '../headless/overrides';
-
-/** An optional `KeybindingsHost` member. */
-export type KeybindingsHostCapability = 'save' | 'openInEditor' | 'location';
-
-const CAPABILITIES: readonly KeybindingsHostCapability[] = ['save', 'openInEditor', 'location'];
-
-/** What the backend behind the host holds. */
-export interface KeybindingsHostContractBackend {
-  /** The stored overrides (action → spec, unknown actions and empty specs included), or `null`: none stored. */
-  stored: Readonly<Record<string, string>> | null;
-}
-
-/** Reads the backend and changes it from outside. */
-export interface KeybindingsHostContractControl {
-  /** The overrides stored now, or `null`. */
-  stored(): Readonly<Record<string, string>> | null;
-  /** The user edited the stored overrides (`null` removes them). The host reads them on its next `refresh`. */
-  store(overrides: Readonly<Record<string, string>> | null): void;
-}
-
-/** A host built over a backend, the backend's control, and how to tear them down. */
-export interface KeybindingsHostHarness {
-  /** The host under test. */
-  host: KeybindingsHost;
-  /** Reads and changes the backend. */
-  control: KeybindingsHostContractControl;
-  /** Closes listeners after each test. */
-  dispose?(): void;
-}
-
-/** Builds a fresh host (and its backend) for one test. */
-export type KeybindingsHostHarnessFactory = (
-  backend: KeybindingsHostContractBackend,
-) => KeybindingsHostHarness | Promise<KeybindingsHostHarness>;
-
-const STORED = { openPalette: 'cmd+p', closeTab: '  ', notAnAction: 'ctrl+q' };
-
-/**
- * Declares the shared `KeybindingsHost` suite for one implementation.
- *
- * @param name - The implementation's name, shown in the suite title.
- * @param makeHarness - Builds a fresh host over a backend that holds what it is given, once per test.
- * @param capabilities - The optional members the host offers. Every other optional member must be undefined.
- */
-export function describeKeybindingsHostContract(
-  name: string,
-  makeHarness: KeybindingsHostHarnessFactory,
-  capabilities: readonly KeybindingsHostCapability[],
-): void {
-  const has = (capability: KeybindingsHostCapability) => capabilities.includes(capability);
-
-  describe(`KeybindingsHost contract: ${name}`, () => {
-    const cleanup: (() => void)[] = [];
-    afterEach(() => {
-      for (const done of cleanup.splice(0).reverse()) done();
-    });
-
-    const setup = async (stored: KeybindingsHostContractBackend['stored'] = STORED) => {
-      const harness = await makeHarness({ stored });
-      cleanup.push(() => harness.dispose?.());
-      return harness;
-    };
-
-    it('offers exactly its capabilities; the members it leaves out are undefined', async () => {
-      const { host } = await setup();
-      expect(typeof host.overrides.get).toBe('function');
-      expect(typeof host.refresh).toBe('function');
-      for (const capability of CAPABILITIES) {
-        expect(typeof host[capability], capability).toBe(has(capability) ? 'function' : 'undefined');
-      }
-    });
-
-    it('reads nothing until refreshed, then the known actions with a spec', async () => {
-      const { host } = await setup();
-      expect(host.overrides.get()).toEqual({});
-      await host.refresh();
-      expect(host.overrides.get()).toEqual({ openPalette: 'cmd+p' });
-      expect(getMergedKeybindings(host)).toEqual({ ...DEFAULT_KEYBINDINGS, openPalette: 'cmd+p' });
-    });
-
-    it('reads none when nothing is stored, and never rejects', async () => {
-      const { host } = await setup(null);
-      await expect(host.refresh()).resolves.toBeUndefined();
-      expect(host.overrides.get()).toEqual({});
-    });
-
-    it('a refresh picks up an edit and tells subscribers, also when nothing changed', async () => {
-      const { host, control } = await setup();
-      const seen = vi.fn();
-      cleanup.push(host.overrides.subscribe(seen));
-      await host.refresh();
-      expect(seen).toHaveBeenCalledTimes(1);
-      control.store({ toggleSidebar: 'ctrl+b' });
-      await host.refresh();
-      expect(host.overrides.get()).toEqual({ toggleSidebar: 'ctrl+b' });
-      expect(seen).toHaveBeenCalledTimes(2);
-      control.store(null);
-      await host.refresh();
-      expect(host.overrides.get()).toEqual({});
-    });
-
-    it.skipIf(!has('save'))('save replaces the stored overrides and the store follows', async () => {
-      const { host, control } = await setup();
-      await host.save!({ newSession: 'cmd+n' });
-      expect(host.overrides.get()).toEqual({ newSession: 'cmd+n' });
-      expect(control.stored()).toEqual({ newSession: 'cmd+n' });
-    });
-
-    it.skipIf(!has('location'))('says where the overrides live', async () => {
-      const { host } = await setup();
-      expect(typeof (await host.location!())).toBe('string');
-    });
-
-    it.skipIf(!has('openInEditor'))('opens them in an editor', async () => {
-      const { host } = await setup();
-      await expect(host.openInEditor!()).resolves.toBeUndefined();
-    });
-  });
-}

package/src/keybindings/testing/index.ts

@@ -1,6 +0,0 @@
-/**
- * `zidane-ui/keybindings/testing`: a `KeybindingsHost` that runs in memory
- * (`createFixtureKeybindingsHost`), for docs, demos, galleries and an app's
- * own tests. Not for production hosts.
- */
-export * from '../headless/fixture-host';

package/src/keybindings/useHelpKey.ts

@@ -1,35 +0,0 @@
-/**
- * `?` opens the shortcut reference. A plain window listener, not a catalog
- * action: `?` is a convenience outside the shared catalog. `e.key === '?'`
- * covers `Shift+/` on every layout (the browser resolves the layout before
- * the keydown lands). Typing `?` in a field never opens it, and neither does
- * a press while a modal is open (`blocked`), so a bare `?` never swaps a
- * modal out mid-edit.
- */
-import { useEffect, useRef } from 'react';
-
-import { isTypingTarget } from './headless/key-scope';
-
-/**
- * Calls `onOpen` on a bare `?` outside fields. The listener attaches once; both callbacks are read at press time.
- *
- * @param onOpen - Opens the shortcut reference. Absent: nothing listens.
- * @param blocked - Whether something else owns input now (a modal is open).
- */
-export function useHelpKey(onOpen: (() => void) | undefined, blocked?: () => boolean): void {
-  const latest = useRef({ onOpen, blocked });
-  // eslint-disable-next-line react-hooks/refs -- read at event time only, never during render
-  latest.current = { onOpen, blocked };
-  const on = Boolean(onOpen);
-  useEffect(() => {
-    if (!on) return undefined;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key !== '?' || latest.current.blocked?.()) return;
-      if (isTypingTarget(e)) return;
-      e.preventDefault();
-      latest.current.onOpen?.();
-    };
-    window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
-  }, [on]);
-}

package/src/keybindings/useKeybindingsLabels.ts

@@ -1,14 +0,0 @@
-/**
- * The keybindings components' labels: the defaults, overridable through
- * `<LabelsProvider>` or `KeybindingsProvider`'s `labels`.
- */
-import { useMemo } from 'react';
-
-import { useLabels } from '../labels';
-import { DEFAULT_KEYBINDINGS_LABELS, type KeybindingsLabels } from './headless/labels';
-
-/** Returns the keybindings components' strings: the defaults merged with any overrides. */
-export function useKeybindingsLabels(): KeybindingsLabels {
-  const overrides = useLabels() as Partial<KeybindingsLabels>;
-  return useMemo(() => ({ ...DEFAULT_KEYBINDINGS_LABELS, ...overrides }), [overrides]);
-}