@witchcraft/spellcraft 0.0.1

package/dist/utils/index.d.ts

@@ -0,0 +1,14 @@
+export { chainContainsSubset } from "./chainContainsSubset.js";
+export { cloneChain } from "./cloneChain.js";
+export { cloneKey } from "./cloneKey.js";
+export { containsKey } from "./containsKey.js";
+export { dedupeKeys } from "./dedupeKeys.js";
+export { equalsKey } from "./equalsKey.js";
+export { equalsKeys } from "./equalsKeys.js";
+export { isAnyKey } from "./isAnyKey.js";
+export { isMouseKey } from "./isMouseKey.js";
+export { isNormalKey } from "./isNormalKey.js";
+export { isTriggerKey } from "./isTriggerKey.js";
+export { isWheelKey } from "./isWheelKey.js";
+export { mapKeys } from "./mapKeys.js";
+export { removeKeys } from "./removeKeys.js";

package/dist/utils/index.js

@@ -0,0 +1,14 @@
+export { chainContainsSubset } from "./chainContainsSubset.js";
+export { cloneChain } from "./cloneChain.js";
+export { cloneKey } from "./cloneKey.js";
+export { containsKey } from "./containsKey.js";
+export { dedupeKeys } from "./dedupeKeys.js";
+export { equalsKey } from "./equalsKey.js";
+export { equalsKeys } from "./equalsKeys.js";
+export { isAnyKey } from "./isAnyKey.js";
+export { isMouseKey } from "./isMouseKey.js";
+export { isNormalKey } from "./isNormalKey.js";
+export { isTriggerKey } from "./isTriggerKey.js";
+export { isWheelKey } from "./isWheelKey.js";
+export { mapKeys } from "./mapKeys.js";
+export { removeKeys } from "./removeKeys.js";

package/dist/utils/isAnyKey.d.ts

@@ -0,0 +1,5 @@
+import type { Key } from "../types/index.js";
+/**
+ * Returns whether a key is a key (and not a mouse button or mouse wheel).
+ */
+export declare function isAnyKey(key: Key): boolean;

package/dist/utils/isAnyKey.js

@@ -0,0 +1,5 @@
+import { isMouseKey } from "./isMouseKey.js";
+import { isWheelKey } from "./isWheelKey.js";
+export function isAnyKey(key) {
+  return !isWheelKey(key) && !isMouseKey(key);
+}

package/dist/utils/isMouseKey.d.ts

@@ -0,0 +1,5 @@
+import type { Key } from "../types/index.js";
+/**
+ * Returns whether a key is a mouse key (id = 0-4).
+ */
+export declare function isMouseKey(key: Key): boolean;

package/dist/utils/isMouseKey.js

@@ -0,0 +1,20 @@
+const possibleIds = [
+  "0",
+  "1",
+  "2",
+  "3",
+  "4",
+  "0On",
+  "1On",
+  "2On",
+  "3On",
+  "4On",
+  "0Off",
+  "1Off",
+  "2Off",
+  "3Off",
+  "4Off"
+];
+export function isMouseKey(key) {
+  return possibleIds.includes(key.id) || (key.variants?.some((id) => possibleIds.includes(id)) ?? false);
+}

package/dist/utils/isNormalKey.d.ts

@@ -0,0 +1,5 @@
+import type { Key } from "../types/index.js";
+/**
+ * Returns whether a key is a normal key (it is not a modifier, mouse, wheel, or toggle key).
+ */
+export declare function isNormalKey(key: Key): boolean;

package/dist/utils/isNormalKey.js

@@ -0,0 +1,5 @@
+import { isMouseKey } from "./isMouseKey.js";
+import { isWheelKey } from "./isWheelKey.js";
+export function isNormalKey(key) {
+  return !isWheelKey(key) && !isMouseKey(key) && !key.isModifier && !key.isToggle;
+}

package/dist/utils/isTriggerKey.d.ts

@@ -0,0 +1,5 @@
+import type { Key } from "../types/index.js";
+/**
+ * See {@link Manager} and {@link Manager.pressedNonModifierKeys}.
+ */
+export declare function isTriggerKey(key: Key): boolean;

package/dist/utils/isTriggerKey.js

