@proteos/ui 0.31.0

package/src/lib/commands/match-event.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { isEditableTarget, matches } from './match-event'
+import { parseCombo } from './parse-combo'
+import { _setPlatformForTests } from './platform'
+
+function event(init: KeyboardEventInit): KeyboardEvent {
+  return new KeyboardEvent('keydown', init)
+}
+
+describe('matches', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('fires mod+s for Cmd+S on macOS', () => {
+    expect(matches(event({ metaKey: true, code: 'KeyS', key: 's' }), parseCombo('mod+s'))).toBe(
+      true,
+    )
+  })
+
+  it('fires mod+s when Shift is also held (Cmd+Shift+S)', () => {
+    expect(
+      matches(
+        event({ metaKey: true, shiftKey: true, code: 'KeyS', key: 'S' }),
+        parseCombo('mod+s'),
+      ),
+    ).toBe(true)
+  })
+
+  it('fires mod+s when Alt is also held (Cmd+Alt+S)', () => {
+    expect(
+      matches(
+        event({ metaKey: true, altKey: true, code: 'KeyS', key: 's' }),
+        parseCombo('mod+s'),
+      ),
+    ).toBe(true)
+  })
+
+  it('does not fire for Shift+S alone', () => {
+    expect(
+      matches(event({ shiftKey: true, code: 'KeyS', key: 'S' }), parseCombo('mod+s')),
+    ).toBe(false)
+  })
+
+  it('does not fire for the wrong key', () => {
+    expect(matches(event({ metaKey: true, code: 'KeyD', key: 'd' }), parseCombo('mod+s'))).toBe(
+      false,
+    )
+  })
+
+  it('uses ctrlKey on non-mac platforms', () => {
+    _setPlatformForTests('other')
+    expect(matches(event({ ctrlKey: true, code: 'KeyS', key: 's' }), parseCombo('mod+s'))).toBe(
+      true,
+    )
+    expect(matches(event({ metaKey: true, code: 'KeyS', key: 's' }), parseCombo('mod+s'))).toBe(
+      false,
+    )
+  })
+
+  it('matches named keys via event.key', () => {
+    expect(
+      matches(event({ metaKey: true, code: 'Enter', key: 'Enter' }), parseCombo('mod+enter')),
+    ).toBe(true)
+  })
+
+  it('matches digit keys via event.key', () => {
+    expect(matches(event({ metaKey: true, code: 'Digit0', key: '0' }), parseCombo('mod+0'))).toBe(
+      true,
+    )
+  })
+})
+
+describe('isEditableTarget', () => {
+  it('treats input/textarea/select as editable', () => {
+    expect(isEditableTarget(document.createElement('input'))).toBe(true)
+    expect(isEditableTarget(document.createElement('textarea'))).toBe(true)
+    expect(isEditableTarget(document.createElement('select'))).toBe(true)
+  })
+
+  it('treats contenteditable as editable', () => {
+    const div = document.createElement('div')
+    div.setAttribute('contenteditable', 'true')
+    expect(isEditableTarget(div)).toBe(true)
+  })
+
+  it('treats buttons and plain divs as not editable', () => {
+    expect(isEditableTarget(document.createElement('button'))).toBe(false)
+    expect(isEditableTarget(document.createElement('div'))).toBe(false)
+  })
+
+  it('returns false for null', () => {
+    expect(isEditableTarget(null)).toBe(false)
+  })
+})

package/src/lib/commands/match-event.ts

@@ -0,0 +1,31 @@
+/* Event matcher + editable-target guard. Letter combos match the physical
+   key via `event.code` so QWERTY position is preserved across layouts;
+   non-letter combos match `event.key`. Shift and Alt state are intentionally
+   ignored so `Cmd+S`, `Cmd+Shift+S`, and `Cmd+Alt+S` all fire `mod+s` —
+   this is what makes the discovery-hold-then-press flow work without dual
+   registration. */
+
+import type { KeyCombo } from './parse-combo'
+import { getPlatform } from './platform'
+
+export function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false
+  const tag = target.tagName
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true
+  if (target.isContentEditable) return true
+  // jsdom doesn't always reflect contenteditable in isContentEditable; fall back
+  // to the attribute so tests (and any quirky host) behave consistently.
+  const attr = target.getAttribute('contenteditable')
+  if (attr === '' || attr === 'true' || attr === 'plaintext-only') return true
+  return false
+}
+
+export function matches(event: KeyboardEvent, combo: KeyCombo): boolean {
+  const platform = getPlatform()
+  const modPressed = platform === 'mac' ? event.metaKey : event.ctrlKey
+  if (!modPressed) return false
+  if (combo.isLetter) {
+    return event.code === `Key${combo.key.toUpperCase()}`
+  }
+  return event.key.toLowerCase() === combo.key.toLowerCase()
+}

