@witchcraft/spellcraft 0.0.1

package/src/helpers/doesShortcutConflict.ts

@@ -0,0 +1,72 @@
+import { equalsShortcut } from "./equalsShortcut.js"
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+
+import type { Manager, PickManager, Shortcut } from "../types/index.js"
+import { equalsKey } from "../utils/equalsKey.js"
+import { equalsKeys } from "../utils/equalsKeys.js"
+
+/**
+ * A shortcut conflicts with another if their conditions are equal and their chains are in conflict.
+ *
+ * Chains can be in conflict in any of the following situations:
+ *
+ * - The shortcuts are the same instance.
+ * - All the keys are the same.
+ * - They share starting chords and the last shared chord conflicts. (e.g. [[A], [B]] and [[A]]), i.e. they have a chain conflict.
+ * - The last chords shares all modifiers and one of the chords is all modifiers. (e.g. [[A], [Ctrl]] and [[A], [Ctrl, A]]), i.e. they have a modifier conflict.
+ *
+ * Some of these can be ignored with the experimental ignore* options.
+ *
+ * A context can be passed for a more accurate test, otherwise depending on what type of conditions you use (see {@link ConditionComparer}) you cannot truly tell if shortcuts with complex conditions will conflict. See the option itself for more details.
+ */
+export function doesShortcutConflict<TShortcut extends Shortcut>(
+	shortcutA: TShortcut,
+	shortcutB: Shortcut,
+	manager: Pick<Manager, "keys" | "commands" | "shortcuts"> & { context?: Manager["context"] }
+		& PickManager<"options", "evaluateCondition" | "conditionEquals">
+): boolean {
+	const context = manager.context
+	if (!context && manager.shortcuts.useContextInConflictCheck) {
+		throw new Error("Manager must have a context if `useContextInConflictCheck` is true.")
+	}
+	const {
+		ignoreChainConflicts,
+		ignoreModifierConflicts
+	} = manager.shortcuts
+	if (ignoreChainConflicts && ignoreModifierConflicts) return false
+
+	if (shortcutA.forceUnequal || shortcutB.forceUnequal) return false
+	if (equalsShortcut(shortcutA, shortcutB, manager)) return true
+	const evaluateCondition = manager.options.evaluateCondition
+	const conditionEquals = manager.options.conditionEquals
+	if (context) {
+		if (shortcutA.condition && shortcutB.condition) {
+			const shortcutCondition = evaluateCondition(shortcutA.condition, context)
+			const otherCondition = evaluateCondition(shortcutB.condition, context)
+			if (shortcutCondition !== otherCondition) return false
+			if (!shortcutCondition) return false
+		}
+	} else {
+		if	(!conditionEquals(shortcutA.condition, shortcutB.condition)) return false
+	}
+	const { keys } = manager
+	// an empty chain is always in conflict ?
+	if (shortcutA.chain.length === 0 || shortcutB.chain.length === 0) {
+		return ignoreChainConflicts === true && ignoreModifierConflicts === true
+	}
+
+	const lastSharedIndex = Math.max(0, Math.min(shortcutA.chain.length - 1, shortcutB.chain.length - 1))
+	const lastIsModOnly = shortcutA.chain[lastSharedIndex].find(id => !getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier) === undefined
+	const otherLastIsModOnly = shortcutB.chain[lastSharedIndex].find(id => !getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier) === undefined
+	const sharedModifiers = shortcutA.chain[lastSharedIndex].filter(id => getKeyFromIdOrVariant(id, keys).unwrap()[0].isModifier
+		&& shortcutB.chain[lastSharedIndex].some(otherId => equalsKey(otherId, id, keys, { allowVariants: true }))
+	)
+
+
+	const lastSharedChordConflicts = (lastIsModOnly || otherLastIsModOnly) && sharedModifiers.length > 0
+	const conflictsWithChain = equalsKeys(shortcutA.chain, shortcutB.chain, keys, lastSharedIndex + 1, { allowVariants: true })
+	return (
+		(!ignoreChainConflicts && conflictsWithChain)
+		|| (!ignoreModifierConflicts && lastSharedChordConflicts)
+	)
+}

