@witchcraft/spellcraft 0.0.1

package/src/helpers/managerToStorableClone.ts

@@ -0,0 +1,26 @@
+import type { DeepPartial } from "@alanscodelog/utils/types"
+import { walk } from "@alanscodelog/utils/walk"
+
+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 function managerToStorableClone(m: Manager): DeepPartial<Manager> {
+	const clone = walk(m, undefined, { 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/src/helpers/onKeyboardLayoutChange.ts

@@ -0,0 +1,17 @@
+/**
+	* 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 function onKeyboardLayoutChange(cb: () => void | Promise<void>): boolean {
+	// castType<Navigator>(navigator) // not working during build
+	if (typeof navigator !== "undefined" && "keyboard" in navigator && "addEventListener" in (navigator.keyboard as any)) {
+		(navigator.keyboard as any).addEventListener(cb)
+		return true
+	}
+	return false
+}

package/src/helpers/safeSetManagerChain.ts

@@ -0,0 +1,66 @@
+import { pushIfNotIn } from "@alanscodelog/utils"
+import { last } from "@alanscodelog/utils/last"
+import { Ok, type Result } 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 type { Manager, ManagerSetEntries, MultipleErrors } from "../types/index.js"
+import { cloneChain } from "../utils/cloneChain.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 function safeSetManagerChain(
+	manager: Manager,
+	chain: string[][],
+	{ preserveModifiers = true }: { preserveModifiers?: boolean } = {}
+): Result<string[][], MultipleErrors<
+	ManagerSetEntries["state.chain"]["error"]
+>> {
+	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 as any
+
+	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/src/helpers/shortcutCanExecuteIn.ts

@@ -0,0 +1,24 @@
+import type { Manager, PickManager, Shortcut } from "../types/index.js"
+
+
+export function shortcutCanExecuteIn(
+	shortcut: Shortcut,
+	manager: Pick<Manager, "context" | "commands"> & PickManager<"options", "evaluateCondition">,
+	{
+		allowEmptyCommand = false
+	}: {
+		allowEmptyCommand?: boolean
+	} = {}
+): boolean {
+	const context = manager.context
+	const commands = manager.commands
+	const evaluateCondition = manager.options.evaluateCondition
+
+	const fullCommand = shortcut.command ? commands.entries[shortcut.command] : undefined
+	return shortcut.enabled && (
+		(
+			allowEmptyCommand && (fullCommand?.execute === undefined))
+		|| (fullCommand !== undefined && evaluateCondition(fullCommand?.condition, context)
+		)
+	) && shortcut.condition !== undefined && evaluateCondition(shortcut.condition, context)
+}

package/src/helpers/shortcutIsTriggerableBy.ts

@@ -0,0 +1,15 @@
+import { shortcutCanExecuteIn } from "./shortcutCanExecuteIn.js"
+
+import type { Manager, PickManager, Shortcut } from "../types/index.js"
+import { equalsKeys } from "../utils/equalsKeys.js"
+
+
+export function shortcutIsTriggerableBy(
+	chain: string[][],
+	shortcut: Shortcut,
+	manager: Pick<Manager, "context" | "commands" | "keys"> & PickManager<"options", "evaluateCondition">
+): boolean {
+	return shortcutCanExecuteIn(shortcut, manager, { allowEmptyCommand: true })
+		&& equalsKeys(shortcut.chain, chain, manager.keys, undefined, { allowVariants: true })
+}
+

package/src/helpers/shortcutSwapChords.ts

@@ -0,0 +1,240 @@
+import { crop } from "@alanscodelog/utils/crop"
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { KnownError } from "./KnownError.js"
+
+import { setShortcutProp } from "../core/setShortcutProp.js"
+import { defaultStringifier } from "../defaults/Stringifier.js"
+import type { IStringifier, Keys, Manager, PickManager, Shortcut, Shortcuts } from "../types/index.js"
+import { SHORTCUT_ERROR } from "../types/index.js"
+import { equalsKeys } from "../utils/equalsKeys.js"
+
+
+function setForceUnequalOnAll<TSave extends boolean = false>(shortcuts: Shortcut[], val: boolean | boolean[], save: TSave = false as TSave): TSave extends true ? boolean[] : undefined {
+	const was: boolean[] | undefined = save ? [] : undefined
+	for (let i = 0; i < shortcuts.length; i++) {
+		const shortcut = shortcuts[i]
+		if (save) was!.push(shortcut.forceUnequal)
+		// it's safe to not handle the result, forceUnequal is not canHookable
+		setShortcutProp(shortcut, "forceUnequal", typeof val === "boolean" ? val : val[i], {})
+	}
+	return was as any
+}
+
+function canSwapChords(
+	shortcuts: Shortcuts,
+	manager: Pick<Manager, "keys" | "shortcuts" | "commands">
+		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter">,
+	chainA: string[][],
+	chainB: string[][],
+	filter?: (shortcut: Shortcut) => boolean
+): Result<true, Error | KnownError<typeof SHORTCUT_ERROR.INVALID_SWAP_CHORDS | typeof SHORTCUT_ERROR.DUPLICATE_SHORTCUT>> {
+	let can: Result<true, any> = Ok(true)
+	const shortcutsClone = { ...shortcuts, entries: [...shortcuts.entries.map(_ => ({ ..._ }))] }
+	const managerClone = { ...manager, shortcuts: shortcutsClone }
+
+	const { shortcutsA, shortcutsB } = getToSwap(shortcutsClone, manager, chainA, chainB, filter)
+
+	const wasA = setForceUnequalOnAll(shortcutsA, true, true)
+
+	for (const shortcutB of shortcutsB) {
+		const newChain = [...chainA, ...shortcutB.chain.slice(chainA.length, shortcutB.chain.length)]
+		const res = setShortcutProp(shortcutB, "chain", newChain, managerClone)
+		if (res.isError) {
+			can = res as any
+			break
+		}
+	}
+	setForceUnequalOnAll(shortcutsA, wasA)
+
+	if (can.isOk) {
+		const wasB = setForceUnequalOnAll(shortcutsB, true, true)
+		for (const shortcutA of shortcutsA) {
+			const newChain = [...chainB, ...shortcutA.chain.slice(chainB.length, shortcutA.chain.length)]
+			const res = setShortcutProp(shortcutA, "chain", newChain, managerClone)
+			if (res.isError) {
+				can = res as any
+				break
+			}
+		}
+		setForceUnequalOnAll(shortcutsB, wasB)
+	}
+
+	return can
+}
+
+
+function assertChordsNotEmpty(chord: string[][],
+	keys: Keys,
+	{ stringifier: s = defaultStringifier }: { stringifier?: IStringifier } = {}
+): Result<true, KnownError<typeof SHORTCUT_ERROR.INVALID_SWAP_CHORDS>> {
+	let found: undefined | string[][]
+	if (chord.length === 0 || chord.find(ks => ks.length === 0)) {
+		found = chord
+	}
+	if (found) {
+		return Err(new KnownError(
+			SHORTCUT_ERROR.INVALID_SWAP_CHORDS,
+			`Cannot swap with empty chord, but ${s.stringify(chord, { keys })} contains an empty chord.`,
+			{ chord }
+		))
+	}
+	return Ok(true)
+}
+
+
+function assertCorrectSwapParameters(
+	keys: Keys,
+	chordsA: string[][], chordsB: string[][],
+	{
+		stringifier: s = defaultStringifier
+	}: {
+		stringifier?: IStringifier
+	} = {}
+): Result<true, KnownError<typeof SHORTCUT_ERROR.INVALID_SWAP_CHORDS>> {
+	const canA = assertChordsNotEmpty(chordsA, keys, { stringifier: s })
+	if (canA.isError) { return canA }
+	const canB = assertChordsNotEmpty(chordsB, keys, { stringifier: s })
+	if (canB.isError) { return canB }
+
+	if (equalsKeys(chordsA, chordsB, keys, chordsB.length)
+		|| equalsKeys(chordsB, chordsA, keys, chordsA.length)
+	) {
+		return Err(new KnownError(SHORTCUT_ERROR.INVALID_SWAP_CHORDS, crop`
+			The chords to swap cannot share starting chords.
+			Chords:
+			${s.stringify(chordsA, { keys })}
+			${s.stringify(chordsB, { keys })}
+			`, { chordsA, chordsB }))
+	}
+	return Ok(true)
+}
+function getToSwap(
+	shortcuts: Shortcuts,
+	manager: Pick<Manager, "keys" | "shortcuts" | "commands">
+		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter">,
+	chainA: string[][],
+	chainB: string[][],
+	filter?: (shortcut: Shortcut) => boolean
+): { shortcutsA: Shortcut[], shortcutsB: Shortcut[] } {
+	let shortcutsA = shortcuts.entries.filter(shortcut => equalsKeys(shortcut.chain, chainA, manager.keys, chainA.length))
+	let shortcutsB = shortcuts.entries.filter(shortcut => equalsKeys(shortcut.chain, chainB, manager.keys, chainB.length))
+
+	if (filter) {
+		shortcutsA = shortcutsA.filter(filter)
+		shortcutsB = shortcutsB.filter(filter)
+	}
+	return { shortcutsA, shortcutsB }
+}
+
+/**
+ * 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 function shortcutSwapChords(
+	shortcuts: Shortcuts,
+	chainA: string[][],
+	chainB: string[][],
+	manager: Pick<Manager, "keys" | "shortcuts" | "commands">
+		& PickManager<"options", | "evaluateCondition" | "conditionEquals" | "stringifier" | "sorter">,
+	{
+		check = true
+	}: {
+		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> {
+	const res = assertCorrectSwapParameters(manager.keys, chainA, chainB)
+	if (res.isError) { return res }
+
+	if (check) {
+		const res = canSwapChords(shortcuts, manager, chainA, chainB, filter)
+		if (res.isError) { return res }
+	}
+
+	if (check === "only") {
+		return Ok(true)
+	}
+
+	const { shortcutsA, shortcutsB } = getToSwap(shortcuts, manager, chainA, chainB, filter)
+
+	const wasA = setForceUnequalOnAll(shortcutsA, true, true)
+	for (const shortcutB of shortcutsB) {
+		setShortcutProp(shortcutB, "chain", [...chainA, ...shortcutB.chain.slice(chainA.length, shortcutB.chain.length)], manager, { check: false })
+	}
+	setForceUnequalOnAll(shortcutsA, wasA)
+
+	const wasB = setForceUnequalOnAll(shortcutsA, true, true)
+	for (const shortcutA of shortcutsA) {
+		setShortcutProp(shortcutA, "chain", [...chainB, ...shortcutA.chain.slice(chainB.length, shortcutA.chain.length)], manager, { check: false })
+	}
+	setForceUnequalOnAll(shortcutsA, wasB, true)
+
+
+	return Ok(true)
+}
+

package/src/helpers/virtualPress.ts

@@ -0,0 +1,34 @@
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+
+import { addToChain } from "../internal/addToChain.js"
+import { setKeysState } from "../internal/setKeysState.js"
+import type { Manager } from "../types/index.js"
+
+/**
+ * The manager is not designed to react to setting a key's pressed state directly only to events to then set the key state.
+ *
+ * So this method is provided to allow a "virtual" press (i.e. by some method that is not a real key press such as directly clicking on a visual representation of the key), without having to use the Emulator.
+ *
+ * It takes care of changing the key press state, and adding the key to the chain.
+ *
+ * Note that it is more simplistic and less "precise" than the emulator. It will ignore the type of toggles (native toggles will be treated as emulated). If using {@link Manager.options.updateStateOnAllEvents}, you will probably want to temporarily disable it or the state of the key press might get immediately reset.
+ *
+ * There is also {@link virtualRelease} and {@link virtualToggle}.
+ */
+export function virtualPress(
+	manager: Manager,
+	keyIdOrVariant: string
+): void {
+	const res = getKeyFromIdOrVariant(keyIdOrVariant, manager.keys)
+	if (res.isError) {
+		manager.options.cb(manager, res.error)
+		return
+	}
+	const key = res.value[0]
+	const keys = [key.id]
+
+	manager.listener?.({ isKeydown: true, keys, manager })
+	setKeysState(keys, manager, true, { ignoreToggleType: true })
+	addToChain(manager, keys, undefined)
+}
+

package/src/helpers/virtualRelease.ts

@@ -0,0 +1,25 @@
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+
+import { removeFromChain } from "../internal/removeFromChain.js"
+import { setKeysState } from "../internal/setKeysState.js"
+import type { Manager } from "../types/index.js"
+
+/**
+ * See {@link virtualPress}
+ */
+export function virtualRelease(
+	manager: Manager,
+	keyIdOrVariant: string
+): void {
+	const res = getKeyFromIdOrVariant(keyIdOrVariant, manager.keys)
+	if (res.isError) {
+		manager.options.cb(manager, res.error)
+		return
+	}
+	const key = res.value[0]
+	const keys = [key.id]
+	manager.listener?.({ isKeydown: false, keys, manager })
+	setKeysState(keys, manager, false)
+	removeFromChain(manager, keys, undefined)
+}
+

package/src/helpers/virtualToggle.ts

@@ -0,0 +1,28 @@
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+import { virtualPress } from "./virtualPress.js"
+import { virtualRelease } from "./virtualRelease.js"
+
+import type { Manager } from "../types/index.js"
+
+/**
+ * Calls {@link virtualRelease} if the key is pressed.
+ *
+ * Calls {@link virtualPress} if the key is released.
+ */
+export function virtualToggle(
+	manager:	Manager,
+	keyIdOrVariant: string
+): void {
+	const res = getKeyFromIdOrVariant(keyIdOrVariant, manager.keys)
+	if (res.isError) {
+		manager.options.cb(manager, res.error)
+		return
+	}
+	const key = res.value[0]
+	if (key.pressed) {
+		virtualRelease(manager, keyIdOrVariant)
+	} else {
+		virtualPress(manager, keyIdOrVariant)
+	}
+}
+

package/src/internal/addToChain.ts

@@ -0,0 +1,40 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { checkTrigger } from "./checkTrigger.js"
+
+import { setManagerProp } from "../core/setManagerProp.js"
+import type { AnyInputEvent, Manager, ManagerSetEntries, MultipleErrors } from "../types/index.js"
+import { cloneChain } from "../utils/cloneChain.js"
+
+
+export function addToChain(
+	manager: Manager,
+	keysList: string[],
+	e?: AnyInputEvent
+): Result<true, MultipleErrors<ManagerSetEntries["state.chain"]["error"]>> {
+	const sorter = manager.options.sorter
+	if (manager.state.isAwaitingKeyup) return Ok(true)
+	if (keysList.length === 0) return Ok(true)
+
+	if (manager.state.nextIsChord) {
+		// we unwrap when setting the chain because the manager should not be creating invalid states
+		// if it does, it's a bug
+		setManagerProp(manager, "state.chain", cloneChain([...manager.state.chain, []])).unwrap()
+		setManagerProp(manager, "state.nextIsChord", false)
+	}
+	const length = manager.state.chain.length - 1
+	const lastChord = [...(manager.state.chain[length] ?? [])]
+	for (const id of keysList) {
+		if (!lastChord.includes(id)) {
+			lastChord.push(id)
+			const res = setManagerProp(manager, "state.chain", cloneChain([
+				...manager.state.chain.slice(0, length),
+				sorter.sort(lastChord, manager.keys)
+			]))
+			if (res.isError) return res as any
+			checkTrigger(manager, e)
+		}
+	}
+	return Ok(true)
+}
+

package/src/internal/areValidKeys.ts

@@ -0,0 +1,40 @@
+import { crop } from "@alanscodelog/utils/crop"
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js"
+import { KnownError } from "../helpers/KnownError.js"
+import type { Manager, MultipleErrors, PickManager, Shortcut } from "../types/index.js"
+import { SHORTCUT_ERROR } from "../types/index.js"
+
+/**
+ * @internal
+ */
+export function areValidKeys(
+	chain: string[][] | Shortcut,
+	manager: Pick<Manager, "keys"> & PickManager<"options", "stringifier">
+
+): Result<true, MultipleErrors<typeof SHORTCUT_ERROR.UNKNOWN_KEY>> {
+	const s = manager.options.stringifier
+	const keys = manager.keys
+
+	const shortcut = "type" in chain ? chain : undefined
+	chain = "type" in chain ? chain.chain : chain
+	const unknownKeys = []
+	for (const key of chain.flat()) {
+		const res = getKeyFromIdOrVariant(key, keys)
+		if (res.isError) {
+			unknownKeys.push(key)
+		}
+	}
+
+	if (unknownKeys.length > 0) {
+		const stringified = s.stringifyList("keys", unknownKeys, { keys })
+		return Err(new KnownError(SHORTCUT_ERROR.UNKNOWN_KEY, crop`
+			${s.stringify(shortcut ?? chain, manager)} contains unknown keys: ${stringified}
+			`, {
+			shortcut: shortcut ?? { chain },
+			keys: unknownKeys
+		}))
+	}
+	return Ok(true)
+}

package/src/internal/areValidVariants.ts

@@ -0,0 +1,59 @@
+import { crop } from "@alanscodelog/utils/crop"
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { getKeyFromIdOrVariant } from "../helpers/getKeyFromIdOrVariant.js"
+import { KnownError } from "../helpers/KnownError.js"
+import { type Key, type KeysSetEntries, SHORTCUT_ERROR } from "../types/index.js"
+
+
+export function areValidVariants(
+	key: Key,
+	manager: KeysSetEntries["entries@add"]["manager"]
+): Result<true, KnownError<typeof SHORTCUT_ERROR.INVALID_VARIANT_PAIR>> {
+	const keys = manager.keys
+	const s = manager.options.stringifier
+	const existingVariants = (keys.variants?.[key.id]?.map(id => keys.entries[id]) ?? [])
+
+	const keysVariants = key.variants
+		? key.variants
+				.flatMap(id => {
+					const res = getKeyFromIdOrVariant(id, keys)
+					if (res.isOk) return res.value
+					// it's fine for a key's variants to not exist / have been added yet
+					return []
+				})
+		: []
+
+	const variants = [...existingVariants, ...keysVariants]
+	for (const k of variants) {
+		if (!!key.isToggle !== !!k.isToggle) {
+			const stringKey = s.stringify(key, manager)
+			const stringOtherKey = s.stringify(k, manager)
+			return Err(new KnownError(SHORTCUT_ERROR.INVALID_VARIANT_PAIR, crop`
+				Key ${stringKey} specifies a variant or matches an existing key's variant (${stringOtherKey}), but their functionality is not the same.
+
+				Key ${stringKey} "isToggle" is "${key.isToggle}" while key ${stringOtherKey} "isToggle" is "${k.isToggle}".
+			`, {
+				variants,
+				key,
+				otherKey: k
+
+			}))
+		}
+
+		if (!!key.isModifier !== !!k.isModifier) {
+			const stringKey = s.stringify(key, manager)
+			const stringOtherKey = s.stringify(k, manager)
+			return Err(new KnownError(SHORTCUT_ERROR.INVALID_VARIANT_PAIR, crop`
+				Key ${stringKey} specifies a variant or matches an existing key's variant (${stringOtherKey}), but their functionality is not the same.
+
+				Key ${stringKey} "isModifier" is "${key.isModifier}" while key ${stringOtherKey} "isModifier" is "${k.isModifier}".
+			`, {
+				variants,
+				key,
+				otherKey: k
+			}))
+		}
+	}
+	return Ok(true)
+}

package/src/internal/checkTrigger.ts

@@ -0,0 +1,55 @@
+import { checkUntrigger } from "./checkUntrigger.js"
+import { cloneLastChord } from "./cloneLastChord.js"
+import { inChain } from "./inChain.js"
+
+import { setManagerProp } from "../core/setManagerProp.js"
+import { getTriggerableShortcut } from "../helpers/getTriggerableShortcut.js"
+import { KnownError } from "../helpers/KnownError.js"
+import { type AnyInputEvent, type Manager, SHORTCUT_ERROR } from "../types/index.js"
+import { isTriggerKey } from "../utils/isTriggerKey.js"
+
+
+export function checkTrigger(
+	manager: Manager,
+	e?: AnyInputEvent
+): void {
+	checkUntrigger(manager, e)
+	const hadUntrigger = manager.state.untrigger
+	const cb = manager.options.cb
+	if (!manager.options.enableShortcuts) return
+	const res = getTriggerableShortcut(manager)
+	if (res.isError) {
+		cb(manager, res.error as KnownError<typeof SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS>, e)
+	} else if (res.value && res.value !== hadUntrigger) {
+		setManagerProp(manager, "state.untrigger", res.value)
+		setManagerProp(manager, "state.nextIsChord", false)
+		const command = manager.commands.entries[res.value.command]
+		command?.execute?.({
+			isKeydown: true,
+			command,
+			shortcut: res.value,
+			event: e,
+			manager,
+			context: manager.context
+		})
+	}
+	const triggerKey = cloneLastChord(manager.state.chain)?.find(id => isTriggerKey(manager.keys.entries[id]))
+	const nonTriggerKey = cloneLastChord(manager.state.chain)?.find(id => !isTriggerKey(manager.keys.entries[id]))
+	if (triggerKey) {
+		if (inChain(manager) || manager.state.isRecording) {
+			setManagerProp(manager, "state.nextIsChord", true)
+			if (nonTriggerKey) {
+				setManagerProp(manager, "state.isAwaitingKeyup", true)
+			}
+		} else if (!manager.state.isRecording && !inChain(manager) && (res.isOk && !res.value) && manager.state.chain.length > 1) {
+			const error = new KnownError(
+				SHORTCUT_ERROR.NO_MATCHING_SHORTCUT,
+				"A chord containing a non-modifier key was pressed while in a chord chain, but no shortcut found to trigger.",
+				{ chain: manager.state.chain }
+			)
+
+			cb(manager, error, e)
+		}
+	}
+}
+