@vielzeug/keymap 2.2.0 → 26.10.0

package/dist/parser.js

@@ -1,74 +1,2 @@
-import { KeymapParseError as e } from "./errors.js";
-//#region src/parser.ts
-function t() {
-	if (typeof navigator > "u") return "ctrl";
-	let e = navigator.userAgentData?.platform ?? navigator.platform ?? "";
-	return /mac/i.test(e) ? "meta" : "ctrl";
-}
-var n = {
-	alt: "alt",
-	cmd: "meta",
-	command: "meta",
-	control: "ctrl",
-	ctrl: "ctrl",
-	meta: "meta",
-	opt: "alt",
-	option: "alt",
-	shift: "shift",
-	win: "meta"
-}, r = {
-	del: "delete",
-	down: "arrowdown",
-	esc: "escape",
-	left: "arrowleft",
-	right: "arrowright",
-	space: " ",
-	spacebar: " ",
-	up: "arrowup"
-};
-function i(t, i) {
-	let a = t.trim().split("+").filter(Boolean).map((e) => e.toLowerCase());
-	if (a.length === 0) throw new e(`Invalid shortcut step: "${t}"`);
-	let o = {
-		...n,
-		mod: i
-	}, s = /* @__PURE__ */ new Set(), c = [];
-	for (let e of a) {
-		let t = Object.hasOwn(o, e) ? o[e] : void 0;
-		t ? s.add(t) : c.push(e);
-	}
-	if (c.length === 0) throw new e(`Invalid shortcut step: "${t}"`);
-	if (c.length > 1) throw new e(`Ambiguous shortcut step: "${t}" — multiple non-modifier keys found`);
-	let l = c[0];
-	return {
-		key: Object.hasOwn(r, l) ? r[l] : l,
-		modifiers: s
-	};
-}
-function a(e, n = t()) {
-	try {
-		return i(e, n);
-	} catch {
-		return null;
-	}
-}
-function o(n, r = t()) {
-	let a = n.trim().split(/\s+/).filter(Boolean);
-	if (a.length === 0) throw new e("Shortcut must contain at least one key step");
-	return a.map((e) => i(e, r));
-}
-function s(e) {
-	return e.map((e) => {
-		let t = [...e.modifiers].sort().join("+");
-		return t ? `${t}+${e.key}` : e.key;
-	}).join(" ");
-}
-function c(e, t) {
-	if (typeof e.key != "string" || e.key.toLowerCase() !== t.key) return !1;
-	let { modifiers: n } = t;
-	return e.altKey === n.has("alt") && e.ctrlKey === n.has("ctrl") && e.metaKey === n.has("meta") && e.shiftKey === n.has("shift");
-}
-//#endregion
-export { s as canonicalizeShortcut, t as detectModKey, c as matchStep, o as parseShortcut, a as parseStep };
-
+import{KeymapParseError as e}from"./errors.js";function detectModKey(){if(typeof navigator>`u`)return`ctrl`;let e=navigator.userAgentData?.platform??navigator.platform??``;return/mac/i.test(e)?`meta`:`ctrl`}var t={alt:`alt`,cmd:`meta`,command:`meta`,control:`ctrl`,ctrl:`ctrl`,meta:`meta`,opt:`alt`,option:`alt`,shift:`shift`,win:`meta`},n={del:`delete`,down:`arrowdown`,esc:`escape`,left:`arrowleft`,right:`arrowright`,space:` `,spacebar:` `,up:`arrowup`};function parseStepStrict(r,i){let a=r.trim().split(`+`).filter(Boolean).map(e=>e.toLowerCase());if(a.length===0)throw new e(`Invalid shortcut step: "${r}"`);let o={...t,mod:i},s=new Set,c=[];for(let e of a){let t=Object.hasOwn(o,e)?o[e]:void 0;t?s.add(t):c.push(e)}if(c.length===0)throw new e(`Invalid shortcut step: "${r}"`);if(c.length>1)throw new e(`Ambiguous shortcut step: "${r}" — multiple non-modifier keys found`);let l=c[0];return{key:Object.hasOwn(n,l)?n[l]:l,modifiers:s}}function parseStep(e,t=detectModKey()){try{return parseStepStrict(e,t)}catch{return null}}function parseShortcut(t,n=detectModKey()){let r=t.trim().split(/\s+/).filter(Boolean);if(r.length===0)throw new e(`Shortcut must contain at least one key step`);return r.map(e=>parseStepStrict(e,n))}function canonicalizeShortcut(e){return e.map(e=>{let t=[...e.modifiers].sort().join(`+`);return t?`${t}+${e.key}`:e.key}).join(` `)}function matchStep(e,t){if(typeof e.key!=`string`||e.key.toLowerCase()!==t.key)return!1;let{modifiers:n}=t;return e.altKey===n.has(`alt`)&&e.ctrlKey===n.has(`ctrl`)&&e.metaKey===n.has(`meta`)&&e.shiftKey===n.has(`shift`)}function matchKey(e,t,n=detectModKey()){let r=parseStep(t,n);return r!==null&&matchStep(e,r)}export{canonicalizeShortcut,detectModKey,matchKey,matchStep,parseShortcut,parseStep};
 //# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","names":[],"sources":["../src/parser.ts"],"sourcesContent":["import { KeymapParseError } from './errors';\n\nexport type ModifierKey = 'alt' | 'ctrl' | 'meta' | 'shift';\n\nexport type ShortcutStep = {\n  key: string;\n  modifiers: Set<ModifierKey>;\n};\n\nexport type Shortcut = ShortcutStep[];\n\nexport function detectModKey(): 'ctrl' | 'meta' {\n  if (typeof navigator === 'undefined') return 'ctrl';\n\n  const platform =\n    (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform ??\n    navigator.platform ??\n    '';\n\n  return /mac/i.test(platform) ? 'meta' : 'ctrl';\n}\n\nconst MODIFIER_ALIASES_BASE: Record<string, ModifierKey> = {\n  alt: 'alt',\n  cmd: 'meta',\n  command: 'meta',\n  control: 'ctrl',\n  ctrl: 'ctrl',\n  meta: 'meta',\n  opt: 'alt',\n  option: 'alt',\n  shift: 'shift',\n  win: 'meta',\n};\n\nconst SPECIAL_KEY_ALIASES: Record<string, string> = {\n  del: 'delete',\n  down: 'arrowdown',\n  esc: 'escape',\n  left: 'arrowleft',\n  right: 'arrowright',\n  space: ' ',\n  spacebar: ' ',\n  up: 'arrowup',\n};\n\nfunction parseStepStrict(raw: string, modKey: 'ctrl' | 'meta'): ShortcutStep {\n  const parts = raw\n    .trim()\n    .split('+')\n    .filter(Boolean)\n    .map((part) => part.toLowerCase());\n\n  if (parts.length === 0) throw new KeymapParseError(`Invalid shortcut step: \"${raw}\"`);\n\n  const aliases: Record<string, ModifierKey> = { ...MODIFIER_ALIASES_BASE, mod: modKey };\n  const modifiers = new Set<ModifierKey>();\n  const keyParts: string[] = [];\n\n  for (const part of parts) {\n    const modifier = Object.hasOwn(aliases, part) ? aliases[part]! : undefined;\n\n    if (modifier) modifiers.add(modifier);\n    else keyParts.push(part);\n  }\n\n  if (keyParts.length === 0) throw new KeymapParseError(`Invalid shortcut step: \"${raw}\"`);\n\n  if (keyParts.length > 1) {\n    throw new KeymapParseError(`Ambiguous shortcut step: \"${raw}\" — multiple non-modifier keys found`);\n  }\n\n  const rawKey = keyParts[0]!;\n  const key = Object.hasOwn(SPECIAL_KEY_ALIASES, rawKey) ? SPECIAL_KEY_ALIASES[rawKey]! : rawKey;\n\n  return { key, modifiers };\n}\n\nexport function parseStep(raw: string, modKey: 'ctrl' | 'meta' = detectModKey()): ShortcutStep | null {\n  try {\n    return parseStepStrict(raw, modKey);\n  } catch {\n    return null;\n  }\n}\n\nexport function parseShortcut(raw: string, modKey: 'ctrl' | 'meta' = detectModKey()): Shortcut {\n  const steps = raw.trim().split(/\\s+/).filter(Boolean);\n\n  if (steps.length === 0) throw new KeymapParseError('Shortcut must contain at least one key step');\n\n  return steps.map((step) => parseStepStrict(step, modKey));\n}\n\nexport function canonicalizeShortcut(steps: readonly ShortcutStep[]): string {\n  return steps\n    .map((step) => {\n      const modifiers = [...step.modifiers].sort().join('+');\n\n      return modifiers ? `${modifiers}+${step.key}` : step.key;\n    })\n    .join(' ');\n}\n\nexport function matchStep(event: KeyboardEvent, step: ShortcutStep): boolean {\n  // Headless usage (SSR, non-DOM `EventTarget`s, hand-built test events) means `event` isn't\n  // guaranteed to be a real `KeyboardEvent` at runtime even though the type says so — treat a\n  // missing/non-string `key` as \"doesn't match\" rather than throwing inside the event listener.\n  if (typeof event.key !== 'string') return false;\n\n  if (event.key.toLowerCase() !== step.key) return false;\n\n  const { modifiers } = step;\n\n  return (\n    event.altKey === modifiers.has('alt') &&\n    event.ctrlKey === modifiers.has('ctrl') &&\n    event.metaKey === modifiers.has('meta') &&\n    event.shiftKey === modifiers.has('shift')\n  );\n}\n"],"mappings":";;AAWA,SAAgB,IAAgC;CAC9C,IAAI,OAAO,YAAc,KAAa,OAAO;CAE7C,IAAM,IACH,UAAoE,eAAe,YACpF,UAAU,YACV;CAEF,OAAO,OAAO,KAAK,CAAQ,IAAI,SAAS;AAC1C;AAEA,IAAM,IAAqD;CACzD,KAAK;CACL,KAAK;CACL,SAAS;CACT,SAAS;CACT,MAAM;CACN,MAAM;CACN,KAAK;CACL,QAAQ;CACR,OAAO;CACP,KAAK;AACP,GAEM,IAA8C;CAClD,KAAK;CACL,MAAM;CACN,KAAK;CACL,MAAM;CACN,OAAO;CACP,OAAO;CACP,UAAU;CACV,IAAI;AACN;AAEA,SAAS,EAAgB,GAAa,GAAuC;CAC3E,IAAM,IAAQ,EACX,KAAK,CAAC,CACN,MAAM,GAAG,CAAC,CACV,OAAO,OAAO,CAAC,CACf,KAAK,MAAS,EAAK,YAAY,CAAC;CAEnC,IAAI,EAAM,WAAW,GAAG,MAAM,IAAI,EAAiB,2BAA2B,EAAI,EAAE;CAEpF,IAAM,IAAuC;EAAE,GAAG;EAAuB,KAAK;CAAO,GAC/E,oBAAY,IAAI,IAAiB,GACjC,IAAqB,CAAC;CAE5B,KAAK,IAAM,KAAQ,GAAO;EACxB,IAAM,IAAW,OAAO,OAAO,GAAS,CAAI,IAAI,EAAQ,KAAS,KAAA;EAEjE,AAAI,IAAU,EAAU,IAAI,CAAQ,IAC/B,EAAS,KAAK,CAAI;CACzB;CAEA,IAAI,EAAS,WAAW,GAAG,MAAM,IAAI,EAAiB,2BAA2B,EAAI,EAAE;CAEvF,IAAI,EAAS,SAAS,GACpB,MAAM,IAAI,EAAiB,6BAA6B,EAAI,qCAAqC;CAGnG,IAAM,IAAS,EAAS;CAGxB,OAAO;EAAE,KAFG,OAAO,OAAO,GAAqB,CAAM,IAAI,EAAoB,KAAW;EAE1E;CAAU;AAC1B;AAEA,SAAgB,EAAU,GAAa,IAA0B,EAAa,GAAwB;CACpG,IAAI;EACF,OAAO,EAAgB,GAAK,CAAM;CACpC,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAgB,EAAc,GAAa,IAA0B,EAAa,GAAa;CAC7F,IAAM,IAAQ,EAAI,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,OAAO,OAAO;CAEpD,IAAI,EAAM,WAAW,GAAG,MAAM,IAAI,EAAiB,6CAA6C;CAEhG,OAAO,EAAM,KAAK,MAAS,EAAgB,GAAM,CAAM,CAAC;AAC1D;AAEA,SAAgB,EAAqB,GAAwC;CAC3E,OAAO,EACJ,KAAK,MAAS;EACb,IAAM,IAAY,CAAC,GAAG,EAAK,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG;EAErD,OAAO,IAAY,GAAG,EAAU,GAAG,EAAK,QAAQ,EAAK;CACvD,CAAC,CAAC,CACD,KAAK,GAAG;AACb;AAEA,SAAgB,EAAU,GAAsB,GAA6B;CAM3E,IAFI,OAAO,EAAM,OAAQ,YAErB,EAAM,IAAI,YAAY,MAAM,EAAK,KAAK,OAAO;CAEjD,IAAM,EAAE,iBAAc;CAEtB,OACE,EAAM,WAAW,EAAU,IAAI,KAAK,KACpC,EAAM,YAAY,EAAU,IAAI,MAAM,KACtC,EAAM,YAAY,EAAU,IAAI,MAAM,KACtC,EAAM,aAAa,EAAU,IAAI,OAAO;AAE5C"}
