@witchcraft/spellcraft 0.0.1

package/dist/helpers/generateKeyShortcutMap.js

@@ -0,0 +1,64 @@
+import { last } from "@alanscodelog/utils/last";
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js";
+import { chainContainsSubset } from "../utils/chainContainsSubset.js";
+import { equalsKeys } from "../utils/equalsKeys.js";
+import { removeKeys } from "../utils/removeKeys.js";
+export function generateKeyShortcutMap(chain, shortcutsList, manager, postFilter) {
+  const obj = {};
+  const nextIsChord = manager.state.nextIsChord;
+  const isEmpty = chain.length === 0 || chain.length === 1 && chain?.[0].length === 0;
+  const index = isEmpty ? 0 : nextIsChord ? chain.length : chain.length - 1;
+  for (const shortcut of shortcutsList) {
+    const containsSubset = chainContainsSubset(shortcut.chain, chain, manager.keys, { onlySubset: true, onlyPressable: false });
+    const isPressed = equalsKeys(shortcut.chain, chain, manager.keys);
+    if (!containsSubset && !isPressed) continue;
+    const keysLeftInChord = removeKeys(shortcut.chain[index] ?? [], chain[index] ?? [], manager.keys).map((_) => getKeyFromIdOrVariant(_, manager.keys).unwrap()[0]);
+    const isPressableChord = keysLeftInChord.length === 1;
+    const isPressable = isPressableChord && shortcut.chain.length - 1 === index;
+    const isPressableChain = isPressableChord && shortcut.chain.length - 1 > index;
+    const unpressedModifiers = keysLeftInChord.length > 1 ? keysLeftInChord.filter((_) => _.isModifier) : [];
+    const hasUnpressedModifiers = unpressedModifiers.length > 0;
+    if (!isPressable && !isPressableChain && !isPressed && unpressedModifiers.length <= 0) continue;
+    const pressableKeys = isPressed ? (last(shortcut.chain) ?? []).map((_) => getKeyFromIdOrVariant(_, manager.keys).unwrap()[0]) : unpressedModifiers.length === 0 ? keysLeftInChord : [];
+    const entry = {
+      shortcut,
+      isPressed,
+      isPressable,
+      isPressableChain,
+      hasUnpressedModifiers
+    };
+    if (postFilter !== void 0 && !postFilter(entry, { unpressedModifiers, pressableKeys, isPressed, containsSubset })) continue;
+    if (!hasUnpressedModifiers || isPressed) {
+      for (const k of pressableKeys) {
+        if (k.render) {
+          obj[k.id] ??= {
+            pressableEntries: [],
+            modifierEntries: [],
+            containsConflicting: false,
+            isModifierHint: false
+          };
+          if (!obj[k.id].containsConflicting) {
+            const containsConflicting = obj[k.id].pressableEntries.some((_) => _.isPressable || _.isPressableChain);
+            obj[k.id].containsConflicting = containsConflicting;
+          }
+          obj[k.id].pressableEntries.push({ ...entry });
+        }
+      }
+    }
+    if (!isPressed && !isPressable && !isPressableChain) {
+      for (const k of unpressedModifiers) {
+        if (k.render) {
+          obj[k.id] ??= {
+            pressableEntries: [],
+            modifierEntries: [],
+            containsConflicting: false,
+            isModifierHint: false
+          };
+          obj[k.id].modifierEntries.push({ ...entry });
+          obj[k.id].isModifierHint ||= true;
+        }
+      }
+    }
+  }
+  return obj;
+}

package/dist/helpers/getKeyFromEventCode.d.ts

@@ -0,0 +1,15 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import { type Key, SHORTCUT_ERROR } from "../types/index.js";
+export declare function getKeyFromEventCode(code: string, e: {
+    code: string;
+} | {
+    key: string;
+} | {
+    button: number;
+} | {
+    deltaY: number;
+}, keys: Record<string, Key>, { pressedState: pressState, includeDisabled }?: {
+    includeDisabled?: boolean;
+    pressedState?: boolean;
+}): Result<string[], KnownError<typeof SHORTCUT_ERROR.UNKNOWN_KEY_EVENT>>;

