@witchcraft/spellcraft 0.0.4 → 0.2.0

package/README.md

@@ -123,7 +123,7 @@ You can choose in your execute function what exactly to do at that point for bot
 
 If non-modifier keys are still being held at this point, the manager will not allow triggering a shortcut until they are released (see `state.isAwaitingKeyup`). Modifiers are not affect by this. We usually want the user to be able to keep the modifier pressed and do, for example, `Ctrl+B` then `Ctrl+I` to bold and italicize text, without having to release `Ctrl`, only `B` and `I`.
 
-## Errors and `{check}` Option
+## Errors and Checking if Actions can be Performed
 
 Note the use of `unwrap()`. Because many actions can throw "soft" errors, to better help deal with all the errors the library uses a Result monad in most of the return types. `unwrap` is like rust's unwrap and will throw the error if there was one, otherwise "unwrap" and return the value within. 
 
@@ -278,12 +278,58 @@ export { }
 ```
 
 Additionally, when you create a condition, you can pass a function to `parse` it and add these needed properties:
+
+You'll probably want to create a wrapping function to do this. Here's an example with the expressit library:
+
+
+<details>
+
+<summary>Click to Expand</summary>
+
 ```ts
-const condition = createCondition("a || b ", (_) => {
-	_.ast = parse(_.text)
+import { ShortcutContextParser } from "@witchcraft/expressit/examples/ShortcutContextParser"
+import { createCondition as _createCondition } from "@witchcraft/spellcraft"
+
+const dummyContext = { a: { }, b: { c: {} } }
+const shortcutParser = new ShortcutContextParser(dummyContext) // see docs for details
+function parser(text: string, _: Condition) {
+	const res = shortcutsParser.parse(text)
+	// === undefined is to narrow out the ErrorToken type
+	if (!res.valid || res.type === undefined) {
+		throw new Error(`Shortcut context parser failed to parse condition ${_.text}`)
+	}
+
+	_.ast = res
 	return _
+}
+
+/** Creates a condition with the ast saved in it. */
+function createCondition(text: string) {
+	return _createCondition(text, parser)
+}
+const condition = createCondition("a || b")
+condition.ast // should exist
+
+// tell the manager how to evaluare the condition:
+const manager = createmanager({
+	context: createcontext<context<map<string, boolean>>>(new map()),
+	options: {
+		evaluatecondition(condition, context) {
+			if (condition.ast === undefined) throw new Error("condition ast is undefined")
+
+			const res = condition.ast.valid 
+				? conditionParser.evaluate(
+					conditionParser.normalize(condition.ast),
+					context.value.isActive
+				) 
+				: false 
+			return res
+		},
+	}
 })
+
 ```
+</details>
 
 ## Contexts
 
@@ -292,10 +338,10 @@ Similarly with contexts, you can use any sort of object or type that you like.
 You can tell the manager it's type when you create it. For example, say we wanted to use a map:
 
 ```ts
-const manager = createManager({
-	context: createContext<Context<Map<string, boolean>>>(new Map()),
+const manager = createmanager({
+	context: createcontext<context<map<string, boolean>>>(new map()),
 	options: {
-		evaluateCondition(condition, context) {
+		evaluatecondition(condition, context) {
 			// context is now correctly typed
 			return context.value.has(condition.text)
 		},
@@ -308,10 +354,10 @@ const manager = createManager({
 Creating a shortcut requires a the key/commands we created and the manager options to create a valid shortcut.
 
 ```ts
-const shortcut =createShortcut({
+const shortcut = createShortcut({
 	command: "test",
 	chain: [["a"]],
-	condition: createCondition("a || b", true),
+	condition: createCondition("a || b"),
 	enabled: true,
 }, {options, keys, commands}).unwrap()
 
@@ -379,6 +425,10 @@ Note that while the built in errors are property specific, custom errors are not
 
 A helper class `ShortcutManagerManager` is provided to help manage multiple managers.
 
+<details>
+
+<summary>Click to Expand</summary>
+
 ```ts
 import { ShortcutManagerManager } from "@witchcraft/spellcraft"
 
@@ -435,6 +485,9 @@ managerManager.duplicateManager("myManagerName", "myDuplicateManagerName")
 managerManager.deleteManager("myManagerName")
 managerManager.renameManager("myManagerName", "myNewManagerName")
 ```
+
+</details>
+
 You can then use the active manager's `onSet*Prop` hooks to call debouncedSave. You can wrap only the active manager to intercept all it's `onSet*Prop` calls. See the `useMultipleManagers` composable in the demo.
 
 ## Other Helpers and Utilities
@@ -453,6 +506,7 @@ There are many helpers provided to simplify common use cases under `/helpers`. S
 There's also some smaller utility functions in `/utils`:
 - `equals/dedupe/clone/*Key` These are particularly important for manipulating chords. This is because keys which are variants of eachother (see `Key.variants`) do not have matching ids and we usually want to be able to dedupe by the variants as well. 
 - `isAny/Trigger/Wheel/MouseKey`.
+- `getKeyCodesFromKeys` for getting the raw key codes from a list of keys for use with third-party libraries.
 
 
 There's also a few other functions that in the future might be moved from the demo were I created them and into the library. See [demo/src/common](https://github.com/AlansCodeLog/spellcraft/tree/master/demo/src/common).
@@ -490,18 +544,28 @@ Under gnome at least, if a key (usually Ctrl) is set to locate the cursor, it wi
 
 # FAQ 
 
-## Browser shortcuts interfere with certain shortcuts, how can this be avoided?
+
+<details>
+
+<summary>Browser shortcuts interfere with certain shortcuts, how can this be avoided?</summary>
 
 You can use a listener on the manager to e.preventDefault() some of these, but this doesn't work for all of them.
 
 If available you can also try using the [Keyboard API's](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API) lock method (see [Keyboard Locking](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API#keyboard_locking) ).
 
-## How to label keys with their local names?
+</details>
+
+<details>
+
+<summary>How to label keys with their local names?</summary>
 
 If the [Keyboard API](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API) is available, you can use it's [navigator.keyboard.getLayoutMap method.](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/getLayoutMap). Helpers (getKeyboardLayoutMap and labelWithNavigator) are provided for this purpose, see them for details.
 
+</details>
 
-## How to set multiple manager properties safely (i.e. batch replace shortcuts/commands/keys)?
+<details>
+
+<summary>How to set multiple manager properties safely (i.e. batch replace shortcuts/commands/keys)?</summary>
 
 This can be an issue because there isn't a way to tell the manager you want to replace *multiple* properties and it might be impossible to, for example, replace commands with a smaller subset but not have it error even if you're planning to replace the shortcuts so they don't contain missing commands.
 
@@ -519,7 +583,11 @@ if (isValidManager(manager)) {
 }
 
 ```
-## How to create `modifier-only` shortcuts? (e.g. a shortcut `Ctrl` that changes the some state like enabling multiple selection).
+</details>
+
+<details>
+
+<summary>How to create `modifier-only` shortcuts? (e.g. a shortcut `Ctrl` that changes the some state like enabling multiple selection).</summary>
 
 To do this, instead of clearing the manager's chain, you just set the state directly.
 
@@ -563,17 +631,48 @@ function addToSelected(item) {
 }
 </script>
 ```
-# How to type the context?
+</details>
+
+<details>
+
+<summary>How to show pretty shortcut strings to the user?</summary>
+
+To show a pretty stringified version of a shortcut, use `manager.options.stringifier.stringify(shortcut.chain, manager)`.
+
+Here's an advanced example in vue that shows a hint only when needed:
+
+```ts
+const usageInstructions = computed(() => {
+	const manager = shortcuts.activeManager!.value!
+	const s = manager.options.stringifier
+	const context = shortcuts.context!
+	const isDragging = context.value.layout.drag.isDragging
+	const splitChain = manager.shortcuts.entries.find(_ => _.command === LAYOUT_COMMANDS.dragModifierSplit)?.chain
+		
+	return isDragging && splitChain
+		`Hold ${s.stringify(splitChain, manager)} to Split` 
+		: undefined,
+})
+```
+
+</details>
+
+<details>
+
+<summary>How to type the context?</summary>
+
+Types can be extended multiple times from different files so long as the `NAME` part below is unique for each extension.
 
 ```ts [global.ts]
 declare module "@witchcraft/spellcraft/types" {
 // or for nuxt
 // declare module "#witchcraft/spellcraft/types.js" {
 	export interface Register {
-		ExtendedContextInfo: {
+		ShortcutManagerContextNAME: { //replace NAME with something
 			// extend types here
 		}
 	}
 }
 ```
+</details>
 

package/dist/core/createManagerOptions.js

@@ -4,6 +4,7 @@ import { defaultSorter } from "../defaults/KeysSorter.js";
 import { defaultStringifier } from "../defaults/Stringifier.js";
 export function createManagerOptions(rawOpts) {
   const options = {
+    shortcutEqualityStrategy: "ignoreCommand",
     sorter: defaultSorter,
     stringifier: defaultStringifier,
     conditionEquals: defaultConditionEquals,

package/dist/core/createShortcuts.d.ts

@@ -6,7 +6,7 @@ import type { CanHookErrors, Manager, MultipleErrors, PickManager, Shortcut, Sho
  * Creates a set of shortcuts.
  *
  */
-export declare function createShortcuts<THooks extends Manager["hooks"], TRawShortcuts extends Shortcut[], TCheck extends boolean | "only" = true>(shortcutsList: TRawShortcuts, manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter"> & {
+export declare function createShortcuts<THooks extends Manager["hooks"], TRawShortcuts extends Shortcut[], TCheck extends boolean | "only" = true>(shortcutsList: TRawShortcuts, manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter" | "shortcutEqualityStrategy"> & {
     hooks?: THooks;
 }, opts?: Partial<Pick<Shortcuts, "ignoreModifierConflicts" | "ignoreChainConflicts">>, { check }?: {
     check?: boolean | "only";

package/dist/core/setShortcutsProp.js

@@ -20,7 +20,7 @@ export function setShortcutsProp(prop, val, manager, {
         castType(manager);
         const shortcut = val;
         const existing = shortcuts.entries.find(
-          (_) => equalsShortcut(shortcut, _, manager, { ignoreCommand: true }) || doesShortcutConflict(_, shortcut, manager)
+          (_) => equalsShortcut(shortcut, _, manager) || doesShortcutConflict(_, shortcut, manager)
         );
         if (existing) {
           return Err(new KnownError(
@@ -41,7 +41,7 @@ export function setShortcutsProp(prop, val, manager, {
       case "entries@remove": {
         const shortcut = val;
         const existing = shortcuts.entries.find(
-          (_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false })
+          (_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { shortcutEqualityStrategy: "all" })
         );
         if (existing === void 0) {
           return Err(new KnownError(
@@ -77,7 +77,7 @@ export function setShortcutsProp(prop, val, manager, {
     }
     case "entries@remove": {
       const shortcut = val;
-      const i = shortcuts.entries.findIndex((_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false }));
+      const i = shortcuts.entries.findIndex((_) => _ === shortcut || equalsShortcut(shortcut, _, manager, { shortcutEqualityStrategy: "all" }));
       if (i < 0) {
         throw new Error("If used correctly, shortcut should exist at this point, but it does not.");
       }

package/dist/defaults/defaultConditionEquals.d.ts

@@ -1,19 +1,5 @@
 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).
+ * IMPORTANT: Please read {@link ConditionComparer} before using.
  */
-export declare function defaultConditionEquals<TCondition extends Condition>(conditionA?: TCondition, conditionB?: Condition): conditionB is TCondition;
+export declare function defaultConditionEquals<TCondition extends Condition>(conditionA: TCondition | undefined, conditionB: Condition | undefined, _type: "shortcut" | "command"): conditionB is TCondition;

package/dist/defaults/defaultConditionEquals.js

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

package/dist/helpers/doesShortcutConflict.d.ts

@@ -15,4 +15,4 @@ import type { Manager, PickManager, Shortcut } from "../types/index.js";
  */
 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;
+} & PickManager<"options", "evaluateCondition" | "conditionEquals" | "shortcutEqualityStrategy">): boolean;

package/dist/helpers/doesShortcutConflict.js

@@ -24,7 +24,7 @@ export function doesShortcutConflict(shortcutA, shortcutB, manager) {
       if (!shortcutCondition) return false;
     }
   } else {
-    if (!conditionEquals(shortcutA.condition, shortcutB.condition)) return false;
+    if (!conditionEquals(shortcutA.condition, shortcutB.condition, "shortcut")) return false;
   }
   const { keys } = manager;
   if (shortcutA.chain.length === 0 || shortcutB.chain.length === 0) {

package/dist/helpers/equalsCommand.js

@@ -1,4 +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;
+  return commandA.name === commandB.name && commandA.execute === commandB.execute && manager.options.conditionEquals(commandA.condition, commandB.condition, "command") && commandA.description === commandB.description;
 }

package/dist/helpers/equalsShortcut.d.ts

@@ -2,8 +2,10 @@ 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.
+ * To return true, their keys, conditions, and commands (depends on the configured `manager.options.shortcutEqualityStrategy`) must be equal.
+ *
+ * See {@link Manager.options.shortcutEqualityStrategy} for details.
+ *
+ * You can temporarily override the strategy witht the third parameter.
  */
-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;
+export declare function equalsShortcut<TShortcut extends Shortcut>(shortcutA: TShortcut, shortcutB: Shortcut, manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "shortcutEqualityStrategy">, overrides?: PickManager<"options", "shortcutEqualityStrategy">["options"]): shortcutB is TShortcut;

package/dist/helpers/equalsShortcut.js

@@ -1,7 +1,10 @@
 import { equalsCommand } from "./equalsCommand.js";
 import { equalsKeys } from "../utils/equalsKeys.js";
-export function equalsShortcut(shortcutA, shortcutB, manager, { ignoreCommand = false } = {}) {
+export function equalsShortcut(shortcutA, shortcutB, manager, overrides) {
   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));
+  const commandA = shortcutA.command ? manager.commands.entries[shortcutA.command] : void 0;
+  const commandB = shortcutB.command ? manager.commands.entries[shortcutB.command] : void 0;
+  const shortcutEqualityStrategy = overrides?.shortcutEqualityStrategy ?? manager.options.shortcutEqualityStrategy;
+  return equalsKeys(shortcutA.chain, shortcutB.chain, manager.keys, void 0, { allowVariants: true }) && manager.options.conditionEquals(shortcutA.condition, shortcutB.condition, "shortcut") && (shortcutEqualityStrategy === "ignoreCommand" || shortcutEqualityStrategy === "ignoreCommandWithDifferentCondition" && commandA?.condition && commandB?.condition && manager.options.conditionEquals(commandA.condition, commandB.condition, "command") || 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/getKeyCodesFromKeyIds.d.ts

@@ -0,0 +1,12 @@
+import { getKeyCodesFromKeys } from "./getKeyCodesFromKeys.js";
+import type { Keys } from "../types/keys.js";
+/**
+ * Given an list of key ids, returns an array of deduped key codes. If you have a list of `Key`s instead use {@link getKeyCodesFromKeys}.
+ *
+ * Useful for when the codes must be passed to a third-party library (for example, a dragging library that takes a list modifiers).
+ *
+ * This properly takes a look at the key and all it's variants.
+ *
+ * `skipIdIfHasVariants` is true by default and will skip adding the key's id if it has variants as it's assumed the id is not a valid name.
+ */
+export declare function getKeyCodesFromKeyIds(keyIds: string[], keys: Keys, opts: Parameters<typeof getKeyCodesFromKeys>[1]): string[];

package/dist/helpers/getKeyCodesFromKeyIds.js

@@ -0,0 +1,6 @@
+import { getKeyCodesFromKeys } from "./getKeyCodesFromKeys.js";
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js";
+export function getKeyCodesFromKeyIds(keyIds, keys, opts) {
+  const keysList = keyIds.flatMap((id) => getKeyFromIdOrVariant(id, keys).unwrap());
+  return getKeyCodesFromKeys(keysList, opts);
+}

package/dist/helpers/getKeyCodesFromKeys.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Given an list of keys, returns an array of deduped key codes.
+ *
+ * Useful for when the codes must be passed to a third-party library (for example, a dragging library that takes a list modifiers).
+ *
+ * This properly takes a look at the key and all it's variants.
+ *
+ * `skipIdIfHasVariants` is true by default and will skip adding the key's id if it has variants as it's assumed the id is not a valid name.
+ */
+import type { Key } from "../types/keys.js";
+export declare function getKeyCodesFromKeys(keys: Key[], { skipIdIfHasVariants }?: {
+    skipIdIfHasVariants?: boolean;
+}): string[];

package/dist/helpers/getKeyCodesFromKeys.js

@@ -0,0 +1,16 @@
+export function getKeyCodesFromKeys(keys, { skipIdIfHasVariants = true } = {}) {
+  const res = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (key.variants && key.variants.length > 0) {
+      if (!skipIdIfHasVariants) {
+        res.add(key.id);
+      }
+      for (const variant of key.variants) {
+        res.add(variant);
+      }
+    } else {
+      res.add(key.id);
+    }
+  }
+  return Array.from(res);
+}

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "witchcraftSpellcraft",
   "configKey": "witchcraftSpellcraft",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { createResolver, defineNuxtModule, addTypeTemplate, addImportsDir } from '@nuxt/kit';
 
 const { resolve } = createResolver(import.meta.url);
-const module = defineNuxtModule({
+const module$1 = defineNuxtModule({
   meta: {
     name: "witchcraftSpellcraft",
     configKey: "witchcraftSpellcraft"
@@ -32,4 +32,4 @@ const module = defineNuxtModule({
   }
 });
 
-export { module as default };
+export { module$1 as default };

package/dist/runtime/types.d.ts

@@ -1,9 +1,8 @@
+import type { OrToAnd } from "@alanscodelog/utils/types";
 export interface Register {
 }
-type ExtendedContextInfo = Register extends {
-    ExtendedContextInfo: infer T;
-} ? T : unknown;
-export type ContextInfo = ExtendedContextInfo & {
+export type ExtendedShortcutManagerInfo = keyof Register extends `ShortcutManagerContext${infer T}` ? Register extends Record<`ShortcutManagerContext${T}`, infer U> ? U : {} : {};
+export type ContextInfo = OrToAnd<ExtendedShortcutManagerInfo> & {
     count: Record<string, number>;
     isActive: Record<string, boolean>;
 };

package/dist/types/condition.d.ts

@@ -24,6 +24,8 @@ export interface Condition {
  * 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).
+ *
+ * This is why the manager now has the option `shortcutEqualityStrategy` which can be se to `ignoreCommandWithDifferentCondition`. You can implement a comparer that only checks when a command is being checked.
  */
-export type ConditionComparer = (conditionA?: Condition, conditionB?: Condition) => boolean;
+export type ConditionComparer = (conditionA: Condition | undefined, conditionB: Condition | undefined, type: "shortcut" | "command") => boolean;
 export type ConditionEvaluator<TContext extends Context<any>> = (condition: Condition, context: TContext) => boolean;

package/dist/types/manager.d.ts

@@ -114,9 +114,20 @@ export type Manager<THooks extends Partial<Hooks> = Partial<Hooks>, TKeys extend
         /**
          * 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.
+         * This is actually not a good idea to implement for shortcuts if you use boolean conditions. See {@link ConditionComparer} for why.
+         *
+         * See also {@link Manager.options.shortcutEqualityStrategy}.
          */
         conditionEquals: ConditionComparer;
+        /**
+         * Determines how shortcuts are compared.
+         *
+         * - `ignoreCommand` (default) will ignore both shortcuts' commands. If everything else is equal, they are considered equal.
+         * - `ignoreCommandWithDifferentCondition` will ignore both commands' names and only compare their conditions. If everything else is equal, they are considered equal. Use it if you allow command conditions to equal eachother. See {@link ConditionComparer} for details.
+         * - `all` will compare everything.
+         *
+         */
+        shortcutEqualityStrategy: "ignoreCommand" | "ignoreCommandWithDifferentCondition" | "all";
         /** Determines how conditions are evaluated. */
         evaluateCondition: ConditionEvaluator<TContext>;
         /** Enable/disable triggering of shortcuts. The manager otherwise works as normal. */

package/dist/types/shortcuts.d.ts

@@ -126,12 +126,12 @@ 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>;
+type BaseShortcutsManager = Pick<Manager, "keys" | "commands" | "shortcuts"> & PickManager<"options", "evaluateCondition" | "conditionEquals" | "stringifier" | "shortcutEqualityStrategy"> & Record<any, any>;
 export type ShortcutsSetEntries = {
     "entries@add": {
         val: Shortcut;
         hooks: GetShortcutHooks<`entries@add`>;
-        manager: BaseShortcutsManager & PickManager<"options", "sorter">;
+        manager: BaseShortcutsManager & PickManager<"options", "sorter" | "shortcutEqualityStrategy">;
         error: typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT | typeof SHORTCUT_ERROR.UNKNOWN_COMMAND | ChainError;
     };
     "entries@remove": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@witchcraft/spellcraft",
   "description": "A shortcut manager library for handling ALL the shortcut needs of an application.",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/core/index.js",
   "sideEffects": false,
@@ -39,8 +39,8 @@
     }
   },
   "peerDependencies": {
-    "@witchcraft/expressit": "^0.4.1",
-    "@witchcraft/ui": "^0.3.7"
+    "@witchcraft/expressit": "^0.4.2",
+    "@witchcraft/ui": "^0.3.20"
   },
   "peerDependenciesMeta": {
     "@witchcraft/ui": {
@@ -52,45 +52,46 @@
   },
   "dependencies": {
     "@alanscodelog/utils": "^6.0.2",
-    "@witchcraft/expressit": "^0.4.1",
-    "@witchcraft/ui": "^0.3.7",
-    "vue": "^3.5.21"
+    "@witchcraft/expressit": "^0.4.2",
+    "@witchcraft/ui": "^0.3.20",
+    "reka-ui": "^2.8.0",
+    "vue": "^3.5.27"
   },
   "devDependencies": {
     "@alanscodelog/commitlint-config": "^3.1.2",
     "@alanscodelog/eslint-config": "^6.3.1",
     "@alanscodelog/semantic-release-config": "^6.0.0",
     "@alanscodelog/tsconfigs": "^6.2.0",
-    "@alanscodelog/vite-config": "^0.0.6",
-    "@commitlint/cli": "^19.8.1",
-    "@iconify/json": "^2.2.385",
-    "@nuxt/eslint-config": "^1.9.0",
-    "@nuxt/kit": "^4.1.2",
+    "@alanscodelog/vite-config": "^0.0.7",
+    "@commitlint/cli": "^20.4.1",
+    "@iconify/json": "^2.2.436",
+    "@nuxt/eslint-config": "^1.13.0",
+    "@nuxt/kit": "^4.3.0",
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "^4.1.2",
+    "@nuxt/schema": "^4.3.0",
     "@nuxt/types": "^2.18.1",
-    "@types/node": "^24.5.2",
-    "@vitejs/plugin-vue": "^6.0.1",
+    "@types/node": "^25.2.1",
+    "@vitejs/plugin-vue": "^6.0.4",
     "@vitest/coverage-c8": "^0.33.0",
     "concurrently": "^9.2.1",
-    "cross-env": "^10.0.0",
+    "cross-env": "^10.1.0",
     "defu": "^6.1.4",
     "fast-glob": "^3.3.3",
     "http-server": "^14.1.1",
     "husky": "^9.1.7",
     "indexit": "2.1.0-beta.3",
     "madge": "^8.0.0",
-    "nuxt": "^4.1.2",
+    "nuxt": "^4.3.0",
     "onchange": "^7.1.0",
-    "semantic-release": "^24.2.8",
-    "tailwindcss": "^4.1.13",
-    "typedoc": "0.28.13",
-    "typescript": "^5.9.2",
+    "semantic-release": "^25.0.3",
+    "tailwindcss": "^4.1.18",
+    "typedoc": "0.28.16",
+    "typescript": "^5.9.3",
     "unbuild": "^3.6.1",
-    "unplugin-icons": "^22.3.0",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.4",
-    "vue-tsc": "^3.0.7"
+    "unplugin-icons": "^23.0.1",
+    "vite-tsconfig-paths": "^6.0.5",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4"
   },
   "author": "Alan <alanscodelog@gmail.com>",
   "repository": "https://github.com/witchcraftjs/spellcraft",
@@ -126,7 +127,8 @@
     "node": ">=20.0.0"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "scripts": {
     "build": "nuxt-module-build prepare && nuxt-module-build build && nuxi generate playground",

package/src/core/createManagerOptions.ts

@@ -16,6 +16,7 @@ export function createManagerOptions(
 	rawOpts: Parameters<typeof createManager>[0]["options"]
 ): Manager["options"] {
 	const options: Manager["options"] = {
+		shortcutEqualityStrategy: "ignoreCommand",
 		sorter: defaultSorter,
 		stringifier: defaultStringifier,
 		conditionEquals: defaultConditionEquals,

package/src/core/createShortcuts.ts

@@ -17,7 +17,7 @@ export function createShortcuts<
 >(
 	shortcutsList: TRawShortcuts,
 	manager: Pick<Manager, "keys" | "commands">
-		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter">
+		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter" | "shortcutEqualityStrategy">
 		& { hooks?: THooks },
 	opts?: Partial<Pick<Shortcuts, "ignoreModifierConflicts" | "ignoreChainConflicts">>,
 	{

package/src/core/setShortcutsProp.ts

@@ -43,7 +43,7 @@ export function setShortcutsProp<
 
 				const shortcut = val as any as Shortcut
 				const existing = (shortcuts.entries).find(_ =>
-					equalsShortcut(shortcut, _, manager, { ignoreCommand: true })
+					equalsShortcut(shortcut, _, manager)
 					|| doesShortcutConflict(_, shortcut, manager)
 				)
 
@@ -67,7 +67,7 @@ export function setShortcutsProp<
 				const shortcut = val as any as Shortcut
 				// note we don't ignore the command here, we want to find an exact match
 				const existing = (shortcuts.entries).find(_ =>
-					_ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false })
+					_ === shortcut || equalsShortcut(shortcut, _, manager, { shortcutEqualityStrategy: "all" })
 				)
 				if (existing === undefined) {
 					return Err(new KnownError(
@@ -105,7 +105,7 @@ export function setShortcutsProp<
 		}
 		case "entries@remove": {
 			const shortcut = val
-			const i = shortcuts.entries.findIndex(_ => _ === shortcut || equalsShortcut(shortcut, _, manager, { ignoreCommand: false }))
+			const i = shortcuts.entries.findIndex(_ => _ === shortcut || equalsShortcut(shortcut, _, manager, { shortcutEqualityStrategy: "all" }))
 			if (i < 0) {
 				throw new Error("If used correctly, shortcut should exist at this point, but it does not.")
 			}

package/src/defaults/defaultConditionEquals.ts

@@ -1,25 +1,12 @@
 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).
+ * IMPORTANT: Please read {@link ConditionComparer} before using.
  */
 export function defaultConditionEquals<TCondition extends Condition>(
-	conditionA?: TCondition,
-	conditionB?: Condition
+	conditionA: TCondition | undefined,
+	conditionB: Condition | undefined,
+	_type: "shortcut" | "command"
 ): conditionB is TCondition {
 	// both are the same object or both undefined
 	if (conditionA === conditionB) return true

package/src/helpers/doesShortcutConflict.ts

@@ -23,7 +23,7 @@ export function doesShortcutConflict<TShortcut extends Shortcut>(
 	shortcutA: TShortcut,
 	shortcutB: Shortcut,
 	manager: Pick<Manager, "keys" | "commands" | "shortcuts"> & { context?: Manager["context"] }
-		& PickManager<"options", "evaluateCondition" | "conditionEquals">
+		& PickManager<"options", "evaluateCondition" | "conditionEquals" | "shortcutEqualityStrategy">
 ): boolean {
 	const context = manager.context
 	if (!context && manager.shortcuts.useContextInConflictCheck) {
@@ -47,7 +47,7 @@ export function doesShortcutConflict<TShortcut extends Shortcut>(
 			if (!shortcutCondition) return false
 		}
 	} else {
-		if	(!conditionEquals(shortcutA.condition, shortcutB.condition)) return false
+		if	(!conditionEquals(shortcutA.condition, shortcutB.condition, "shortcut")) return false
 	}
 	const { keys } = manager
 	// an empty chain is always in conflict ?

package/src/helpers/equalsCommand.ts

@@ -13,6 +13,6 @@ export function equalsCommand<TCommand extends Command>(
 	if (commandA === commandB) return true
 	return commandA.name === commandB.name
 		&& commandA.execute === commandB.execute
-		&& manager.options.conditionEquals(commandA.condition, commandB.condition)
+		&& manager.options.conditionEquals(commandA.condition, commandB.condition, "command")
 		&& commandA.description === commandB.description
 }

package/src/helpers/equalsShortcut.ts

@@ -6,20 +6,32 @@ import { equalsKeys } from "../utils/equalsKeys.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.
+ * To return true, their keys, conditions, and commands (depends on the configured `manager.options.shortcutEqualityStrategy`) must be equal.
+ *
+ * See {@link Manager.options.shortcutEqualityStrategy} for details.
+ *
+ * You can temporarily override the strategy witht the third parameter.
  */
 export function equalsShortcut<TShortcut extends Shortcut>(
 	shortcutA: TShortcut,
 	shortcutB: Shortcut,
-	manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", | "evaluateCondition" | "conditionEquals">,
-	{ ignoreCommand = false }: { ignoreCommand?: boolean } = {}
+	manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", | "evaluateCondition" | "conditionEquals" | "shortcutEqualityStrategy">,
+	overrides?: PickManager<"options", "shortcutEqualityStrategy">["options"]
 ): shortcutB is TShortcut {
 	if (shortcutA.forceUnequal || shortcutB.forceUnequal) return false
 	if (shortcutA === shortcutB) return true
+	const commandA = shortcutA.command ? manager.commands.entries[shortcutA.command] : undefined
+	const commandB = shortcutB.command ? manager.commands.entries[shortcutB.command] : undefined
+	const shortcutEqualityStrategy = overrides?.shortcutEqualityStrategy ?? manager.options.shortcutEqualityStrategy
 	return (
 		equalsKeys(shortcutA.chain, shortcutB.chain, manager.keys, undefined, { allowVariants: true })
-		&& manager.options.conditionEquals(shortcutA.condition, shortcutB.condition)
-		&& (ignoreCommand
+		&& manager.options.conditionEquals(shortcutA.condition, shortcutB.condition, "shortcut")
+		&& (shortcutEqualityStrategy === "ignoreCommand"
+			|| (
+				shortcutEqualityStrategy === "ignoreCommandWithDifferentCondition"
+				&& commandA?.condition && commandB?.condition
+				&& manager.options.conditionEquals(commandA.condition, commandB.condition, "command")
+			)
 			|| (
 				shortcutA.command === shortcutB.command
 				&& shortcutA.command === undefined

package/src/helpers/getKeyCodesFromKeyIds.ts

@@ -0,0 +1,20 @@
+import { getKeyCodesFromKeys } from "./getKeyCodesFromKeys.js"
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+
+import type { Keys } from "../types/keys.js"
+
+/**
+ * Given an list of key ids, returns an array of deduped key codes. If you have a list of `Key`s instead use {@link getKeyCodesFromKeys}.
+ *
+ * Useful for when the codes must be passed to a third-party library (for example, a dragging library that takes a list modifiers).
+ *
+ * This properly takes a look at the key and all it's variants.
+ *
+ * `skipIdIfHasVariants` is true by default and will skip adding the key's id if it has variants as it's assumed the id is not a valid name.
+ */
+
+
+export function getKeyCodesFromKeyIds(keyIds: string[], keys: Keys, opts: Parameters<typeof getKeyCodesFromKeys>[1]): string[] {
+	const keysList = keyIds.flatMap(id => getKeyFromIdOrVariant(id, keys).unwrap())
+	return getKeyCodesFromKeys(keysList, opts)
+}

package/src/helpers/getKeyCodesFromKeys.ts

@@ -0,0 +1,28 @@
+/**
+ * Given an list of keys, returns an array of deduped key codes.
+ *
+ * Useful for when the codes must be passed to a third-party library (for example, a dragging library that takes a list modifiers).
+ *
+ * This properly takes a look at the key and all it's variants.
+ *
+ * `skipIdIfHasVariants` is true by default and will skip adding the key's id if it has variants as it's assumed the id is not a valid name.
+ */
+
+import type { Key } from "../types/keys.js"
+
+export function getKeyCodesFromKeys(keys: Key[], { skipIdIfHasVariants = true}: { skipIdIfHasVariants?: boolean } = {}): string[] {
+	const res = new Set<string>()
+	for (const key of keys) {
+		if (key.variants && key.variants.length > 0) {
+			if (!skipIdIfHasVariants) {
+				res.add(key.id)
+			}
+			for (const variant of key.variants) {
+				res.add(variant)
+			}
+		} else {
+			res.add(key.id)
+		}
+	}
+	return Array.from(res)
+}

package/src/runtime/types.ts

@@ -1,9 +1,23 @@
-export interface Register { }
+import type { OrToAnd } from "@alanscodelog/utils/types"
+// allows users to register multiple contexts
+// @eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Register {}
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
-type ExtendedContextInfo = Register extends { ExtendedContextInfo: infer T } ? T : unknown
+export type ExtendedShortcutManagerInfo = keyof Register extends `ShortcutManagerContext${infer T}`
+	? Register extends Record<`ShortcutManagerContext${T}`, infer U>
+		? U
+		// we can further constrain the type users can register if needed
+		// ? U extends { }
+		// 	? U
+		// 	: {}
+		// : {}
+		// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+		: {}
+	// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+	: {}
 
-export type ContextInfo = ExtendedContextInfo & {
+
+export type ContextInfo = OrToAnd<ExtendedShortcutManagerInfo> & {
 	count: Record<string, number>
 	isActive: Record<string, boolean>
 }

package/src/types/condition.ts

@@ -28,8 +28,10 @@ export interface Condition {
  * 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).
+ *
+ * This is why the manager now has the option `shortcutEqualityStrategy` which can be se to `ignoreCommandWithDifferentCondition`. You can implement a comparer that only checks when a command is being checked.
  */
-export type ConditionComparer = (conditionA?: Condition, conditionB?: Condition) => boolean
+export type ConditionComparer = (conditionA: Condition | undefined, conditionB: Condition | undefined, type: "shortcut" | "command") => boolean
 
 export type ConditionEvaluator<TContext extends Context<any>> = (condition: Condition, context: TContext) => boolean
 

package/src/types/manager.ts

@@ -212,9 +212,21 @@ export type Manager<
 		/**
 		 * 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.
+		 * This is actually not a good idea to implement for shortcuts if you use boolean conditions. See {@link ConditionComparer} for why.
+		 *
+		 * See also {@link Manager.options.shortcutEqualityStrategy}.
 		 */
 		conditionEquals: ConditionComparer
+		/**
+		 * Determines how shortcuts are compared.
+		 *
+		 * - `ignoreCommand` (default) will ignore both shortcuts' commands. If everything else is equal, they are considered equal.
+		 * - `ignoreCommandWithDifferentCondition` will ignore both commands' names and only compare their conditions. If everything else is equal, they are considered equal. Use it if you allow command conditions to equal eachother. See {@link ConditionComparer} for details.
+		 * - `all` will compare everything.
+		 *
+		 */
+		shortcutEqualityStrategy: "ignoreCommand" | "ignoreCommandWithDifferentCondition" | "all"
+
 		/** Determines how conditions are evaluated. */
 		evaluateCondition: ConditionEvaluator<TContext>
 		/** Enable/disable triggering of shortcuts. The manager otherwise works as normal. */

package/src/types/shortcuts.ts

@@ -178,7 +178,7 @@ export type OnHookShortcutsProps = SyntheticOnHookShortcutsProps
 
 type BaseShortcutsManager
 	= & Pick<Manager, "keys" | "commands" | "shortcuts">
-		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier">
+		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "shortcutEqualityStrategy">
 		& Record<any, any>
 
 export type ShortcutsSetEntries = {
@@ -187,7 +187,7 @@ export type ShortcutsSetEntries = {
 		val: Shortcut
 		hooks: GetShortcutHooks<`entries@add`>
 		manager: BaseShortcutsManager
-			& PickManager<"options", "sorter">
+			& PickManager<"options", "sorter" | "shortcutEqualityStrategy">
 
 		error:
 			| typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT