@witchcraft/spellcraft 0.0.1

package/dist/types/manager.d.ts

@@ -0,0 +1,249 @@
+import type { AnyFunction } from "@alanscodelog/utils/types";
+import type { CanHookCommandProps, CanHookCommandsProps, CanHookKeyProps, CanHookKeysProps, CanHookShortcutProps, CanHookShortcutsProps, ChainError, Command, Commands, CommandSetEntries, CommandsSetEntries, ConditionComparer, ConditionEvaluator, Context, IKeysSorter, IStringifier, Key, KeyboardLayoutMap, Keys, KeySetEntries, KeysSetEntries, MultipleErrors, OnHookCommandProps, OnHookCommandsProps, OnHookKeyProps, OnHookKeysProps, OnHookShortcutProps, OnHookShortcutsProps, Shortcut, SHORTCUT_ERROR, Shortcuts, ShortcutSetEntries, ShortcutsSetEntries, TriggerableShortcut } from "./index.js";
+import type { EmulatedEvent } from "../core/EmulatedEvent.js";
+import type { KnownError } from "../helpers/index.js";
+export type AnyInputEvent = KeyboardEvent | MouseEvent | WheelEvent | EmulatedEvent;
+export type MinimalInputEvent = ({
+    button: number;
+} | {
+    code?: string;
+    key: string;
+} | {
+    deltaY: number;
+}) & Record<string, any>;
+export type ManagerReplaceValue = Partial<Pick<Manager, "shortcuts" | "keys" | "commands">>;
+export type ManagerReplaceErrors = KnownError<typeof SHORTCUT_ERROR.UNKNOWN_KEY | typeof SHORTCUT_ERROR.UNKNOWN_COMMAND>;
+export type ManagerListener = ({ event, keys, isKeydown, manager }: {
+    event?: AnyInputEvent;
+    keys: string[];
+    isKeydown: boolean;
+    manager: Manager;
+}) => void;
+export type ExportedManager = {
+    shortcuts?: Shortcuts;
+    keys?: Keys;
+    commands?: Commands;
+};
+export type OnHook<TBase, T extends Record<string, {
+    val: any;
+}>, TKey extends keyof T = keyof T, TVal extends T[TKey]["val"] = T[TKey]["val"]> = (obj: TBase, key: TKey, val: TVal) => void;
+export type CanHook<TBase, T extends Record<string, {
+    val: any;
+}>, TKey extends keyof T = keyof T, TVal extends T[TKey]["val"] = T[TKey]["val"], TError extends Error = Error> = (obj: TBase, key: TKey, val: TVal) => TError | true;
+type GetManagerHooks<T extends OnHookManagerProps> = T extends CanHookManagerProps ? Partial<Pick<NonNullable<Manager["hooks"]>, "canSetManagerProp" | "onSetManagerProp">> : Partial<Pick<NonNullable<Manager["hooks"]>, "onSetManagerProp">>;
+export type OnHookManagerProps = "state.chain" | "shortcuts" | "keys" | "commands" | `state.${keyof Manager["state"]}`;
+export type CanHookManagerProps = "state.chain" | "shortcuts" | "keys" | "commands" | `state.${keyof Pick<Manager["state"], "isRecording">}`;
+type ManagerStateHook<T extends keyof Manager["state"]> = {
+    val: Manager["state"][T];
+    manager: Manager;
+    hooks: GetManagerHooks<`state.${T}`>;
+    error: never;
+};
+export type ManagerSetEntries = {
+    "state.chain": {
+        val: string[][];
+        manager: Manager;
+        hooks: GetManagerHooks<"state.chain">;
+        error: typeof SHORTCUT_ERROR.UNKNOWN_KEY;
+    };
+    shortcuts: {
+        val: Shortcuts;
+        manager: Manager;
+        hooks: GetManagerHooks<"shortcuts">;
+        error: typeof SHORTCUT_ERROR.UNKNOWN_COMMAND | ChainError;
+    };
+    commands: {
+        val: Commands;
+        manager: Manager;
+        hooks: GetManagerHooks<"commands">;
+        error: typeof SHORTCUT_ERROR.UNKNOWN_COMMAND;
+    };
+    keys: {
+        val: Keys;
+        manager: Manager;
+        hooks: GetManagerHooks<"keys">;
+        error: ChainError;
+    };
+    "state.isRecording": ManagerStateHook<"isRecording">;
+    "state.isAwaitingKeyup": ManagerStateHook<"isAwaitingKeyup">;
+    "state.nextIsChord": ManagerStateHook<"nextIsChord">;
+    "state.untrigger": ManagerStateHook<"untrigger">;
+};
+export type CanHooks = {
+    canSetKeyProp?: CanHook<Key, Pick<KeySetEntries, CanHookKeyProps>>;
+    canSetKeysProp?: CanHook<Keys, Pick<KeysSetEntries, CanHookKeysProps>>;
+    canSetCommandProp?: CanHook<Command, Pick<CommandSetEntries, CanHookCommandProps>>;
+    canSetCommandsProp?: CanHook<Commands, Pick<CommandsSetEntries, CanHookCommandsProps>>;
+    canSetShortcutProp?: CanHook<Shortcut, Pick<ShortcutSetEntries, CanHookShortcutProps>>;
+    canSetShortcutsProp?: CanHook<Shortcuts, Pick<ShortcutsSetEntries, CanHookShortcutsProps>>;
+    canSetManagerProp?: CanHook<Manager, Pick<ManagerSetEntries, CanHookManagerProps>>;
+};
+export type OnHooks = {
+    onSetKeyProp?: OnHook<Key, Pick<KeySetEntries, OnHookKeyProps>>;
+    onSetKeysProp?: OnHook<Keys, Pick<KeysSetEntries, OnHookKeysProps>>;
+    onSetCommandProp?: OnHook<Command, Pick<CommandSetEntries, OnHookCommandProps>>;
+    onSetCommandsProp?: OnHook<Commands, Pick<CommandsSetEntries, OnHookCommandsProps>>;
+    onSetShortcutProp?: OnHook<Shortcut, Pick<ShortcutSetEntries, OnHookShortcutProps>>;
+    onSetShortcutsProp?: OnHook<Shortcuts, Pick<ShortcutsSetEntries, OnHookShortcutsProps>>;
+    onSetManagerProp?: OnHook<Manager, Pick<ManagerSetEntries, OnHookManagerProps>>;
+};
+export type Hooks = OnHooks & CanHooks;
+export type CanHookErrors<T extends CanHooks | any, TKey extends keyof T | string> = T extends CanHooks ? TKey extends keyof T ? Extract<ReturnType<Extract<T[TKey], AnyFunction>>, Error> : never : never;
+export type Manager<THooks extends Partial<Hooks> = Partial<Hooks>, TKeys extends Keys = Keys, TShortcuts extends Shortcuts = Shortcuts, TCommands extends Commands = Commands, TContext extends Context = Context, TListener extends ManagerListener = ManagerListener> = {
+    /** A name for the manager. */
+    name: string;
+    type: "manager";
+    context: TContext;
+    keys: TKeys;
+    shortcuts: TShortcuts;
+    commands: TCommands;
+    /** Most options can be set directly, except any readonly options which must go through {@link setManagerProperties} to ensure state remains consistent. */
+    options: {
+        sorter: IKeysSorter;
+        stringifier: IStringifier;
+        /**
+         * The error callback for recoverable errors such as multiple shortcuts matching, no shortcut matching once a chord chain has been "started", or an unknown key event because no matching key was found (only for keyboard events).
+         *
+         * Usually you will want to clear the manager's chain when this happens and display the error to the user. The default callback logs the error and clears the chain.
+         *
+         * In the case of multiple valid shortcuts, if you trigger any of the shortcuts "manually" note that you will need to simulate both the keydown/keyup calls if you differentiate between them.
+         *
+         * Also the input event can be undefined if you set the manager chain directly since it will check if it should trigger shortcuts.
+         */
+        cb: (manager: Manager, error: MultipleErrors<typeof SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS | typeof SHORTCUT_ERROR.NO_MATCHING_SHORTCUT | typeof SHORTCUT_ERROR.UNKNOWN_KEY_EVENT | typeof SHORTCUT_ERROR.UNKNOWN_KEY_ID | typeof SHORTCUT_ERROR.UNKNOWN_KEY>, e?: AnyInputEvent) => void;
+        /**
+         * Determines if two conditions are equal.
+         *
+         * This is actually not a good idea to implement if you use boolean conditions. See {@link ConditionComparer} for why.
+         */
+        conditionEquals: ConditionComparer;
+        /** Determines how conditions are evaluated. */
+        evaluateCondition: ConditionEvaluator<TContext>;
+        /** Enable/disable triggering of shortcuts. The manager otherwise works as normal. */
+        enableShortcuts: boolean;
+        /** Enable/disable listeners. Listeners will remain attached but do nothing. */
+        enableListeners: boolean;
+        /**
+         * Whether to check the state of modifier or toggle keys using `event.getModifierState`.
+         *
+         * This is set to true by default when using `createManager` because it is usually what you want. It tracks the state with the most accuracy when, for example, the user focuses out, toggles a key, then focuses back.
+         *
+         * But, if you are allowing the user to change key states in some way (e.g. clicking on keys in the settings to visualize shortcuts), you will want to disable this temporarily so that they can click modifier keys. Otherwise they'd be immediately toggled off again (by the state check during the click) and nothing would happen.
+         *
+         * Keys also have their own individual {@link Key.updateStateOnAllEvents} in case you need more fine grained control.
+         *
+         * When this is set to false, the default mouseenter handler will ignore the event.
+         *
+         * If you will always have this set to false, you can forego the mouseenter event listener.
+         */
+        updateStateOnAllEvents: boolean;
+    };
+    /**
+     * An event listener for all events the manager handles including {@link virtualPress}/{@link virtualRelease}.
+     *
+     * The listener is called right after keys are found so you can have access to the keys as the manager understood them, but before everything else (setting the state, labeling, adding/removing from the chain). Note that `isKeydown` is always true for wheel events since their keyup is emulated within the same event handler.
+     *
+     * This exists because not all events trigger shortcuts (which can access only the event that triggered them) but there are many times when you might still want access to the event to do things like `e.preventdefault()`:
+     *
+     * - When recording, we usually always need to do `e.preventDefault()` except in some rare cases:
+     * 	- For example say you have a div which records while focused, if the manager is attached to a parent element, you will have to allow clicks to the parent so losing focus stops the recording. You do not generally need to allow keys through as you can set all shortcut conditions to only trigger when not recording, temporily swap out the shortcuts while recording, or use the onSetKeyProp hook (note this would mean hardcoding keys, but might be acceptable for a case such as this).
+     * 	 - We also need to `e.preventDefault()` for any chords that are also browser shortcuts (though note not all browser shortcuts can be overriden). If you really need to there is the [Keyboard API](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API) which allows requesting some keyboard shortcuts be locked (see [Keyboard Locking](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API#keyboard_locking)).
+     *
+     *
+     * The following should give you a good starting point:
+     *
+     * ```ts
+     * manager.listener = (({event, isKeydown, keys}) => {
+     * 	if (
+     * 		(manager.isRecording && !(event instanceof MouseEvent))
+     * 		// || TODO browser shortcuts filter
+     * 	) {
+     * 		event.preventDefault()
+     * 	}
+     * })
+     * ```
+     */
+    listener?: TListener;
+    /**
+     * Hooks provide a way to set further limits on what can be changed (can hooks), and provide listeners for when something *is* about to change (on* hooks).
+     *
+     * on* hooks allow hooking into changes for certain properties (such as key size/pos changed) to trigger recalculations (e.g. of layouts).
+     *
+     * They could also technically be used as an escape hatch for frameworks that don't support working mutable data, but I would advice against it. Instead I would recommend using a proxy based state management solution like valtio that allows for mutations and optimized rendering.
+     */
+    hooks: THooks;
+    /**
+     * The manager requires some state to function and be a little bit more efficient. All properties are readonly because they should not be modified unless they are allowed to be by {@link setManagerProp}.
+     */
+    state: {
+        /**
+         * The current chain of chords.
+         *
+         * Note that the manager's chain is not neccesarily valid and should be checked before assigning to a shortcut.
+         *
+         * @RequiresSet @OnHookable @Managed
+         */
+        readonly chain: string[][];
+        /**
+         * Whether the manager is waiting for non-modifier keys to be release.
+         *
+         *@RequiresSet @OnHookable @Managed
+         */
+        readonly isAwaitingKeyup: boolean;
+        /**
+         * Whether the manager is in recording mode.
+         *
+         * When enabling/disabling this property, you should clear the chain first with {@link safeSetSetManagerChain}.
+         *
+         * ```
+         * safeSetManagerChain(manager, [])
+         * setManagerProp(manager, "state.isRecording", true)
+         * //...
+         * safeSetManagerChain(manager, [])
+         * setManagerProp(manager, "state.isRecording", false)
+         * ```
+         *
+         * To allow users to record shortcuts, you can do something like have an input element that on focus starts recording and stops when focused is blurred (this has the advantage of working with keyboard navigation). In such a case, you can use the {@link Manager.listener} to `e.preventDefault()` all events except clicks outside the input. See it for more details.
+         *
+         * @RequiresSet @OnHookable @CanHookable
+         */
+        readonly isRecording: boolean;
+        /**
+         * There are times, such as after a keydown event, that a shortcut command will trigger, but we also need to "untrigger" it later on key up. If there is a triggerable shortcut it is saved here. See {@link Manager.state.chain}.
+         *
+         * @RequiresSet @OnHookable @Managed
+         */
+        readonly untrigger: false | TriggerableShortcut;
+        /**
+         * The manager keeps track of whether the next key press should start a new chord or not.
+         *
+         * @RequiresSet @OnHookable @Managed
+         */
+        readonly nextIsChord: boolean;
+    };
+};
+export type LabelOptions = {
+    /**
+     * See {@link labelWithKeyboardMap}. This is required for label strategies that use the navigator. You can get the map using [navigator.keyboard.getLayoutMap()](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/getLayoutMap).
+     */
+    map: KeyboardLayoutMap;
+    /**
+     * Filters the auto labeling.
+     *
+     * If the filter returns true, the key is not labeled.
+     *
+     * You can also use this to label the key yourself.
+     *
+     * Common filter actions:
+     * - Capitalize all single character keys to match what they look like on real keyboard.
+     * - Prevent keys with multi-line labels (e.g. `Num\nLock`, `Scroll\nLock` from getting changed).
+     *
+     * Note the event is not always a real event because if it's the navigator labeling the key or you're using the {@link Emulator} class, there isn't a real event.
+     */
+    labelFilter?: (e: AnyInputEvent | MinimalInputEvent, keyId: string, label: string, keys: Keys) => boolean;
+};
+export type EventTypes = "keydown" | "keyup" | "wheel" | "mousedown" | "mouseup" | "mouseenter";
+export type EventListenerTypes<T extends EventTypes = EventTypes> = {
+    [key in T]: ((e: key extends "keydown" | "keyup" ? KeyboardEvent : key extends "wheel" ? WheelEvent : MouseEvent) => boolean) | ((e: key extends "keydown" | "keyup" ? KeyboardEvent : key extends "wheel" ? WheelEvent : MouseEvent) => void);
+};
+export {};

