@witchcraft/spellcraft 0.0.1

package/dist/core/setShortcutsProp.js

@@ -0,0 +1,93 @@
+import { castType } from "@alanscodelog/utils/castType";
+import { Err, Ok } from "@alanscodelog/utils/Result";
+import { doesShortcutConflict } from "../helpers/doesShortcutConflict.js";
+import { equalsShortcut } from "../helpers/equalsShortcut.js";
+import { isValidShortcut } from "../helpers/isValidShortcut.js";
+import { KnownError } from "../helpers/KnownError.js";
+import { errorTextAdd } from "../internal/errorTextAdd.js";
+import { errorTextRemove } from "../internal/errorTextRemove.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+const canHookable = ["entries@add", "entries@remove"];
+export function setShortcutsProp(prop, val, manager, {
+  check = true
+} = {}) {
+  const s = manager.options.stringifier;
+  const shortcuts = manager.shortcuts;
+  if (check) {
+    switch (prop) {
+      case "entries@add": {
+        castType(val);
+        castType(manager);
+        const shortcut = val;
+        const existing = shortcuts.entries.find(
+          (_) => equalsShortcut(shortcut, _, manager, { ignoreCommand: true }) || doesShortcutConflict(_, shortcut, manager)
+        );
+        if (existing) {
+          return Err(new KnownError(
+            SHORTCUT_ERROR.DUPLICATE_SHORTCUT,
+            errorTextAdd(
+              "Shortcut",
+              s.stringify(existing.chain, manager),
+              s.stringify(existing, manager),
+              s.stringify(shortcut, manager)
+            ),
+            { existing, self: shortcuts }
+          ));
+        }
+        const isValid = isValidShortcut(shortcut, manager);
+        if (isValid.isError) return isValid;
+        break;
+      }
+      case "entries@remove": {
+        const shortcut = val;
+        const existing = shortcuts.entries.find(
+          (_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false })
+        );
+        if (existing === void 0) {
+          return Err(new KnownError(
+            SHORTCUT_ERROR.MISSING,
+            errorTextRemove(
+              "Shortcut",
+              s.stringify(shortcut, manager),
+              s.stringifyList("shortcuts", shortcuts.entries, manager)
+            ),
+            { entry: shortcut, self: shortcuts }
+          ));
+        }
+        break;
+      }
+      default:
+        break;
+    }
+    if (manager?.hooks && "canSetShortcutsProp" in manager.hooks && canHookable.includes(prop)) {
+      const canHook = manager.hooks.canSetShortcutsProp?.(shortcuts, prop, val);
+      if (canHook instanceof Error) {
+        return Err(canHook);
+      }
+    }
+  }
+  if (check === "only") {
+    return Ok(true);
+  }
+  switch (prop) {
+    case "entries@add": {
+      const shortcut = val;
+      shortcuts.entries.push(shortcut);
+      break;
+    }
+    case "entries@remove": {
+      const shortcut = val;
+      const i = shortcuts.entries.findIndex((_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false }));
+      if (i < 0) {
+        throw new Error("If used correctly, shortcut should exist at this point, but it does not.");
+      }
+      shortcuts.entries.splice(i, 1);
+      break;
+    }
+    default:
+      shortcuts[prop] = val;
+      break;
+  }
+  manager.hooks?.onSetShortcutsProp?.(shortcuts, prop, val);
+  return Ok(shortcuts);
+}

package/dist/defaults/KeysSorter.d.ts