package/src/helpers/equalsCommand.ts

@@ -0,0 +1,18 @@
+import type { Command, PickManager } from "../types/index.js"
+
+/**
+ * Returns whether the command passed is equal to this one.
+ *
+ * The name, execute, description, and conditions must be equal.
+ */
+export function equalsCommand<TCommand extends Command>(
+	commandA: TCommand,
+	commandB: Command,
+	manager: PickManager<"options", "conditionEquals">
+): commandB is TCommand {
+	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
+}

package/src/helpers/equalsContext.ts

@@ -0,0 +1,29 @@
+import type { Context, RecursiveRecord } from "../types/index.js"
+
+
+function fastIsEqual(obj: RecursiveRecord, other: RecursiveRecord): boolean {
+	const keys1 = Object.keys(obj)
+	const keys2 = Object.keys(other)
+	if (keys1.length !== keys2.length) return false
+	for (const key of keys1) {
+		const val1 = obj[key]
+		const val2 = other[key]
+		if (typeof val1 === "object" && typeof val2 === "object") {
+			if (!fastIsEqual(val1, val2)) return false
+		}
+		if (val1 !== val2) {
+			return false
+		}
+	}
+	return true
+}
+
+/**
+ * Returns whether the context passed is equal to this one.
+ *
+ * The default methods provides a simple comparison that can handle simple flat or nested objects (simple as in it assumes values are not arrays). If you need something more complex you will need to provide your own function.
+ */
+
+export function equalsContext(contextA: Context, contextB: Context): boolean {
+	return fastIsEqual(contextA.value, contextB.value)
+}

package/src/helpers/equalsShortcut.ts

@@ -0,0 +1,34 @@
+import { equalsCommand } from "./equalsCommand.js"
+
+import type { Manager, PickManager, Shortcut } from "../types/index.js"
+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.
+ */
+export function equalsShortcut<TShortcut extends Shortcut>(
+	shortcutA: TShortcut,
+	shortcutB: Shortcut,
+	manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", | "evaluateCondition" | "conditionEquals">,
+	{ ignoreCommand = false }: { ignoreCommand?: boolean } = {}
+): shortcutB is TShortcut {
+	if (shortcutA.forceUnequal || shortcutB.forceUnequal) return false
+	if (shortcutA === shortcutB) return true
+	return (
+		equalsKeys(shortcutA.chain, shortcutB.chain, manager.keys, undefined, { allowVariants: true })
+		&& manager.options.conditionEquals(shortcutA.condition, shortcutB.condition)
+		&& (ignoreCommand
+			|| (
+				shortcutA.command === shortcutB.command
+				&& shortcutA.command === undefined
+			)
+			|| (shortcutA.command !== undefined
+				&& shortcutB.command !== undefined
+				&& equalsCommand(manager.commands.entries[shortcutA.command], manager.commands.entries[shortcutB.command], manager)
+			)
+		)
+	)
+}
+

package/src/helpers/forceClear.ts

@@ -0,0 +1,31 @@
+import { setKeyProp } from "../core/setKeyProp.js"
+import { setManagerProp } from "../core/setManagerProp.js"
+import type { Manager } from "../types/index.js"
+
+/**
+ * Force clears/resets all state. Clears the chain and sets all keys to unpressed.
+ *
+ * Useful for testing.
+ *
+ * @param opts
+ * @param {false} opts.ignoreNative  If true, does not change state of native modifier/toggle keys.
+ */
+
+
+export function forceClear(manager: Manager, { ignoreNative = false }: { ignoreNative?: boolean } = {}): void {
+	setManagerProp(manager, "state.chain", [])
+	setManagerProp(manager, "state.nextIsChord", true)
+	setManagerProp(manager, "state.untrigger", false)
+	setManagerProp(manager, "state.isAwaitingKeyup", false)
+
+	for (const key of Object.values(manager.keys.entries)) {
+		if ((key.isModifier === "native" || key.isToggle === "native") && ignoreNative) return
+		setKeyProp(key, "pressed", false, manager)
+		if (key.isToggle) {
+			// safe not to check return because setting to false will never error
+			setKeyProp(key, "toggleOnPressed", false, manager)
+			setKeyProp(key, "toggleOffPressed", false, manager)
+		}
+	}
+}
+

