@opentui/keymap 0.2.0 → 0.2.2

package/src/extras/formatting.d.ts

@@ -0,0 +1,24 @@
+import type { KeySequencePart } from "../types.js";
+export type KeyModifierName = "ctrl" | "shift" | "meta" | "super" | "hyper";
+export interface KeySequenceFormatPart {
+    stroke: KeySequencePart["stroke"];
+    display: string;
+    match?: KeySequencePart["match"];
+    tokenName?: string;
+}
+export type TokenDisplayResolver = Readonly<Record<string, string>> | ((tokenName: string, part: KeySequenceFormatPart) => string | undefined);
+export interface FormatKeySequenceOptions {
+    tokenDisplay?: TokenDisplayResolver;
+    keyNameAliases?: Readonly<Record<string, string>>;
+    modifierAliases?: Partial<Record<KeyModifierName, string>>;
+    separator?: string;
+}
+export interface FormatCommandBindingsOptions extends FormatKeySequenceOptions {
+    bindingSeparator?: string;
+    dedupe?: boolean;
+}
+export interface SequenceBindingLike {
+    sequence: readonly KeySequenceFormatPart[];
+}
+export declare function formatKeySequence(parts: readonly KeySequenceFormatPart[] | undefined, options?: FormatKeySequenceOptions): string;
+export declare function formatCommandBindings(bindings: readonly SequenceBindingLike[] | undefined, options?: FormatCommandBindingsOptions): string | undefined;

package/src/extras/index.d.ts

@@ -0,0 +1,6 @@
+export { resolveBindingSections } from "./binding-sections.js";
+export { commandBindings } from "./command-bindings.js";
+export { formatCommandBindings, formatKeySequence } from "./formatting.js";
+export type { BindingSectionConfig, BindingSectionItem, BindingSectionsConfig, BindingValue, ResolveBindingSectionsOptions, ResolvedBindingSections, } from "./binding-sections.js";
+export type { FormatCommandBindingsOptions, FormatKeySequenceOptions, KeySequenceFormatPart, KeyModifierName, SequenceBindingLike, TokenDisplayResolver, } from "./formatting.js";
+export type { CommandBindingMap, CommandBindingsOptions, CommandBindingsOverrideWarning, CommandBindingsError, } from "./command-bindings.js";

package/src/extras/index.js