@@ -0,0 +1,35 @@
+import { type IKeysSorter, type Keys, type KeySortPos } from "../types/index.js";
+/**
+ * The default class based implementation of the {@link IKeysSorter} interface.
+ *
+ * Creates a keys sorter for shortcut chains.
+ *
+ * Can either be passed some (object) enum of KeySortPos or it's keys with the values changed, for example:
+ * ```ts
+ * const MyKeySortPos = {
+ * 	[KEY_SORT_POS.modmouse]: 0,
+ * 	[KEY_SORT_POS.mod]: 1,
+ * 	// or
+ * 	modmouse: 0,
+ * 	mod: 1,
+ * 	//...
+ * }
+ *
+ * const mySorter = new KeysSorter(MyKeySortPos)
+ * new Shortcut([...keys], {sorter: mySorter})
+ * ```
+ * They way this works is the enum should contain every possible combination of key "types". All sort does is determine the type and use it's position in the enum to know where to sort it. If two keys are of the same type, they are sorted alphabetically by their id.
+ *
+ * Or you can extend from the class and implement a custom sort function.
+ *
+ * Ideally a single sorter should be created and shared amongst all instances. This is already taken care of if you do not pass a custom sorter, a default sorter instance is re-used throughout.
+ *
+ * The order of the default sorter can be changed without creating a new class by importing it early and changing it's `order` property.
+ */
+export declare class KeysSorter implements IKeysSorter {
+    private _sort;
+    order: KeySortPos;
+    constructor(order?: KeysSorter["order"]);
+    sort(keyList: string[], keys: Keys): string[];
+}
+export declare const defaultSorter: KeysSorter;

package/dist/defaults/KeysSorter.js

@@ -0,0 +1,20 @@
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js";
+import { keyOrder } from "../internal/keyOrder.js";
+import { KEY_SORT_POS } from "../types/index.js";
+export class KeysSorter {
+  _sort(aId, bId, keys, order) {
+    const a = getKeyFromIdOrVariant(aId, keys).unwrap()[0];
+    const b = getKeyFromIdOrVariant(bId, keys).unwrap()[0];
+    if (keyOrder(a, order) < keyOrder(b, order)) return -1;
+    if (keyOrder(b, order) < keyOrder(a, order)) return 1;
+    return aId.localeCompare(bId);
+  }
+  order;
+  constructor(order = KEY_SORT_POS) {
+    this.order = order;
+  }
+  sort(keyList, keys) {
+    return keyList.sort((a, b) => this._sort(a, b, keys, this.order));
+  }
+}
+export const defaultSorter = new KeysSorter();

package/dist/defaults/Stringifier.d.ts

@@ -0,0 +1,66 @@
+import type { Command, Condition, DefaultStringifierOptions, IStringifier, Key, Manager, Shortcut } from "../types/index.js";
+/**
+ * The default class based implementation of the {@link IStringifier} interface.
+ *
+ * It can be passed (and a default instance is passed by default) to most functions to specify how to stringify items in errors.
+ *
+ * The default method `stringify` can be called with any key, chord, chain, shortcut, etc. and calls the respective {@link DefaultStringifierOptions} method depending on the type property or in the case of chains, chords, and keys, the array depth.
+ *
+ * That method called then calls any others it needs (e.g. if you pass a shortcut, it will call `stringifyShortcut` which will call `stringifyCommand`, `stringifyCondition`, and `stringifyChain`, which will call `stringifyChord` and so on)
+ *
+ * These can be customized by changing the options of the default instance (see Customizing below). These options are methods that describe in simpler term how items should be joined, without handling all the logic (the class pieces it all together)
+ *
+ * For chains the default method uses a key's label and combines keys inside chords with `+` and the chords of shortcut chains with a space ` `.
+ * ```
+ * Key+Key Key+Key+Key
+ * ^Chord^ ^Chord    ^
+ * ^Chain            ^
+ * ```
+ *
+ * For shortcuts, the default is:
+ * ```
+ * Shortcut Key+Key Key+Key+Key (command: command_name, condition: condition_text)
+ * ```
+ * If the condition or command are undefined:
+ * 	- For command it will still say it's undefined.
+ * 	- The condition is removed entirely if it's undefined.
+ * ```
+ * Shortcut Key+Key Key+Key+Key (command: undefined)
+ * ```
+ *
+ * `stringifyLists` returns a lists joined by a comma and new line:
+ *
+ * ```
+ * 	 item,
+ * 	 item
+ * ```
+ *
+ * ## Customizing
+ * Ideally a single stringifier should be created and shared amongst all instances. This is already taken care of if you do not pass a custom stringifier, a default stringifier instance is re-used throughout. Unless you're implementing your own {@link IStringifier}, you should not need to pass the default one around.
+ *
+ * You can just import it early and change it's options.
+ */
+export declare class Stringifier implements IStringifier {
+    opts: DefaultStringifierOptions;
+    constructor(opts?: DefaultStringifierOptions);
+    stringify(entry: string | string[] | string[][], manager: Pick<Manager, "keys">): string;
+    stringify(entry: Shortcut, manager: Pick<Manager, "keys" | "commands">): string;
+    stringify(entry: Key | Key[] | Command | Condition): string;
+    stringifyPropertyValue(entry: any): string;
+    protected stringifyShortcut(shortcut: Shortcut, manager: Pick<Manager, "keys" | "commands">): string;
+    protected stringifyCondition(condition?: Condition): string;
+    stringifyCommand(name: string, manager: Pick<Manager, "commands">): string;
+    stringifyCommand(command?: Command): string;
+    protected stringifyKey(key: Key): string;
+    protected stringifyKey(key: string, manager: Pick<Manager, "keys">): string;
+    protected stringifyChord(chord: Key[]): string;
+    protected stringifyChord(chord: string[], manager: Pick<Manager, "keys">): string;
+    protected stringifyChain(chain: Key[][]): string;
+    protected stringifyChain(chain: string[][], manager: Pick<Manager, "keys">): string;
+    stringifyList(type: "keys", entries: Key[]): string;
+    stringifyList(type: "commands", entries: Command[]): string;
+    stringifyList(type: "keys", entries: string[], manager: Pick<Manager, "keys">): string;
+    stringifyList(type: "commands", entries: string[], manager: Pick<Manager, "commands">): string;
+    stringifyList(type: "shortcuts", entries: Shortcut[], manager: Pick<Manager, "keys" | "commands">): string;
+}
+export declare const defaultStringifier: Stringifier;

package/dist/defaults/Stringifier.js

