@opentui/keymap 0.2.0 → 0.2.2

package/README.md

@@ -43,6 +43,16 @@ They do not compile into public attrs.
 Binding and command fields can compile metadata into attrs that later appear on
 active bindings, active keys, and command query results.
 
+## Formatting Keys
+
+Use `keymap.formatKey` when formatting raw binding config. It parses string
+bindings through the keymap's registered parsers and tokens before stringifying.
+
+```ts
+keymap.formatKey("<leader>s", { separator: " " }) // "space s"
+keymap.formatKey("<leader>s", { preferDisplay: true }) // "<leader>s"
+```
+
 ## Re-entry
 
 Runtime/data-style re-entry is supported during dispatch. For example, command

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@opentui/keymap",
-  "module": "index.js",
-  "main": "index.js",
+  "module": "src/index.js",
+  "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Standalone keymap package for OpenTUI",
   "license": "MIT",
   "repository": {
@@ -15,42 +15,52 @@
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
-      "import": "./index.js",
-      "require": "./index.js"
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    },
+    "./extras": {
+      "types": "./src/extras/index.d.ts",
+      "import": "./src/extras/index.js",
+      "require": "./src/extras/index.js"
     },
     "./addons": {
       "types": "./src/addons/index.d.ts",
-      "import": "./addons/index.js",
-      "require": "./addons/index.js"
+      "import": "./src/addons/index.js",
+      "require": "./src/addons/index.js"
     },
     "./addons/opentui": {
       "types": "./src/addons/opentui/index.d.ts",
-      "import": "./addons/opentui/index.js",
-      "require": "./addons/opentui/index.js"
+      "import": "./src/addons/opentui/index.js",
+      "require": "./src/addons/opentui/index.js"
     },
     "./html": {
       "types": "./src/html.d.ts",
-      "import": "./html.js",
-      "require": "./html.js"
+      "import": "./src/html.js",
+      "require": "./src/html.js"
     },
     "./opentui": {
       "types": "./src/opentui.d.ts",
-      "import": "./opentui.js",
-      "require": "./opentui.js"
+      "import": "./src/opentui.js",
+      "require": "./src/opentui.js"
     },
     "./react": {
       "types": "./src/react/index.d.ts",
-      "import": "./react/index.js",
-      "require": "./react/index.js"
+      "import": "./src/react/index.js",
+      "require": "./src/react/index.js"
     },
     "./solid": {
       "types": "./src/solid/index.d.ts",
-      "import": "./solid/index.js",
-      "require": "./solid/index.js"
+      "import": "./src/solid/index.js",
+      "require": "./src/solid/index.js"
+    },
+    "./runtime-modules": {
+      "types": "./src/runtime-modules.d.ts",
+      "import": "./src/runtime-modules.js",
+      "require": "./src/runtime-modules.js"
     }
   },
   "dependencies": {
-    "@opentui/core": "0.2.0"
+    "@opentui/core": "0.2.2"
   },
   "devDependencies": {
     "@opentui/react": "workspace:*",
@@ -63,8 +73,8 @@
     "typescript": "^5"
   },
   "peerDependencies": {
-    "@opentui/react": "0.2.0",
-    "@opentui/solid": "0.2.0",
+    "@opentui/react": "0.2.2",
+    "@opentui/solid": "0.2.2",
     "react": ">=19.0.0",
     "solid-js": "1.9.12"
   },

package/{addons → src/addons}/index.js

@@ -144,7 +144,7 @@ function stringifyKeyStroke(input, options) {
   return stringifyCanonicalStroke(normalizeKeyStroke(input));
 }
 function stringifyKeySequence(input, options) {
-  return input.map((part) => stringifyKeyStroke(part, options)).join("");
+  return input.map((part) => stringifyKeyStroke(part, options)).join(options?.separator ?? "");
 }
 function stringifyCanonicalStroke(stroke) {
   const parts = [];
@@ -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;
@@ -898,6 +900,19 @@ class CommandCatalogService {
       bindings: item.bindings
     }));
   }