package/src/helpers/forceUpdateNativeKeysState.ts

@@ -0,0 +1,9 @@
+import { updateNativeKeysState } from "../internal/updateNativeKeysState.js"
+import type { AnyInputEvent, Manager } from "../types/index.js"
+
+/**
+	* Force the manager to update the state of modifier/toggle keys during a keyboard or mouse event.
+	*/
+export function forceUpdateNativeKeysState(manager: Manager, e: AnyInputEvent): void {
+	updateNativeKeysState(manager, e)
+}

package/src/helpers/generateKeyShortcutMap.ts

@@ -0,0 +1,113 @@
+import { last } from "@alanscodelog/utils/last"
+
+import { getKeyFromIdOrVariant } from "./getKeyFromIdOrVariant.js"
+
+import type { KeyInfo, Manager, Shortcut, ShortcutInfo } from "../types/index.js"
+import type { Key } from "../types/keys.js"
+import { chainContainsSubset } from "../utils/chainContainsSubset.js"
+import { equalsKeys } from "../utils/equalsKeys.js"
+import { removeKeys } from "../utils/removeKeys.js"
+
+
+/**
+ * Given a chain, a shortcut list, and a manager, this will return a record with information for each key id regarding what shortcuts can be pressed and some additional information useful for visual displaying them on a keyboard (See {@link KeyInfo}).
+ *
+ * The record will contain all renderable keys by their id (see {@link Key.render}). It will not contain variants or toggle states, only full keys (i.e. {@link Keys.entries}).
+ *
+ * It is recommended you pre-filter the shortcut's list to remove any shortcuts that are disabled or not executable.
+ *
+ * You can also post filter depending on the generated {@link ShortcutInfo} entry. See the postFilter param.
+ */
+
+export function generateKeyShortcutMap(
+	chain: string[][],
+	shortcutsList: Shortcut[],
+	manager: Manager,
+	/**
+		* Filter entries by their {@link ShortcutInfo}, before adding/modifying the corresponding keys. Return false to filter the entry out, true to keep it.
+		*
+		* The second argument also provides some additional info the function looks at to generate the result.
+		*/
+	postFilter?: (
+		entry: ShortcutInfo,
+		info: {
+			pressableKeys: Key[]
+			unpressedModifiers: Key[]
+			isPressed: boolean
+			containsSubset: boolean
+		}
+	) => boolean
+): Record<Key["id"], KeyInfo> {
+	const obj: Record<string, KeyInfo> = {}
+	const nextIsChord = manager.state.nextIsChord
+
+	const isEmpty = chain.length === 0 || (chain.length === 1 && chain?.[0].length === 0)
+	const index = isEmpty ? 0 : nextIsChord ? chain.length : chain.length - 1
+	for (const shortcut of shortcutsList) {
+		const containsSubset = chainContainsSubset(shortcut.chain, chain, manager.keys, { onlySubset: true, onlyPressable: false })
+		const isPressed = equalsKeys(shortcut.chain, chain, manager.keys)
+		if (!containsSubset && !isPressed) continue
+
+		const keysLeftInChord = removeKeys((shortcut.chain[index] ?? []), (chain[index] ?? []), manager.keys)
+			// normalize to Key[] so that we are only looking at "full" keys
+			.map(_ => getKeyFromIdOrVariant(_, manager.keys).unwrap()[0])
+
+		const isPressableChord = keysLeftInChord.length === 1
+		const isPressable = isPressableChord && shortcut.chain.length - 1 === index
+		const isPressableChain = isPressableChord && shortcut.chain.length - 1 > index
+
+		const unpressedModifiers = keysLeftInChord.length > 1 ? keysLeftInChord.filter(_ => _.isModifier) : []
+		const hasUnpressedModifiers = unpressedModifiers.length > 0
+
+		if (!isPressable && !isPressableChain && !isPressed && unpressedModifiers.length <= 0) continue
+
+		const pressableKeys = isPressed
+			? (last(shortcut.chain) ?? []).map(_ => getKeyFromIdOrVariant(_, manager.keys).unwrap()[0])
+			: unpressedModifiers.length === 0
+				? keysLeftInChord
+				: []
+
+		const entry = {
+			shortcut,
+			isPressed,
+			isPressable,
+			isPressableChain,
+			hasUnpressedModifiers
+		}
+		if (postFilter !== undefined && !postFilter(entry, { unpressedModifiers, pressableKeys, isPressed, containsSubset })) continue
+		if (!hasUnpressedModifiers || isPressed) {
+			for (const k of pressableKeys) {
+				if (k.render) {
+					obj[k.id] ??= {
+						pressableEntries: [] as ShortcutInfo[],
+						modifierEntries: [] as ShortcutInfo[],
+						containsConflicting: false,
+						isModifierHint: false
+					}
+					if (!obj[k.id].containsConflicting) {
+						const containsConflicting = obj[k.id].pressableEntries
+							.some(_ => _.isPressable || _.isPressableChain)
+						obj[k.id].containsConflicting = containsConflicting
+					}
+					obj[k.id].pressableEntries.push({ ...entry })
+				}
+			}
+		}
+		if (!isPressed && !isPressable && !isPressableChain) {
+			for (const k of unpressedModifiers) {
+				if (k.render) {
+					obj[k.id] ??= {
+						pressableEntries: [] as ShortcutInfo[],
+						modifierEntries: [] as ShortcutInfo[],
+						containsConflicting: false,
+						isModifierHint: false
+					}
+					obj[k.id].modifierEntries.push({ ...entry })
+					obj[k.id].isModifierHint ||= true
+				}
+			}
+		}
+	}
+
+	return obj
+}

