@witchcraft/spellcraft 0.0.1

package/src/utils/chainContainsSubset.ts

@@ -0,0 +1,97 @@
+import { containsKey } from "./containsKey.js"
+import { dedupeKeys } from "./dedupeKeys.js"
+import { equalsKeys } from "./equalsKeys.js"
+
+import type { Keys } from "../types/index.js"
+
+
+/**
+ * Returns whether a chain is a subset of another, taking into account variants (this can be disabled).
+ */
+
+export const chainContainsSubset = (
+	chain: readonly string[][],
+	chainSubset: readonly string[][],
+	keys: Keys,
+	{
+		onlySubset = false,
+		onlyPressable = false,
+		allowVariants = true
+	}: {
+		/**
+		 * If true, will return false if the last chord of the chainSubset is exactly equal.
+		 *
+		 * So for example, for the chain: [[a], [ctrl+b]], the following would return as follows:
+		 *
+		 * ```
+		 * // true
+		 * [[]] or []
+		 * [[a]]
+		 * [[a], []]
+		 * [[a], [ctrl]]
+		 * [[a], [b]]
+		 *
+		 * // false
+		 * [[a], [ctrl, b]]
+		 * ```
+		 */
+		onlySubset?: boolean
+		/** If true, will return false if the shortcut is not one key press away. */
+		onlyPressable?: boolean
+		allowVariants?: boolean
+	} = { }
+): boolean => {
+	const opts = { allowVariants }
+
+	if (chainSubset.length === 0) {
+		const isEmpty = chain.length === 0 || (chain.length === 1 && chain[0].length === 0)
+		if (isEmpty) return onlySubset
+		return !onlyPressable || (chain.length === 1 && chain[0].length === 1)
+	}
+
+	if (chainSubset.length > chain.length) return false
+
+
+	const index = chainSubset.length === 0 ? 0 : chainSubset.length - 1
+
+	const precedingChords = chainSubset.slice(0, index)
+	const precedingChordsEqual = index === 0 || equalsKeys(chain, precedingChords, keys, precedingChords.length, opts)
+	if (!precedingChordsEqual) return false
+	if (onlyPressable && index !== chain.length - 1) return false
+
+	const subsetLastChord = dedupeKeys(chainSubset[index], keys, opts)
+	// note it might NOT be the last chord
+	const chainLastSharedChord = dedupeKeys(chain[index], keys, opts)
+
+	if (onlySubset) {
+		if (subsetLastChord.length === chainLastSharedChord.length) {
+			// they match exactly, so it's not strictly a subset
+			if (chainSubset.length === chain.length) return false
+			// the chainSubset is x chords too short, this is always a subset
+			if (chainSubset.length < chain.length) return true
+		}
+	}
+
+	for (const key of subsetLastChord) {
+		if (!containsKey(chainLastSharedChord, key, keys, opts)) {
+			return false
+		}
+	}
+
+	const subsetModifiers = subsetLastChord.filter(key => keys.entries[key].isModifier)
+	const modifiers = chainLastSharedChord.filter(key => keys.entries[key].isModifier)
+
+	const modKeysDiff = modifiers.length - subsetModifiers.length
+
+	const subsetNonModKeysCount = subsetLastChord.length - subsetModifiers.length
+	const nonModKeysCount = chainLastSharedChord.length - modifiers.length
+	const nonModKeysDiff = nonModKeysCount - subsetNonModKeysCount
+
+	if (onlySubset && modKeysDiff === 0 && nonModKeysDiff === 0) return false
+	if (onlyPressable && !(
+		(modKeysDiff === 0 && nonModKeysDiff === 1)
+		|| (modKeysDiff === 1 && nonModKeysDiff === 0)
+	)) { return false }
+
+	return true
+}

package/src/utils/cloneChain.ts

@@ -0,0 +1,13 @@
+/** Deep clones a shortcut chain. */
+export function cloneChain(chain: string[][]): string[][] {
+	const clone = []
+	for (const chord of chain) {
+		const chordClone = []
+		for (const key of chord) {
+			chordClone.push(key)
+		}
+		clone.push(chordClone)
+	}
+
+	return clone
+}

package/src/utils/cloneKey.ts