@@ -0,0 +1,3 @@
+export function isTriggerKey(key) {
+  return !key.isModifier && !key.isToggle;
+}

package/dist/utils/isWheelKey.d.ts

@@ -0,0 +1,5 @@
+import type { Key } from "../types/index.js";
+/**
+ * Returns whether a key is a a wheel up/down "key".
+ */
+export declare function isWheelKey(key: Key): boolean;

package/dist/utils/isWheelKey.js

@@ -0,0 +1,11 @@
+const possibleIds = [
+  "WheelUp",
+  "WheelDown",
+  "WheelUpOn",
+  "WheelDownOn",
+  "WheelUpOff",
+  "WheelDownOff"
+];
+export function isWheelKey(key) {
+  return possibleIds.includes(key.id) || (key.variants?.some((id) => possibleIds.includes(id)) ?? false);
+}

package/dist/utils/mapKeys.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Map keys of a chain or chord\* by the given function.
+ *
+ * Useful for inspecting a chain/chord when debugging.
+ *
+ * \*This is determined by checking if the first element is an array or not.
+ */
+export declare function mapKeys<TType extends any[] | any[][], TReturn = string>(chainOrChord: TType, func?: (key: TType extends any[][] ? TType[number][number] : TType[number]) => TReturn): TType extends any[][] ? TReturn[][] : TReturn[];

package/dist/utils/mapKeys.js

@@ -0,0 +1,5 @@
+import { isArray } from "@alanscodelog/utils/isArray";
+export function mapKeys(chainOrChord, func = (key) => key?.id) {
+  if (chainOrChord.length === 0) return [];
+  return isArray(chainOrChord[0]) ? chainOrChord.map((chord) => chord.map((key) => func(key))) : chainOrChord.map((key) => func(key));
+}

package/dist/utils/removeKeys.d.ts

@@ -0,0 +1,7 @@
+import type { Keys } from "../types/index.js";
+/**
+ * Returns a copy of keysList with the keys given to remove, removed, checking equality according to {@link equalsKey}.
+ */
+export declare const removeKeys: (keysList: readonly string[], toRemove: readonly string[], keys: Keys, opts?: {
+    allowVariants?: boolean;
+}) => string[];

package/dist/utils/removeKeys.js

@@ -0,0 +1,4 @@
+import { equalsKey } from "./equalsKey.js";
+export const removeKeys = (keysList, toRemove, keys, opts = {}) => keysList.filter(
+  (key) => toRemove.find((_) => equalsKey(key, _, keys, opts)) === void 0
+);

package/package.json