package/src/helpers/getKeyFromEventCode.ts

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

package/src/helpers/getKeyFromIdOrVariant.ts

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

package/src/helpers/getKeyboardLayoutMap.ts

@@ -0,0 +1,13 @@
+import type { KeyboardLayoutMap } from "../types/general.js"
+
+/**
+ * Safely get the [KeyboardLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardLayoutMap) with [navigator.getLayoutMap](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/navigator.getLayoutMap).
+ */
+export async function getKeyboardLayoutMap(): Promise<KeyboardLayoutMap | undefined> {
+	// castType<Navigator>(navigator) // not working during build
+	if (typeof navigator !== "undefined" && "keyboard" in navigator) {
+		return (navigator.keyboard as any).getLayoutMap()
+	} else {
+		return undefined
+	}
+}

package/src/helpers/getLabel.ts

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

package/src/helpers/getTriggerableShortcut.ts

@@ -0,0 +1,37 @@
+import { crop } from "@alanscodelog/utils/crop"
+import { indent } from "@alanscodelog/utils/indent"
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { KnownError } from "./KnownError.js"
+import { shortcutIsTriggerableBy } from "./shortcutIsTriggerableBy.js"
+
+import type { Manager, PickManager, TriggerableShortcut } from "../types/index.js"
+import { SHORTCUT_ERROR } from "../types/index.js"
+
+
+/** Gets all triggerable shortcuts in a manager. */
+export function getTriggerableShortcut(
+	manager: Pick<Manager, "shortcuts" | "keys" | "context" | "commands">
+		& PickManager<"options", "stringifier" | "evaluateCondition">
+		& PickManager<"state", "chain" | "isRecording">
+): Result<false | TriggerableShortcut, KnownError<typeof SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS>> {
+	const s = manager.options.stringifier
+
+	if (manager.state.isRecording) return Ok(false)
+
+	const shortcuts = manager.shortcuts.entries.filter(shortcut => shortcutIsTriggerableBy(manager.state.chain, shortcut, manager))
+
+	if (shortcuts.length === 0) return Ok(false)
+	if (shortcuts.length > 1) {
+		return Err(new KnownError(SHORTCUT_ERROR.MULTIPLE_MATCHING_SHORTCUTS,
+			crop`
+				Multiple commands are assigned to the key combination ${s.stringify(manager.state.chain, manager)}:
+
+				${indent(s.stringifyList("shortcuts", shortcuts, manager), 4)}
+			`,
+			{ shortcuts }))
+	} else {
+		return Ok(shortcuts[0] as TriggerableShortcut)
+	}
+}
+