package/dist/helpers/getKeyFromEventCode.js

@@ -0,0 +1,36 @@
+import { Err, Ok } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+export function getKeyFromEventCode(code, e, keys, {
+  pressedState: pressState,
+  includeDisabled = false
+} = {}) {
+  const keyIds = [];
+  const disabledIds = [];
+  for (const key of Object.values(keys)) {
+    if ((pressState === void 0 ? true : key.pressed === pressState) && (key.id === code || key.variants?.includes(code))) {
+      if (key.enabled) {
+        keyIds.push(key.id);
+      } else if (!key.enabled) {
+        if (includeDisabled) {
+          keyIds.push(key.id);
+        } else {
+          disabledIds.push(key.id);
+        }
+      }
+    }
+  }
+  if (keyIds.length === 0 && disabledIds.length === 0) {
+    const withCode = "code" in e && e.code !== void 0 ? `code: ${e.code}` : void 0;
+    const withKey = "key" in e && e.key !== void 0 ? `key: ${e.key}` : void 0;
+    const withButton = "button" in e && e.button !== void 0 ? `button: ${e.button}` : void 0;
+    const withDeltaY = "deltaY" in e && e.deltaY !== void 0 ? `deltaY: ${e.deltaY}` : void 0;
+    const info = [withCode, withKey, withButton, withDeltaY].filter((_) => _ !== "undefined").join(", ");
+    return Err(new KnownError(
+      SHORTCUT_ERROR.UNKNOWN_KEY_EVENT,
+      `An unknown key (${info}) was pressed.`,
+      { e, button: withButton, code: withCode, key: withKey, deltaY: withDeltaY }
+    ));
+  }
+  return Ok(keyIds);
+}

package/dist/helpers/getKeyFromIdOrVariant.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import { type Key, type Keys, SHORTCUT_ERROR } from "../types/index.js";
+export declare function getKeyFromIdOrVariant(id: string, keys: Keys): Result<Key[], KnownError<typeof SHORTCUT_ERROR.UNKNOWN_KEY_ID>>;

package/dist/helpers/getKeyFromIdOrVariant.js

@@ -0,0 +1,26 @@
+import { isArray } from "@alanscodelog/utils/isArray";
+import { Err, Ok } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+export function getKeyFromIdOrVariant(id, keys) {
+  let k = keys.entries[id] ?? keys.toggles[id];
+  if (k === void 0) {
+    if (keys.variants[id]) {
+      const variants = [];
+      for (const variant of keys.variants[id]) {
+        const v = keys.entries[variant] ?? keys.toggles[variant];
+        if (v !== void 0) variants.push(v);
+      }
+      if (variants.length > 0) k = variants;
+    }
+  }
+  if (!isArray(k) && k !== void 0) k = [k];
+  if (k === void 0) {
+    return Err(new KnownError(
+      SHORTCUT_ERROR.UNKNOWN_KEY_ID,
+      `Tried to get unknown key (${id}).`,
+      { id }
+    ));
+  }
+  return Ok(k);
+}

package/dist/helpers/getKeyboardLayoutMap.d.ts

@@ -0,0 +1,5 @@
+import type { KeyboardLayoutMap } from "../types/general.js";
+/**
+ * Safely get the [KeyboardLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardLayoutMap) with [navigator.getLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/navigator.getLayoutMap).
+ */
+export declare function getKeyboardLayoutMap(): Promise<KeyboardLayoutMap | undefined>;

package/dist/helpers/getKeyboardLayoutMap.js

@@ -0,0 +1,7 @@
+export async function getKeyboardLayoutMap() {
+  if (typeof navigator !== "undefined" && "keyboard" in navigator) {
+    return navigator.keyboard.getLayoutMap();
+  } else {
+    return void 0;
+  }
+}

package/dist/helpers/getLabel.d.ts