package/dist/types/plugins.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shortcuts.d.ts

@@ -0,0 +1,144 @@
+import type { Command } from "./commands.js";
+import type { Condition } from "./condition.js";
+import type { ChainError, SHORTCUT_ERROR } from "./enums.js";
+import type { PickManager } from "./general.js";
+import type { Key } from "./keys.js";
+import type { Manager } from "./manager.js";
+/**
+ * Same as {@link Shortcut} except you're allowed to exclude all properties except the chain.
+ */
+export interface RawShortcut<TRawCommand extends Command["name"] | Command = Command["name"] | Command, TCommand extends TRawCommand extends string ? Command<TRawCommand> : TRawCommand = TRawCommand extends string ? Command<TRawCommand> : TRawCommand, TCondition extends Condition = Condition> extends Omit<Partial<Shortcut<TCommand["name"], TCondition>>, "chain" | "command"> {
+    chain: (string | Key)[][];
+    command?: TRawCommand;
+}
+export interface Shortcut<TCommand extends Command["name"] = Command["name"], TCondition extends Condition = Condition> {
+    type: "shortcut";
+    /**
+     * The {@link Command} to associate with the shortcut.
+     *
+     * @RequiresSet @OnHookable @CanHookable
+     */
+    readonly command?: TCommand;
+    /**
+     * The {@link Condition} a shortcut is allowed to be triggered on. If both the command and the shortcut have a condition, both must be met.
+     *
+     * @RequiresSet @OnHookable @CanHookable
+     */
+    readonly condition: TCondition;
+    /**
+     * Whether the shortcut is enabled. Defaults to true.
+     *
+     * @RequiresSet @OnHookable @CanHookable
+     */
+    readonly enabled: boolean;
+    /**
+     * The chain of key chords that make up the shortcut. Note that this is NOT a unique identifier for shortcuts and cannot be used to compare them if you are making use of the when/context/active options.
+     *
+     * @RequiresSet @OnHookable @CanHookable
+     */
+    readonly chain: (Key["id"])[][];
+    /**
+     * It is sometimes useful for some shortcuts to not equal or conflict with eachother temporarily.
+     *
+     * Only methods that compare shortcut instances are affected.
+     *
+     * While the property is managed by the manager, it can be safely set then unset if not modifying anything.
+     *
+     * @RequiresSet @OnHookable @Managed
+     */
+    readonly forceUnequal: boolean;
+}
+export type Shortcuts<TEntries extends Shortcut[] = Shortcut[]> = {
+    /**
+     * The shortcut entries.
+     *
+     * To add/remove entries you should {@link addShortcut}/{@link removeShortcut} or {@link setShortcutsProp} with the synthetic `entries@add/remove` properties.
+     *
+     * The synthetic properties can be hooked into with {@link Manager.hooks}.
+     *
+     * @RequiresSet @OnHookable @Managed
+     */
+    readonly entries: TEntries;
+    /**
+     * For {@link doesShortcutConflictWith}.
+     *
+     * @experimental
+     * If this is true, the manager's context will be used to check conditions agains.
+     *
+     * Given all other conditions are equal, the shortcuts can only be in conflict if they both match the context. Note this means if neither match the context they are not considered to conflict (even though they might in another context). This is meant to be used when they both match the context, but some behavior had to be chosen for when they don't.
+     */
+    useContextInConflictCheck?: boolean;
+    /**
+     * For {@link doesShortcutConflictWith}.
+     *
+     * @experimental
+     * If this is true, modifier conflicts (e.g. `Ctrl` conflicts with `Ctrl+A`) will be ignored. You will need to figure out how to handle them manually.
+     */
+    ignoreModifierConflicts?: boolean;
+    /**
+     * For {@link doesShortcutConflictWith}.
+     *
+     * @experimental
+     * If this is true, partial chain conflicts (e.g. `Space` conflicts with `Space+A`) will be ignored. You will need to figure out how to handle them manually.
+     */
+    ignoreChainConflicts?: boolean;
+};
+export type RawShortcuts = Pick<Shortcuts, "entries"> & Partial<Shortcuts>;
+export type TriggerableShortcut = Shortcut & {
+    command: NonNullable<Command["name"]>;
+};
+type GetShortcutHooks<T extends keyof ShortcutSetEntries | keyof ShortcutsSetEntries> = T extends CanHookShortcutProps ? Partial<Pick<NonNullable<Manager["hooks"]>, "canSetShortcutProp" | "onSetShortcutProp">> : T extends OnHookShortcutProps ? Partial<Pick<NonNullable<Manager["hooks"]>, "onSetShortcutProp">> : T extends CanHookShortcutsProps ? Partial<Pick<NonNullable<Manager["hooks"]>, "canSetShortcutsProp" | "onSetShortcutsProp">> : Partial<Pick<NonNullable<Manager["hooks"]>, "onSetShortcutsProp">>;
+type BaseShortcutManager = Record<any, any>;
+export type ShortcutSetEntries = {
+    chain: {
+        val: Shortcut["chain"];
+        manager: BaseShortcutManager & PickManager<"options", "stringifier" | "sorter"> & Pick<Manager, "shortcuts" | "commands" | "keys">;
+        hooks: GetShortcutHooks<"chain">;
+        error: ChainError | typeof SHORTCUT_ERROR.DUPLICATE_KEY | typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT;
+    };
+    command: {
+        val: Shortcut["command"];
+        manager: BaseShortcutManager & PickManager<"options", "stringifier"> & Pick<Manager, "commands"> & Partial<Pick<Manager, "keys">>;
+        hooks: GetShortcutHooks<"command">;
+        error: typeof SHORTCUT_ERROR.UNKNOWN_COMMAND;
+    };
+    condition: {
+        val: Shortcut["condition"];
+        manager: never;
+        hooks: GetShortcutHooks<"condition">;
+        error: never;
+    };
+    enabled: {
+        val: Shortcut["enabled"];
+        manager: never;
+        hooks: GetShortcutHooks<"enabled">;
+        error: never;
+    };
+    forceUnequal: {
+        val: Shortcut["forceUnequal"];
+        manager: never;
+        hooks: GetShortcutHooks<"forceUnequal">;
+        error: never;
+    };
+};
+export type OnHookShortcutProps = "chain" | "command" | "condition" | "enabled" | "forceUnequal";
+export type CanHookShortcutProps = Exclude<OnHookShortcutProps, "forceUnequal">;
+export type SyntheticOnHookShortcutsProps = "entries@add" | "entries@remove";
+export type CanHookShortcutsProps = SyntheticOnHookShortcutsProps;
+export type OnHookShortcutsProps = SyntheticOnHookShortcutsProps;
+type BaseShortcutsManager = Pick<Manager, "keys" | "commands" | "shortcuts"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "stringifier"> & Record<any, any>;
+export type ShortcutsSetEntries = {
+    "entries@add": {
+        val: Shortcut;
+        hooks: GetShortcutHooks<`entries@add`>;
+        manager: BaseShortcutsManager & PickManager<"options", "sorter">;
+        error: typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT | typeof SHORTCUT_ERROR.UNKNOWN_COMMAND | ChainError;
+    };
+    "entries@remove": {
+        val: Shortcut;
+        hooks: GetShortcutHooks<`entries@remove`>;
+        manager: BaseShortcutsManager;
+        error: typeof SHORTCUT_ERROR.MISSING;
+    };
+};
+export {};