+  getCommandBindings(query) {
+    const bindingsByCommand = new Map;
+    for (const command of query.commands) {
+      if (!bindingsByCommand.has(command)) {
+        bindingsByCommand.set(command, []);
+      }
+    }
+    if (bindingsByCommand.size === 0) {
+      return bindingsByCommand;
+    }
+    this.collectCommandBindings(bindingsByCommand, this.getCommandQueryContext(query));
+    return bindingsByCommand;
+  }
   getResolvedCommandChain(command, focused, includeRecord) {
     const view = this.getActiveCommandView(focused);
     const entries = this.getResolvedCommandChainFromView(view, command, focused, includeRecord, "active", view.chainsByName.get(command));
@@ -926,14 +941,26 @@ class CommandCatalogService {
     cache.set(command, resolved);
     return resolved;
   }
-  getRegisteredResolverFallback(command, includeRecord) {
-    const view = this.getRegisteredCommandView();
-    const fallback = this.getFallbackResolvedCommand(view, command, null, includeRecord, "registered");
-    const hadError = (includeRecord ? view.fallbackWithRecordErrors : view.fallbackWithoutRecordErrors).has(command);
-    return {
-      resolved: fallback?.resolved,
-      hadError
-    };
+  getActiveRegisteredResolvedEntries(command, focused, includeRecord) {
+    const view = this.getActiveCommandView(focused);
+    const chain = view.chainsByName.get(command);
+    if (!chain || chain.length === 0) {
+      return;
+    }
+    const resolved = [];
+    for (const entry of chain) {
+      resolved.push({
+        target: entry.layer.target,
+        resolved: resolveRegisteredCommand(entry.command, { includeRecord })
+      });
+    }
+    return resolved;
+  }
+  resolveRegisteredResolverFallback(command, includeRecord) {
+    return this.resolveCommandWithResolvers(command, null, { includeRecord, mode: "registered" });
+  }
+  resolveActiveResolverFallback(command, focused, includeRecord) {
+    return this.resolveCommandWithResolvers(command, focused, { includeRecord, mode: "active" });
   }
   getCommandAttrs(command, focused) {
     const top = this.getTopResolvedCommand(command, focused, false);
@@ -1240,6 +1267,31 @@ class CommandCatalogService {
       }
     }
   }
+  collectCommandBindings(bindingsByCommand, context) {
+    if (context.visibility === "registered") {
+      for (const layer of this.state.layers.layers) {
+        for (const binding of layer.compiledBindings) {
+          this.collectBindingForCommandBindings(bindingsByCommand, binding, context);
+        }
+      }
+      return;
+    }
+    const activeView = context.activeView;
+    if (!activeView) {
+      return;
+    }
+    for (const layer of getActiveLayersForFocused(this.state.layers, this.host, context.focused)) {
+      if (layer.compiledBindings.length === 0 || !this.conditions.layerMatchesRuntimeState(layer)) {
+        continue;
+      }
+      for (const binding of layer.compiledBindings) {
+        if (!this.conditions.matchesConditions(binding) || !this.isBindingVisible(binding, context.focused, activeView)) {
+          continue;
+        }
+        this.collectBindingForCommandBindings(bindingsByCommand, binding, context);
+      }
+    }
+  }
   collectBindingForCommandEntries(grouped, indexesByName, binding) {
     if (typeof binding.command !== "string") {
       return;
@@ -1253,16 +1305,42 @@ class CommandCatalogService {
       if (!item) {
         continue;
       }
-      item.bindings.push({
-        sequence: binding.sequence,
-        command: binding.command,
-        commandAttrs: item.command.attrs,
-        attrs: binding.attrs,
-        event: binding.event,
-        preventDefault: binding.preventDefault,
-        fallthrough: binding.fallthrough
-      });
+      item.bindings.push(this.createActiveBinding(binding, item.command.attrs));
+    }
+  }
+  collectBindingForCommandBindings(bindingsByCommand, binding, context) {
+    if (typeof binding.command !== "string") {
+      return;
+    }
+    const bindings = bindingsByCommand.get(binding.command);
+    if (!bindings) {
+      return;
+    }
+    bindings.push(this.createActiveBinding(binding, this.getCommandBindingAttrs(binding, context)));
+  }
+  createActiveBinding(binding, commandAttrs) {
+    return {
+      sequence: binding.sequence,
+      command: binding.command,
+      commandAttrs,
+      attrs: binding.attrs,
+      event: binding.event,
+      preventDefault: binding.preventDefault,
+      fallthrough: binding.fallthrough
+    };
+  }
+  getCommandBindingAttrs(binding, context) {
+    if (typeof binding.command !== "string") {
+      return;
+    }
+    if (context.visibility === "registered") {
+      return this.getTopRegisteredCommand(binding.command)?.command.attrs;
     }
+    const activeView = context.activeView;
+    if (!activeView) {
+      return;
+    }
+    return this.getBindingCommandAttrs(binding, context.focused, activeView);
   }
   resolveCommandWithResolvers(command, focused, options) {
     const includeRecord = options?.includeRecord === true;
@@ -1457,12 +1535,53 @@ function queryLayerCommandEntries(options) {
   const filter = options.query?.filter;
   let filterEntries;
   let filterPredicate;
+  let exactNameFilter;
   if (typeof filter === "function") {
     filterPredicate = filter;
   } else if (filter) {
-    filterEntries = Object.entries(filter);
+    const entries = Object.entries(filter);
+    const remainingEntries = [];
+    for (const [key, matcher] of entries) {
+      if (key === "name") {
+        if (typeof matcher === "string") {
+          exactNameFilter = new Set([matcher]);
+          continue;
+        }
+        if (Array.isArray(matcher)) {
+          const names = new Set;
+          for (const value of matcher) {
+            if (typeof value === "string") {
+              names.add(value);
+            }
+          }
+          exactNameFilter = names;
+          continue;
+        }
+      }
+      remainingEntries.push([key, matcher]);
+    }
+    filterEntries = remainingEntries.length > 0 ? remainingEntries : undefined;
   }
   const results = [];
+  if (exactNameFilter) {
+    for (const entry of options.entries) {
+      const command = entry.command;
+      if (!commandMatchesNamespace(command, namespace)) {
+        continue;
+      }
+      if (!commandMatchesSearch(command, normalizedSearch, searchKeys)) {
+        continue;
+      }
+      if (!exactNameFilter.has(command.name)) {
+        continue;
+      }
+      if (!commandMatchesFilters(command, filterEntries, options)) {
+        continue;
+      }
+      results.push(entry);
+    }
+    return results;
+  }
   for (const entry of options.entries) {
     const command = entry.command;
     if (!commandMatchesNamespace(command, namespace)) {
@@ -1702,7 +1821,7 @@ class CommandExecutorService {
         rejectedResult = execution.result;
       }
     }
-    const fallback = this.catalog.getRegisteredResolverFallback(normalized, includeRecord);
+    const fallback = this.catalog.resolveRegisteredResolverFallback(normalized, includeRecord);
     if (fallback.resolved) {
       const execution = this.executeResolvedCommand(normalized, fallback.resolved, {
         keymap: this.options.keymap,
@@ -1735,8 +1854,7 @@ class CommandExecutorService {
     const focused = options?.focused ?? this.activation.getFocusedTargetIfAvailable();
     const event = options?.event ?? this.options.createCommandEvent();
     const data = this.runtime.getReadonlyData();
-    const chainLookup = this.catalog.getResolvedCommandChain(normalized, focused, includeRecord);
-    const chain = chainLookup.entries;
+    const chain = this.catalog.getActiveRegisteredResolvedEntries(normalized, focused, includeRecord);
     let rejectedResult;
     if (chain?.length === 1) {
       const [entry] = chain;
@@ -1769,7 +1887,21 @@ class CommandExecutorService {
         rejectedResult = execution.result;
       }
     }
-    if (chainLookup.hadError) {
+    const fallback = this.catalog.resolveActiveResolverFallback(normalized, focused, includeRecord);
+    if (fallback.resolved) {
+      const execution = this.executeResolvedCommand(normalized, fallback.resolved, {
+        keymap: this.options.keymap,
+        event,
+        focused,
+        target: options?.target ?? null,
+        data
+      });
+      if (execution.status === "handled" || execution.status === "error") {
+        return execution.result;
+      }
+      rejectedResult = execution.result;
+    }
+    if (fallback.hadError) {
       return { ok: false, reason: "error" };
     }
     const unavailable = this.catalog.getDispatchUnavailableCommandState(normalized, focused, includeRecord);
@@ -1881,21 +2013,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 }
   }));
@@ -1948,6 +2091,23 @@ class CompilerService {
       parseObjectKey: (value, options) => this.parseObjectKeyPart(value, options)
     });
   }
+  parseKeySequence(key) {
+    if (typeof key !== "string") {
+      return [this.parseObjectKeyPart(key)];
+    }
+    const parsed = parseBindingSequenceWithParsers(key, this.state.environment.bindingParsers.values(), {
+      tokens: this.state.environment.tokens,
+      layer: EMPTY_COMPILE_FIELDS,
+      parseObjectKey: (value, options) => this.parseObjectKeyPart(value, options)
+    });
+    for (const tokenName of parsed.unknownTokens) {
+      this.options.warnUnknownToken(tokenName, key);
+    }
+    return parsed.parts;
+  }
+  formatKey(key, options) {
+    return stringifyKeySequence(this.parseKeySequence(key), options);
+  }
   compileBindings(bindings, tokens, sourceTarget, sourceLayerOrder, compileFields) {
     const root = createSequenceNode(null, null, null);
     const compiledBindings = [];
@@ -3219,6 +3379,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 +3586,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 +3739,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 +4230,7 @@ function createKeymapState() {
     environment: {
       tokens: new Map,
       layerFields: new Map,
+      layerBindingsTransformers: new OrderedRegistry,
       bindingExpanders: new OrderedRegistry,
       bindingParsers: new OrderedRegistry,
       bindingTransformers: new OrderedRegistry,
@@ -4239,6 +4427,12 @@ class Keymap {
       return getKeyMatchKey(input) === match;
     };
   }
+  parseKeySequence(key) {
+    return this.compiler.parseKeySequence(key);
+  }
+  formatKey(key, options) {
+    return this.compiler.formatKey(key, options);
+  }
   clearPendingSequence() {
     this.activation.setPendingSequence(null);
   }
@@ -4254,11 +4448,8 @@ class Keymap {
   getCommandEntries(query) {
     return this.catalog.getCommandEntries(query);
   }
-  normalizeCommandName(name) {
-    return normalizeCommandName(name);
-  }
-  normalizeBindings(bindings) {
-    return normalizeBindingInputs(bindings);
+  getCommandBindings(query) {
+    return this.catalog.getCommandBindings(query);
   }
   acquireResource(key, setup) {
     if (this.cleanedUp || this.host.isDestroyed) {
@@ -4305,6 +4496,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 +4895,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 +5206,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 +5481,7 @@ export {
   registerDefaultBindingParser,
   registerDeadBindingWarnings,
   registerCommaBindings,
+  registerBindingOverrides,
   registerBackspacePopsPendingSequence,
   registerAliasesField,
   defaultEventMatchResolver,