@@ -0,0 +1,119 @@
+import { castType } from "@alanscodelog/utils/castType";
+import { crop } from "@alanscodelog/utils/crop";
+import { dedupe } from "@alanscodelog/utils/dedupe";
+import { isArray } from "@alanscodelog/utils/isArray";
+import { isObject } from "@alanscodelog/utils/isObject";
+import { pretty } from "@alanscodelog/utils/pretty";
+import { unreachable } from "@alanscodelog/utils/unreachable";
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js";
+import { getLabel } from "../helpers/getLabel.js";
+export class Stringifier {
+  opts;
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  stringify(entry, manager) {
+    if (isObject(entry) && "type" in entry) {
+      switch (entry.type) {
+        case "key":
+          return this.stringifyKey(entry);
+        case "shortcut":
+          return this.stringifyShortcut(entry, manager);
+        case "command":
+          return this.stringifyCommand(entry, manager);
+        case "condition":
+          return this.stringifyCondition(entry);
+      }
+    } else {
+      if (isArray(entry)) {
+        if (entry.length === 0) return this.stringifyChord([]);
+        if (!isArray(entry[0])) {
+          castType(entry);
+          return this.stringifyChord(entry, manager);
+        }
+        castType(entry);
+        return this.stringifyChain(entry, manager);
+      } else {
+        return this.stringifyKey(entry, manager);
+      }
+    }
+    unreachable();
+  }
+  stringifyPropertyValue(entry) {
+    let res = "";
+    try {
+      res = this.stringify(entry);
+      return res;
+    } catch (e) {
+    }
+    const type = typeof entry;
+    switch (type) {
+      case "string":
+        return entry;
+      case "number":
+      case "boolean":
+        return `${entry}`;
+      case "function":
+        return `function "${entry.constructor.name}"`;
+      case "object":
+        return pretty(entry);
+      default:
+        return entry.toString();
+    }
+  }
+  stringifyShortcut(shortcut, manager) {
+    if (this.opts.shortcut) return this.opts.shortcut(shortcut);
+    const command = `command: ${this.stringifyCommand(shortcut.command ? manager.commands.entries[shortcut.command] : void 0)}`;
+    const chain = this.stringifyChain(shortcut.chain.map((chord) => chord.map((id) => manager.keys.entries[id] ?? manager.keys.toggles[id] ?? id)), manager);
+    const condition = this.stringifyCondition(shortcut.condition);
+    return crop`Shortcut ${chain} (${command}${shortcut.condition ? `, ${condition}` : ""})`;
+  }
+  stringifyCondition(condition) {
+    if (this.opts.condition) return this.opts.condition(condition);
+    return condition ? `condition: "${condition?.text}"` : `condition: undefined`;
+  }
+  stringifyCommand(nameOrCommand, manager) {
+    const command = typeof nameOrCommand === "string" ? manager.commands.entries[nameOrCommand] : nameOrCommand;
+    if (this.opts.command) return this.opts.command(command);
+    return command ? command.name : "(None)";
+  }
+  stringifyKey(keyOrId, manager) {
+    if (typeof keyOrId === "string") {
+      const res = getKeyFromIdOrVariant(keyOrId, manager.keys);
+      const key = res.isOk ? res.value[0] : void 0;
+      if (key) {
+        if (this.opts.key) return this.opts.key(keyOrId, key);
+        return getLabel(keyOrId, key);
+      } else {
+        if (this.opts.key) return this.opts.key(keyOrId);
+        return keyOrId;
+      }
+    } else {
+      if (this.opts.key) return this.opts.key(keyOrId.id, keyOrId);
+      return getLabel(keyOrId.id, keyOrId);
+    }
+  }
+  stringifyChord(chord, manager) {
+    const stringified = dedupe(chord.map((key) => this.stringifyKey(key, manager)), { mutate: true });
+    if (this.opts.chord) return this.opts.chord(stringified);
+    return stringified.join("+");
+  }
+  stringifyChain(chain, manager) {
+    const stringified = chain.map((chord) => this.stringifyChord(chord, manager));
+    if (this.opts.chain) return this.opts.chain(stringified);
+    return stringified.join(" ");
+  }
+  stringifyList(type, entries, manager) {
+    let stringified;
+    if (typeof entries[0] === "string") {
+      stringified = entries.map(
+        (entry) => type === "keys" ? this.stringify(entry, manager) : this.stringifyCommand(entry, manager)
+      );
+    } else {
+      stringified = entries.map((entry) => this.stringify(entry, manager));
+    }
+    if (this.opts.list) return this.opts.list(stringified, type);
+    return stringified.join(",\n");
+  }
+}
+export const defaultStringifier = new Stringifier();

package/dist/defaults/defaultConditionEquals.d.ts

@@ -0,0 +1,19 @@
+import type { Condition } from "../types/index.js";
+/**
+ * Returns whether the condition passed is equal to this one.
+ *
+ * The default method does a simplistic object check, and otherwise a  check of the `text` property for equality. If both conditions are undefined, note this will return true.
+ *
+ * If you override the default conditionEquals option you will likely want it to just always return false.
+ *
+ * Why? Because unless you're using simple single variable conditions that you can presort to make them uniquely identifiable (i.e. not boolean expressions, e.g. `!a b !c`), this will return A LOT of false negatives.
+ *
+ * Why the false negatives? Because two conditions might be functionally equal but have differing representations (e.g: `a && b`, `b && a`). You might think, lets normalize them all, but normalizing boolean expressions (converting them to CNF) can be dangerous with very long expressions because it can take exponential time.
+ *
+ * Now the main reason for checking the equality of two conditions is to check if two shortcuts might conflict. If we're using boolean expressions it just can't be done safely.
+ *
+ * This is a personal preference, but if we have a method that gives false negatives it can be confusing that some shortcuts immediately error when added because their conditions are simple, while others don't until triggered. The simpler, more consistent alternative is to only have them error on triggering. Aditionally conflicting conditions can be shown on the keyboard layout when then user picks contexts to check against.
+ *
+ * Why use the default implementation at all then? Well, shortcuts aren't the only ones that have conditions, commands can too, but unlike shortcuts, usually it's developers who are in charge of assigning a command's condition, and since they are usually simple, it's more possible to make sure the conditions are unique (e.g. tests could enforce they're unique by converting them all to CNF and pre-checking them for equality).
+ */
+export declare function defaultConditionEquals<TCondition extends Condition>(conditionA?: TCondition, conditionB?: Condition): conditionB is TCondition;