package/dist/types/utils.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/dist/utils/chainContainsSubset.d.ts

@@ -0,0 +1,27 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns whether a chain is a subset of another, taking into account variants (this can be disabled).
+ */
+export declare const chainContainsSubset: (chain: readonly string[][], chainSubset: readonly string[][], keys: Keys, { onlySubset, onlyPressable, allowVariants }?: {
+    /**
+     * If true, will return false if the last chord of the chainSubset is exactly equal.
+     *
+     * So for example, for the chain: [[a], [ctrl+b]], the following would return as follows:
+     *
+     * ```
+     * // true
+     * [[]] or []
+     * [[a]]
+     * [[a], []]
+     * [[a], [ctrl]]
+     * [[a], [b]]
+     *
+     * // false
+     * [[a], [ctrl, b]]
+     * ```
+     */
+    onlySubset?: boolean;
+    /** If true, will return false if the shortcut is not one key press away. */
+    onlyPressable?: boolean;
+    allowVariants?: boolean;
+}) => boolean;

package/dist/utils/chainContainsSubset.js

@@ -0,0 +1,45 @@
+import { containsKey } from "./containsKey.js";
+import { dedupeKeys } from "./dedupeKeys.js";
+import { equalsKeys } from "./equalsKeys.js";
+export const chainContainsSubset = (chain, chainSubset, keys, {
+  onlySubset = false,
+  onlyPressable = false,
+  allowVariants = true
+} = {}) => {
+  const opts = { allowVariants };
+  if (chainSubset.length === 0) {
+    const isEmpty = chain.length === 0 || chain.length === 1 && chain[0].length === 0;
+    if (isEmpty) return onlySubset;
+    return !onlyPressable || chain.length === 1 && chain[0].length === 1;
+  }
+  if (chainSubset.length > chain.length) return false;
+  const index = chainSubset.length === 0 ? 0 : chainSubset.length - 1;
+  const precedingChords = chainSubset.slice(0, index);
+  const precedingChordsEqual = index === 0 || equalsKeys(chain, precedingChords, keys, precedingChords.length, opts);
+  if (!precedingChordsEqual) return false;
+  if (onlyPressable && index !== chain.length - 1) return false;
+  const subsetLastChord = dedupeKeys(chainSubset[index], keys, opts);
+  const chainLastSharedChord = dedupeKeys(chain[index], keys, opts);
+  if (onlySubset) {
+    if (subsetLastChord.length === chainLastSharedChord.length) {
+      if (chainSubset.length === chain.length) return false;
+      if (chainSubset.length < chain.length) return true;
+    }
+  }
+  for (const key of subsetLastChord) {
+    if (!containsKey(chainLastSharedChord, key, keys, opts)) {
+      return false;
+    }
+  }
+  const subsetModifiers = subsetLastChord.filter((key) => keys.entries[key].isModifier);
+  const modifiers = chainLastSharedChord.filter((key) => keys.entries[key].isModifier);
+  const modKeysDiff = modifiers.length - subsetModifiers.length;
+  const subsetNonModKeysCount = subsetLastChord.length - subsetModifiers.length;
+  const nonModKeysCount = chainLastSharedChord.length - modifiers.length;
+  const nonModKeysDiff = nonModKeysCount - subsetNonModKeysCount;
+  if (onlySubset && modKeysDiff === 0 && nonModKeysDiff === 0) return false;
+  if (onlyPressable && !(modKeysDiff === 0 && nonModKeysDiff === 1 || modKeysDiff === 1 && nonModKeysDiff === 0)) {
+    return false;
+  }
+  return true;
+};