package/src/helpers/index.ts

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

package/src/helpers/isValidManager.ts

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

package/src/helpers/isValidShortcut.ts

@@ -0,0 +1,20 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { isValidChain } from "../internal/isValidChain.js"
+import { isValidCommand } from "../internal/isValidCommand.js"
+import type { ChainError, Manager, MultipleErrors, PickManager, Shortcut, SHORTCUT_ERROR } from "../types/index.js"
+
+
+export function isValidShortcut(
+	shortcut: Shortcut,
+	manager: Pick<Manager, "keys" | "commands"> & PickManager<"options", "stringifier" | "sorter">
+): Result<true, MultipleErrors<
+	| ChainError
+	| typeof SHORTCUT_ERROR.UNKNOWN_COMMAND
+>> {
+	const resCommandsValid = isValidCommand(shortcut.command, manager, shortcut)
+	if (resCommandsValid.isError) return resCommandsValid
+	const resChainValid = isValidChain(shortcut.chain, manager)
+	if (resChainValid.isError) return resChainValid
+	return Ok(true)
+}

package/src/helpers/labelWithEvent.ts

@@ -0,0 +1,41 @@
+import { setKeyProp } from "../core/setKeyProp.js"
+import type { AnyInputEvent, KeySetEntries, LabelOptions, Manager, MinimalInputEvent, PickManager } from "../types/index.js"
+/**
+ * Labels keys using events.
+ *
+ * For keys uses `KeyboardEvent.key`. For mouse buttons it will label them `Button x` where x is `MouseEvent.button`, and for the mouse wheel, `WheelEvent.deltaY` is used to label them `Wheel Up`/`Wheel Down`.
+ *
+ * This is intended to be used for labeling keys as they are pressed or as a fallback to {@link labelWithKeyboardMap}. See it for the recommended labeling strategy.
+ *
+ * A filter can be provided to avoid labeling some keys.
+ */
+export function labelWithEvent<
+	T extends MinimalInputEvent | AnyInputEvent = MinimalInputEvent | AnyInputEvent,
+	THooks extends KeySetEntries["label"]["hooks"] = KeySetEntries["label"]["hooks"]
+>(
+	e: T,
+	keyIds: string[],
+	manager: Pick<Manager, "keys"> & PickManager<"options", "stringifier"> & { hooks?: THooks },
+	options: Partial<Omit<LabelOptions, "map">> = {}
+): string[] {
+	const set = []
+	for (const id of keyIds) {
+		let label = ""
+		// we don't use instanceof so that we can still be compatible with emulated events
+		if ("deltaY" in e) {
+			label = e.deltaY < 0 ? "Wheel Up" : "Wheel Down"
+		} else if ("button" in e) {
+			label = `Button ${e.button}`
+		} else if ("key" in e) {
+			label = e.key
+		}
+		if (!options.labelFilter || options.labelFilter(e, id, label, manager.keys)) {
+			const key = manager.keys.entries[id]
+			set.push(key.id)
+			// its fine to ignore any errors even if they're custom errors
+			setKeyProp(key, "label", label, manager)
+		}
+	}
+	return set
+}
+

package/src/helpers/labelWithKeyboardMap.ts

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