@tooee/commands 0.1.0

package/dist/use-command.js

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from "react";
+import { useCommandRegistry } from "./context.jsx";
+export function useCommand(options) {
+    const { registry } = useCommandRegistry();
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    useEffect(() => {
+        const command = {
+            id: options.id,
+            title: options.title,
+            handler: (...args) => optionsRef.current.handler(...args),
+            defaultHotkey: options.hotkey,
+            modes: options.modes,
+            category: options.category,
+            group: options.group,
+            icon: options.icon,
+            when: optionsRef.current.when ? (ctx) => optionsRef.current.when(ctx) : undefined,
+            hidden: options.hidden,
+        };
+        return registry.register(command);
+    }, [
+        options.id,
+        options.title,
+        options.hotkey,
+        options.modes,
+        options.category,
+        options.group,
+        options.icon,
+        options.hidden,
+        registry,
+    ]);
+}
+//# sourceMappingURL=use-command.js.map

package/dist/use-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-command.js","sourceRoot":"","sources":["../src/use-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAelD,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,MAAM,EAAE,QAAQ,EAAE,GAAG,kBAAkB,EAAE,CAAA;IACzC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAClC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAA;IAE5B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAY;YACvB,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,CAAC,GAAG,IAAoC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;YACzF,aAAa,EAAE,OAAO,CAAC,MAAM;YAC7B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;YAClF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAA;QACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnC,CAAC,EAAE;QACD,OAAO,CAAC,EAAE;QACV,OAAO,CAAC,KAAK;QACb,OAAO,CAAC,MAAM;QACd,OAAO,CAAC,KAAK;QACb,OAAO,CAAC,QAAQ;QAChB,OAAO,CAAC,KAAK;QACb,OAAO,CAAC,IAAI;QACZ,OAAO,CAAC,MAAM;QACd,QAAQ;KACT,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tooee/commands",
+  "version": "0.1.0",
+  "description": "Vim-inspired modal command system for Tooee",
+  "license": "MIT",
+  "author": "Gareth Andrew",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gingerhendrix/tooee.git",
+    "directory": "packages/commands"
+  },
+  "homepage": "https://github.com/gingerhendrix/tooee",
+  "bugs": "https://github.com/gingerhendrix/tooee/issues",
+  "keywords": ["tui", "terminal", "cli", "opentui", "vim", "keybindings"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "@tooee/source": "./src/index.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.1.67",
+    "@opentui/react": "^0.1.67",
+    "@types/bun": "^1.3.5",
+    "@types/react": "^19.1.10",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@opentui/core": "^0.1.67",
+    "@opentui/react": "^0.1.67",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,221 @@
+import { createContext, useContext, useRef, useCallback, useEffect, type ReactNode } from "react"
+import { useKeyboard } from "@opentui/react"
+import type { Command, CommandContext, CommandRegistry, ParsedHotkey } from "./types.js"
+import type { Mode } from "./mode.jsx"
+import { ModeProvider, useMode, useSetMode } from "./mode.jsx"
+import { parseHotkey } from "./parse.js"
+import { matchStep } from "./match.js"
+import { SequenceTracker } from "./sequence.js"
+
+const DEFAULT_MODES: Mode[] = ["cursor"]
+
+type ContextGetter = () => Partial<CommandContext>
+
+interface CommandContextValue {
+  registry: CommandRegistry
+  leaderKey?: string
+  contextSources: Map<string, ContextGetter>
+}
+
+const CommandContext = createContext<CommandContextValue | null>(null)
+
+export interface CommandProviderProps {
+  children: ReactNode
+  leader?: string
+  keymap?: Record<string, string>
+  initialMode?: Mode
+}
+
+export function CommandProvider({ children, leader, keymap, initialMode }: CommandProviderProps) {
+  return (
+    <ModeProvider initialMode={initialMode}>
+      <CommandDispatcher leader={leader} keymap={keymap}>
+        {children}
+      </CommandDispatcher>
+    </ModeProvider>
+  )
+}
+
+function CommandDispatcher({
+  children,
+  leader,
+  keymap,
+}: {
+  children: ReactNode
+  leader?: string
+  keymap?: Record<string, string>
+}) {
+  const registryRef = useRef<CommandRegistry | null>(null)
+  const contextSourcesRef = useRef(new Map<string, ContextGetter>())
+  const mode = useMode()
+  const modeRef = useRef(mode)
+  modeRef.current = mode
+  const setMode = useSetMode()
+
+  const buildCtx = useCallback((): CommandContext => {
+    const ctx: Record<string, any> = {
+      mode: modeRef.current,
+      setMode,
+      commands: {
+        invoke: (id: string) => registryRef.current?.invoke(id),
+        list: () => Array.from(registryRef.current?.commands.values() ?? []),
+      },
+      exit: () => {},
+    }
+    for (const getter of contextSourcesRef.current.values()) {
+      Object.assign(ctx, getter())
+    }
+    return ctx as CommandContext
+  }, [setMode])
+
+  if (registryRef.current === null) {
+    const commands = new Map<string, Command>()
+    registryRef.current = {
+      commands,
+      register(command: Command) {
+        commands.set(command.id, command)
+        return () => {
+          commands.delete(command.id)
+        }
+      },
+      invoke(id: string) {
+        const ctx = buildCtx()
+        const cmd = commands.get(id)
+        if (cmd && (!cmd.when || cmd.when(ctx))) {
+          cmd.handler(ctx)
+        }
+      },
+    }
+  }
+
+  const trackerRef = useRef(new SequenceTracker())
+  const parseCacheRef = useRef(new Map<string, ParsedHotkey>())
+
+  const getParsedHotkey = useCallback(
+    (hotkey: string) => {
+      const cache = parseCacheRef.current
+      const cacheKey = `${hotkey}:${leader ?? ""}`
+      let parsed = cache.get(cacheKey)
+      if (!parsed) {
+        parsed = parseHotkey(hotkey, leader)
+        cache.set(cacheKey, parsed)
+      }
+      return parsed
+    },
+    [leader],
+  )
+
+  useKeyboard((event) => {
+    if (event.defaultPrevented) return
+
+    const registry = registryRef.current
+    if (!registry) return
+
+    const currentMode = mode
+    const ctx = buildCtx()
+
+    // Collect eligible commands with their parsed hotkeys
+    const singleStepCandidates: { command: Command; parsed: ParsedHotkey }[] = []
+    const multiStepHotkeys: ParsedHotkey[] = []
+    const multiStepCommands: Command[] = []
+
+    for (const command of registry.commands.values()) {
+      const commandModes = command.modes ?? DEFAULT_MODES
+      if (!commandModes.includes(currentMode)) continue
+      if (command.when && !command.when(ctx)) continue
+
+      const hotkey = keymap?.[command.id] ?? command.defaultHotkey
+      if (!hotkey) continue
+
+      const parsed = getParsedHotkey(hotkey)
+
+      if (parsed.steps.length === 1) {
+        singleStepCandidates.push({ command, parsed })
+      } else {
+        multiStepHotkeys.push(parsed)
+        multiStepCommands.push(command)
+      }
+    }
+
+    // Check multi-step sequences first (they consume buffer state)
+    if (multiStepHotkeys.length > 0) {
+      const idx = trackerRef.current.feed(event, multiStepHotkeys)
+      if (idx >= 0) {
+        event.preventDefault()
+        multiStepCommands[idx]!.handler(ctx)
+        return
+      }
+    }
+
+    // Check single-step matches
+    for (const { command, parsed } of singleStepCandidates) {
+      if (matchStep(event, parsed.steps[0]!)) {
+        event.preventDefault()
+        command.handler(ctx)
+        return
+      }
+    }
+  })
+
+  return (
+    <CommandContext.Provider
+      value={{
+        registry: registryRef.current,
+        leaderKey: leader,
+        contextSources: contextSourcesRef.current,
+      }}
+    >
+      {children}
+    </CommandContext.Provider>
+  )
+}
+
+export function useCommandContext(): { commands: Command[]; invoke: (id: string) => void } {
+  const ctx = useContext(CommandContext)
+  if (!ctx) {
+    throw new Error("useCommandContext must be used within a CommandProvider")
+  }
+
+  const { registry } = ctx
+  return {
+    get commands() {
+      return Array.from(registry.commands.values())
+    },
+    invoke: registry.invoke,
+  }
+}
+
+export function useCommandRegistry(): CommandContextValue {
+  const ctx = useContext(CommandContext)
+  if (!ctx) {
+    throw new Error("useCommandRegistry must be used within a CommandProvider")
+  }
+  return ctx
+}
+
+let nextContextSourceId = 0
+
+export function useProvideCommandContext(getter: () => Partial<CommandContext>): void {
+  const ctx = useContext(CommandContext)
+  if (!ctx) {
+    throw new Error("useProvideCommandContext must be used within a CommandProvider")
+  }
+
+  const idRef = useRef<string | null>(null)
+  if (idRef.current === null) {
+    idRef.current = `ctx-${nextContextSourceId++}`
+  }
+
+  const getterRef = useRef(getter)
+  getterRef.current = getter
+
+  const { contextSources } = ctx
+
+  useEffect(() => {
+    const id = idRef.current!
+    contextSources.set(id, () => getterRef.current())
+    return () => {
+      contextSources.delete(id)
+    }
+  }, [contextSources])
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  Command,
+  CommandContext,
+  CommandContextBase,
+  CommandHandler,
+  CommandWhen,
+  ParsedHotkey,
+  ParsedStep,
+} from "./types.js"
+export type { Mode } from "./mode.jsx"
+export { ModeProvider, useMode, useSetMode } from "./mode.jsx"
+export type { ModeProviderProps } from "./mode.jsx"
+export { parseHotkey } from "./parse.js"
+export { matchStep } from "./match.js"
+export { SequenceTracker } from "./sequence.js"
+export type { SequenceTrackerOptions } from "./sequence.js"
+export { CommandProvider, useCommandContext, useProvideCommandContext } from "./context.jsx"
+export type { CommandProviderProps } from "./context.jsx"
+export { useCommand } from "./use-command.js"
+export type { UseCommandOptions } from "./use-command.js"
+export { useActions } from "./use-actions.js"
+export type { ActionDefinition } from "./use-actions.js"

package/src/match.ts

@@ -0,0 +1,14 @@
+import type { KeyEvent } from "@opentui/core"
+import type { ParsedStep } from "./types.js"
+
+/**
+ * Check if a KeyEvent matches a ParsedStep.
+ */
+export function matchStep(event: KeyEvent, step: ParsedStep): boolean {
+  if (event.name !== step.key) return false
+  if (event.ctrl !== step.ctrl) return false
+  if (event.meta !== step.meta) return false
+  if (event.shift !== step.shift) return false
+  if (event.option !== step.option) return false
+  return true
+}

package/src/mode.tsx

@@ -0,0 +1,38 @@
+import { createContext, useContext, useState, useCallback, type ReactNode } from "react"
+
+export type Mode = "cursor" | "insert" | "select"
+
+interface ModeContextValue {
+  mode: Mode
+  setMode: (mode: Mode) => void
+}
+
+const ModeContext = createContext<ModeContextValue | null>(null)
+
+export interface ModeProviderProps {
+  children: ReactNode
+  initialMode?: Mode
+}
+
+export function ModeProvider({ children, initialMode = "cursor" }: ModeProviderProps) {
+  const [mode, setModeState] = useState<Mode>(initialMode)
+  const setMode = useCallback((m: Mode) => setModeState(m), [])
+
+  return <ModeContext.Provider value={{ mode, setMode }}>{children}</ModeContext.Provider>
+}
+
+export function useMode(): Mode {
+  const ctx = useContext(ModeContext)
+  if (!ctx) {
+    throw new Error("useMode must be used within a ModeProvider")
+  }
+  return ctx.mode
+}
+
+export function useSetMode(): (mode: Mode) => void {
+  const ctx = useContext(ModeContext)
+  if (!ctx) {
+    throw new Error("useSetMode must be used within a ModeProvider")
+  }
+  return ctx.setMode
+}

package/src/parse.ts

@@ -0,0 +1,71 @@
+import type { ParsedHotkey, ParsedStep } from "./types.js"
+
+const KEY_ALIASES: Record<string, string> = {
+  esc: "escape",
+  enter: "return",
+  cr: "return",
+  del: "delete",
+  space: " ",
+  tab: "tab",
+  backspace: "backspace",
+}
+
+function normalizeKey(key: string): string {
+  const lower = key.toLowerCase()
+  return KEY_ALIASES[lower] ?? lower
+}
+
+function parseStep(step: string): ParsedStep {
+  const parts = step.toLowerCase().split("+")
+  let key = ""
+  let ctrl = false
+  let meta = false
+  let shift = false
+  let option = false
+
+  for (const part of parts) {
+    const trimmed = part.trim()
+    if (trimmed === "ctrl" || trimmed === "control") {
+      ctrl = true
+    } else if (trimmed === "meta" || trimmed === "alt") {
+      meta = true
+    } else if (trimmed === "shift") {
+      shift = true
+    } else if (trimmed === "option") {
+      option = true
+    } else if (trimmed === "super") {
+      // super modifier — not tracked in ParsedStep currently
+    } else {
+      key = normalizeKey(trimmed)
+    }
+  }
+
+  return { key, ctrl, meta, shift, option }
+}
+
+/**
+ * Parse a hotkey string into a ParsedHotkey.
+ *
+ * Supports:
+ * - Modifier combos: "ctrl+s", "ctrl+shift+p"
+ * - Sequences (space-separated): "g g", "d d"
+ * - Leader prefix: "<leader>n" expands to leaderKey + "n"
+ */
+export function parseHotkey(hotkey: string, leaderKey?: string): ParsedHotkey {
+  const trimmed = hotkey.trim()
+
+  // Handle leader prefix
+  const leaderMatch = trimmed.match(/^<leader>(.+)$/)
+  if (leaderMatch) {
+    const leaderStep = leaderKey
+      ? parseStep(leaderKey)
+      : { key: "x", ctrl: true, meta: false, shift: false, option: false }
+    const followStep = parseStep(leaderMatch[1]!)
+    return { steps: [leaderStep, followStep] }
+  }
+
+  // Space-separated = sequence
+  const parts = trimmed.split(/\s+/)
+  const steps = parts.map(parseStep)
+  return { steps }
+}

package/src/sequence.ts

@@ -0,0 +1,70 @@
+import type { KeyEvent } from "@opentui/core"
+import type { ParsedHotkey } from "./types.js"
+import { matchStep } from "./match.js"
+
+export interface SequenceTrackerOptions {
+  timeout?: number // ms, default 500
+}
+
+export class SequenceTracker {
+  private buffer: KeyEvent[] = []
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private timeout: number
+
+  constructor(options?: SequenceTrackerOptions) {
+    this.timeout = options?.timeout ?? 500
+  }
+
+  /**
+   * Feed a key event and check against registered hotkeys.
+   * Returns the index of the matched hotkey, or -1 if no match.
+   */
+  feed(event: KeyEvent, hotkeys: ParsedHotkey[]): number {
+    this.buffer.push(event)
+    this.resetTimer()
+
+    for (let i = 0; i < hotkeys.length; i++) {
+      const hotkey = hotkeys[i]!
+      if (this.matchesBuffer(hotkey)) {
+        this.reset()
+        return i
+      }
+    }
+
+    // Prune buffer if no hotkey could possibly match
+    const maxLen = Math.max(...hotkeys.map((h) => h.steps.length))
+    if (this.buffer.length > maxLen) {
+      this.buffer.shift()
+    }
+
+    return -1
+  }
+
+  private matchesBuffer(hotkey: ParsedHotkey): boolean {
+    const { steps } = hotkey
+    if (this.buffer.length < steps.length) return false
+
+    const start = this.buffer.length - steps.length
+    for (let i = 0; i < steps.length; i++) {
+      if (!matchStep(this.buffer[start + i]!, steps[i]!)) return false
+    }
+    return true
+  }
+
+  reset(): void {
+    this.buffer = []
+    this.clearTimer()
+  }
+
+  private resetTimer(): void {
+    this.clearTimer()
+    this.timer = setTimeout(() => this.reset(), this.timeout)
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+import type { Mode } from "./mode.jsx"
+
+export interface CommandContextBase {
+  mode: Mode
+  setMode: (mode: Mode) => void
+  commands: { invoke: (id: string) => void; list: () => Command[] }
+  exit: () => void
+}
+
+export interface CommandContext extends CommandContextBase {
+  [key: string]: any
+}
+
+export type CommandHandler = (ctx: CommandContext) => void | Promise<void>
+export type CommandWhen = (ctx: CommandContext) => boolean
+
+export interface Command {
+  id: string
+  title: string
+  handler: CommandHandler
+  defaultHotkey?: string
+  modes?: Mode[]
+  when?: CommandWhen
+  category?: string
+  group?: string
+  icon?: string
+  hidden?: boolean
+}
+
+export interface ParsedHotkey {
+  steps: ParsedStep[]
+}
+
+export interface ParsedStep {
+  key: string
+  ctrl: boolean
+  meta: boolean
+  shift: boolean
+  option: boolean
+}
+
+export interface CommandRegistry {
+  commands: Map<string, Command>
+  register: (command: Command) => () => void
+  invoke: (id: string) => void
+}

package/src/use-actions.ts

@@ -0,0 +1,47 @@
+import { useEffect, useMemo, useRef } from "react"
+import { useCommandRegistry } from "./context.jsx"
+import type { Command, CommandHandler, CommandWhen } from "./types.js"
+import type { Mode } from "./mode.jsx"
+
+export interface ActionDefinition {
+  id: string
+  title: string
+  hotkey?: string
+  modes?: Mode[]
+  handler: CommandHandler
+  when?: CommandWhen
+}
+
+export function useActions(actions: ActionDefinition[] | undefined): void {
+  const { registry } = useCommandRegistry()
+  const actionsRef = useRef(actions)
+  actionsRef.current = actions
+
+  const key = useMemo(
+    () => actions?.map((a) => `${a.id}:${a.hotkey ?? ""}`).join(",") ?? "",
+    [actions],
+  )
+
+  useEffect(() => {
+    const current = actionsRef.current
+    if (!current || current.length === 0) return
+
+    const unregisters = current.map((action, i) => {
+      const command: Command = {
+        id: action.id,
+        title: action.title,
+        defaultHotkey: action.hotkey,
+        modes: action.modes,
+        handler: (ctx) => actionsRef.current?.[i]?.handler(ctx),
+        when: action.when ? (ctx) => actionsRef.current?.[i]?.when?.(ctx) ?? false : undefined,
+      }
+      return registry.register(command)
+    })
+
+    return () => {
+      for (const unregister of unregisters) {
+        unregister()
+      }
+    }
+  }, [key, registry])
+}

package/src/use-command.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from "react"
+import type { Command, CommandHandler, CommandWhen } from "./types.js"
+import type { Mode } from "./mode.jsx"
+import { useCommandRegistry } from "./context.jsx"
+
+export interface UseCommandOptions {
+  id: string
+  title: string
+  handler: CommandHandler
+  hotkey?: string
+  modes?: Mode[]
+  category?: string
+  group?: string
+  icon?: string
+  when?: CommandWhen
+  hidden?: boolean
+}
+
+export function useCommand(options: UseCommandOptions): void {
+  const { registry } = useCommandRegistry()
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  useEffect(() => {
+    const command: Command = {
+      id: options.id,
+      title: options.title,
+      handler: (...args: Parameters<Command["handler"]>) => optionsRef.current.handler(...args),
+      defaultHotkey: options.hotkey,
+      modes: options.modes,
+      category: options.category,
+      group: options.group,
+      icon: options.icon,
+      when: optionsRef.current.when ? (ctx) => optionsRef.current.when!(ctx) : undefined,
+      hidden: options.hidden,
+    }
+    return registry.register(command)
+  }, [
+    options.id,
+    options.title,
+    options.hotkey,
+    options.modes,
+    options.category,
+    options.group,
+    options.icon,
+    options.hidden,
+    registry,
+  ])
+}