package/dist/utils/cloneChain.d.ts

@@ -0,0 +1,2 @@
+/** Deep clones a shortcut chain. */
+export declare function cloneChain(chain: string[][]): string[][];

package/dist/utils/cloneChain.js

@@ -0,0 +1,11 @@
+export function cloneChain(chain) {
+  const clone = [];
+  for (const chord of chain) {
+    const chordClone = [];
+    for (const key of chord) {
+      chordClone.push(key);
+    }
+    clone.push(chordClone);
+  }
+  return clone;
+}

package/dist/utils/cloneKey.d.ts

@@ -0,0 +1,3 @@
+import type { Key } from "../types/index.js";
+/** Deep clones a key. */
+export declare function cloneKey(key: Key): Key;

package/dist/utils/cloneKey.js

@@ -0,0 +1,26 @@
+export function cloneKey(key) {
+  const clone = {
+    type: key.type,
+    id: key.id,
+    label: key.label,
+    classes: [...key.classes],
+    x: key.x,
+    y: key.y,
+    width: key.width,
+    height: key.height,
+    enabled: key.enabled,
+    pressed: key.pressed,
+    isModifier: key.isModifier,
+    variants: key.variants ? [...key.variants] : void 0,
+    render: key.render,
+    updateStateOnAllEvents: key.updateStateOnAllEvents,
+    isToggle: key.isToggle,
+    ...key.isToggle ? {
+      toggleOnPressed: key.toggleOnPressed,
+      toggleOnId: key.toggleOnId,
+      toggleOffId: key.toggleOffId,
+      toggleOffPressed: key.toggleOffPressed
+    } : {}
+  };
+  return clone;
+}

package/dist/utils/containsKey.d.ts

@@ -0,0 +1,7 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns whether a shortcut's chain or chord contains the given key according to {@link equalsKey}.
+ */
+export declare function containsKey(chordOrChain: string[][] | string[], key: string, keys: Keys, opts?: {
+    allowVariants?: boolean;
+}): boolean;

package/dist/utils/containsKey.js

@@ -0,0 +1,4 @@
+import { equalsKey } from "./equalsKey.js";
+export function containsKey(chordOrChain, key, keys, opts = {}) {
+  return chordOrChain.flat().some((existing) => equalsKey(existing, key, keys, opts));
+}

package/dist/utils/dedupeKeys.d.ts

@@ -0,0 +1,9 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns a new array deduped according to {@link equalsKey}.
+ *
+ * This is useful when keys have variants to dedupe them by their variants since a shortcut might contain multiple variants, which can make it hard to check chords satisfy certain conditions (e.g. x amount of modifiers).
+ */
+export declare const dedupeKeys: (keyList: string[], keys: Keys, opts?: {
+    allowVariants?: boolean;
+}) => string[];

package/dist/utils/dedupeKeys.js

@@ -0,0 +1,9 @@
+import { equalsKey } from "./equalsKey.js";
+export const dedupeKeys = (keyList, keys, opts = {}) => {
+  const res = [];
+  for (const keyId of keyList) {
+    if (res.find((id) => equalsKey(id, keyId, keys, opts))) continue;
+    res.push(keyId);
+  }
+  return res;
+};