package/src/lib/commands/parse-combo.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseCombo } from './parse-combo'
+
+describe('parseCombo', () => {
+  it('parses mod+<letter>', () => {
+    const combo = parseCombo('mod+k')
+    expect(combo).toEqual({ raw: 'mod+k', key: 'k', isLetter: true })
+  })
+
+  it('parses mod+<named-key>', () => {
+    const combo = parseCombo('mod+enter')
+    expect(combo).toEqual({ raw: 'mod+enter', key: 'enter', isLetter: false })
+  })
+
+  it('accepts "cmd" and "meta" as aliases for mod', () => {
+    expect(parseCombo('cmd+k').raw).toBe('mod+k')
+    expect(parseCombo('meta+k').raw).toBe('mod+k')
+  })
+
+  it('is case-insensitive', () => {
+    expect(parseCombo('MOD+K').raw).toBe('mod+k')
+    expect(parseCombo('Cmd+K').raw).toBe('mod+k')
+  })
+
+  it('trims whitespace around parts', () => {
+    expect(parseCombo(' mod + k ').raw).toBe('mod+k')
+  })
+
+  it('rejects empty input', () => {
+    expect(() => parseCombo('')).toThrow(/empty/i)
+    expect(() => parseCombo('   ')).toThrow(/empty/i)
+  })
+
+  it('rejects bare keys', () => {
+    expect(() => parseCombo('s')).toThrow(/Expected "mod\+<key>"/)
+    expect(() => parseCombo('Escape')).toThrow(/Expected "mod\+<key>"/)
+  })
+
+  it('rejects non-mod modifiers', () => {
+    expect(() => parseCombo('alt+s')).toThrow(/Modifier must be "mod"/)
+    expect(() => parseCombo('shift+s')).toThrow(/Modifier must be "mod"/)
+    expect(() => parseCombo('ctrl+s')).toThrow(/Modifier must be "mod"/)
+  })
+
+  it('rejects multi-modifier combos', () => {
+    expect(() => parseCombo('mod+shift+k')).toThrow(/Expected "mod\+<key>"/)
+    expect(() => parseCombo('mod+alt+k')).toThrow(/Expected "mod\+<key>"/)
+  })
+
+  it('rejects combos that look like extra modifiers as the key', () => {
+    expect(() => parseCombo('mod+shift')).toThrow(/Multi-modifier/)
+    expect(() => parseCombo('mod+alt')).toThrow(/Multi-modifier/)
+  })
+
+  it('rejects missing key', () => {
+    expect(() => parseCombo('mod+')).toThrow(/Missing key/)
+  })
+
+  it('marks single-letter keys with isLetter', () => {
+    expect(parseCombo('mod+a').isLetter).toBe(true)
+    expect(parseCombo('mod+enter').isLetter).toBe(false)
+    expect(parseCombo('mod+1').isLetter).toBe(false)
+  })
+})

package/src/lib/commands/parse-combo.ts