@@ -0,0 +1,9 @@
+import type { Key } from "../types/index.js";
+/**
+    * Returns the label, adding an `(On)` or `(Off)` suffix to any toggle keys.
+    *
+    * If the key has not label, uses the id
+    *
+    * Used by the {@link defaultStringifier}
+    */
+export declare function getLabel(id: string | undefined, key: Key): string;

package/dist/helpers/getLabel.js

@@ -0,0 +1,6 @@
+export function getLabel(id, key) {
+  const name = key.label ?? key.id;
+  if (id === key.toggleOnId) return `${name} (On)`;
+  if (id === key.toggleOffId) return `${name} (Off)`;
+  return name;
+}

package/dist/helpers/getTriggerableShortcut.d.ts

@@ -0,0 +1,6 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import type { Manager, PickManager, TriggerableShortcut } from "../types/index.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+/** Gets all triggerable shortcuts in a manager. */
+export declare function getTriggerableShortcut(manager: Pick<Manager, "shortcuts" | "keys" | "context" | "commands"> & PickManager<"options", "stringifier" | "evaluateCondition"> & PickManager<"state", "chain" | "isRecording">): Result<false | TriggerableShortcut, KnownError<typeof SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS>>;

package/dist/helpers/getTriggerableShortcut.js

@@ -0,0 +1,25 @@
+import { crop } from "@alanscodelog/utils/crop";
+import { indent } from "@alanscodelog/utils/indent";
+import { Err, Ok } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import { shortcutIsTriggerableBy } from "./shortcutIsTriggerableBy.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+export function getTriggerableShortcut(manager) {
+  const s = manager.options.stringifier;
+  if (manager.state.isRecording) return Ok(false);
+  const shortcuts = manager.shortcuts.entries.filter((shortcut) => shortcutIsTriggerableBy(manager.state.chain, shortcut, manager));
+  if (shortcuts.length === 0) return Ok(false);
+  if (shortcuts.length > 1) {
+    return Err(new KnownError(
+      SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS,
+      crop`
+				Multiple commands are assigned to the key combination ${s.stringify(manager.state.chain, manager)}:
+
+				${indent(s.stringifyList("shortcuts", shortcuts, manager), 4)}
+			`,
+      { shortcuts }
+    ));
+  } else {
+    return Ok(shortcuts[0]);
+  }
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,28 @@
+export { calculateAndSetPositionAndSize } from "./calculateAndSetPositionAndWidth.js";
+export { calculateLayoutSize } from "./calculateLayoutSize.js";
+export { doesShortcutConflict } from "./doesShortcutConflict.js";
+export { equalsCommand } from "./equalsCommand.js";
+export { equalsContext } from "./equalsContext.js";
+export { equalsShortcut } from "./equalsShortcut.js";
+export { forceClear } from "./forceClear.js";
+export { forceUpdateNativeKeysState } from "./forceUpdateNativeKeysState.js";
+export { generateKeyShortcutMap } from "./generateKeyShortcutMap.js";
+export { getKeyboardLayoutMap } from "./getKeyboardLayoutMap.js";
+export { getKeyFromEventCode } from "./getKeyFromEventCode.js";
+export { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js";
+export { getLabel } from "./getLabel.js";
+export { getTriggerableShortcut } from "./getTriggerableShortcut.js";
+export { isValidManager } from "./isValidManager.js";
+export { isValidShortcut } from "./isValidShortcut.js";
+export { KnownError } from "./KnownError.js";
+export { labelWithEvent } from "./labelWithEvent.js";
+export { labelWithKeyboardMap } from "./labelWithKeyboardMap.js";
+export { managerToStorableClone } from "./managerToStorableClone.js";
+export { onKeyboardLayoutChange } from "./onKeyboardLayoutChange.js";
+export { safeSetManagerChain } from "./safeSetManagerChain.js";
+export { shortcutCanExecuteIn } from "./shortcutCanExecuteIn.js";
+export { shortcutIsTriggerableBy } from "./shortcutIsTriggerableBy.js";
+export { shortcutSwapChords } from "./shortcutSwapChords.js";
+export { virtualPress } from "./virtualPress.js";
+export { virtualRelease } from "./virtualRelease.js";
+export { virtualToggle } from "./virtualToggle.js";

package/dist/helpers/index.js

@@ -0,0 +1,28 @@
+export { calculateAndSetPositionAndSize } from "./calculateAndSetPositionAndWidth.js";
+export { calculateLayoutSize } from "./calculateLayoutSize.js";
+export { doesShortcutConflict } from "./doesShortcutConflict.js";
+export { equalsCommand } from "./equalsCommand.js";
+export { equalsContext } from "./equalsContext.js";
+export { equalsShortcut } from "./equalsShortcut.js";
+export { forceClear } from "./forceClear.js";
+export { forceUpdateNativeKeysState } from "./forceUpdateNativeKeysState.js";
+export { generateKeyShortcutMap } from "./generateKeyShortcutMap.js";
+export { getKeyboardLayoutMap } from "./getKeyboardLayoutMap.js";
+export { getKeyFromEventCode } from "./getKeyFromEventCode.js";
+export { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js";
+export { getLabel } from "./getLabel.js";
+export { getTriggerableShortcut } from "./getTriggerableShortcut.js";
+export { isValidManager } from "./isValidManager.js";
+export { isValidShortcut } from "./isValidShortcut.js";
+export { KnownError } from "./KnownError.js";
+export { labelWithEvent } from "./labelWithEvent.js";
+export { labelWithKeyboardMap } from "./labelWithKeyboardMap.js";
+export { managerToStorableClone } from "./managerToStorableClone.js";
+export { onKeyboardLayoutChange } from "./onKeyboardLayoutChange.js";
+export { safeSetManagerChain } from "./safeSetManagerChain.js";
+export { shortcutCanExecuteIn } from "./shortcutCanExecuteIn.js";
+export { shortcutIsTriggerableBy } from "./shortcutIsTriggerableBy.js";
+export { shortcutSwapChords } from "./shortcutSwapChords.js";
+export { virtualPress } from "./virtualPress.js";
+export { virtualRelease } from "./virtualRelease.js";
+export { virtualToggle } from "./virtualToggle.js";

package/dist/helpers/isValidManager.d.ts

@@ -0,0 +1,3 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import { type ChainError, type Manager, type MultipleErrors, SHORTCUT_ERROR } from "../types/index.js";
+export declare function isValidManager(manager: Manager): Result<true, MultipleErrors<ChainError | typeof SHORTCUT_ERROR.INVALID_MANAGER | typeof SHORTCUT_ERROR.UNKNOWN_COMMAND>>;

package/dist/helpers/isValidManager.js

@@ -0,0 +1,20 @@
+import { Err, Ok } from "@alanscodelog/utils/Result";
+import { isValidShortcut } from "./isValidShortcut.js";
+import { KnownError } from "./KnownError.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+export function isValidManager(manager) {
+  const required = ["shortcuts", "keys", "commands"];
+  if (required.some((key) => manager[key] === void 0)) {
+    return Err(new KnownError(
+      SHORTCUT_ERROR.INVALID_MANAGER,
+      "Manager is missing required properties.",
+      { keys: Object.keys(manager) }
+    ));
+  }
+  let res;
+  for (const shortcut of manager.shortcuts.entries) {
+    res = isValidShortcut(shortcut, manager);
+    if (res.isError) return res;
+  }
+  return Ok(true);
+}

package/dist/helpers/isValidShortcut.d.ts

@@ -0,0 +1,3 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import type { ChainError, Manager, MultipleErrors, PickManager, Shortcut, SHORTCUT_ERROR } from "../types/index.js";
+export declare function isValidShortcut(shortcut: Shortcut, manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "stringifier" | "sorter">): Result<true, MultipleErrors<ChainError | typeof SHORTCUT_ERROR.UNKNOWN_COMMAND>>;

package/dist/helpers/isValidShortcut.js

@@ -0,0 +1,10 @@
+import { Ok } from "@alanscodelog/utils/Result";
+import { isValidChain } from "../internal/isValidChain.js";
+import { isValidCommand } from "../internal/isValidCommand.js";
+export function isValidShortcut(shortcut, manager) {
+  const resCommandsValid = isValidCommand(shortcut.command, manager, shortcut);
+  if (resCommandsValid.isError) return resCommandsValid;
+  const resChainValid = isValidChain(shortcut.chain, manager);
+  if (resChainValid.isError) return resChainValid;
+  return Ok(true);
+}

package/dist/helpers/labelWithEvent.d.ts

@@ -0,0 +1,13 @@
+import type { AnyInputEvent, KeySetEntries, LabelOptions, Manager, MinimalInputEvent, PickManager } from "../types/index.js";
+/**
+ * Labels keys using events.
+ *
+ * For keys uses `KeyboardEvent.key`. For mouse buttons it will label them `Button x` where x is `MouseEvent.button`, and for the mouse wheel, `WheelEvent.deltaY` is used to label them `Wheel Up`/`Wheel Down`.
+ *
+ * This is intended to be used for labeling keys as they are pressed or as a fallback to {@link labelWithKeyboardMap}. See it for the recommended labeling strategy.
+ *
+ * A filter can be provided to avoid labeling some keys.
+ */
+export declare function labelWithEvent<T extends MinimalInputEvent | AnyInputEvent = MinimalInputEvent | AnyInputEvent, THooks extends KeySetEntries["label"]["hooks"] = KeySetEntries["label"]["hooks"]>(e: T, keyIds: string[], manager: Pick<Manager, "keys"> & PickManager<"options", "stringifier"> & {
+    hooks?: THooks;
+}, options?: Partial<Omit<LabelOptions, "map">>): string[];

package/dist/helpers/labelWithEvent.js

@@ -0,0 +1,20 @@
+import { setKeyProp } from "../core/setKeyProp.js";
+export function labelWithEvent(e, keyIds, manager, options = {}) {
+  const set = [];
+  for (const id of keyIds) {
+    let label = "";
+    if ("deltaY" in e) {
+      label = e.deltaY < 0 ? "Wheel Up" : "Wheel Down";
+    } else if ("button" in e) {
+      label = `Button ${e.button}`;
+    } else if ("key" in e) {
+      label = e.key;
+    }
+    if (!options.labelFilter || options.labelFilter(e, id, label, manager.keys)) {
+      const key = manager.keys.entries[id];
+      set.push(key.id);
+      setKeyProp(key, "label", label, manager);
+    }
+  }
+  return set;
+}

package/dist/helpers/labelWithKeyboardMap.d.ts

@@ -0,0 +1,15 @@
+import type { KeySetEntries, LabelOptions, Manager } from "../types/index.js";
+/**
+ * Labels keys using the experimental navigator keyboard [map](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardLayoutMap) (you can get it using {@link getKeyboardLayoutMap} which safely gets it if it's available, otherwise you can use [navigator.getLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/navigator.getLayoutMap)).
+ *
+ * It will check for the key in the map first by the id, then by their variants.
+ *
+ *It returns a list of key ids that were set.
+ *
+ * Note that not all keys can be auto labeled with the navigator. Modifier keys and some other keys are not available.
+ *
+ * You can use {@link labelWithEvent} as a fallback, by using it with a filter and only labeling the keys that were not set by this function.
+ */
+export declare function labelWithKeyboardMap<THooks extends KeySetEntries["label"]["hooks"]>(manager: Pick<Manager, "keys"> & {
+    hooks?: THooks;
+}, opts: LabelOptions): string[];

package/dist/helpers/labelWithKeyboardMap.js

@@ -0,0 +1,17 @@
+import { setKeyProp } from "../core/setKeyProp.js";
+export function labelWithKeyboardMap(manager, opts) {
+  const set = [];
+  for (const key of Object.values(manager.keys.entries)) {
+    const codes = [key.id, ...key.variants ?? []];
+    for (const code of codes) {
+      const label = opts.map.get(code);
+      if (label) {
+        if (!opts.labelFilter || opts.labelFilter({ key: label }, key.id, label, manager.keys)) {
+          setKeyProp(key, "label", label, manager);
+          set.push(key.id);
+        }
+      }
+    }
+  }
+  return set;
+}

package/dist/helpers/managerToStorableClone.d.ts

@@ -0,0 +1,12 @@
+import type { DeepPartial } from "@alanscodelog/utils/types";
+import type { Manager } from "../types/index.js";
+/**
+ * Strips the manager of properties that should not be saved such as `hooks`, `listener`, `state`, and the following function options:
+ *
+ * - `evaluateCondition`
+ * - `cb`
+ * - `sorter`
+ * - `stringifier`
+ * - `conditionEquals`
+ */
+export declare function managerToStorableClone(m: Manager): DeepPartial<Manager>;

package/dist/helpers/managerToStorableClone.js

@@ -0,0 +1,13 @@
+import { walk } from "@alanscodelog/utils/walk";
+export function managerToStorableClone(m) {
+  const clone = walk(m, void 0, { save: true });
+  delete clone.hooks;
+  delete clone.listener;
+  delete clone.state;
+  delete clone.options.evaluateCondition;
+  delete clone.options.cb;
+  delete clone.options.sorter;
+  delete clone.options.stringifier;
+  delete clone.options.conditionEquals;
+  return clone;
+}

package/dist/helpers/onKeyboardLayoutChange.d.ts

@@ -0,0 +1,10 @@
+/**
+    * The spec describes a ["layoutchange" event](https://wicg.github.io/keyboard-map/#layoutchange-event) that can be added to the navigator.keyboard.
+    *
+    * I have not found a browser that implements it.
+    *
+    * But this should safely attach to the event if it exists and call the given callback if it does.
+    *
+    * It will return true if it managed to attach.
+    */
+export declare function onKeyboardLayoutChange(cb: () => void | Promise<void>): boolean;

package/dist/helpers/onKeyboardLayoutChange.js

@@ -0,0 +1,7 @@
+export function onKeyboardLayoutChange(cb) {
+  if (typeof navigator !== "undefined" && "keyboard" in navigator && "addEventListener" in navigator.keyboard) {
+    navigator.keyboard.addEventListener(cb);
+    return true;
+  }
+  return false;
+}

package/dist/helpers/safeSetManagerChain.d.ts

@@ -0,0 +1,20 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import type { Manager, ManagerSetEntries, MultipleErrors } from "../types/index.js";
+/**
+    * Safely sets the manager's chain.
+    *
+    * Note that it might seem to do odd things to keep the state consistant and prevent us from getting into invalid states or triggering shorcuts when we shouldn't. Some of these include:
+    * 	- If the new chain would trigger a shortcut, the shortcut will be synthetically triggered with a keyup.
+ * 	- If the manager is {@link Manager.state.isAwaitingKeyup} to trigger anything ({@link Manager.state.untrigger}), the shortcut will be synthetically triggered with a keyup.
+ * 	- If there are still non-modifier keys being pressed, the manager will wait until they are all released before allowing keys to be added to the chained again.
+ * 	- Modifiers will stay in the first chord if they are still being pressed according to {@link Key.press}. This makes it possible for the user to trigger multiple shortcuts without releasing a modifier.  This can result in potentially strange behavior for shortcuts longer than one chord, as further chords can be started without releasing the modifiers. If you don't like this, you can pass `{preserveModifiers: false}` to force the user to release the modifiers.
+ * 	- If there are still modifier keys being pressed, the manager will add them to the last chord, unless you pass `preserverModifiers: false`.
+ *		- **If keys are currently being held ({@link Key.pressed} is true), note that the manager's state and the key state state may not match. This is usually not a problem with normal key presses, but... **
+ * 	- If using virtualPress/virtualToggle, the keys might remain pressed, potentially causing issues. In those cases you can use the {@link Manager.listener} to keep track of whether keys are virtually pressed or not (virtually pressed keys have no events), and unpress the ones you should.
+ * 	- Setting a `[]` chain is slightly different than setting a `[[]]` chain to keep the behavior of the manager consistent on the next key press.
+ * 		- When you set `[]`, the function will also set {@link Manager.state.nextIsChord} to `true`, so it knows to insert a chord on the next key press.
+ * 		- When you set `[[]]`, it will set it to `false`, since the chord already exists.
+ */
+export declare function safeSetManagerChain(manager: Manager, chain: string[][], { preserveModifiers }?: {
+    preserveModifiers?: boolean;
+}): Result<string[][], MultipleErrors<ManagerSetEntries["state.chain"]["error"]>>;

package/dist/helpers/safeSetManagerChain.js

@@ -0,0 +1,37 @@
+import { pushIfNotIn } from "@alanscodelog/utils";
+import { last } from "@alanscodelog/utils/last";
+import { Ok } from "@alanscodelog/utils/Result";
+import { setManagerProp } from "../core/setManagerProp.js";
+import { checkTrigger } from "../internal/checkTrigger.js";
+import { checkUntrigger } from "../internal/checkUntrigger.js";
+import { getPressedModifierKeys } from "../internal/getPressedModifierKeys.js";
+import { getPressedNonModifierKeys } from "../internal/getPressedNonModifierKeys.js";
+import { inChain } from "../internal/inChain.js";
+import { cloneChain } from "../utils/cloneChain.js";
+export function safeSetManagerChain(manager, chain, { preserveModifiers = true } = {}) {
+  const newChain = cloneChain(chain);
+  if (getPressedNonModifierKeys(manager).length > 0) {
+    setManagerProp(manager, "state.isAwaitingKeyup", true, { check: false });
+  }
+  const pressedModifiers = getPressedModifierKeys(manager);
+  if (preserveModifiers && pressedModifiers.length > 0) {
+    if (newChain.length > 0) {
+      pushIfNotIn(last(newChain), pressedModifiers);
+    } else {
+      newChain.push(pressedModifiers);
+    }
+  }
+  const can = setManagerProp(manager, "state.chain", newChain, { check: "only" });
+  if (can.isError) return can;
+  checkUntrigger(manager);
+  setManagerProp(manager, "state.chain", newChain).unwrap();
+  const isEmpty = newChain.length === 0 || newChain.length === 1 && newChain?.[0].length === 0;
+  if (!isEmpty) {
+    setManagerProp(manager, "state.nextIsChord", inChain(manager), { check: false });
+    checkTrigger(manager);
+    checkUntrigger(manager);
+  } else {
+    setManagerProp(manager, "state.nextIsChord", newChain.length === 0, { check: false });
+  }
+  return Ok(manager.state.chain);
+}

package/dist/helpers/shortcutCanExecuteIn.d.ts

@@ -0,0 +1,4 @@
+import type { Manager, PickManager, Shortcut } from "../types/index.js";
+export declare function shortcutCanExecuteIn(shortcut: Shortcut, manager: Pick<Manager, "context" | "commands"> & PickManager<"options", "evaluateCondition">, { allowEmptyCommand }?: {
+    allowEmptyCommand?: boolean;
+}): boolean;

package/dist/helpers/shortcutCanExecuteIn.js

@@ -0,0 +1,9 @@
+export function shortcutCanExecuteIn(shortcut, manager, {
+  allowEmptyCommand = false
+} = {}) {
+  const context = manager.context;
+  const commands = manager.commands;
+  const evaluateCondition = manager.options.evaluateCondition;
+  const fullCommand = shortcut.command ? commands.entries[shortcut.command] : void 0;
+  return shortcut.enabled && (allowEmptyCommand && fullCommand?.execute === void 0 || fullCommand !== void 0 && evaluateCondition(fullCommand?.condition, context)) && shortcut.condition !== void 0 && evaluateCondition(shortcut.condition, context);
+}

package/dist/helpers/shortcutIsTriggerableBy.d.ts

@@ -0,0 +1,2 @@
+import type { Manager, PickManager, Shortcut } from "../types/index.js";
+export declare function shortcutIsTriggerableBy(chain: string[][], shortcut: Shortcut, manager: Pick<Manager, "context" | "commands" | "keys"> & PickManager<"options", "evaluateCondition">): boolean;

package/dist/helpers/shortcutIsTriggerableBy.js

@@ -0,0 +1,5 @@
+import { shortcutCanExecuteIn } from "./shortcutCanExecuteIn.js";
+import { equalsKeys } from "../utils/equalsKeys.js";
+export function shortcutIsTriggerableBy(chain, shortcut, manager) {
+  return shortcutCanExecuteIn(shortcut, manager, { allowEmptyCommand: true }) && equalsKeys(shortcut.chain, chain, manager.keys, void 0, { allowVariants: true });
+}

package/dist/helpers/shortcutSwapChords.d.ts

@@ -0,0 +1,75 @@
+import { type Result } from "@alanscodelog/utils/Result";
+import { KnownError } from "./KnownError.js";
+import type { Manager, PickManager, Shortcut, Shortcuts } from "../types/index.js";
+import { SHORTCUT_ERROR } from "../types/index.js";
+/**
+ * Swaps the given chords for all matching shortcuts.
+ *
+ * This is done by using forceUnequal for each set of matching shortcuts in turn.
+ *
+ * EXAMPLES:
+ *
+ * Given the following shortcuts:
+ *
+ * ```
+ * 1 A
+ * 1 B
+ * 2 C
+ * 2 D
+ * ```
+ *
+ * `swapChords([[1]], [[2]])` would result in:
+ *
+ * ```
+ * 2 A
+ * 2 B
+ * 1 C
+ * 1 D
+ * ```
+ *
+ * Multiple chords, and chords of unequal lengths can be safely swapped.
+ *
+ * ```
+ * 1 2 A
+ * 1 2 B
+ * 3 C
+ * 3 D
+ * ```
+ *
+ * `swapChords([[1], [2]], [[3]])`:
+ * ```
+ * 3 A
+ * 3 B
+ * 1 2 C
+ * 1 2 D
+ * ```
+ *
+ * A filter function is provided, to, for example, filter out disabled entries from the swap. Note that it might be unsafe to swap entries with a filter if the new entries can be equal to the ignored ones, hence why the `check` exists.
+ *
+ * Example of how it might be a problem:
+ * ```
+ * A
+ * B
+ * ```
+ * `shortcutSwapChords([[A]], [[B]], () => { filter that ignores A })` would result in two A shortcuts.
+ *
+ * But if, for example, you use the filter to ignore disabled shortcuts, this wouldn't be a problem because you'd get two unequal shortcuts (A and A(disabled)), though re/dis-abling one of them would trigger a conflict.
+ *
+ * Note: Certain types of chords cannot be swapped, like empty chords, or chords which share a base.
+ *
+ * If using the experimental {@link ignoreModifierConflicts  Shortcuts["ignoreModifierConflicts"]}, note that you cannot use this to swap the base modifiers.
+ *
+ * For example, say you had:
+ * ```
+ * Ctrl+A
+ *	Ctrl
+ * ```
+ * If you do `swapChords([Ctrl],[Shift])`, `Ctrl+A` is not considered to match the `[Ctrl]` chord and you will get:
+ * ```
+ * Ctrl+A
+ *	Shift
+ * ```
+ */
+export declare function shortcutSwapChords(shortcuts: Shortcuts, chainA: string[][], chainB: string[][], manager: Pick<Manager, "keys" | "shortcuts" | "commands"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter">, { check }?: {
+    check?: boolean | "only";
+}, filter?: (shortcut: Shortcut) => boolean): Result<true, KnownError<typeof SHORTCUT_ERROR.INVALID_SWAP_CHORDS | typeof SHORTCUT_ERROR.INVALID_SWAP_CHORDS | typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT> | Error>;