package/dist/utils/equalsKey.d.ts

@@ -0,0 +1,12 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns whether the key (b) passed is equal to key (a).
+ *
+ * To return true, their ids must be equal.
+ *
+ * There is an `allowVariants` option that is true by default that allows the keyB to be equal if any of their variants match.
+ *
+ */
+export declare function equalsKey(keyIdA: string, keyIdB: string, keys: Keys, { allowVariants }?: {
+    allowVariants?: boolean;
+}): boolean;

package/dist/utils/equalsKey.js

@@ -0,0 +1,13 @@
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js";
+export function equalsKey(keyIdA, keyIdB, keys, { allowVariants = true } = {}) {
+  const idsEqual = keyIdA === keyIdB;
+  const keyA = getKeyFromIdOrVariant(keyIdA, keys).unwrap()[0];
+  const keyB = getKeyFromIdOrVariant(keyIdB, keys).unwrap()[0];
+  if (!idsEqual && allowVariants && keyA.variants && keyB.variants) {
+    for (const variant of keyA.variants) {
+      if (keyB.variants.includes(variant)) return true;
+    }
+    return false;
+  }
+  return idsEqual;
+}

package/dist/utils/equalsKeys.d.ts

@@ -0,0 +1,24 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns if the given chords are equal.
+ *
+ * Can be passed a length, to limit the search to only the first x chords.
+ *
+ * ```ts
+ * equalsKeys([[keyA]], [[keyA]]) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA]]) // false
+ * equalsKeys([[keyA], [keyB]], [[keyA]], 1) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA], [keyB]], 2) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA], [keyB], [keyC]], 3) // false
+ * equalsKeys([[keyA], [keyB]], [[keyB]], 1) // false
+ * ```
+ * Can also pass options to {@link equalsKey}:
+ *
+ * ```ts
+ * equalsKeys([[keyA], [keyB]], [[keyAVariant], [keyB]], 2, { allowVariants: true }) // true
+ * ```
+ *
+ */
+export declare function equalsKeys(chain: readonly string[][], base: readonly string[][], keys: Keys, length?: number, opts?: {
+    allowVariants?: boolean;
+}): boolean;

package/dist/utils/equalsKeys.js

@@ -0,0 +1,15 @@
+import { containsKey } from "./containsKey.js";
+import { dedupeKeys } from "./dedupeKeys.js";
+export function equalsKeys(chain, base, keys, length, opts = {}) {
+  if (length === void 0 && base.length !== chain.length || length !== void 0 && (chain.length < length || base.length < length)) return false;
+  return chain.slice(0, length ?? chain.length).find((thisChord, c) => {
+    if (!base[c]) return true;
+    const otherChord = dedupeKeys(base[c], keys, opts);
+    thisChord = dedupeKeys(thisChord, keys, opts);
+    if (otherChord.length !== thisChord.length) return true;
+    for (const otherKey of otherChord) {
+      if (!containsKey(thisChord, otherKey, keys, opts)) return true;
+    }
+    return false;
+  }) === void 0;
+}