+{"version":3,"file":"parser.js","names":[],"sources":["../src/parser.ts"],"sourcesContent":["import { KeymapParseError } from './errors';\n\nexport type ModifierKey = 'alt' | 'ctrl' | 'meta' | 'shift';\n\nexport type ShortcutStep = {\n  key: string;\n  modifiers: Set<ModifierKey>;\n};\n\nexport type Shortcut = ShortcutStep[];\n\nexport function detectModKey(): 'ctrl' | 'meta' {\n  if (typeof navigator === 'undefined') return 'ctrl';\n\n  const platform =\n    (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform ??\n    navigator.platform ??\n    '';\n\n  return /mac/i.test(platform) ? 'meta' : 'ctrl';\n}\n\nconst MODIFIER_ALIASES_BASE: Record<string, ModifierKey> = {\n  alt: 'alt',\n  cmd: 'meta',\n  command: 'meta',\n  control: 'ctrl',\n  ctrl: 'ctrl',\n  meta: 'meta',\n  opt: 'alt',\n  option: 'alt',\n  shift: 'shift',\n  win: 'meta',\n};\n\nconst SPECIAL_KEY_ALIASES: Record<string, string> = {\n  del: 'delete',\n  down: 'arrowdown',\n  esc: 'escape',\n  left: 'arrowleft',\n  right: 'arrowright',\n  space: ' ',\n  spacebar: ' ',\n  up: 'arrowup',\n};\n\nfunction parseStepStrict(raw: string, modKey: 'ctrl' | 'meta'): ShortcutStep {\n  const parts = raw\n    .trim()\n    .split('+')\n    .filter(Boolean)\n    .map((part) => part.toLowerCase());\n\n  if (parts.length === 0) throw new KeymapParseError(`Invalid shortcut step: \"${raw}\"`);\n\n  const aliases: Record<string, ModifierKey> = { ...MODIFIER_ALIASES_BASE, mod: modKey };\n  const modifiers = new Set<ModifierKey>();\n  const keyParts: string[] = [];\n\n  for (const part of parts) {\n    const modifier = Object.hasOwn(aliases, part) ? aliases[part]! : undefined;\n\n    if (modifier) modifiers.add(modifier);\n    else keyParts.push(part);\n  }\n\n  if (keyParts.length === 0) throw new KeymapParseError(`Invalid shortcut step: \"${raw}\"`);\n\n  if (keyParts.length > 1) {\n    throw new KeymapParseError(`Ambiguous shortcut step: \"${raw}\" — multiple non-modifier keys found`);\n  }\n\n  const rawKey = keyParts[0]!;\n  const key = Object.hasOwn(SPECIAL_KEY_ALIASES, rawKey) ? SPECIAL_KEY_ALIASES[rawKey]! : rawKey;\n\n  return { key, modifiers };\n}\n\nexport function parseStep(raw: string, modKey: 'ctrl' | 'meta' = detectModKey()): ShortcutStep | null {\n  try {\n    return parseStepStrict(raw, modKey);\n  } catch {\n    return null;\n  }\n}\n\nexport function parseShortcut(raw: string, modKey: 'ctrl' | 'meta' = detectModKey()): Shortcut {\n  const steps = raw.trim().split(/\\s+/).filter(Boolean);\n\n  if (steps.length === 0) throw new KeymapParseError('Shortcut must contain at least one key step');\n\n  return steps.map((step) => parseStepStrict(step, modKey));\n}\n\nexport function canonicalizeShortcut(steps: readonly ShortcutStep[]): string {\n  return steps\n    .map((step) => {\n      const modifiers = [...step.modifiers].sort().join('+');\n\n      return modifiers ? `${modifiers}+${step.key}` : step.key;\n    })\n    .join(' ');\n}\n\nexport function matchStep(event: KeyboardEvent, step: ShortcutStep): boolean {\n  // Headless usage (SSR, non-DOM `EventTarget`s, hand-built test events) means `event` isn't\n  // guaranteed to be a real `KeyboardEvent` at runtime even though the type says so — treat a\n  // missing/non-string `key` as \"doesn't match\" rather than throwing inside the event listener.\n  if (typeof event.key !== 'string') return false;\n\n  if (event.key.toLowerCase() !== step.key) return false;\n\n  const { modifiers } = step;\n\n  return (\n    event.altKey === modifiers.has('alt') &&\n    event.ctrlKey === modifiers.has('ctrl') &&\n    event.metaKey === modifiers.has('meta') &&\n    event.shiftKey === modifiers.has('shift')\n  );\n}\n\n/**\n * Match a keyboard event against a single shortcut pattern such as `'ArrowDown'`,\n * `'esc'`, `'mod+k'`, or `'shift+Home'`. Aliases and `mod` resolve through the same\n * parser `createKeymap` uses, and modifier state must match exactly: `ArrowDown`\n * does not match Ctrl+ArrowDown. Returns `false` for unparseable patterns instead\n * of throwing, so it is safe inside event listeners.\n */\nexport function matchKey(event: KeyboardEvent, pattern: string, modKey: 'ctrl' | 'meta' = detectModKey()): boolean {\n  const step = parseStep(pattern, modKey);\n\n  return step !== null && matchStep(event, step);\n}\n"],"mappings":"+CAWA,SAAgB,cAAgC,CAC9C,GAAI,OAAO,UAAc,IAAa,MAAO,OAE7C,IAAM,EACH,UAAoE,eAAe,UACpF,UAAU,UACV,GAEF,MAAO,OAAO,KAAK,CAAQ,EAAI,OAAS,MAC1C,CAEA,IAAM,EAAqD,CACzD,IAAK,MACL,IAAK,OACL,QAAS,OACT,QAAS,OACT,KAAM,OACN,KAAM,OACN,IAAK,MACL,OAAQ,MACR,MAAO,QACP,IAAK,MACP,EAEM,EAA8C,CAClD,IAAK,SACL,KAAM,YACN,IAAK,SACL,KAAM,YACN,MAAO,aACP,MAAO,IACP,SAAU,IACV,GAAI,SACN,EAEA,SAAS,gBAAgB,EAAa,EAAuC,CAC3E,IAAM,EAAQ,EACX,KAAK,CAAC,CACN,MAAM,GAAG,CAAC,CACV,OAAO,OAAO,CAAC,CACf,IAAK,GAAS,EAAK,YAAY,CAAC,EAEnC,GAAI,EAAM,SAAW,EAAG,MAAM,IAAI,EAAiB,2BAA2B,EAAI,EAAE,EAEpF,IAAM,EAAuC,CAAE,GAAG,EAAuB,IAAK,CAAO,EAC/E,EAAY,IAAI,IAChB,EAAqB,CAAC,EAE5B,IAAK,IAAM,KAAQ,EAAO,CACxB,IAAM,EAAW,OAAO,OAAO,EAAS,CAAI,EAAI,EAAQ,GAAS,IAAA,GAE7D,EAAU,EAAU,IAAI,CAAQ,EAC/B,EAAS,KAAK,CAAI,CACzB,CAEA,GAAI,EAAS,SAAW,EAAG,MAAM,IAAI,EAAiB,2BAA2B,EAAI,EAAE,EAEvF,GAAI,EAAS,OAAS,EACpB,MAAM,IAAI,EAAiB,6BAA6B,EAAI,qCAAqC,EAGnG,IAAM,EAAS,EAAS,GAGxB,MAAO,CAAE,IAFG,OAAO,OAAO,EAAqB,CAAM,EAAI,EAAoB,GAAW,EAE1E,WAAU,CAC1B,CAEA,SAAgB,UAAU,EAAa,EAA0B,aAAa,EAAwB,CACpG,GAAI,CACF,OAAO,gBAAgB,EAAK,CAAM,CACpC,MAAQ,CACN,OAAO,IACT,CACF,CAEA,SAAgB,cAAc,EAAa,EAA0B,aAAa,EAAa,CAC7F,IAAM,EAAQ,EAAI,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,OAAO,OAAO,EAEpD,GAAI,EAAM,SAAW,EAAG,MAAM,IAAI,EAAiB,6CAA6C,EAEhG,OAAO,EAAM,IAAK,GAAS,gBAAgB,EAAM,CAAM,CAAC,CAC1D,CAEA,SAAgB,qBAAqB,EAAwC,CAC3E,OAAO,EACJ,IAAK,GAAS,CACb,IAAM,EAAY,CAAC,GAAG,EAAK,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,EAErD,OAAO,EAAY,GAAG,EAAU,GAAG,EAAK,MAAQ,EAAK,GACvD,CAAC,CAAC,CACD,KAAK,GAAG,CACb,CAEA,SAAgB,UAAU,EAAsB,EAA6B,CAM3E,GAFI,OAAO,EAAM,KAAQ,UAErB,EAAM,IAAI,YAAY,IAAM,EAAK,IAAK,MAAO,GAEjD,GAAM,CAAE,aAAc,EAEtB,OACE,EAAM,SAAW,EAAU,IAAI,KAAK,GACpC,EAAM,UAAY,EAAU,IAAI,MAAM,GACtC,EAAM,UAAY,EAAU,IAAI,MAAM,GACtC,EAAM,WAAa,EAAU,IAAI,OAAO,CAE5C,CASA,SAAgB,SAAS,EAAsB,EAAiB,EAA0B,aAAa,EAAY,CACjH,IAAM,EAAO,UAAU,EAAS,CAAM,EAEtC,OAAO,IAAS,MAAQ,UAAU,EAAO,CAAI,CAC/C"}