package/dist/defaults/defaultConditionEquals.js

@@ -0,0 +1,5 @@
+export function defaultConditionEquals(conditionA, conditionB) {
+  if (conditionA === conditionB) return true;
+  if (!conditionA || !conditionB) return false;
+  return conditionA.text === conditionB.text;
+}

package/dist/defaults/defaultManagerCallback.d.ts

@@ -0,0 +1,7 @@
+import type { Manager } from "../types/index.js";
+/**
+ * The default callback for the manager which logs the error, the event that caused it, and clears the chain.
+ *
+ * @internal
+ */
+export declare const defaultManagerCallback: Manager["options"]["cb"];

package/dist/defaults/defaultManagerCallback.js

@@ -0,0 +1,5 @@
+import { setManagerProp } from "../core/setManagerProp.js";
+export const defaultManagerCallback = (manager, error, e) => {
+  console.warn(error, e);
+  setManagerProp(manager, "state.chain", []);
+};

package/dist/helpers/KnownError.d.ts

@@ -0,0 +1,8 @@
+import { TypedError } from "@alanscodelog/utils";
+import type { ErrorInfo, ShortcutError, TypeError } from "../types/index.js";
+/**
+ * Creates a known error that extends the base Error with some extra information.
+ * All the variables used to create the error message are stored in it's info property so you can easily craft your own error messages to show to users.
+ */
+export declare class KnownError<T extends ShortcutError | TypeError = ShortcutError | TypeError> extends TypedError<T, ErrorInfo<T>> {
+}

package/dist/helpers/KnownError.js

@@ -0,0 +1,3 @@
+import { TypedError } from "@alanscodelog/utils";
+export class KnownError extends TypedError {
+}

package/dist/helpers/calculateAndSetPositionAndWidth.d.ts

@@ -0,0 +1,13 @@
+import type { RawKey } from "../types/keys.js";
+/**
+ * Auto calculate and set the x positions of a row of raw keys based on their width if set (otherwise width is set to 1). If the key already has an x position it takes priority and "shifts" the rest of the keys.
+ *
+ * Useful for creating layouts.
+ *
+ * This is for *RAW* keys, so it mutates the key directly without going through {@link setKeyProp}
+ */
+export declare function calculateAndSetPositionAndSize<T extends RawKey>(row: T[]): (T & {
+    x: number;
+    width: number;
+    height: 1;
+})[];

package/dist/helpers/calculateAndSetPositionAndWidth.js

@@ -0,0 +1,18 @@
+import { setReadOnly } from "@alanscodelog/utils/setReadOnly";
+export function calculateAndSetPositionAndSize(row) {
+  let x = 0;
+  for (const key of row) {
+    if (key.x) x = key.x;
+    setReadOnly(key, "x", x);
+    if (key.width) {
+      x += key.width;
+    } else {
+      setReadOnly(key, "width", 1);
+      x++;
+    }
+    if (key.height === void 0) {
+      setReadOnly(key, "height", 1);
+    }
+  }
+  return row;
+}

package/dist/helpers/calculateLayoutSize.d.ts

@@ -0,0 +1,9 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns the layout size in key units for a set of {@link Keys}. This will only look at keys which are set to ({@link Key.render}).
+ *
+ * See {@link Keys.autoManageLayout} and {@link Keys.layout}.
+ *
+ * This should be done after creating {@link Keys} then on any user changes to the size/pos properties of keys. You can hook into these changed with the manager's {@link Manager.hooks.onSetKeyProp}.
+ */
+export declare function calculateLayoutSize(keys: Keys): Keys["layout"];

