@xincli/opentui-core 0.4.6

package/src/lib/keybinding.internal.test.ts

@@ -0,0 +1,342 @@
+import { describe, expect, it } from "bun:test"
+import {
+  mergeKeyBindings,
+  getKeyBindingKey,
+  getKeyBindingAction,
+  buildKeyBindingsMap,
+  mergeKeyAliases,
+  defaultKeyAliases,
+  keyBindingToString,
+  matchesKeyBinding,
+  type KeyAliasMap,
+} from "./keybinding.internal.js"
+
+describe("keybinding.internal", () => {
+  describe("getKeyBindingKey", () => {
+    it("should generate key with meta modifier", () => {
+      const metaBinding = { name: "a", meta: true, action: "test" }
+      const key = getKeyBindingKey(metaBinding)
+      expect(key).toBe("a:0:0:1:0")
+    })
+
+    it("should generate different keys for different modifiers", () => {
+      const noMod = getKeyBindingKey({ name: "a" })
+      const withMeta = getKeyBindingKey({ name: "a", meta: true })
+      const withCtrl = getKeyBindingKey({ name: "a", ctrl: true })
+      const withShift = getKeyBindingKey({ name: "a", shift: true })
+
+      expect(noMod).not.toBe(withMeta)
+      expect(noMod).not.toBe(withCtrl)
+      expect(noMod).not.toBe(withShift)
+      expect(withMeta).not.toBe(withCtrl)
+    })
+
+    it("should handle combined modifiers", () => {
+      const key = getKeyBindingKey({ name: "a", ctrl: true, shift: true, meta: true })
+      expect(key).toBe("a:1:1:1:0")
+    })
+
+    it("should generate key with super modifier", () => {
+      const superBinding = { name: "z", super: true, action: "test" }
+      const key = getKeyBindingKey(superBinding)
+      expect(key).toBe("z:0:0:0:1")
+    })
+  })
+
+  describe("getKeyBindingAction", () => {
+    it("should fall back to baseCode when the parsed name differs", () => {
+      const map = buildKeyBindingsMap([{ name: "c", ctrl: true, action: "copy" as const }])
+
+      const action = getKeyBindingAction(map, { name: "ㅊ", baseCode: 99, ctrl: true })
+
+      expect(action).toBe("copy")
+    })
+
+    it("should prefer a direct name match over the baseCode fallback", () => {
+      const map = buildKeyBindingsMap([
+        { name: "c", ctrl: true, action: "copy" as const },
+        { name: "ㅊ", ctrl: true, action: "insert" as const },
+      ])
+
+      const action = getKeyBindingAction(map, { name: "ㅊ", baseCode: 99, ctrl: true })
+
+      expect(action).toBe("insert")
+    })
+  })
+
+  describe("matchesKeyBinding", () => {
+    it("should match a binding by baseCode when available", () => {
+      expect(matchesKeyBinding({ name: "ㅊ", baseCode: 99, ctrl: true }, { name: "c", ctrl: true })).toBe(true)
+    })
+  })
+
+  describe("mergeKeyBindings", () => {
+    it("should merge defaults and custom bindings", () => {
+      const defaults = [
+        { name: "a", action: "action1" as const },
+        { name: "b", action: "action2" as const },
+      ]
+      const custom = [{ name: "c", action: "action3" as const }]
+
+      const merged = mergeKeyBindings(defaults, custom)
+      expect(merged.length).toBe(3)
+    })
+
+    it("should allow custom to override defaults", () => {
+      const defaults = [{ name: "a", action: "action1" as const }]
+      const custom = [{ name: "a", action: "action2" as const }]
+
+      const merged = mergeKeyBindings(defaults, custom)
+      expect(merged.length).toBe(1)
+      expect(merged[0]!.action).toBe("action2")
+    })
+
+    it("should override when meta matches", () => {
+      const defaults = [{ name: "a", meta: true, action: "action1" as const }]
+      const custom = [{ name: "a", meta: true, action: "action2" as const }]
+
+      const merged = mergeKeyBindings(defaults, custom)
+      expect(merged.length).toBe(1)
+      expect(merged[0]!.action).toBe("action2")
+    })
+  })
+
+  describe("buildKeyBindingsMap", () => {
+    it("should build map from bindings", () => {
+      const bindings = [
+        { name: "a", action: "action1" as const },
+        { name: "b", meta: true, action: "action2" as const },
+      ]
+
+      const map = buildKeyBindingsMap(bindings)
+      expect(map.size).toBe(2)
+      expect(map.get("a:0:0:0:0")).toBe("action1")
+      expect(map.get("b:0:0:1:0")).toBe("action2")
+    })
+
+    it("should handle meta modifier correctly", () => {
+      const bindings = [{ name: "a", meta: true, action: "action1" as const }]
+
+      const map = buildKeyBindingsMap(bindings)
+      expect(map.get("a:0:0:1:0")).toBe("action1")
+    })
+
+    it("should handle aliases and normalize key names", () => {
+      const bindings = [{ name: "return", action: "submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const map = buildKeyBindingsMap(bindings, aliases)
+
+      expect(map.get("return:0:0:0:0")).toBe("submit")
+      expect(map.get("enter:0:0:0:0")).toBeUndefined()
+    })
+
+    it("should create aliased mappings for aliased key names", () => {
+      const bindings = [{ name: "enter", action: "submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const map = buildKeyBindingsMap(bindings, aliases)
+
+      expect(map.get("enter:0:0:0:0")).toBe("submit")
+      expect(map.get("return:0:0:0:0")).toBe("submit")
+    })
+
+    it("should handle multiple aliases", () => {
+      const bindings = [
+        { name: "enter", action: "submit" as const },
+        { name: "esc", action: "cancel" as const },
+      ]
+      const aliases: KeyAliasMap = { enter: "return", esc: "escape" }
+
+      const map = buildKeyBindingsMap(bindings, aliases)
+
+      expect(map.get("enter:0:0:0:0")).toBe("submit")
+      expect(map.get("return:0:0:0:0")).toBe("submit")
+      expect(map.get("esc:0:0:0:0")).toBe("cancel")
+      expect(map.get("escape:0:0:0:0")).toBe("cancel")
+    })
+
+    it("should handle aliases with modifiers", () => {
+      const bindings = [{ name: "enter", meta: true, action: "special-submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const map = buildKeyBindingsMap(bindings, aliases)
+
+      expect(map.get("enter:0:0:1:0")).toBe("special-submit")
+      expect(map.get("return:0:0:1:0")).toBe("special-submit")
+    })
+  })
+
+  describe("mergeKeyAliases", () => {
+    it("should merge default and custom aliases", () => {
+      const defaults: KeyAliasMap = { enter: "return" }
+      const custom: KeyAliasMap = { esc: "escape" }
+
+      const merged = mergeKeyAliases(defaults, custom)
+
+      expect(merged.enter).toBe("return")
+      expect(merged.esc).toBe("escape")
+    })
+
+    it("should allow custom aliases to override defaults", () => {
+      const defaults: KeyAliasMap = { enter: "return" }
+      const custom: KeyAliasMap = { enter: "custom-return" }
+
+      const merged = mergeKeyAliases(defaults, custom)
+
+      expect(merged.enter).toBe("custom-return")
+    })
+
+    it("should preserve defaults when no custom aliases provided", () => {
+      const defaults: KeyAliasMap = { enter: "return", esc: "escape" }
+      const custom: KeyAliasMap = {}
+
+      const merged = mergeKeyAliases(defaults, custom)
+
+      expect(merged.enter).toBe("return")
+      expect(merged.esc).toBe("escape")
+    })
+  })
+
+  describe("defaultKeyAliases", () => {
+    it("should have enter -> return alias", () => {
+      expect(defaultKeyAliases.enter).toBe("return")
+    })
+
+    it("should have esc -> escape alias", () => {
+      expect(defaultKeyAliases.esc).toBe("escape")
+    })
+
+    it("should have keypad aliases to normalized key names", () => {
+      const keypadAliases: KeyAliasMap = {
+        kp0: "0",
+        kp1: "1",
+        kp2: "2",
+        kp3: "3",
+        kp4: "4",
+        kp5: "5",
+        kp6: "6",
+        kp7: "7",
+        kp8: "8",
+        kp9: "9",
+        kpdecimal: ".",
+        kpdivide: "/",
+        kpmultiply: "*",
+        kpminus: "-",
+        kpplus: "+",
+        kpenter: "enter",
+        kpequal: "=",
+        kpseparator: ",",
+        kpleft: "left",
+        kpright: "right",
+        kpup: "up",
+        kpdown: "down",
+        kppageup: "pageup",
+        kppagedown: "pagedown",
+        kphome: "home",
+        kpend: "end",
+        kpinsert: "insert",
+        kpdelete: "delete",
+      }
+
+      for (const [key, value] of Object.entries(keypadAliases)) {
+        expect(defaultKeyAliases[key]).toBe(value)
+      }
+    })
+  })
+
+  describe("alias override behavior", () => {
+    it("should override 'return' binding when custom provides 'enter' binding with aliases", () => {
+      const defaults = [{ name: "return", action: "newline" as const }]
+      const custom = [{ name: "enter", action: "submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const merged = mergeKeyBindings(defaults, custom)
+      const map = buildKeyBindingsMap(merged, aliases)
+
+      const returnAction = map.get("return:0:0:0:0")
+      const enterAction = map.get("enter:0:0:0:0")
+
+      expect(returnAction).toBe("submit")
+      expect(enterAction).toBe("submit")
+    })
+
+    it("should also allow direct override using canonical name", () => {
+      const defaults = [{ name: "return", action: "newline" as const }]
+      const custom = [{ name: "return", action: "submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const merged = mergeKeyBindings(defaults, custom)
+      const map = buildKeyBindingsMap(merged, aliases)
+
+      const returnAction = map.get("return:0:0:0:0")
+      const enterAction = map.get("enter:0:0:0:0")
+
+      expect(returnAction).toBe("submit")
+      expect(enterAction).toBeUndefined()
+    })
+
+    it("should handle the Textarea scenario: defaults with 'return', custom with 'enter'", () => {
+      const defaults = [
+        { name: "return", action: "newline" as const },
+        { name: "return", meta: true, action: "submit" as const },
+      ]
+      const custom = [{ name: "enter", action: "custom-submit" as const }]
+      const aliases: KeyAliasMap = { enter: "return" }
+
+      const merged = mergeKeyBindings(defaults, custom)
+      const map = buildKeyBindingsMap(merged, aliases)
+
+      const returnNoMod = map.get("return:0:0:0:0")
+      const returnWithMeta = map.get("return:0:0:1:0")
+      const enterNoMod = map.get("enter:0:0:0:0")
+
+      expect(returnNoMod).toBe("custom-submit")
+      expect(enterNoMod).toBe("custom-submit")
+      expect(returnWithMeta).toBe("submit")
+    })
+  })
+
+  describe("keyBindingToString", () => {
+    it("should convert simple key binding without modifiers", () => {
+      const binding = { name: "escape", action: "cancel" as const }
+      expect(keyBindingToString(binding)).toBe("escape")
+    })
+
+    it("should convert key binding with ctrl modifier", () => {
+      const binding = { name: "c", ctrl: true, action: "copy" as const }
+      expect(keyBindingToString(binding)).toBe("ctrl+c")
+    })
+
+    it("should convert key binding with shift modifier", () => {
+      const binding = { name: "up", shift: true, action: "scroll-fast" as const }
+      expect(keyBindingToString(binding)).toBe("shift+up")
+    })
+
+    it("should convert key binding with multiple modifiers", () => {
+      const binding = { name: "y", ctrl: true, shift: true, action: "copy" as const }
+      expect(keyBindingToString(binding)).toBe("ctrl+shift+y")
+    })
+
+    it("should convert key binding with all modifiers", () => {
+      const binding = { name: "a", ctrl: true, shift: true, meta: true, super: true, action: "all" as const }
+      expect(keyBindingToString(binding)).toBe("ctrl+shift+meta+super+a")
+    })
+
+    it("should convert key binding with meta modifier", () => {
+      const binding = { name: "s", meta: true, action: "save" as const }
+      expect(keyBindingToString(binding)).toBe("meta+s")
+    })
+
+    it("should convert key binding with super modifier", () => {
+      const binding = { name: "z", super: true, action: "undo" as const }
+      expect(keyBindingToString(binding)).toBe("super+z")
+    })
+
+    it("should handle special keys correctly", () => {
+      expect(keyBindingToString({ name: "return", action: "submit" as const })).toBe("return")
+      expect(keyBindingToString({ name: "space", action: "select" as const })).toBe("space")
+      expect(keyBindingToString({ name: "tab", action: "next" as const })).toBe("tab")
+    })
+  })
+})

package/src/lib/keybinding.internal.ts

@@ -0,0 +1,182 @@
+export interface KeyBindingLike {
+  name: string
+  ctrl?: boolean
+  shift?: boolean
+  meta?: boolean
+  super?: boolean
+}
+
+export interface KeyBinding<Action extends string = string> extends KeyBindingLike {
+  action: Action
+}
+
+export interface KeyBindingLookup extends KeyBindingLike {
+  // Kitty's base-layout codepoint as a Unicode number. Example: 99 means "c".
+  baseCode?: number
+}
+
+export type KeyAliasMap = Record<string, string>
+
+export const defaultKeyAliases: KeyAliasMap = {
+  enter: "return",
+  esc: "escape",
+  kp0: "0",
+  kp1: "1",
+  kp2: "2",
+  kp3: "3",
+  kp4: "4",
+  kp5: "5",
+  kp6: "6",
+  kp7: "7",
+  kp8: "8",
+  kp9: "9",
+  kpdecimal: ".",
+  kpdivide: "/",
+  kpmultiply: "*",
+  kpminus: "-",
+  kpplus: "+",
+  kpenter: "enter",
+  kpequal: "=",
+  kpseparator: ",",
+  kpleft: "left",
+  kpright: "right",
+  kpup: "up",
+  kpdown: "down",
+  kppageup: "pageup",
+  kppagedown: "pagedown",
+  kphome: "home",
+  kpend: "end",
+  kpinsert: "insert",
+  kpdelete: "delete",
+}
+
+export function mergeKeyAliases(defaults: KeyAliasMap, custom: KeyAliasMap): KeyAliasMap {
+  return { ...defaults, ...custom }
+}
+
+export function mergeKeyBindings<Action extends string>(
+  defaults: KeyBinding<Action>[],
+  custom: KeyBinding<Action>[],
+): KeyBinding<Action>[] {
+  const map = new Map<string, KeyBinding<Action>>()
+  for (const binding of defaults) {
+    const key = getKeyBindingKey(binding)
+    map.set(key, binding)
+  }
+  for (const binding of custom) {
+    const key = getKeyBindingKey(binding)
+    map.set(key, binding)
+  }
+  return Array.from(map.values())
+}
+
+export function getKeyBindingKey(binding: KeyBindingLike): string {
+  return `${binding.name}:${binding.ctrl ? 1 : 0}:${binding.shift ? 1 : 0}:${binding.meta ? 1 : 0}:${binding.super ? 1 : 0}`
+}
+
+// `baseCode` is Kitty's "base layout codepoint": the character for the same
+// physical key on the keyboard's base layout. Example: an event may arrive as
+// `name: "ㅊ", baseCode: 99`, where `99` is Unicode `c`. We normalize that
+// numeric codepoint to the key names we store in key maps so Ctrl+ㅊ can still
+// match a Ctrl+C binding.
+function getBaseCodeKeyName(baseCode: number | undefined): string | undefined {
+  if (baseCode === undefined || baseCode < 32 || baseCode === 127) {
+    return undefined
+  }
+
+  try {
+    const name = String.fromCodePoint(baseCode)
+
+    if (name.length === 1 && name >= "A" && name <= "Z") {
+      return name.toLowerCase()
+    }
+
+    return name
+  } catch {
+    return undefined
+  }
+}
+
+// Return every lookup key that can represent this event. We try the parsed
+// name first, then the base-layout key when Kitty provides one. That keeps
+// direct character bindings precise, and still lets physical-layout
+// shortcuts resolve.
+export function getKeyBindingKeys(binding: KeyBindingLookup): string[] {
+  const names = new Set([binding.name])
+  const baseCodeName = getBaseCodeKeyName(binding.baseCode)
+
+  if (baseCodeName) {
+    names.add(baseCodeName)
+  }
+
+  return [...names].map((name) => getKeyBindingKey({ ...binding, name }))
+}
+
+export function getKeyBindingAction<Action extends string>(
+  map: Map<string, Action>,
+  binding: KeyBindingLookup,
+): Action | undefined {
+  for (const key of getKeyBindingKeys(binding)) {
+    const action = map.get(key)
+
+    if (action !== undefined) {
+      return action
+    }
+  }
+
+  return undefined
+}
+
+export function matchesKeyBinding(binding: KeyBindingLookup, match: KeyBindingLike): boolean {
+  const matchKey = getKeyBindingKey(match)
+
+  return getKeyBindingKeys(binding).includes(matchKey)
+}
+
+export function buildKeyBindingsMap<Action extends string>(
+  bindings: KeyBinding<Action>[],
+  aliasMap?: KeyAliasMap,
+): Map<string, Action> {
+  const map = new Map<string, Action>()
+  const aliases = aliasMap || {}
+
+  for (const binding of bindings) {
+    const key = getKeyBindingKey(binding)
+    map.set(key, binding.action)
+  }
+
+  // Add aliased versions of all bindings
+  for (const binding of bindings) {
+    const normalizedName = aliases[binding.name] || binding.name
+    if (normalizedName !== binding.name) {
+      // Create aliased key with normalized name
+      const aliasedKey = getKeyBindingKey({ ...binding, name: normalizedName })
+      map.set(aliasedKey, binding.action)
+    }
+  }
+
+  return map
+}
+
+/**
+ * Converts a key binding to a human-readable string representation
+ * @param binding The key binding to stringify
+ * @returns A string like "ctrl+shift+y" or just "escape"
+ * @example
+ * keyBindingToString({ name: "y", ctrl: true, shift: true }) // "ctrl+shift+y"
+ * keyBindingToString({ name: "escape" }) // "escape"
+ * keyBindingToString({ name: "c", ctrl: true }) // "ctrl+c"
+ * keyBindingToString({ name: "s", super: true }) // "super+s"
+ */
+export function keyBindingToString<Action extends string>(binding: KeyBinding<Action>): string {
+  const parts: string[] = []
+
+  if (binding.ctrl) parts.push("ctrl")
+  if (binding.shift) parts.push("shift")
+  if (binding.meta) parts.push("meta")
+  if (binding.super) parts.push("super")
+
+  parts.push(binding.name)
+
+  return parts.join("+")
+}