@@ -0,0 +1,226 @@
+// @bun
+// src/extras/binding-sections.ts
+var hasOwn = Object.prototype.hasOwnProperty;
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isKeyLike(value) {
+  return typeof value === "string" || isObject(value);
+}
+function cloneKeyLike(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  return { ...key };
+}
+function invalidBindingValue(section, command, index) {
+  const location = index === undefined ? `"${section}.${command}"` : `"${section}.${command}" at index ${index}`;
+  return new Error(`Invalid binding value for ${location}: expected false, a key, a binding object, or an array of keys/binding objects`);
+}
+function resolveBindingItem(section, command, item, index) {
+  if (!isKeyLike(item)) {
+    throw invalidBindingValue(section, command, index);
+  }
+  if (typeof item === "string" || !("key" in item)) {
+    return {
+      key: cloneKeyLike(item),
+      cmd: command
+    };
+  }
+  const key = item.key;
+  if (!isKeyLike(key)) {
+    throw invalidBindingValue(section, command, index);
+  }
+  return {
+    ...item,
+    key: cloneKeyLike(key),
+    cmd: command
+  };
+}
+function resolveBindingValue(section, command, value) {
+  if (value === false || value === "none") {
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return;
+    }
+    const items = value;
+    const bindings = new Array(items.length);
+    for (let index = 0;index < items.length; index += 1) {
+      bindings[index] = resolveBindingItem(section, command, items[index], index);
+    }
+    return bindings;
+  }
+  return [resolveBindingItem(section, command, value)];
+}
+function resolveBindingSections(config, options) {
+  const sections = {};
+  const lookups = new Map;
+  for (const section of options?.sections ?? []) {
+    sections[section] = [];
+    lookups.set(section, new Map);
+  }
+  for (const section in config) {
+    if (!hasOwn.call(config, section)) {
+      continue;
+    }
+    const sectionConfig = config[section];
+    if (!isObject(sectionConfig)) {
+      throw new Error(`Invalid binding section "${section}": expected an object`);
+    }
+    const sectionLookup = new Map;
+    for (const rawCommand in sectionConfig) {
+      if (!hasOwn.call(sectionConfig, rawCommand)) {
+        continue;
+      }
+      const command = rawCommand.trim();
+      const bindings = resolveBindingValue(section, command, sectionConfig[rawCommand]);
+      if (!bindings) {
+        sectionLookup.delete(command);
+        continue;
+      }
+      sectionLookup.set(command, bindings);
+    }
+    let sectionBindingCount = 0;
+    for (const bindings of sectionLookup.values()) {
+      sectionBindingCount += bindings.length;
+    }
+    const sectionBindings = new Array(sectionBindingCount);
+    let bindingIndex = 0;
+    for (const bindings of sectionLookup.values()) {
+      for (let index = 0;index < bindings.length; index += 1) {
+        sectionBindings[bindingIndex] = bindings[index];
+        bindingIndex += 1;
+      }
+    }
+    sections[section] = sectionBindings;
+    lookups.set(section, sectionLookup);
+  }
+  return {
+    sections,
+    get(section, cmd) {
+      return lookups.get(section)?.get(cmd.trim());
+    }
+  };
+}
+// src/extras/command-bindings.ts
+function isCommandBindingKey(value) {
+  return typeof value === "string" || !!value && typeof value === "object" && !Array.isArray(value);
+}
+function commandBindings(bindings, options) {
+  const normalized = [];
+  const indexesByCommand = new Map;
+  for (const [command, key] of Object.entries(bindings)) {
+    if (!isCommandBindingKey(key)) {
+      const error = new Error(`Invalid command binding for "${command}": command bindings must map command strings to key strings or keystroke objects`);
+      options?.onError?.({
+        code: "invalid-command-binding",
+        command,
+        value: key,
+        reason: error
+      });
+      continue;
+    }
+    const normalizedCommand = command.trim();
+    const nextBinding = {
+      key: typeof key === "string" ? key : { ...key },
+      cmd: normalizedCommand
+    };
+    const existingIndex = indexesByCommand.get(normalizedCommand);
+    if (existingIndex !== undefined) {
+      const previousBinding = normalized[existingIndex];
+      options?.onWarning?.({
+        code: "command-binding-override",
+        command: normalizedCommand,
+        previousKey: previousBinding.key,
+        nextKey: nextBinding.key
+      });
+      normalized[existingIndex] = nextBinding;
+      continue;
+    }
+    indexesByCommand.set(normalizedCommand, normalized.length);
+    normalized.push(nextBinding);
+  }
+  return normalized;
+}
+// src/extras/formatting.ts
+function formatStroke(part, options) {
+  if (part.tokenName) {
+    const tokenDisplay = options.tokenDisplay;
+    if (!tokenDisplay)
+      return part.display;
+    if (typeof tokenDisplay === "function")
+      return tokenDisplay(part.tokenName, part) ?? part.display;
+    return tokenDisplay[part.tokenName] ?? part.display;
+  }
+  const stroke = part.stroke;
+  const modifierAliases = options.modifierAliases;
+  let formatted = "";
+  let pieceCount = 0;
+  if (stroke.ctrl) {
+    formatted = modifierAliases?.ctrl ?? "ctrl";
+    pieceCount = 1;
+  }
+  if (stroke.shift) {
+    const alias = modifierAliases?.shift ?? "shift";
+    formatted = pieceCount === 0 ? alias : `${formatted}+${alias}`;
+    pieceCount += 1;
+  }
+  if (stroke.meta) {
+    const alias = modifierAliases?.meta ?? "meta";
+    formatted = pieceCount === 0 ? alias : `${formatted}+${alias}`;
+    pieceCount += 1;
+  }
+  if (stroke.super) {
+    const alias = modifierAliases?.super ?? "super";
+    formatted = pieceCount === 0 ? alias : `${formatted}+${alias}`;
+    pieceCount += 1;
+  }
+  if (stroke.hyper) {
+    const alias = modifierAliases?.hyper ?? "hyper";
+    formatted = pieceCount === 0 ? alias : `${formatted}+${alias}`;
+    pieceCount += 1;
+  }
+  const name = stroke.name === "return" ? "enter" : stroke.name;
+  const keyName = options.keyNameAliases?.[name] ?? name;
+  return pieceCount === 0 ? keyName : `${formatted}+${keyName}`;
+}
+function formatKeySequence(parts, options = {}) {
+  if (!parts || parts.length === 0)
+    return "";
+  const separator = options.separator ?? " ";
+  let formatted = formatStroke(parts[0], options);
+  for (let index = 1;index < parts.length; index += 1) {
+    formatted += separator + formatStroke(parts[index], options);
+  }
+  return formatted;
+}
+function formatCommandBindings(bindings, options = {}) {
+  if (!bindings?.length)
+    return;
+  const bindingSeparator = options.bindingSeparator ?? ", ";
+  const dedupe = options.dedupe !== false;
+  const seen = dedupe ? new Set : undefined;
+  let formatted = "";
+  let itemCount = 0;
+  for (const binding of bindings) {
+    const item = formatKeySequence(binding.sequence, options);
+    if (!item)
+      continue;
+    if (seen) {
+      if (seen.has(item))
+        continue;
+      seen.add(item);
+    }
+    formatted = itemCount === 0 ? item : `${formatted}${bindingSeparator}${item}`;
+    itemCount += 1;
+  }
+  return formatted;
+}
+export {
+  resolveBindingSections,
+  formatKeySequence,
+  formatCommandBindings,
+  commandBindings
+};