@opentui/keymap 0.0.0-20260424-2e949539 → 0.0.0-20260429-00ce2fef

package/README.md

@@ -65,8 +65,7 @@ bun install @opentui/keymap
 bun run build
 bun run test
 bun src/keymap-benchmark.ts
-bun run serve:keymap-html
 ```
 
 - `bun src/keymap-benchmark.ts` runs the benchmark suite from `src/keymap-benchmark.ts`.
-- `bun run serve:keymap-html` builds the package and serves the HTML demo locally.
+- The HTML demo now lives in the docs app at `/demos/keymap-html/` under `packages/web`.

package/addons/index.js

@@ -729,6 +729,28 @@ var RESERVED_COMMAND_FIELDS = new Set(["name", "run"]);
 var RESERVED_BINDING_FIELDS = new Set(["key", "cmd", "event", "preventDefault", "fallthrough"]);
 var RESERVED_LAYER_FIELDS = new Set(["target", "targetMode", "priority", "bindings", "commands"]);
 
+// src/services/primitives/command-normalization.ts
+function normalizeBindingCommand(command) {
+  if (command === undefined || typeof command === "function") {
+    return command;
+  }
+  const trimmed = command.trim();
+  if (!trimmed) {
+    throw new Error("Invalid keymap command: command cannot be empty");
+  }
+  return trimmed;
+}
+function normalizeCommandName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error("Invalid keymap command name: name cannot be empty");
+  }
+  if (/\s/.test(trimmed)) {
+    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
+  }
+  return trimmed;
+}
+
 // src/services/primitives/field-invariants.ts
 function mergeRequirement(target, name, value, source) {
   if (Object.prototype.hasOwnProperty.call(target, name) && !Object.is(target[name], value)) {
@@ -806,26 +828,6 @@ function createCommandChainCacheState() {
     fallbackWithRecordErrors: new Set
   };
 }
-function normalizeBindingCommand(command) {
-  if (command === undefined || typeof command === "function") {
-    return command;
-  }
-  const trimmed = command.trim();
-  if (!trimmed) {
-    throw new Error("Invalid keymap command: command cannot be empty");
-  }
-  return trimmed;
-}
-function normalizeCommandName(name) {
-  const trimmed = name.trim();
-  if (!trimmed) {
-    throw new Error("Invalid keymap command name: name cannot be empty");
-  }
-  if (/\s/.test(trimmed)) {
-    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
-  }
-  return trimmed;
-}
 
 class CommandCatalogService {
   state;
@@ -1881,21 +1883,32 @@ function applyBindingEventEffects(binding, event) {
 }
 
 // src/services/primitives/binding-inputs.ts
-function normalizeBindingInputs(bindings) {
-  if (Array.isArray(bindings)) {
-    return bindings;
+function isKeyLike(value) {
+  return typeof value === "string" || !!value && typeof value === "object" && !Array.isArray(value);
+}
+function validateBindingInputs(bindings) {
+  if (!Array.isArray(bindings)) {
+    return { ok: false, reason: "Invalid keymap bindings: expected an array of binding objects" };
   }
-  const normalized = [];
-  for (const [key, cmd] of Object.entries(bindings)) {
-    if (typeof cmd !== "string" && typeof cmd !== "function") {
-      throw new Error(`Invalid keymap binding for "${key}": shorthand bindings must map to string or function commands`);
+  for (const [index, binding] of bindings.entries()) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      return { ok: false, reason: `Invalid keymap binding at index ${index}: expected a binding object` };
+    }
+    if (!isKeyLike(binding.key)) {
+      return {
+        ok: false,
+        reason: `Invalid keymap binding at index ${index}: expected "key" to be a string or keystroke object`
+      };
     }
-    normalized.push({ key, cmd });
   }
-  return normalized;
+  return { ok: true };
 }
 function snapshotBindingInputs(bindings) {
-  return normalizeBindingInputs(bindings).map((binding) => ({
+  const validation = validateBindingInputs(bindings);
+  if (!validation.ok) {
+    throw new Error(validation.reason);
+  }
+  return bindings.map((binding) => ({
     ...binding,
     key: typeof binding.key === "string" ? binding.key : { ...binding.key }
   }));
@@ -3219,6 +3232,15 @@ class EnvironmentService {
   prependBindingTransformer(transformer) {
     return this.state.environment.bindingTransformers.prepend(transformer);
   }
+  prependLayerBindingsTransformer(transformer) {
+    return this.state.environment.layerBindingsTransformers.prepend(transformer);
+  }
+  appendLayerBindingsTransformer(transformer) {
+    return this.state.environment.layerBindingsTransformers.append(transformer);
+  }
+  clearLayerBindingsTransformers() {
+    this.state.environment.layerBindingsTransformers.clear();
+  }
   appendBindingTransformer(transformer) {
     return this.state.environment.bindingTransformers.append(transformer);
   }
@@ -3417,7 +3439,7 @@ class LayerService {
       let targetMode;
       try {
         targetMode = this.normalizeTargetMode(layer);
-        bindingInputs = snapshotBindingInputs(layer.bindings ?? []);
+        bindingInputs = this.applyLayerBindingsTransformers(snapshotBindingInputs(layer.bindings ?? []), layer);
         commands = !layer.commands || layer.commands.length === 0 ? [] : this.options.commands.normalizeCommands(layer.commands);
         commandLookup = createCommandLookup(commands);
         ({ requires, matchers, conditionKeys, hasUnkeyedMatchers, compileFields } = this.compileLayerRuntimeState(layer));
@@ -3570,6 +3592,24 @@ class LayerService {
     }
     return layer.target ? "focus-within" : undefined;
   }
+  applyLayerBindingsTransformers(bindings, layer) {
+    const transformers = this.state.environment.layerBindingsTransformers.values();
+    if (transformers.length === 0) {
+      return bindings;
+    }
+    let current = bindings;
+    for (const transformer of transformers) {
+      const next = transformer(current, {
+        layer,
+        validateBindings: (bindings2) => validateBindingInputs(bindings2)
+      });
+      if (!next) {
+        continue;
+      }
+      current = snapshotBindingInputs(next);
+    }
+    return current;
+  }
   runLayerAnalyzers(options) {
     const analyzers = this.state.layers.layerAnalyzers.values();
     if (analyzers.length === 0) {
@@ -4043,6 +4083,7 @@ function createKeymapState() {
     environment: {
       tokens: new Map,
       layerFields: new Map,
+      layerBindingsTransformers: new OrderedRegistry,
       bindingExpanders: new OrderedRegistry,
       bindingParsers: new OrderedRegistry,
       bindingTransformers: new OrderedRegistry,
@@ -4254,12 +4295,6 @@ class Keymap {
   getCommandEntries(query) {
     return this.catalog.getCommandEntries(query);
   }
-  normalizeCommandName(name) {
-    return normalizeCommandName(name);
-  }
-  normalizeBindings(bindings) {
-    return normalizeBindingInputs(bindings);
-  }
   acquireResource(key, setup) {
     if (this.cleanedUp || this.host.isDestroyed) {
       throw new Error("Cannot use a keymap after its host was destroyed");
@@ -4305,6 +4340,15 @@ class Keymap {
   registerLayerFields(fields) {
     return this.environment.registerLayerFields(fields);
   }
+  prependLayerBindingsTransformer(transformer) {
+    return this.environment.prependLayerBindingsTransformer(transformer);
+  }
+  appendLayerBindingsTransformer(transformer) {
+    return this.environment.appendLayerBindingsTransformer(transformer);
+  }
+  clearLayerBindingsTransformers() {
+    this.environment.clearLayerBindingsTransformers();
+  }
   prependBindingTransformer(transformer) {
     return this.environment.prependBindingTransformer(transformer);
   }
@@ -4695,6 +4739,48 @@ function registerDefaultKeys(keymap) {
     offParser();
   };
 }
+// src/addons/universal/binding-overrides.ts
+function normalizeBindingOverrides(value) {
+  if (!Array.isArray(value)) {
+    throw new Error('Keymap layer field "bindingOverrides" must be an array of binding objects');
+  }
+  return value;
+}
+function getBindingOverrides(layer) {
+  const overrides = layer.bindingOverrides;
+  if (!overrides || !Array.isArray(overrides)) {
+    return;
+  }
+  return normalizeBindingOverrides(overrides);
+}
+function registerBindingOverrides(keymap) {
+  const offLayerField = keymap.registerLayerFields({
+    bindingOverrides(value) {
+      normalizeBindingOverrides(value);
+    }
+  });
+  const offTransformer = keymap.appendLayerBindingsTransformer((bindings, ctx) => {
+    const overrides = getBindingOverrides(ctx.layer);
+    if (!overrides) {
+      return;
+    }
+    const validation = ctx.validateBindings(overrides);
+    if (!validation.ok) {
+      throw new Error(validation.reason);
+    }
+    const overrideCommands = new Set(overrides.flatMap((binding) => typeof binding.cmd === "string" ? [binding.cmd.trim()] : []));
+    return [
+      ...overrides,
+      ...bindings.filter((binding) => {
+        return typeof binding.cmd !== "string" || !overrideCommands.has(binding.cmd.trim());
+      })
+    ];
+  });
+  return () => {
+    offTransformer();
+    offLayerField();
+  };
+}
 // src/addons/universal/aliases.ts
 function normalizeAliases(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4964,8 +5050,14 @@ function registerEmacsBindings(keymap) {
 }
 // src/addons/universal/ex-commands.ts
 var EMPTY_FIELDS = Object.freeze({});
-function normalizeExCommandName(keymap, name) {
-  const normalized = keymap.normalizeCommandName(name);
+function normalizeExCommandName(_keymap, name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("Invalid keymap command name: name cannot be empty");
+  }
+  if (/\s/.test(normalized)) {
+    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
+  }
   if (normalized.startsWith(":")) {
     return normalized;
   }
@@ -5233,6 +5325,7 @@ export {
   registerDefaultBindingParser,
   registerDeadBindingWarnings,
   registerCommaBindings,
+  registerBindingOverrides,
   registerBackspacePopsPendingSequence,
   registerAliasesField,
   defaultEventMatchResolver,

package/addons/opentui/index.js

@@ -729,6 +729,28 @@ var RESERVED_COMMAND_FIELDS = new Set(["name", "run"]);
 var RESERVED_BINDING_FIELDS = new Set(["key", "cmd", "event", "preventDefault", "fallthrough"]);
 var RESERVED_LAYER_FIELDS = new Set(["target", "targetMode", "priority", "bindings", "commands"]);
 
+// src/services/primitives/command-normalization.ts
+function normalizeBindingCommand(command) {
+  if (command === undefined || typeof command === "function") {
+    return command;
+  }
+  const trimmed = command.trim();
+  if (!trimmed) {
+    throw new Error("Invalid keymap command: command cannot be empty");
+  }
+  return trimmed;
+}
+function normalizeCommandName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error("Invalid keymap command name: name cannot be empty");
+  }
+  if (/\s/.test(trimmed)) {
+    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
+  }
+  return trimmed;
+}
+
 // src/services/primitives/field-invariants.ts
 function mergeRequirement(target, name, value, source) {
   if (Object.prototype.hasOwnProperty.call(target, name) && !Object.is(target[name], value)) {
@@ -806,26 +828,6 @@ function createCommandChainCacheState() {
     fallbackWithRecordErrors: new Set
   };
 }
-function normalizeBindingCommand(command) {
-  if (command === undefined || typeof command === "function") {
-    return command;
-  }
-  const trimmed = command.trim();
-  if (!trimmed) {
-    throw new Error("Invalid keymap command: command cannot be empty");
-  }
-  return trimmed;
-}
-function normalizeCommandName(name) {
-  const trimmed = name.trim();
-  if (!trimmed) {
-    throw new Error("Invalid keymap command name: name cannot be empty");
-  }
-  if (/\s/.test(trimmed)) {
-    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
-  }
-  return trimmed;
-}
 
 class CommandCatalogService {
   state;
@@ -1881,21 +1883,32 @@ function applyBindingEventEffects(binding, event) {
 }
 
 // src/services/primitives/binding-inputs.ts
-function normalizeBindingInputs(bindings) {
-  if (Array.isArray(bindings)) {
-    return bindings;
+function isKeyLike(value) {
+  return typeof value === "string" || !!value && typeof value === "object" && !Array.isArray(value);
+}
+function validateBindingInputs(bindings) {
+  if (!Array.isArray(bindings)) {
+    return { ok: false, reason: "Invalid keymap bindings: expected an array of binding objects" };
   }
-  const normalized = [];
-  for (const [key, cmd] of Object.entries(bindings)) {
-    if (typeof cmd !== "string" && typeof cmd !== "function") {
-      throw new Error(`Invalid keymap binding for "${key}": shorthand bindings must map to string or function commands`);
+  for (const [index, binding] of bindings.entries()) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      return { ok: false, reason: `Invalid keymap binding at index ${index}: expected a binding object` };
+    }
+    if (!isKeyLike(binding.key)) {
+      return {
+        ok: false,
+        reason: `Invalid keymap binding at index ${index}: expected "key" to be a string or keystroke object`
+      };
     }
-    normalized.push({ key, cmd });
   }
-  return normalized;
+  return { ok: true };
 }
 function snapshotBindingInputs(bindings) {
-  return normalizeBindingInputs(bindings).map((binding) => ({
+  const validation = validateBindingInputs(bindings);
+  if (!validation.ok) {
+    throw new Error(validation.reason);
+  }
+  return bindings.map((binding) => ({
     ...binding,
     key: typeof binding.key === "string" ? binding.key : { ...binding.key }
   }));
@@ -3219,6 +3232,15 @@ class EnvironmentService {
   prependBindingTransformer(transformer) {
     return this.state.environment.bindingTransformers.prepend(transformer);
   }
+  prependLayerBindingsTransformer(transformer) {
+    return this.state.environment.layerBindingsTransformers.prepend(transformer);
+  }
+  appendLayerBindingsTransformer(transformer) {
+    return this.state.environment.layerBindingsTransformers.append(transformer);
+  }
+  clearLayerBindingsTransformers() {
+    this.state.environment.layerBindingsTransformers.clear();
+  }
   appendBindingTransformer(transformer) {
     return this.state.environment.bindingTransformers.append(transformer);
   }
@@ -3417,7 +3439,7 @@ class LayerService {
       let targetMode;
       try {
         targetMode = this.normalizeTargetMode(layer);
-        bindingInputs = snapshotBindingInputs(layer.bindings ?? []);
+        bindingInputs = this.applyLayerBindingsTransformers(snapshotBindingInputs(layer.bindings ?? []), layer);
         commands = !layer.commands || layer.commands.length === 0 ? [] : this.options.commands.normalizeCommands(layer.commands);
         commandLookup = createCommandLookup(commands);
         ({ requires, matchers, conditionKeys, hasUnkeyedMatchers, compileFields } = this.compileLayerRuntimeState(layer));
@@ -3570,6 +3592,24 @@ class LayerService {
     }
     return layer.target ? "focus-within" : undefined;
   }
+  applyLayerBindingsTransformers(bindings, layer) {
+    const transformers = this.state.environment.layerBindingsTransformers.values();
+    if (transformers.length === 0) {
+      return bindings;
+    }
+    let current = bindings;
+    for (const transformer of transformers) {
+      const next = transformer(current, {
+        layer,
+        validateBindings: (bindings2) => validateBindingInputs(bindings2)
+      });
+      if (!next) {
+        continue;
+      }
+      current = snapshotBindingInputs(next);
+    }
+    return current;
+  }
   runLayerAnalyzers(options) {
     const analyzers = this.state.layers.layerAnalyzers.values();
     if (analyzers.length === 0) {
@@ -4043,6 +4083,7 @@ function createKeymapState() {
     environment: {
       tokens: new Map,
       layerFields: new Map,
+      layerBindingsTransformers: new OrderedRegistry,
       bindingExpanders: new OrderedRegistry,
       bindingParsers: new OrderedRegistry,
       bindingTransformers: new OrderedRegistry,
@@ -4254,12 +4295,6 @@ class Keymap {
   getCommandEntries(query) {
     return this.catalog.getCommandEntries(query);
   }
-  normalizeCommandName(name) {
-    return normalizeCommandName(name);
-  }
-  normalizeBindings(bindings) {
-    return normalizeBindingInputs(bindings);
-  }
   acquireResource(key, setup) {
     if (this.cleanedUp || this.host.isDestroyed) {
       throw new Error("Cannot use a keymap after its host was destroyed");
@@ -4305,6 +4340,15 @@ class Keymap {
   registerLayerFields(fields) {
     return this.environment.registerLayerFields(fields);
   }
+  prependLayerBindingsTransformer(transformer) {
+    return this.environment.prependLayerBindingsTransformer(transformer);
+  }
+  appendLayerBindingsTransformer(transformer) {
+    return this.environment.appendLayerBindingsTransformer(transformer);
+  }
+  clearLayerBindingsTransformers() {
+    this.environment.clearLayerBindingsTransformers();
+  }
   prependBindingTransformer(transformer) {
     return this.environment.prependBindingTransformer(transformer);
   }
@@ -4695,6 +4739,48 @@ function registerDefaultKeys(keymap) {
     offParser();
   };
 }
+// src/addons/universal/binding-overrides.ts
+function normalizeBindingOverrides(value) {
+  if (!Array.isArray(value)) {
+    throw new Error('Keymap layer field "bindingOverrides" must be an array of binding objects');
+  }
+  return value;
+}
+function getBindingOverrides(layer) {
+  const overrides = layer.bindingOverrides;
+  if (!overrides || !Array.isArray(overrides)) {
+    return;
+  }
+  return normalizeBindingOverrides(overrides);
+}
+function registerBindingOverrides(keymap) {
+  const offLayerField = keymap.registerLayerFields({
+    bindingOverrides(value) {
+      normalizeBindingOverrides(value);
+    }
+  });
+  const offTransformer = keymap.appendLayerBindingsTransformer((bindings, ctx) => {
+    const overrides = getBindingOverrides(ctx.layer);
+    if (!overrides) {
+      return;
+    }
+    const validation = ctx.validateBindings(overrides);
+    if (!validation.ok) {
+      throw new Error(validation.reason);
+    }
+    const overrideCommands = new Set(overrides.flatMap((binding) => typeof binding.cmd === "string" ? [binding.cmd.trim()] : []));
+    return [
+      ...overrides,
+      ...bindings.filter((binding) => {
+        return typeof binding.cmd !== "string" || !overrideCommands.has(binding.cmd.trim());
+      })
+    ];
+  });
+  return () => {
+    offTransformer();
+    offLayerField();
+  };
+}
 // src/addons/universal/aliases.ts
 function normalizeAliases(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4964,8 +5050,14 @@ function registerEmacsBindings(keymap) {
 }
 // src/addons/universal/ex-commands.ts
 var EMPTY_FIELDS = Object.freeze({});
-function normalizeExCommandName(keymap, name) {
-  const normalized = keymap.normalizeCommandName(name);
+function normalizeExCommandName(_keymap, name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("Invalid keymap command name: name cannot be empty");
+  }
+  if (/\s/.test(normalized)) {
+    throw new Error(`Invalid keymap command name "${name}": command names cannot contain whitespace`);
+  }
   if (normalized.startsWith(":")) {
     return normalized;
   }
@@ -5310,42 +5402,42 @@ var editBufferActions = [
   "submit"
 ];
 var editBufferCommandNames = {
-  "move-left": "move-left",
-  "move-right": "move-right",
-  "move-up": "move-up",
-  "move-down": "move-down",
-  "select-left": "select-left",
-  "select-right": "select-right",
-  "select-up": "select-up",
-  "select-down": "select-down",
-  "line-home": "line-home",
-  "line-end": "line-end",
-  "select-line-home": "select-line-home",
-  "select-line-end": "select-line-end",
-  "visual-line-home": "visual-line-home",
-  "visual-line-end": "visual-line-end",
-  "select-visual-line-home": "select-visual-line-home",
-  "select-visual-line-end": "select-visual-line-end",
-  "buffer-home": "buffer-home",
-  "buffer-end": "buffer-end",
-  "select-buffer-home": "select-buffer-home",
-  "select-buffer-end": "select-buffer-end",
-  "delete-line": "delete-line",
-  "delete-to-line-end": "delete-to-line-end",
-  "delete-to-line-start": "delete-to-line-start",
-  backspace: "backspace",
-  delete: "delete",
-  newline: "newline",
-  undo: "undo",
-  redo: "redo",
-  "word-forward": "word-forward",
-  "word-backward": "word-backward",
-  "select-word-forward": "select-word-forward",
-  "select-word-backward": "select-word-backward",
-  "delete-word-forward": "delete-word-forward",
-  "delete-word-backward": "delete-word-backward",
-  "select-all": "select-all",
-  submit: "submit"
+  "move-left": "input.move.left",
+  "move-right": "input.move.right",
+  "move-up": "input.move.up",
+  "move-down": "input.move.down",
+  "select-left": "input.select.left",
+  "select-right": "input.select.right",
+  "select-up": "input.select.up",
+  "select-down": "input.select.down",
+  "line-home": "input.line.home",
+  "line-end": "input.line.end",
+  "select-line-home": "input.select.line.home",
+  "select-line-end": "input.select.line.end",
+  "visual-line-home": "input.visual.line.home",
+  "visual-line-end": "input.visual.line.end",
+  "select-visual-line-home": "input.select.visual.line.home",
+  "select-visual-line-end": "input.select.visual.line.end",
+  "buffer-home": "input.buffer.home",
+  "buffer-end": "input.buffer.end",
+  "select-buffer-home": "input.select.buffer.home",
+  "select-buffer-end": "input.select.buffer.end",
+  "delete-line": "input.delete.line",
+  "delete-to-line-end": "input.delete.to.line.end",
+  "delete-to-line-start": "input.delete.to.line.start",
+  backspace: "input.backspace",
+  delete: "input.delete",
+  newline: "input.newline",
+  undo: "input.undo",
+  redo: "input.redo",
+  "word-forward": "input.word.forward",
+  "word-backward": "input.word.backward",
+  "select-word-forward": "input.select.word.forward",
+  "select-word-backward": "input.select.word.backward",
+  "delete-word-forward": "input.delete.word.forward",
+  "delete-word-backward": "input.delete.word.backward",
+  "select-all": "input.select.all",
+  submit: "input.submit"
 };
 var editBufferCommandDescriptions = {
   "move-left": "Cursor left",
@@ -5592,7 +5684,7 @@ function registerManagedTextareaLayer(keymap, renderer, layer, options) {
     const { bindings, target: _ignoredTarget, targetMode: _ignoredTargetMode, ...rest } = layer;
     const offLayer = keymap.registerLayer({
       ...rest,
-      bindings: createTextareaBindingsWithResolvedOptions(bindings ? keymap.normalizeBindings(bindings) : undefined, commandNames, descriptions)
+      bindings: createTextareaBindingsWithResolvedOptions(bindings, commandNames, descriptions)
     });
     return () => {
       offLayer();
@@ -5623,6 +5715,7 @@ export {
   registerDefaultBindingParser,
   registerDeadBindingWarnings,
   registerCommaBindings,
+  registerBindingOverrides,
   registerBaseLayoutFallback,
   registerBackspacePopsPendingSequence,
   registerAliasesField,