@@ -0,0 +1,33 @@
+import type { Key } from "../types/index.js"
+
+/** Deep clones a key. */
+export function cloneKey(key: Key): Key {
+	// cloning like this is just lightining fast.
+	const clone: Key = {
+		type: key.type,
+		id: key.id,
+		label: key.label,
+		classes: [...key.classes],
+		x: key.x,
+		y: key.y,
+		width: key.width,
+		height: key.height,
+		enabled: key.enabled,
+		pressed: key.pressed,
+		isModifier: key.isModifier,
+		variants: key.variants ? [...key.variants] : undefined,
+		render: key.render,
+		updateStateOnAllEvents: key.updateStateOnAllEvents,
+		isToggle: key.isToggle,
+		...(key.isToggle
+			? {
+				toggleOnPressed: key.toggleOnPressed,
+				toggleOnId: key.toggleOnId,
+				toggleOffId: key.toggleOffId,
+				toggleOffPressed: key.toggleOffPressed
+			} satisfies Partial<Key<string>>
+			: {}) as any
+	}
+
+	return clone
+}

package/src/utils/containsKey.ts

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

package/src/utils/dedupeKeys.ts

@@ -0,0 +1,23 @@
+import { equalsKey } from "./equalsKey.js"
+
+import type { Keys } from "../types/index.js"
+
+/**
+ * Returns a new array deduped according to {@link equalsKey}.
+ *
+ * This is useful when keys have variants to dedupe them by their variants since a shortcut might contain multiple variants, which can make it hard to check chords satisfy certain conditions (e.g. x amount of modifiers).
+ */
+export const dedupeKeys = (
+	// we take a string to avoid having to deal with toggle keys
+	keyList: string[],
+	keys: Keys,
+	opts: { allowVariants?: boolean } = {}
+): string[] => {
+	const res: string[] = []
+	for (const keyId of keyList) {
+		if (res.find(id => equalsKey(id, keyId, keys, opts))) continue
+		res.push(keyId)
+	}
+	return res
+}
+

package/src/utils/equalsKey.ts

@@ -0,0 +1,32 @@
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js"
+import type { Keys } from "../types/index.js"
+
+/**
+ * Returns whether the key (b) passed is equal to key (a).
+ *
+ * To return true, their ids must be equal.
+ *
+ * There is an `allowVariants` option that is true by default that allows the keyB to be equal if any of their variants match.
+ *
+ */
+
+export function equalsKey(
+	keyIdA: string,
+	keyIdB: string,
+	keys: Keys,
+	{ allowVariants = true }: { allowVariants?: boolean } = {}
+): boolean {
+	const idsEqual = keyIdA === keyIdB
+
+	const keyA = getKeyFromIdOrVariant(keyIdA, keys).unwrap()[0]
+	const keyB = getKeyFromIdOrVariant(keyIdB, keys).unwrap()[0]
+
+	if (!idsEqual && allowVariants && keyA.variants && keyB.variants) {
+		for (const variant of keyA.variants) {
+			if (keyB.variants.includes(variant)) return true
+		}
+		return false
+	}
+	return idsEqual
+}
+

package/src/utils/equalsKeys.ts

@@ -0,0 +1,50 @@
+import { containsKey } from "./containsKey.js"
+import { dedupeKeys } from "./dedupeKeys.js"
+
+import type { Keys } from "../types/index.js"
+
+/**
+ * Returns if the given chords are equal.
+ *
+ * Can be passed a length, to limit the search to only the first x chords.
+ *
+ * ```ts
+ * equalsKeys([[keyA]], [[keyA]]) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA]]) // false
+ * equalsKeys([[keyA], [keyB]], [[keyA]], 1) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA], [keyB]], 2) // true
+ * equalsKeys([[keyA], [keyB]], [[keyA], [keyB], [keyC]], 3) // false
+ * equalsKeys([[keyA], [keyB]], [[keyB]], 1) // false
+ * ```
+ * Can also pass options to {@link equalsKey}:
+ *
+ * ```ts
+ * equalsKeys([[keyA], [keyB]], [[keyAVariant], [keyB]], 2, { allowVariants: true }) // true
+ * ```
+ *
+ */
+export function equalsKeys(
+	chain: readonly string[][],
+	base: readonly string[][],
+	keys: Keys,
+	length?: number,
+	opts: { allowVariants?: boolean } = {}
+): boolean {
+	// Since they're pre-sorted this should be quite fast
+	if (
+		(length === undefined && base.length !== chain.length)
+		|| (length !== undefined && (chain.length < length || base.length < length))
+	) return false
+
+	return chain.slice(0, length ?? chain.length)
+		.find((thisChord, c) => {
+			if (!base[c]) return true
+			const otherChord = dedupeKeys(base[c], keys, opts)
+			thisChord = dedupeKeys(thisChord, keys, opts)
+			if (otherChord.length !== thisChord.length) return true
+			for (const otherKey of otherChord) {
+				if (!containsKey(thisChord, otherKey, keys, opts)) return true
+			}
+			return false
+		}) === undefined
+}

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+/* Autogenerated Index [Ignore] */
+
+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/src/utils/isAnyKey.ts

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