package/dist/helpers/calculateLayoutSize.js

@@ -0,0 +1,13 @@
+export function calculateLayoutSize(keys) {
+  let x = 0;
+  let y = 0;
+  for (const key of Object.values(keys.entries)) {
+    if (key.render) {
+      const xLimit = key.x + key.width;
+      x = xLimit > x ? xLimit : x;
+      const yLimit = key.y + key.height;
+      y = yLimit > y ? yLimit : y;
+    }
+  }
+  return { x, y };
+}

package/dist/helpers/doesShortcutConflict.d.ts

@@ -0,0 +1,18 @@
+import type { Manager, PickManager, Shortcut } from "../types/index.js";
+/**
+ * A shortcut conflicts with another if their conditions are equal and their chains are in conflict.
+ *
+ * Chains can be in conflict in any of the following situations:
+ *
+ * - The shortcuts are the same instance.
+ * - All the keys are the same.
+ * - They share starting chords and the last shared chord conflicts. (e.g. [[A], [B]] and [[A]]), i.e. they have a chain conflict.
+ * - The last chords shares all modifiers and one of the chords is all modifiers. (e.g. [[A], [Ctrl]] and [[A], [Ctrl, A]]), i.e. they have a modifier conflict.
+ *
+ * Some of these can be ignored with the experimental ignore* options.
+ *
+ * A context can be passed for a more accurate test, otherwise depending on what type of conditions you use (see {@link ConditionComparer}) you cannot truly tell if shortcuts with complex conditions will conflict. See the option itself for more details.
+ */
+export declare function doesShortcutConflict<TShortcut extends Shortcut>(shortcutA: TShortcut, shortcutB: Shortcut, manager: Pick<Manager, "keys" | "commands" | "shortcuts"> & {
+    context?: Manager["context"];
+} & PickManager<"options", "evaluateCondition" | "conditionEquals">): boolean;

package/dist/helpers/doesShortcutConflict.js

@@ -0,0 +1,42 @@
+import { equalsShortcut } from "./equalsShortcut.js";
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js";
+import { equalsKey } from "../utils/equalsKey.js";
+import { equalsKeys } from "../utils/equalsKeys.js";
+export function doesShortcutConflict(shortcutA, shortcutB, manager) {
+  const context = manager.context;
+  if (!context && manager.shortcuts.useContextInConflictCheck) {
+    throw new Error("Manager must have a context if `useContextInConflictCheck` is true.");
+  }
+  const {
+    ignoreChainConflicts,
+    ignoreModifierConflicts
+  } = manager.shortcuts;
+  if (ignoreChainConflicts && ignoreModifierConflicts) return false;
+  if (shortcutA.forceUnequal || shortcutB.forceUnequal) return false;
+  if (equalsShortcut(shortcutA, shortcutB, manager)) return true;
+  const evaluateCondition = manager.options.evaluateCondition;
+  const conditionEquals = manager.options.conditionEquals;
+  if (context) {
+    if (shortcutA.condition && shortcutB.condition) {
+      const shortcutCondition = evaluateCondition(shortcutA.condition, context);
+      const otherCondition = evaluateCondition(shortcutB.condition, context);
+      if (shortcutCondition !== otherCondition) return false;
+      if (!shortcutCondition) return false;
+    }
+  } else {
+    if (!conditionEquals(shortcutA.condition, shortcutB.condition)) return false;
+  }
+  const { keys } = manager;
+  if (shortcutA.chain.length === 0 || shortcutB.chain.length === 0) {
+    return ignoreChainConflicts === true && ignoreModifierConflicts === true;
+  }
+  const lastSharedIndex = Math.max(0, Math.min(shortcutA.chain.length - 1, shortcutB.chain.length - 1));
+  const lastIsModOnly = shortcutA.chain[lastSharedIndex].find((id) => !getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier) === void 0;
+  const otherLastIsModOnly = shortcutB.chain[lastSharedIndex].find((id) => !getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier) === void 0;
+  const sharedModifiers = shortcutA.chain[lastSharedIndex].filter(
+    (id) => getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier && shortcutB.chain[lastSharedIndex].some((otherId) => equalsKey(otherId, id, keys, { allowVariants: true }))
+  );
+  const lastSharedChordConflicts = (lastIsModOnly || otherLastIsModOnly) && sharedModifiers.length > 0;
+  const conflictsWithChain = equalsKeys(shortcutA.chain, shortcutB.chain, keys, lastSharedIndex + 1, { allowVariants: true });
+  return !ignoreChainConflicts && conflictsWithChain || !ignoreModifierConflicts && lastSharedChordConflicts;
+}