@@ -0,0 +1,156 @@
+{
+	"name": "@witchcraft/spellcraft",
+	"description": "A shortcut manager library for handling ALL the shortcut needs of an application.",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "./dist/core/index.js",
+	"sideEffects": false,
+	"build": {
+		"failOnWarn": false
+	},
+	"exports": {
+		".": {
+			"types": "./dist/core/index.d.ts",
+			"import": "./dist/core/index.js"
+		},
+		"./utils": {
+			"types": "./dist/utils/index.d.ts",
+			"import": "./dist/utils/index.js"
+		},
+		"./helpers": {
+			"types": "./dist/helpers/index.d.ts",
+			"import": "./dist/helpers/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/types/index.js"
+		},
+		"./core": {
+			"types": "./dist/core/index.d.ts",
+			"import": "./dist/core/index.js"
+		},
+		"./nuxt": {
+			"types": "./dist/types.d.mts",
+			"import": "./dist/module.mjs"
+		},
+		"./*": {
+			"types": "./dist/*.js",
+			"import": "./dist/*.js"
+		}
+	},
+	"scripts": {
+		"prepare": "husky && cd playground && pnpm i",
+		"build": "nuxt-module-build prepare && nuxt-module-build build && nuxi generate playground",
+		"build:only": "nuxt-module-build build",
+		"dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+		"dev:playground": "nuxi dev playground",
+		"dev": "nuxi dev playground",
+		"test": "pnpm lint:types && vitest run --exclude '.direnv/**/*'",
+		"test:watch": "vitest --watch --exclude '.direnv/**/*'",
+		"test:inspect-errors": "cross-env INSPECT_ERRORS=true npm run test",
+		"coverage": "vitest --exclude '.direnv/**/*' --coverage",
+		"coverage:dev": "vitest --exclude '.direnv/**/*'  --watch --coverage",
+		"doc": "typedoc",
+		"doc:watch": "onchange -i \"src/**/*.ts\" \"typedoc.config.js\" -- pnpm doc",
+		"doc:serve": "http-server docs --port=5001",
+		"doc:dev": "concurrently \"pnpm doc:watch\" \"pnpm doc:serve\"",
+		"doc:check-invalid": "typedoc --listInvalidSymbolLinks",
+		"lint:eslint": "eslint \"{src,test,playground/app}/**/*.{js,ts,vue,cjs}\" \"*.{js,ts}\" --max-warnings=0 --report-unused-disable-directives",
+		"lint:types": "vue-tsc --noEmit && echo 'todo cd playground && vue-tsc --noEmit'",
+		"lint:commits": "commitlint --from-last-tag --to HEAD --verbose",
+		"lint:imports": "madge --circular --extensions ts ./src",
+		"lint": "pnpm lint:types && pnpm lint:eslint && pnpm lint:imports",
+		"actions:debug": "act -r -v",
+		"gen:exports": "indexit update -o '${path}.js'"
+	},
+	"peerDependencies": {
+		"@witchcraft/expressit": "^0.4.0",
+		"@witchcraft/ui": "^0.2.3"
+	},
+	"peerDependenciesMeta": {
+		"@witchcraft/ui": {
+			"optional": true
+		},
+		"@witchcraft/expressit": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"@alanscodelog/utils": "^6.0.2",
+		"@witchcraft/expressit": "^0.4.1",
+		"@witchcraft/ui": "^0.2.4",
+		"vue": "^3.5.21"
+	},
+	"devDependencies": {
+		"@alanscodelog/commitlint-config": "^3.1.2",
+		"@alanscodelog/eslint-config": "^6.3.1",
+		"@alanscodelog/semantic-release-config": "^5.0.4",
+		"@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",
+		"@nuxt/module-builder": "^1.0.2",
+		"@nuxt/schema": "^4.1.2",
+		"@nuxt/types": "^2.18.1",
+		"@types/node": "^24.5.2",
+		"@vitejs/plugin-vue": "^6.0.1",
+		"@vitest/coverage-c8": "^0.33.0",
+		"concurrently": "^9.2.1",
+		"cross-env": "^10.0.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",
+		"onchange": "^7.1.0",
+		"semantic-release": "^24.2.8",
+		"tailwindcss": "^4.1.13",
+		"typedoc": "0.28.13",
+		"typescript": "^5.9.2",
+		"unbuild": "^3.6.1",
+		"unplugin-icons": "^22.3.0",
+		"vite-tsconfig-paths": "^5.1.4",
+		"vitest": "^3.2.4",
+		"vue-tsc": "^3.0.7"
+	},
+	"author": "Alan <alanscodelog@gmail.com>",
+	"repository": "https://github.com/witchcraftjs/spellcraft",
+	"license": "MIT",
+	"files": [
+		"src",
+		"dist"
+	],
+	"release": {
+		"extends": [
+			"@alanscodelog/semantic-release-config"
+		]
+	},
+	"commitlint": {
+		"extends": [
+			"@alanscodelog"
+		]
+	},
+	"babel": {
+		"presets": [
+			"@alanscodelog"
+		]
+	},
+	"madge": {
+		"detectiveOptions": {
+			"ts": {
+				"skipTypeImports": true
+			}
+		}
+	},
+	"browserslist": "> 0.5%, last 2 versions, not dead, not < 0.25%, not IE > 0, maintained node versions",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/core/EmulatedEvent.ts

@@ -0,0 +1,29 @@
+export class EmulatedEvent<
+	TType extends "keydown" | "keyup" | "mousedown" | "mouseup" | "wheel" | "mouseenter" = "keydown" | "keyup" | "mousedown" | "mouseup" | "wheel" | "mouseenter"
+> {
+	code!: TType extends "keydown" | "keyup" ? string : never
+
+	button!: TType extends "mousedown" | "mouseup" ? number : never
+
+	deltaY!: TType extends "wheel" ? number : never
+
+	modifiers: string[]
+
+	type: TType
+
+	constructor(type: TType, info: Partial<EmulatedEvent<TType>> = {}, modifiers: string[] = []) {
+		this.modifiers = modifiers
+		this.type = type
+		for (const property of Object.keys(info)) {
+			(this as any)[property] = (info as any)[property]
+		}
+	}
+
+	getModifierState(code: string): boolean {
+		return this.modifiers.includes(code)
+	}
+
+	preventDefault(): void {
+		// so we don't get annoying type errors
+	}
+}

package/src/core/Emulator.ts

@@ -0,0 +1,185 @@
+import type { AnyFunction } from "@alanscodelog/utils/types"
+
+import { EmulatedEvent } from "./EmulatedEvent.js"
+
+import type { Keys } from "../types/index.js"
+
+
+const mouseButtons = ["0", "1", "2", "3", "4", "5"]
+const mouseButtonsDown = mouseButtons.map(b => `${b}+`)
+const mouseButtonsUp = mouseButtons.map(b => `${b}-`)
+const wheelKeys = ["wheelUp", "wheelDown"]
+
+/**
+ * A simple key emulator for testing purposes. Should be hooked up to a manager class as if it was an element:
+ * ```ts
+ * const emulator = new Emulator()
+ * manager.attach(emulator)
+ * // press and release a
+ * emulator.fire("KeyA")
+ * // in case the pressed keys need to be cleared you can use the manager to do so:
+ * manager.clear()
+ * ```
+ */
+export class Emulator {
+	validKeys?: Keys
+
+	constructor(keys?: Keys) {
+		this.validKeys = keys
+	}
+
+	listeners: {
+		keydown: AnyFunction[]
+		keyup: AnyFunction[]
+		wheel: AnyFunction[]
+		mousedown: AnyFunction[]
+		mouseup: AnyFunction[]
+		mouseenter: AnyFunction[]
+	} = {
+		keydown: [],
+		keyup: [],
+		wheel: [],
+		mousedown: [],
+		mouseenter: [],
+		mouseup: []
+	}
+
+	initiated: boolean = false
+
+	addEventListener(type: string, func: AnyFunction): void {
+		this.listeners[type as keyof Emulator["listeners"]].push(func)
+		this.initiated = true
+	}
+
+	removeEventListener(type: string, func: AnyFunction): void {
+		const i = this.listeners[type as keyof Emulator["listeners"]].indexOf(func)
+		if (i === -1) throw new Error(`Listener ${type} could not be found.`)
+		this.listeners[type as keyof Emulator["listeners"]].splice(i, 1)
+	}
+
+	mouseenter(modifiers: string[] = []): void {
+		const event = new EmulatedEvent("mouseenter", { }, modifiers)
+		this._dispatch("mouseenter", event)
+	}
+
+	/**
+	 *
+	 * Emulate pressing/releasing keys.
+	 *
+	 * ```ts
+	 * // press and release a
+	 * emulator.fire("KeyA")
+	 * // hold A down
+	 * emulator.fire("KeyA+")
+	 * // release A
+	 * emulator.fire("KeyA-")
+	 * // press Ctrl+A
+	 * emulator.fire("Ctrl+ KeyA Ctrl-")
+	 *
+	 * // to truly simulate pressing native modifiers, pass all modifiers pressed as an array
+	 * emulator.fire("Ctrl+ KeyA Ctrl-", ["ControlLeft"])
+	 *
+	 * // emulate a modifier state change out of focus
+	 * // e.g. user focuses out, holds control+A, and focuses back
+	 * // only KeyA would fire
+	 *	emulator.fire("KeyA+", ["ControlLeft"])
+	 * // they release both in focus
+	 * emulater.fire("KeyA- Ctrl-")
+	 *
+	 * // to simulate them releasing out of focus again you will have to add a delay since no events would fire
+	 * delay(1000)
+	 *
+	 * ```
+	 *
+	 * Keys should be a {@link KeyboardEvent.code} (though this is not validated) seperated by one or more whitespace characters*. For buttons `0-5` can be used. For wheel events, you can pass `wheelUp/Down` to set the deltaY respectively which is how the manager gets the direction.
+	 *
+	 * `+` and `-` are used to indicate keydown and keyup respectively (except for wheel events*). This can seem confusing but think of the signs as adding/removing from the set of currently held keys. If no `+/-` is given, both are fired.
+	 *
+	 * There is no need to handle toggle keys in any special way. You should fire the root code normally (e.g. `emulator.fire("Capslock")` or `emulator.fire("Capslock+ Capslock-")`)
+	 *
+	 * \* Multiple whitespace characters have no real meaning, but in tests usually I use them to more easily delimite chords.
+	 * \*\* Wheel events do not have keyup/keydown so passing `wheelUp+/-` will incorrectly create a keyboard event.
+	 *
+	 * Note: While the emulator is aware of correct mouse/wheel names, it does not check key names are valid.
+	 */
+	fire(str: string, modifiers: string[] = [], validKeys?: Keys): void {
+		if (!this.initiated) {
+			// eslint-disable-next-line no-console
+			console.warn("No manager attached to the emulator.")
+			return
+		}
+		const keys = str.split(/(\s+)/).filter(part => part.trim() !== "")
+		for (const key of keys) {
+			if (mouseButtons.includes(key)) {
+				this.press("mouse", key, modifiers, validKeys)
+				this.release("mouse", key, modifiers, validKeys)
+			} else if (mouseButtonsDown.includes(key)) {
+				this.press("mouse", key[0], modifiers, validKeys)
+			} else if (mouseButtonsUp.includes(key)) {
+				this.release("mouse", key[0], modifiers, validKeys)
+			} else if (wheelKeys.includes(key)) {
+				this.press("wheel", key, modifiers, validKeys)
+			} else if (key.endsWith("+")) {
+				this.press("key", key.slice(0, key.length - 1), modifiers, validKeys)
+			} else if (key.endsWith("-")) {
+				this.release("key", key.slice(0, key.length - 1), modifiers, validKeys)
+			} else {
+				this.press("key", key, modifiers, validKeys)
+				this.release("key", key, modifiers, validKeys)
+			}
+		}
+	}
+
+	press(type: "mouse" | "wheel" | "key", key: string, modifiers: string[] = [], validKeys?: Keys): void {
+		this._checkIsValidKey(key, validKeys)
+		switch (type) {
+			case "mouse": {
+				const event = new EmulatedEvent("mousedown", { button: Number.parseInt(key, 10) }, modifiers)
+				this._dispatch("mousedown", event)
+			} break
+			case "wheel": {
+				const event = new EmulatedEvent("wheel", { deltaY: key === "wheelDown" ? 1 : 0 }, modifiers)
+				this._dispatch("wheel", event)
+			} break
+			case "key": {
+				const event = new EmulatedEvent("keydown", { code: key }, modifiers)
+				this._dispatch("keydown", event)
+			} break
+		}
+	}
+
+	release(type: "mouse" | "key", key: string, modifiers: string[] = [], validKeys?: Keys): void {
+		this._checkIsValidKey(key, validKeys)
+		switch (type) {
+			case "mouse": {
+				const event = new EmulatedEvent("mouseup", { button: Number.parseInt(key, 10) }, modifiers)
+				this._dispatch("mouseup", event)
+			} break
+			case "key": {
+				const event = new EmulatedEvent("keyup", { code: key }, modifiers)
+				this._dispatch("keyup", event)
+			} break
+		}
+	}
+
+	private _checkIsValidKey(key: string, validKeys?: Keys): void {
+		const valid = validKeys ?? this.validKeys
+
+		if (valid) {
+			const match = Object.values(valid.entries).find(k => k.id === key
+				|| k.toggleOnId === key
+				|| k.toggleOffId === key
+				|| k.variants?.includes(key))
+			if (match === undefined) {
+				throw new Error(`Emulator was asked to fire key not in valid keys array. ${key}`)
+			}
+		}
+	}
+
+	private _dispatch<T extends keyof Emulator["listeners"]>(type: T, event: EmulatedEvent<T>): void {
+		for (const listener of this.listeners[type]) {
+			listener(event)
+		}
+	}
+}
+