@@ -0,0 +1,48 @@
+/* Parse a textual combo like "mod+k" into a typed KeyCombo. v1 supports
+   exactly `mod+<key>` where the modifier resolves to Cmd on macOS and Ctrl
+   elsewhere. Aliases `cmd` and `meta` normalize to `mod`. Any other shape
+   (`alt+s`, `mod+shift+k`, bare `s`) throws with a clear message so misuse
+   is caught at registration time, not at the next key press. */
+
+export type KeyCombo = {
+  /** Normalized form for registry keying. Always `mod+<key>`. */
+  raw: string
+  /** Key part, lowercased. Letters use `event.code` (`KeyS`); others match `event.key`. */
+  key: string
+  /** True when `key` is a single A–Z letter — match against `event.code` so the
+   *  binding stays on the physical key regardless of keyboard layout. */
+  isLetter: boolean
+}
+
+const MOD_ALIASES: ReadonlySet<string> = new Set(['mod', 'cmd', 'meta'])
+const FORBIDDEN_EXTRA_MODS: ReadonlySet<string> = new Set(['shift', 'alt', 'option'])
+
+export function parseCombo(input: string): KeyCombo {
+  const trimmed = input.trim()
+  if (!trimmed) {
+    throw new Error('Invalid key combo: empty string. Expected "mod+<key>".')
+  }
+  const parts = trimmed.toLowerCase().split('+').map((p) => p.trim())
+  if (parts.length !== 2) {
+    throw new Error(
+      `Invalid key combo: "${input}". Expected "mod+<key>" — exactly one modifier and one key. ` +
+        `v1 does not support bare keys, multiple modifiers, or sequences.`,
+    )
+  }
+  const [modPart, keyPart] = parts as [string, string]
+  if (!MOD_ALIASES.has(modPart)) {
+    throw new Error(
+      `Invalid key combo: "${input}". Modifier must be "mod" (or alias "cmd"/"meta"); got "${modPart}".`,
+    )
+  }
+  if (!keyPart) {
+    throw new Error(`Invalid key combo: "${input}". Missing key after modifier.`)
+  }
+  if (FORBIDDEN_EXTRA_MODS.has(keyPart)) {
+    throw new Error(
+      `Invalid key combo: "${input}". Multi-modifier combos (mod+shift+…, mod+alt+…) are not supported in v1.`,
+    )
+  }
+  const isLetter = /^[a-z]$/.test(keyPart)
+  return { raw: `mod+${keyPart}`, key: keyPart, isLetter }
+}

package/src/lib/commands/platform.ts

@@ -0,0 +1,27 @@
+/* Platform detection for the command system. Resolves once at module load
+   so `mod` always means the same thing in a given session. */
+
+export type Platform = 'mac' | 'other'
+
+let cached: Platform | undefined
+
+export function getPlatform(): Platform {
+  if (cached !== undefined) return cached
+  cached = detect()
+  return cached
+}
+
+function detect(): Platform {
+  if (typeof navigator === 'undefined') return 'other'
+  const ua = (navigator as { userAgentData?: { platform?: string } }).userAgentData
+  if (ua?.platform) {
+    return /mac/i.test(ua.platform) ? 'mac' : 'other'
+  }
+  const legacy = (navigator as { platform?: string }).platform ?? ''
+  return /mac/i.test(legacy) ? 'mac' : 'other'
+}
+
+// Test-only: reset or force the cached platform.
+export function _setPlatformForTests(p: Platform | undefined): void {
+  cached = p
+}

package/src/lib/commands/protected-combos.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseCombo } from './parse-combo'
+import { assertNotProtected, PROTECTED_COMBOS } from './protected-combos'
+
+describe('protected combos', () => {
+  it('each protected combo throws on registration', () => {
+    for (const raw of PROTECTED_COMBOS) {
+      const combo = parseCombo(raw)
+      expect(() => assertNotProtected(combo)).toThrow(/protected/i)
+    }
+  })
+
+  it('does not throw for non-protected combos', () => {
+    const combo = parseCombo('mod+k')
+    expect(() => assertNotProtected(combo)).not.toThrow()
+  })
+})

package/src/lib/commands/protected-combos.ts

@@ -0,0 +1,38 @@
+/* Browser/OS combos we refuse to bind. Catching this at registration time
+   gives a clear error instead of silently shipping a shortcut the browser
+   intercepts. `mod+shift+t` is listed for documentation; it can't be expressed
+   in v1 anyway (the parser rejects multi-modifier combos). */
+
+import type { KeyCombo } from './parse-combo'
+
+/* `mod+n` is intentionally NOT in this list. Chrome/Safari/Firefox on macOS
+   intercept it at the OS/browser level for "new window" so the page's
+   handler can't fire in those environments — but we still allow registration
+   so it works on platforms/configurations where the browser does deliver the
+   event, and so the discovery hint can advertise it. */
+
+export const PROTECTED_COMBOS: ReadonlySet<string> = new Set([
+  'mod+w',
+  'mod+t',
+  'mod+q',
+  'mod+r',
+  'mod+l',
+  'mod+1',
+  'mod+2',
+  'mod+3',
+  'mod+4',
+  'mod+5',
+  'mod+6',
+  'mod+7',
+  'mod+8',
+  'mod+9',
+])
+
+export function assertNotProtected(combo: KeyCombo): void {
+  if (PROTECTED_COMBOS.has(combo.raw)) {
+    throw new Error(
+      `Cannot bind "${combo.raw}" — it is a protected browser/OS shortcut. ` +
+        `Pick a different key.`,
+    )
+  }
+}

package/src/lib/commands/registry.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { parseCombo } from './parse-combo'
+import { _setPlatformForTests } from './platform'
+import { _resetRegistry, register } from './registry'
+
+function dispatchKey(init: KeyboardEventInit & { cancelable?: boolean }): KeyboardEvent {
+  const ev = new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init })
+  window.dispatchEvent(ev)
+  return ev
+}
+
+describe('registry', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetRegistry()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('fires the registered handler on matching keydown', () => {
+    const fn = vi.fn()
+    register(parseCombo('mod+k'), fn)
+    dispatchKey({ metaKey: true, code: 'KeyK', key: 'k' })
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('newest-mounted handler wins for the same combo', () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    register(parseCombo('mod+k'), first)
+    register(parseCombo('mod+k'), second)
+    dispatchKey({ metaKey: true, code: 'KeyK', key: 'k' })
+    expect(second).toHaveBeenCalledTimes(1)
+    expect(first).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the previous handler after the newest unmounts', () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    register(parseCombo('mod+k'), first)
+    const unregisterSecond = register(parseCombo('mod+k'), second)
+    unregisterSecond()
+    dispatchKey({ metaKey: true, code: 'KeyK', key: 'k' })
+    expect(first).toHaveBeenCalledTimes(1)
+    expect(second).not.toHaveBeenCalled()
+  })
+
+  it('does not fire after unregister', () => {
+    const fn = vi.fn()
+    const unregister = register(parseCombo('mod+k'), fn)
+    unregister()
+    dispatchKey({ metaKey: true, code: 'KeyK', key: 'k' })
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('fires even when the focus is in a text input (mod+ combos use a modifier, so they cannot be confused with typing)', () => {
+    const fn = vi.fn()
+    register(parseCombo('mod+k'), fn)
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    const ev = new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      metaKey: true,
+      code: 'KeyK',
+      key: 'k',
+    })
+    input.dispatchEvent(ev)
+    document.body.removeChild(input)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('calls preventDefault and stopImmediatePropagation on match', () => {
+    register(parseCombo('mod+k'), () => {})
+    const ev = new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      metaKey: true,
+      code: 'KeyK',
+      key: 'k',
+    })
+    const preventSpy = vi.spyOn(ev, 'preventDefault')
+    const stopSpy = vi.spyOn(ev, 'stopImmediatePropagation')
+    window.dispatchEvent(ev)
+    expect(preventSpy).toHaveBeenCalled()
+    expect(stopSpy).toHaveBeenCalled()
+  })
+
+  it('does not fire for unrelated keys', () => {
+    const fn = vi.fn()
+    register(parseCombo('mod+k'), fn)
+    dispatchKey({ metaKey: true, code: 'KeyJ', key: 'j' })
+    expect(fn).not.toHaveBeenCalled()
+  })
+})

package/src/lib/commands/registry.ts