package/dist/helpers/equalsCommand.d.ts

@@ -0,0 +1,7 @@
+import type { Command, PickManager } from "../types/index.js";
+/**
+ * Returns whether the command passed is equal to this one.
+ *
+ * The name, execute, description, and conditions must be equal.
+ */
+export declare function equalsCommand<TCommand extends Command>(commandA: TCommand, commandB: Command, manager: PickManager<"options", "conditionEquals">): commandB is TCommand;

package/dist/helpers/equalsCommand.js

@@ -0,0 +1,4 @@
+export function equalsCommand(commandA, commandB, manager) {
+  if (commandA === commandB) return true;
+  return commandA.name === commandB.name && commandA.execute === commandB.execute && manager.options.conditionEquals(commandA.condition, commandB.condition) && commandA.description === commandB.description;
+}

package/dist/helpers/equalsContext.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../types/index.js";
+/**
+ * Returns whether the context passed is equal to this one.
+ *
+ * The default methods provides a simple comparison that can handle simple flat or nested objects (simple as in it assumes values are not arrays). If you need something more complex you will need to provide your own function.
+ */
+export declare function equalsContext(contextA: Context, contextB: Context): boolean;

package/dist/helpers/equalsContext.js

@@ -0,0 +1,19 @@
+function fastIsEqual(obj, other) {
+  const keys1 = Object.keys(obj);
+  const keys2 = Object.keys(other);
+  if (keys1.length !== keys2.length) return false;
+  for (const key of keys1) {
+    const val1 = obj[key];
+    const val2 = other[key];
+    if (typeof val1 === "object" && typeof val2 === "object") {
+      if (!fastIsEqual(val1, val2)) return false;
+    }
+    if (val1 !== val2) {
+      return false;
+    }
+  }
+  return true;
+}
+export function equalsContext(contextA, contextB) {
+  return fastIsEqual(contextA.value, contextB.value);
+}

package/dist/helpers/equalsShortcut.d.ts

@@ -0,0 +1,9 @@
+import type { Manager, PickManager, Shortcut } from "../types/index.js";
+/**
+ * Returns whether the shortcut passed is equal to shortcutA one.
+ *
+ * To return true, their keys and command must be equal (unless ignoreCommand is passed), their condition must be equal according to shortcutA shortcut's condition.
+ */
+export declare function equalsShortcut<TShortcut extends Shortcut>(shortcutA: TShortcut, shortcutB: Shortcut, manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "evaluateCondition" | "conditionEquals">, { ignoreCommand }?: {
+    ignoreCommand?: boolean;
+}): shortcutB is TShortcut;

package/dist/helpers/equalsShortcut.js

@@ -0,0 +1,7 @@
+import { equalsCommand } from "./equalsCommand.js";
+import { equalsKeys } from "../utils/equalsKeys.js";
+export function equalsShortcut(shortcutA, shortcutB, manager, { ignoreCommand = false } = {}) {
+  if (shortcutA.forceUnequal || shortcutB.forceUnequal) return false;
+  if (shortcutA === shortcutB) return true;
+  return equalsKeys(shortcutA.chain, shortcutB.chain, manager.keys, void 0, { allowVariants: true }) && manager.options.conditionEquals(shortcutA.condition, shortcutB.condition) && (ignoreCommand || shortcutA.command === shortcutB.command && shortcutA.command === void 0 || shortcutA.command !== void 0 && shortcutB.command !== void 0 && equalsCommand(manager.commands.entries[shortcutA.command], manager.commands.entries[shortcutB.command], manager));
+}

