@opentui/keymap 0.2.0 → 0.2.2

package/{index.js → src/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,17 +1305,43 @@ 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;
     const context = this.createCommandResolverContext(includeRecord, focused, options?.mode ?? "active");
@@ -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);
   }

package/src/keymap.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveKey, ActiveKeyOptions, BindingInput, BindingExpander, BindingParser, BindingFieldCompiler, Bindings, BindingTransformer, Events, CommandFieldCompiler, CommandEntry, CommandQuery, CommandRecord, KeymapEvent, KeymapHost, LayerAnalyzer, Listener, RunCommandOptions, RunCommandResult, CommandResolver, KeyInterceptOptions, KeyInputContext, Layer, LayerFieldCompiler, KeyDisambiguationResolver, RawInterceptOptions, RawInputContext, EventMatchResolver, KeyStringifyInput, KeyToken, KeyLike, KeySequencePart } from "./types.js";
+import type { ActiveBinding, ActiveKey, ActiveKeyOptions, BindingExpander, BindingParser, BindingFieldCompiler, LayerBindingsTransformer, BindingTransformer, Events, CommandFieldCompiler, CommandBindingsQuery, CommandEntry, CommandQuery, CommandRecord, KeymapEvent, KeymapHost, LayerAnalyzer, Listener, RunCommandOptions, RunCommandResult, CommandResolver, KeyInterceptOptions, KeyInputContext, Layer, LayerFieldCompiler, KeyDisambiguationResolver, RawInterceptOptions, RawInputContext, EventMatchResolver, KeyStringifyInput, KeyToken, KeyLike, KeySequencePart, StringifyOptions } from "./types.js";
 export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent = KeymapEvent> {
     private readonly host;
     private readonly state;
@@ -28,13 +28,14 @@ export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent =
     hasPendingSequence(): boolean;
     getPendingSequence(): readonly KeySequencePart[];
     createKeyMatcher(key: KeyLike): (input: KeyStringifyInput | null | undefined) => boolean;
+    parseKeySequence(key: KeyLike): readonly KeySequencePart[];
+    formatKey(key: KeyLike, options?: StringifyOptions): string;
     clearPendingSequence(): void;
     popPendingSequence(): boolean;
     getActiveKeys(options?: ActiveKeyOptions): readonly ActiveKey<TTarget, TEvent>[];
     getCommands(query?: CommandQuery<TTarget>): readonly CommandRecord[];
     getCommandEntries(query?: CommandQuery<TTarget>): readonly CommandEntry<TTarget, TEvent>[];
-    normalizeCommandName(name: string): string;
-    normalizeBindings(bindings: Bindings<TTarget, TEvent>): BindingInput<TTarget, TEvent>[];
+    getCommandBindings(query: CommandBindingsQuery<TTarget>): ReadonlyMap<string, readonly ActiveBinding<TTarget, TEvent>[]>;
     acquireResource(key: symbol, setup: () => () => void): () => void;
     runCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
     dispatchCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
@@ -46,6 +47,9 @@ export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent =
     intercept(name: "raw", fn: (ctx: RawInputContext) => void, options?: RawInterceptOptions): () => void;
     registerLayer(layer: Layer<TTarget, TEvent>): () => void;
     registerLayerFields(fields: Record<string, LayerFieldCompiler>): () => void;
+    prependLayerBindingsTransformer(transformer: LayerBindingsTransformer<TTarget, TEvent>): () => void;
+    appendLayerBindingsTransformer(transformer: LayerBindingsTransformer<TTarget, TEvent>): () => void;
+    clearLayerBindingsTransformers(): void;
     prependBindingTransformer(transformer: BindingTransformer<TTarget, TEvent>): () => void;
     appendBindingTransformer(transformer: BindingTransformer<TTarget, TEvent>): () => void;
     clearBindingTransformers(): void;