@@ -0,0 +1,59 @@
+/* Module-singleton registry. One window listener handles every command.
+   Handlers for the same combo stack on push; the newest wins
+   deterministically. preventDefault + stopImmediatePropagation on match so
+   the page's own keydown listeners (and other registry entries) don't also
+   fire.
+
+   Editable targets are NOT skipped here — `mod+<key>` combos use a real
+   modifier, so they can't be confused with text input the way bare keys
+   can. Cmd+S in a form field should still save. (The `useEscapeKey` path
+   keeps its editable-target skip because Escape is bare.) */
+
+import { matches } from './match-event'
+import type { KeyCombo } from './parse-combo'
+
+type Handler = (event: KeyboardEvent) => void
+type Entry = { combo: KeyCombo; handler: Handler }
+
+const stacks = new Map<string, Entry[]>()
+let listenerInstalled = false
+
+function onWindowKeyDown(event: KeyboardEvent): void {
+  for (const entries of stacks.values()) {
+    const top = entries[entries.length - 1]
+    if (!top) continue
+    if (matches(event, top.combo)) {
+      event.preventDefault()
+      event.stopImmediatePropagation()
+      top.handler(event)
+      return
+    }
+  }
+}
+
+function ensureListener(): void {
+  if (listenerInstalled) return
+  if (typeof window === 'undefined') return
+  window.addEventListener('keydown', onWindowKeyDown, { capture: true })
+  listenerInstalled = true
+}
+
+export function register(combo: KeyCombo, handler: Handler): () => void {
+  ensureListener()
+  const list = stacks.get(combo.raw) ?? []
+  const entry: Entry = { combo, handler }
+  list.push(entry)
+  stacks.set(combo.raw, list)
+  return () => {
+    const current = stacks.get(combo.raw)
+    if (!current) return
+    const idx = current.lastIndexOf(entry)
+    if (idx >= 0) current.splice(idx, 1)
+    if (current.length === 0) stacks.delete(combo.raw)
+  }
+}
+
+// Test-only: clear the registry between cases.
+export function _resetRegistry(): void {
+  stacks.clear()
+}

package/src/lib/commands/use-command.test.tsx

@@ -0,0 +1,91 @@
+import { render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { _setPlatformForTests } from './platform'
+import { _resetRegistry } from './registry'
+import { useCommand } from './use-command'
+
+function Bind({
+  combo,
+  handler,
+  enabled,
+}: {
+  combo: string
+  handler: (e: KeyboardEvent) => void
+  enabled?: boolean
+}) {
+  useCommand(combo, handler, enabled !== undefined ? { enabled } : undefined)
+  return null
+}
+
+function dispatchModK() {
+  window.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      metaKey: true,
+      code: 'KeyK',
+      key: 'k',
+    }),
+  )
+}
+
+describe('useCommand', () => {
+  beforeEach(() => {
+    _setPlatformForTests('mac')
+    _resetRegistry()
+  })
+  afterEach(() => {
+    _setPlatformForTests(undefined)
+  })
+
+  it('fires the handler when the combo is pressed', () => {
+    const fn = vi.fn()
+    render(<Bind combo="mod+k" handler={fn} />)
+    dispatchModK()
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('respects enabled=false', () => {
+    const fn = vi.fn()
+    render(<Bind combo="mod+k" handler={fn} enabled={false} />)
+    dispatchModK()
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('cleans up on unmount', () => {
+    const fn = vi.fn()
+    const { unmount } = render(<Bind combo="mod+k" handler={fn} />)
+    unmount()
+    dispatchModK()
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('fires from inside a text input (Cmd+S while typing should still save)', () => {
+    const fn = vi.fn()
+    render(<Bind combo="mod+k" handler={fn} />)
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    input.dispatchEvent(
+      new KeyboardEvent('keydown', {
+        bubbles: true,
+        cancelable: true,
+        metaKey: true,
+        code: 'KeyK',
+        key: 'k',
+      }),
+    )
+    document.body.removeChild(input)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('always calls the latest handler', () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    const { rerender } = render(<Bind combo="mod+k" handler={first} />)
+    rerender(<Bind combo="mod+k" handler={second} />)
+    dispatchModK()
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/commands/use-command.ts

@@ -0,0 +1,32 @@
+/* Bind a `mod+<key>` command. The handler is wrapped in a ref so changing
+   handler identity each render does not re-register; only `combo` and
+   `enabled` are real dependencies. */
+
+import { useEffect, useRef } from 'react'
+
+import { parseCombo } from './parse-combo'
+import { assertNotProtected } from './protected-combos'
+import { register } from './registry'
+
+export type UseCommandOptions = {
+  /** Defaults to `true`. Set to `false` to temporarily disable without unmounting. */
+  enabled?: boolean
+}
+
+export function useCommand(
+  combo: string,
+  handler: (event: KeyboardEvent) => void,
+  options?: UseCommandOptions,
+): void {
+  const enabled = options?.enabled ?? true
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  })
+  useEffect(() => {
+    if (!enabled) return undefined
+    const parsed = parseCombo(combo)
+    assertNotProtected(parsed)
+    return register(parsed, (event) => handlerRef.current(event))
+  }, [combo, enabled])
+}