package/dist/types.d.ts

@@ -1,9 +1,4 @@
 import type { ShortcutStep } from './parser';
-export type BindingEntry = {
-    readonly shortcut: readonly ShortcutStep[];
-    readonly trigger: 'keydown' | 'keyup';
-};
-export type Handler = (event: KeyboardEvent) => void;
 /**
  * Guard function for fine-grained binding context.
  *
@@ -20,59 +15,73 @@ export type Handler = (event: KeyboardEvent) => void;
  * { when: (e) => !isModalOpen() }
  *
  * // Per-binding: only fire when event target is the specific panel
- * { 'escape': { handler: closePanel, when: (e) => e.target === panel } }
+ * { id: 'close-panel', shortcut: 'escape', handler: closePanel, when: (e) => e.target === panel }
  *
  * Both conditions must be met for the handler to execute.
  */
 export type When = (event: KeyboardEvent) => boolean;
-export type BindingOptions = {
-    handler: Handler;
-    trigger?: 'keydown' | 'keyup';
-    when?: When;
+export type Handler = (event: KeyboardEvent) => void;
+export type KeymapEvent = {
+    readonly target: EventTarget;
+    readonly trigger: 'keydown' | 'keyup';
+    readonly type: 'chord-cancel';
+} | {
+    readonly step: ShortcutStep;
+    readonly target: EventTarget;
+    readonly trigger: 'keydown' | 'keyup';
+    readonly type: 'chord-start';
+} | {
+    readonly steps: readonly ShortcutStep[];
+    readonly target: EventTarget;
+    readonly trigger: 'keydown' | 'keyup';
+    readonly type: 'chord-progress';
+} | {
+    readonly target: EventTarget;
+    readonly trigger: 'keydown' | 'keyup';
+    readonly type: 'chord-timeout';
+} | {
+    readonly binding: BindingEntry;
+    readonly target: EventTarget;
+    readonly trigger: 'keydown' | 'keyup';
+    readonly type: 'match';
+} | {
+    readonly type: 'dispose';
 };
-export type BindingValue = Handler | BindingOptions;
 /**
- * Chord state change event emitted when chord progression changes.
+ * A single ordered binding.
  *
- * Use `onChordState` callback in `KeymapOptions` to observe chord state
- * for debugging, UI hints, or chord history. When a chord fully matches,
- * the binding handler fires immediately; no separate 'completed' event.
+ * Each binding has an explicit `id` (string) so duplicate shortcuts can coexist
+ * with different ids — `unbind(id)` removes by id, not by shortcut string.
+ *
+ * @example
+ * const map = createKeymap([
+ *   { id: 'save', shortcut: 'mod+s', handler: save },
+ *   { id: 'palette', shortcut: 'mod+shift+p', handler: openPalette },
+ *   { id: 'top', shortcut: 'g g', handler: goToTop },
+ *   { id: 'close', shortcut: 'escape', handler: closePanel, when: (e) => !isEditableTarget(e.target) },
+ *   { id: 'play', shortcut: 'space', handler: togglePlay, trigger: 'keyup' },
+ * ], { modKey: 'ctrl' });
  */
-export type ChordStateChange = {
-    type: 'started';
-    target: EventTarget;
-    step: ShortcutStep;
-    trigger: 'keydown' | 'keyup';
-} | {
-    type: 'progressed';
-    target: EventTarget;
-    steps: readonly ShortcutStep[];
-    trigger: 'keydown' | 'keyup';
-} | {
-    type: 'timeout';
-    target: EventTarget;
-    trigger: 'keydown' | 'keyup';
-};
+export interface Binding {
+    /** Handler invoked when the shortcut matches. */
+    handler: Handler;
+    /** Stable identifier for this binding. Used by `unbind(id)`. */
+    id: string;
+    /** Call `event.preventDefault()` when matched. Defaults to `true`. */
+    preventDefault?: boolean;
+    /** Shortcut string, e.g. `'mod+s'` or `'g g'`. */
+    shortcut: string;
+    /** Call `event.stopPropagation()` when matched. Defaults to `false`. */
+    stopPropagation?: boolean;
+    /** Event phase. Defaults to `'keydown'`. */
+    trigger?: 'keydown' | 'keyup';
+    /** Per-binding guard. Both global and per-binding guards must pass. */
+    when?: When;
+}
 export interface KeymapOptions {
+    /** Milliseconds to wait for the next step of a chord before the partial chord expires. Defaults to 1000. Must be a positive finite number; `createKeymap` throws `KeymapConfigError` otherwise. */
     chordTimeout?: number;
     modKey?: 'ctrl' | 'meta';
-    /**
-     * Optional callback to observe chord state changes.
-     *
-     * Fires when a chord starts, progresses through steps, completes, or times out.
-     * Useful for debugging, logging, testing, or implementing chord UI hints.
-     *
-     * @example
-     * {
-     *   onChordState: (change) => {
-     *     if (change.type === 'started') console.log('Chord started:', change.step.key);
-     *     if (change.type === 'timeout') console.log('Chord timed out');
-     *   }
-     * }
-     */
-    onChordState?: (change: ChordStateChange) => void;
-    preventDefault?: boolean;
-    stopPropagation?: boolean;
     /**
      * Guard function for all bindings in this keymap.
      *
@@ -85,13 +94,25 @@ export interface KeymapOptions {
     when?: When;
 }
 export interface Keymap {
-    bind(shortcut: string, value: BindingValue): () => void;
+    /** Adds a binding (replacing any existing binding with the same id) and returns an unbind closure. */
+    bind(binding: Binding): () => void;
     readonly disposalSignal: AbortSignal;
     dispose(): void;
     readonly disposed: boolean;
     listBindings(): readonly BindingEntry[];
     mount(target: EventTarget): () => void;
-    unbind(shortcut: string): void;
+    tap(handler: (event: KeymapEvent) => void, options?: {
+        signal?: AbortSignal;
+    }): () => void;
+    /** Removes the binding with the given id. Warns in development when unknown. */
+    unbind(id: string): void;
     [Symbol.dispose](): void;
 }
+export type BindingEntry = {
+    readonly id: string;
+    readonly shortcut: readonly ShortcutStep[];
+    readonly trigger: 'keydown' | 'keyup';
+    readonly preventDefault: boolean;
+    readonly stopPropagation: boolean;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAErD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC;AAErD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,cAAc,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,YAAY,IAAI,SAAS,YAAY,EAAE,CAAC;IACxC,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,IAAI,CAAC;IACvC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vielzeug/keymap",
-  "version": "2.2.0",
-  "description": "Headless keyboard shortcut manager with chord sequences, context guards, and disposable bindings",
+  "version": "26.10.0",
+  "description": "Headless keyboard shortcut manager with chord sequences",
   "repository": {
     "type": "git",
     "url": "https://github.com/helmuthdu/vielzeug",
@@ -22,6 +22,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "types": "./dist/index.d.ts"
+    },
+    "./parse": {
+      "import": "./dist/parse.js",
+      "require": "./dist/parse.cjs",
+      "types": "./dist/parse.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "parse": [
+        "dist/parse.d.ts"
+      ]
     }
   },
   "sideEffects": false,
@@ -30,18 +42,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build": "vite build && pnpm --silent run build:bundle && pnpm --silent run build:types",
     "build:bundle": "vite build --config vite.bundle.config.ts",
     "build:types": "tsc -p tsconfig.declarations.json",
     "fix": "biome check --write src",
     "lint": "biome ci src",
-    "prepublishOnly": "pnpm run build",
+    "prepublishOnly": "pnpm --silent run build",
     "test": "vitest"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.6.2",
     "typescript": "^6.0.3",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10"
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
   }
 }