package/dist/helpers/forceClear.d.ts

@@ -0,0 +1,12 @@
+import type { Manager } from "../types/index.js";
+/**
+ * Force clears/resets all state. Clears the chain and sets all keys to unpressed.
+ *
+ * Useful for testing.
+ *
+ * @param opts
+ * @param {false} opts.ignoreNative  If true, does not change state of native modifier/toggle keys.
+ */
+export declare function forceClear(manager: Manager, { ignoreNative }?: {
+    ignoreNative?: boolean;
+}): void;

package/dist/helpers/forceClear.js

@@ -0,0 +1,16 @@
+import { setKeyProp } from "../core/setKeyProp.js";
+import { setManagerProp } from "../core/setManagerProp.js";
+export function forceClear(manager, { ignoreNative = false } = {}) {
+  setManagerProp(manager, "state.chain", []);
+  setManagerProp(manager, "state.nextIsChord", true);
+  setManagerProp(manager, "state.untrigger", false);
+  setManagerProp(manager, "state.isAwaitingKeyup", false);
+  for (const key of Object.values(manager.keys.entries)) {
+    if ((key.isModifier === "native" || key.isToggle === "native") && ignoreNative) return;
+    setKeyProp(key, "pressed", false, manager);
+    if (key.isToggle) {
+      setKeyProp(key, "toggleOnPressed", false, manager);
+      setKeyProp(key, "toggleOffPressed", false, manager);
+    }
+  }
+}

package/dist/helpers/forceUpdateNativeKeysState.d.ts

@@ -0,0 +1,5 @@
+import type { AnyInputEvent, Manager } from "../types/index.js";
+/**
+    * Force the manager to update the state of modifier/toggle keys during a keyboard or mouse event.
+    */
+export declare function forceUpdateNativeKeysState(manager: Manager, e: AnyInputEvent): void;

package/dist/helpers/forceUpdateNativeKeysState.js

@@ -0,0 +1,4 @@
+import { updateNativeKeysState } from "../internal/updateNativeKeysState.js";
+export function forceUpdateNativeKeysState(manager, e) {
+  updateNativeKeysState(manager, e);
+}

package/dist/helpers/generateKeyShortcutMap.d.ts

@@ -0,0 +1,23 @@
+import type { KeyInfo, Manager, Shortcut, ShortcutInfo } from "../types/index.js";
+import type { Key } from "../types/keys.js";
+/**
+ * Given a chain, a shortcut list, and a manager, this will return a record with information for each key id regarding what shortcuts can be pressed and some additional information useful for visual displaying them on a keyboard (See {@link KeyInfo}).
+ *
+ * The record will contain all renderable keys by their id (see {@link Key.render}). It will not contain variants or toggle states, only full keys (i.e. {@link Keys.entries}).
+ *
+ * It is recommended you pre-filter the shortcut's list to remove any shortcuts that are disabled or not executable.
+ *
+ * You can also post filter depending on the generated {@link ShortcutInfo} entry. See the postFilter param.
+ */
+export declare function generateKeyShortcutMap(chain: string[][], shortcutsList: Shortcut[], manager: Manager, 
+/**
+    * Filter entries by their {@link ShortcutInfo}, before adding/modifying the corresponding keys. Return false to filter the entry out, true to keep it.
+    *
+    * The second argument also provides some additional info the function looks at to generate the result.
+    */
+postFilter?: (entry: ShortcutInfo, info: {
+    pressableKeys: Key[];
+    unpressedModifiers: Key[];
+    isPressed: boolean;
+    containsSubset: boolean;
+}) => boolean): Record<Key["id"], KeyInfo>;