package/src/utils/isMouseKey.ts

@@ -0,0 +1,27 @@
+import type { Key } from "../types/index.js"
+
+
+const possibleIds = [
+	"0",
+	"1",
+	"2",
+	"3",
+	"4",
+	"0On",
+	"1On",
+	"2On",
+	"3On",
+	"4On",
+	"0Off",
+	"1Off",
+	"2Off",
+	"3Off",
+	"4Off"
+]
+/**
+ * Returns whether a key is a mouse key (id = 0-4).
+ */
+export function isMouseKey(key: Key): boolean {
+	return possibleIds.includes(key.id)
+		|| (key.variants?.some(id => possibleIds.includes(id)) ?? false)
+}

package/src/utils/isNormalKey.ts

@@ -0,0 +1,15 @@
+import { isMouseKey } from "./isMouseKey.js"
+import { isWheelKey } from "./isWheelKey.js"
+
+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 function isNormalKey(key: Key): boolean {
+	return !isWheelKey(key)
+		&& !isMouseKey(key)
+		&& !key.isModifier
+		&& !key.isToggle
+}

package/src/utils/isTriggerKey.ts

@@ -0,0 +1,7 @@
+import type { Key } from "../types/index.js"
+/**
+ * See {@link Manager} and {@link Manager.pressedNonModifierKeys}.
+ */
+export function isTriggerKey(key: Key): boolean {
+	return !key.isModifier && !key.isToggle
+}

package/src/utils/isWheelKey.ts

@@ -0,0 +1,18 @@
+import type { Key } from "../types/index.js"
+
+
+const possibleIds = [
+	"WheelUp",
+	"WheelDown",
+	"WheelUpOn",
+	"WheelDownOn",
+	"WheelUpOff",
+	"WheelDownOff"
+]
+/**
+ * Returns whether a key is a a wheel up/down "key".
+ */
+export function isWheelKey(key: Key): boolean {
+	return possibleIds.includes(key.id)
+		|| (key.variants?.some(id => possibleIds.includes(id)) ?? false)
+}

package/src/utils/mapKeys.ts

@@ -0,0 +1,21 @@
+import { isArray } from "@alanscodelog/utils/isArray"
+
+/**
+ * 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 function mapKeys<
+	TType extends any[] | any[][],
+	TReturn = string
+>(
+	chainOrChord: TType,
+	func: (key: TType extends any[][] ? TType[number][number] : TType[number]) => TReturn = key => (key as any)?.id
+): TType extends any[][] ? TReturn[][] : TReturn[] {
+	if (chainOrChord.length === 0) return []
+	return isArray(chainOrChord[0])
+		? (chainOrChord as TType[][]).map(chord => chord.map(key => func(key as any))) as any
+		: (chainOrChord as TType[]).map(key => func(key as any)) as any
+}

package/src/utils/removeKeys.ts

@@ -0,0 +1,16 @@
+import { equalsKey } from "./equalsKey.js"
+
+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 const removeKeys = (
+	keysList: readonly string[],
+	toRemove: readonly string[],
+	keys: Keys,
+	opts: { allowVariants?: boolean } = {}
+): string[] => keysList
+	.filter(key =>
+		toRemove.find(_ => equalsKey(key, _, keys, opts)) === undefined
+	)