@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/constants.js

@@ -0,0 +1,428 @@
+//#region src/constants.ts
+/**
+* Detects the current platform based on browser navigator properties.
+*
+* Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+* Control elsewhere) and for platform-specific hotkey formatting.
+*
+* @returns The detected platform: 'mac', 'windows', or 'linux'
+* @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+*
+* @example
+* ```ts
+* const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+* const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+* ```
+*/
+function detectPlatform() {
+	if (typeof navigator === "undefined") return "linux";
+	const platform = navigator.platform.toLowerCase();
+	const userAgent = navigator.userAgent.toLowerCase();
+	if (platform.includes("mac") || userAgent.includes("mac")) return "mac";
+	if (platform.includes("win") || userAgent.includes("win")) return "windows";
+	return "linux";
+}
+/**
+* Canonical order for modifiers in normalized hotkey strings.
+*
+* Defines the standard order in which modifiers should appear when formatting
+* hotkeys. This ensures consistent, predictable output across the library.
+*
+* Order: Control → Alt → Shift → Meta
+*
+* @example
+* ```ts
+* // Input: 'Shift+Control+Meta+S'
+* // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)
+* ```
+*/
+const MODIFIER_ORDER = [
+	"Control",
+	"Alt",
+	"Shift",
+	"Meta"
+];
+/**
+* Set of canonical modifier key names for fast lookup.
+*
+* Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when
+* a modifier is released so we can clear non-modifier keys whose keyup events
+* may have been swallowed by the OS (e.g. macOS Cmd+key combos).
+*/
+const MODIFIER_KEYS = new Set(MODIFIER_ORDER);
+/**
+* Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
+*
+* This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')
+* which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the
+* platform-adaptive 'Mod' token.
+*
+* The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`
+* based on the detected platform (Command on Mac, Control elsewhere).
+*
+* @remarks Case-insensitive lookups are supported via lowercase variants
+*
+* @example
+* ```ts
+* MODIFIER_ALIASES['Ctrl'] // 'Control'
+* MODIFIER_ALIASES['Cmd'] // 'Meta'
+* MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)
+* ```
+*/
+const MODIFIER_ALIASES = {
+	Control: "Control",
+	Ctrl: "Control",
+	control: "Control",
+	ctrl: "Control",
+	Shift: "Shift",
+	shift: "Shift",
+	Alt: "Alt",
+	Option: "Alt",
+	alt: "Alt",
+	option: "Alt",
+	Command: "Meta",
+	Cmd: "Meta",
+	Meta: "Meta",
+	command: "Meta",
+	cmd: "Meta",
+	meta: "Meta",
+	CommandOrControl: "Mod",
+	Mod: "Mod",
+	commandorcontrol: "Mod",
+	mod: "Mod"
+};
+/**
+* Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+*
+* The 'Mod' token represents the "primary modifier" on each platform:
+* - macOS: 'Meta' (Command key ⌘)
+* - Windows/Linux: 'Control' (Ctrl key)
+*
+* This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+* map to Command+S on Mac and Ctrl+S on Windows/Linux.
+*
+* @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+* @param platform - The target platform. Defaults to auto-detection.
+* @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+*
+* @example
+* ```ts
+* resolveModifier('Mod', 'mac') // 'Meta'
+* resolveModifier('Mod', 'windows') // 'Control'
+* resolveModifier('Control', 'mac') // 'Control' (unchanged)
+* ```
+*/
+function resolveModifier(modifier, platform = detectPlatform()) {
+	if (modifier === "Mod") return platform === "mac" ? "Meta" : "Control";
+	return modifier;
+}
+/**
+* Set of all valid letter keys (A-Z).
+*
+* Used for validation and type checking. Letter keys are matched case-insensitively
+* in hotkey matching, but normalized to uppercase in canonical form.
+*/
+const LETTER_KEYS = new Set([
+	"A",
+	"B",
+	"C",
+	"D",
+	"E",
+	"F",
+	"G",
+	"H",
+	"I",
+	"J",
+	"K",
+	"L",
+	"M",
+	"N",
+	"O",
+	"P",
+	"Q",
+	"R",
+	"S",
+	"T",
+	"U",
+	"V",
+	"W",
+	"X",
+	"Y",
+	"Z"
+]);
+/**
+* Set of all valid number keys (0-9).
+*
+* Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),
+* so they're excluded from Shift-based hotkey combinations to avoid
+* layout-dependent behavior.
+*/
+const NUMBER_KEYS = new Set([
+	"0",
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6",
+	"7",
+	"8",
+	"9"
+]);
+/**
+* Set of all valid function keys (F1-F12).
+*
+* Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
+* Alt+F4 to close windows) and application-specific commands.
+*/
+const FUNCTION_KEYS = new Set([
+	"F1",
+	"F2",
+	"F3",
+	"F4",
+	"F5",
+	"F6",
+	"F7",
+	"F8",
+	"F9",
+	"F10",
+	"F11",
+	"F12"
+]);
+/**
+* Set of all valid navigation keys for cursor movement and document navigation.
+*
+* Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).
+* These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
+* navigation shortcuts (Alt+ArrowLeft for back).
+*/
+const NAVIGATION_KEYS = new Set([
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown"
+]);
+/**
+* Set of all valid editing and special keys.
+*
+* Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and
+* special actions (Escape, Space). These keys are frequently combined with modifiers
+* for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
+*/
+const EDITING_KEYS = new Set([
+	"Enter",
+	"Escape",
+	"Space",
+	"Tab",
+	"Backspace",
+	"Delete"
+]);
+/**
+* Set of all valid punctuation keys commonly used in keyboard shortcuts.
+*
+* These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,
+* typically US keyboard layout). Common shortcuts include:
+* - `Mod+/` - Toggle comment
+* - `Mod+[` / `Mod+]` - Indent/outdent
+* - `Mod+=` / `Mod+-` - Zoom in/out
+*
+* Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
+* so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
+*/
+const PUNCTUATION_KEYS = new Set([
+	"/",
+	"[",
+	"]",
+	"\\",
+	"=",
+	"-",
+	",",
+	".",
+	"`"
+]);
+/**
+* Set of all valid non-modifier keys.
+*
+* This is the union of all key type sets (letters, numbers, function keys, navigation,
+* editing, and punctuation). Used primarily for validation to check if a key string
+* is recognized and will have type-safe autocomplete support.
+*
+* @see {@link LETTER_KEYS}
+* @see {@link NUMBER_KEYS}
+* @see {@link FUNCTION_KEYS}
+* @see {@link NAVIGATION_KEYS}
+* @see {@link EDITING_KEYS}
+* @see {@link PUNCTUATION_KEYS}
+*/
+const ALL_KEYS = new Set([
+	...LETTER_KEYS,
+	...NUMBER_KEYS,
+	...FUNCTION_KEYS,
+	...NAVIGATION_KEYS,
+	...EDITING_KEYS,
+	...PUNCTUATION_KEYS
+]);
+/**
+* Maps key name aliases to their canonical form.
+*
+* Handles common variations and alternative names for keys to provide a more
+* forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and
+* they'll all normalize to 'Escape'.
+*
+* This map is used internally by `normalizeKeyName()` to convert user input
+* into the canonical key names used throughout the library.
+*
+* @remarks Case-insensitive lookups are supported via lowercase variants
+*
+* @example
+* ```ts
+* KEY_ALIASES['Esc'] // 'Escape'
+* KEY_ALIASES['Del'] // 'Delete'
+* KEY_ALIASES['Up'] // 'ArrowUp'
+* ```
+*/
+const KEY_ALIASES = {
+	Esc: "Escape",
+	esc: "Escape",
+	escape: "Escape",
+	Return: "Enter",
+	return: "Enter",
+	enter: "Enter",
+	" ": "Space",
+	space: "Space",
+	Spacebar: "Space",
+	spacebar: "Space",
+	tab: "Tab",
+	backspace: "Backspace",
+	Del: "Delete",
+	del: "Delete",
+	delete: "Delete",
+	Up: "ArrowUp",
+	up: "ArrowUp",
+	arrowup: "ArrowUp",
+	Down: "ArrowDown",
+	down: "ArrowDown",
+	arrowdown: "ArrowDown",
+	Left: "ArrowLeft",
+	left: "ArrowLeft",
+	arrowleft: "ArrowLeft",
+	Right: "ArrowRight",
+	right: "ArrowRight",
+	arrowright: "ArrowRight",
+	home: "Home",
+	end: "End",
+	pageup: "PageUp",
+	pagedown: "PageDown",
+	PgUp: "PageUp",
+	PgDn: "PageDown",
+	pgup: "PageUp",
+	pgdn: "PageDown"
+};
+/**
+* Normalizes a key name to its canonical form.
+*
+* Converts various key name formats (aliases, case variations) into the standard
+* canonical names used throughout the library. This enables a more forgiving API
+* where users can write keys in different ways and still get correct behavior.
+*
+* Normalization rules:
+* 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
+* 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
+* 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
+* 4. Other keys → returned as-is (already canonical or unknown)
+*
+* @param key - The key name to normalize (can be an alias, lowercase, etc.)
+* @returns The canonical key name
+*
+* @example
+* ```ts
+* normalizeKeyName('esc') // 'Escape'
+* normalizeKeyName('a') // 'A'
+* normalizeKeyName('f1') // 'F1'
+* normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
+* ```
+*/
+function normalizeKeyName(key) {
+	if (key in KEY_ALIASES) return KEY_ALIASES[key];
+	if (key.length === 1 && /^[a-zA-Z]$/.test(key)) return key.toUpperCase();
+	const upperKey = key.toUpperCase();
+	if (/^F([1-9]|1[0-2])$/.test(upperKey)) return upperKey;
+	return key;
+}
+/**
+* Modifier key symbols for macOS display.
+*
+* Used by formatting functions to display hotkeys with macOS-style symbols
+* (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+* a native macOS look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+* MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+* MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+* MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+* ```
+*/
+const MAC_MODIFIER_SYMBOLS = {
+	Control: "⌃",
+	Alt: "⌥",
+	Shift: "⇧",
+	Meta: "⌘"
+};
+/**
+* Modifier key labels for Windows/Linux display.
+*
+* Used by formatting functions to display hotkeys with standard text labels
+* (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+* This provides a familiar Windows/Linux look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+* STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+* STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+* STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+* ```
+*/
+const STANDARD_MODIFIER_LABELS = {
+	Control: "Ctrl",
+	Alt: "Alt",
+	Shift: "Shift",
+	Meta: "Win"
+};
+/**
+* Special key symbols for display formatting.
+*
+* Maps certain keys to their visual symbols for better readability in hotkey displays.
+* Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+* instead of text labels.
+*
+* @example
+* ```ts
+* KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+* KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+* KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+* KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+* ```
+*/
+const KEY_DISPLAY_SYMBOLS = {
+	ArrowUp: "↑",
+	ArrowDown: "↓",
+	ArrowLeft: "←",
+	ArrowRight: "→",
+	Enter: "↵",
+	Escape: "Esc",
+	Backspace: "⌫",
+	Delete: "⌦",
+	Tab: "⇥",
+	Space: "␣"
+};
+
+//#endregion
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, normalizeKeyName, resolveModifier };
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n  CanonicalModifier,\n  EditingKey,\n  FunctionKey,\n  LetterKey,\n  NavigationKey,\n  NumberKey,\n  PunctuationKey,\n} from './hotkey'\n\n// =============================================================================\n// Platform Detection\n// =============================================================================\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  const platform = navigator.platform.toLowerCase()\n  const userAgent = navigator.userAgent.toLowerCase()\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n// =============================================================================\n// Modifier Aliases\n// =============================================================================\n\n/**\n * Canonical order for modifiers in normalized hotkey strings.\n *\n * Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n *\n * Order: Control → Alt → Shift → Meta\n *\n * @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n */\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n  'Control',\n  'Alt',\n  'Shift',\n  'Meta',\n]\n\n/**\n * Set of canonical modifier key names for fast lookup.\n *\n * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n */\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/**\n * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n *\n * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n *\n * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n */\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {\n  // Control variants\n  Control: 'Control',\n  Ctrl: 'Control',\n  control: 'Control',\n  ctrl: 'Control',\n\n  // Shift variants\n  Shift: 'Shift',\n  shift: 'Shift',\n\n  // Alt variants\n  Alt: 'Alt',\n  Option: 'Alt',\n  alt: 'Alt',\n  option: 'Alt',\n\n  // Meta/Command variants\n  Command: 'Meta',\n  Cmd: 'Meta',\n  Meta: 'Meta',\n  command: 'Meta',\n  cmd: 'Meta',\n  meta: 'Meta',\n\n  // Platform-adaptive (resolved at runtime)\n  CommandOrControl: 'Mod',\n  Mod: 'Mod',\n  commandorcontrol: 'Mod',\n  mod: 'Mod',\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n\n// =============================================================================\n// Valid Keys\n// =============================================================================\n\n/**\n * Set of all valid letter keys (A-Z).\n *\n * Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n */\nexport const LETTER_KEYS = new Set<LetterKey>([\n  'A',\n  'B',\n  'C',\n  'D',\n  'E',\n  'F',\n  'G',\n  'H',\n  'I',\n  'J',\n  'K',\n  'L',\n  'M',\n  'N',\n  'O',\n  'P',\n  'Q',\n  'R',\n  'S',\n  'T',\n  'U',\n  'V',\n  'W',\n  'X',\n  'Y',\n  'Z',\n])\n\n/**\n * Set of all valid number keys (0-9).\n *\n * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n */\nexport const NUMBER_KEYS = new Set<NumberKey>([\n  '0',\n  '1',\n  '2',\n  '3',\n  '4',\n  '5',\n  '6',\n  '7',\n  '8',\n  '9',\n])\n\n/**\n * Set of all valid function keys (F1-F12).\n *\n * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n */\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n  'F1',\n  'F2',\n  'F3',\n  'F4',\n  'F5',\n  'F6',\n  'F7',\n  'F8',\n  'F9',\n  'F10',\n  'F11',\n  'F12',\n])\n\n/**\n * Set of all valid navigation keys for cursor movement and document navigation.\n *\n * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n */\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n  'ArrowUp',\n  'ArrowDown',\n  'ArrowLeft',\n  'ArrowRight',\n  'Home',\n  'End',\n  'PageUp',\n  'PageDown',\n])\n\n/**\n * Set of all valid editing and special keys.\n *\n * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n */\nexport const EDITING_KEYS = new Set<EditingKey>([\n  'Enter',\n  'Escape',\n  'Space',\n  'Tab',\n  'Backspace',\n  'Delete',\n])\n\n/**\n * Set of all valid punctuation keys commonly used in keyboard shortcuts.\n *\n * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n *\n * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n */\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n  '/',\n  '[',\n  ']',\n  '\\\\',\n  '=',\n  '-',\n  ',',\n  '.',\n  '`',\n])\n\n/**\n * Set of all valid non-modifier keys.\n *\n * This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n *\n * @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n */\nexport const ALL_KEYS = new Set([\n  ...LETTER_KEYS,\n  ...NUMBER_KEYS,\n  ...FUNCTION_KEYS,\n  ...NAVIGATION_KEYS,\n  ...EDITING_KEYS,\n  ...PUNCTUATION_KEYS,\n])\n\n/**\n * Maps key name aliases to their canonical form.\n *\n * Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n *\n * This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n */\nconst KEY_ALIASES: Record<string, string> = {\n  // Escape variants\n  Esc: 'Escape',\n  esc: 'Escape',\n  escape: 'Escape',\n\n  // Enter variants\n  Return: 'Enter',\n  return: 'Enter',\n  enter: 'Enter',\n\n  // Space variants\n  ' ': 'Space',\n  space: 'Space',\n  Spacebar: 'Space',\n  spacebar: 'Space',\n\n  // Tab variants\n  tab: 'Tab',\n\n  // Backspace variants\n  backspace: 'Backspace',\n\n  // Delete variants\n  Del: 'Delete',\n  del: 'Delete',\n  delete: 'Delete',\n\n  // Arrow key variants\n  Up: 'ArrowUp',\n  up: 'ArrowUp',\n  arrowup: 'ArrowUp',\n  Down: 'ArrowDown',\n  down: 'ArrowDown',\n  arrowdown: 'ArrowDown',\n  Left: 'ArrowLeft',\n  left: 'ArrowLeft',\n  arrowleft: 'ArrowLeft',\n  Right: 'ArrowRight',\n  right: 'ArrowRight',\n  arrowright: 'ArrowRight',\n\n  // Navigation variants\n  home: 'Home',\n  end: 'End',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n  PgUp: 'PageUp',\n  PgDn: 'PageDown',\n  pgup: 'PageUp',\n  pgdn: 'PageDown',\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n *\n * Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function normalizeKeyName(key: string): string {\n  // Check aliases first\n  if (key in KEY_ALIASES) {\n    return KEY_ALIASES[key]!\n  }\n\n  // Check if it's a single letter (normalize to uppercase)\n  if (key.length === 1 && /^[a-zA-Z]$/.test(key)) {\n    return key.toUpperCase()\n  }\n\n  // Check if it's a function key (normalize case)\n  const upperKey = key.toUpperCase()\n  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {\n    return upperKey\n  }\n\n  return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n}\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS: Record<string, string> = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n}\n"],"mappings":"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"}

package/dist/format.cjs

@@ -0,0 +1,178 @@
+const require_constants = require('./constants.cjs');
+const require_parse = require('./parse.cjs');
+
+//#region src/format.ts
+/**
+* Converts a ParsedHotkey back to a hotkey string.
+*
+* @param parsed - The parsed hotkey object
+* @returns A hotkey string in canonical form
+*
+* @example
+* ```ts
+* formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
+* // Returns: 'Control+Shift+S'
+* ```
+*/
+function formatHotkey(parsed) {
+	const parts = [];
+	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+/**
+* Formats a hotkey for display in a user interface.
+*
+* On macOS, uses symbols (⌘⇧S).
+* On Windows/Linux, uses text (Ctrl+Shift+S).
+*
+* @param hotkey - The hotkey string or ParsedHotkey to format
+* @param options - Formatting options
+* @returns A formatted string suitable for display
+*
+* @example
+* ```ts
+* formatForDisplay('Mod+Shift+S', { platform: 'mac' })
+* // Returns: '⇧⌘S'
+*
+* formatForDisplay('Mod+Shift+S', { platform: 'windows' })
+* // Returns: 'Ctrl+Shift+S'
+*
+* formatForDisplay('Escape')
+* // Returns: 'Esc' (on all platforms)
+* ```
+*/
+function formatForDisplay(hotkey, options = {}) {
+	const platform = options.platform ?? require_constants.detectPlatform();
+	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
+	if (platform === "mac") return formatForMac(parsed);
+	return formatForStandard(parsed);
+}
+/**
+* Formats a hotkey for macOS display using symbols.
+*/
+function formatForMac(parsed) {
+	const parts = [];
+	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(require_constants.MAC_MODIFIER_SYMBOLS[modifier]);
+	const keyDisplay = require_constants.KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key;
+	parts.push(keyDisplay);
+	return parts.join("");
+}
+/**
+* Formats a hotkey for Windows/Linux display using text labels.
+*/
+function formatForStandard(parsed) {
+	const parts = [];
+	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(require_constants.STANDARD_MODIFIER_LABELS[modifier]);
+	const keyDisplay = require_constants.KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key;
+	parts.push(keyDisplay);
+	return parts.join("+");
+}
+/**
+* Formats a hotkey using platform-agnostic labels.
+* Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
+*
+* @param hotkey - The hotkey string or ParsedHotkey to format
+* @param platform - The target platform
+* @returns A formatted string with platform-appropriate labels
+*/
+function formatWithLabels(hotkey, platform = require_constants.detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
+	const parts = [];
+	const labels = {
+		Control: "Ctrl",
+		Alt: platform === "mac" ? "Option" : "Alt",
+		Shift: "Shift",
+		Meta: platform === "mac" ? "Cmd" : "Win"
+	};
+	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(labels[modifier] ?? modifier);
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+/**
+* Maps canonical modifier names to debugging-friendly labels per platform.
+*/
+const MODIFIER_DEBUG_LABELS = {
+	mac: {
+		Meta: "Mod (Cmd)",
+		Control: "Ctrl",
+		Alt: "Opt",
+		Shift: "Shift"
+	},
+	windows: {
+		Control: "Mod (Ctrl)",
+		Meta: "Win",
+		Alt: "Alt",
+		Shift: "Shift"
+	},
+	linux: {
+		Control: "Mod (Ctrl)",
+		Meta: "Super",
+		Alt: "Alt",
+		Shift: "Shift"
+	}
+};
+/**
+* Formats a single key name for debugging/devtools display.
+*
+* Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
+* this function formats individual key names (from `event.key`) with rich
+* platform-aware labels suitable for debugging tools and developer-facing displays.
+*
+* Features:
+* - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
+* - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
+* - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
+* - Regular keys pass through unchanged
+*
+* @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
+* @param options - Formatting options
+* @returns A formatted label suitable for debugging display
+*
+* @example
+* ```ts
+* // On macOS:
+* formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
+* formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
+* formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
+* formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
+*
+* // On Windows:
+* formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
+* formatKeyForDebuggingDisplay('Meta')    // 'Win'
+*
+* // Special keys (all platforms):
+* formatKeyForDebuggingDisplay('ArrowUp') // '↑'
+* formatKeyForDebuggingDisplay('Escape')  // 'Esc'
+* formatKeyForDebuggingDisplay('Space')   // '␣'
+*
+* // Regular keys pass through:
+* formatKeyForDebuggingDisplay('A')       // 'A'
+*
+* // With source: 'code', values pass through unchanged:
+* formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
+* formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
+* ```
+*/
+function formatKeyForDebuggingDisplay(key, options = {}) {
+	if (options.source === "code") return key;
+	const platform = options.platform ?? require_constants.detectPlatform();
+	const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key];
+	if (modLabel) {
+		if (platform === "mac") {
+			const symbol = require_constants.MAC_MODIFIER_SYMBOLS[key];
+			if (symbol) return `${symbol} ${modLabel}`;
+		}
+		return modLabel;
+	}
+	const symbol = require_constants.KEY_DISPLAY_SYMBOLS[key];
+	if (symbol) return symbol;
+	return key;
+}
+
+//#endregion
+exports.formatForDisplay = formatForDisplay;
+exports.formatHotkey = formatHotkey;
+exports.formatKeyForDebuggingDisplay = formatKeyForDebuggingDisplay;
+exports.formatWithLabels = formatWithLabels;
+//# sourceMappingURL=format.cjs.map

package/dist/format.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.cjs","names":["MODIFIER_ORDER","detectPlatform","parseHotkey","MAC_MODIFIER_SYMBOLS","KEY_DISPLAY_SYMBOLS","STANDARD_MODIFIER_LABELS"],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ORDER,\n  STANDARD_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S).\n * On Windows/Linux, uses text (Ctrl+Shift+S).\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⇧⌘S'\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: Hotkey | (string & {}) | ParsedHotkey,\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  if (platform === 'mac') {\n    return formatForMac(parsed)\n  }\n\n  return formatForStandard(parsed)\n}\n\n/**\n * Formats a hotkey for macOS display using symbols.\n */\nfunction formatForMac(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in macOS order (typically Control, Option, Shift, Command)\n  // But we'll use our canonical order and just use symbols\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(MAC_MODIFIER_SYMBOLS[modifier])\n    }\n  }\n\n  // Add the key (use symbol if available, otherwise the key itself)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Mac, modifiers are typically concatenated without separators\n  return parts.join('')\n}\n\n/**\n * Formats a hotkey for Windows/Linux display using text labels.\n */\nfunction formatForStandard(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(STANDARD_MODIFIER_LABELS[modifier])\n    }\n  }\n\n  // Add the key (use symbol/short form if available)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Windows/Linux, use + as separator\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey using platform-agnostic labels.\n * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param platform - The target platform\n * @returns A formatted string with platform-appropriate labels\n */\nexport function formatWithLabels(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const parts: Array<string> = []\n\n  // Custom labels for more readable output\n  const labels: Record<string, string> = {\n    Control: 'Ctrl',\n    Alt: platform === 'mac' ? 'Option' : 'Alt',\n    Shift: 'Shift',\n    Meta: platform === 'mac' ? 'Cmd' : 'Win',\n  }\n\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(labels[modifier] ?? modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n// =============================================================================\n// Debugging Display Labels\n// =============================================================================\n\n/**\n * Maps canonical modifier names to debugging-friendly labels per platform.\n */\nconst MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {\n  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },\n  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },\n  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },\n}\n\n/**\n * Options for formatting a single key for debugging display.\n */\nexport interface FormatKeyDebuggingOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /**\n   * Whether the input value comes from `event.key` or `event.code`.\n   *\n   * - `'key'` (default): Applies rich platform-aware formatting (modifier\n   *   labels, special-key symbols, etc.).\n   * - `'code'`: Returns the value unchanged — physical key codes like\n   *   `\"MetaLeft\"` or `\"KeyA\"` are already descriptive for debugging.\n   */\n  source?: 'key' | 'code'\n}\n\n/**\n * Formats a single key name for debugging/devtools display.\n *\n * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,\n * this function formats individual key names (from `event.key`) with rich\n * platform-aware labels suitable for debugging tools and developer-facing displays.\n *\n * Features:\n * - Modifier keys show their platform role (e.g., \"Mod (Cmd)\" for Meta on Mac)\n * - On macOS, modifier keys are prefixed with their symbol (e.g., \"⌘ Mod (Cmd)\")\n * - Special keys use display symbols (ArrowUp -> \"↑\", Escape -> \"Esc\")\n * - Regular keys pass through unchanged\n *\n * @param key - A single key name (e.g., \"Meta\", \"Shift\", \"ArrowUp\", \"A\")\n * @param options - Formatting options\n * @returns A formatted label suitable for debugging display\n *\n * @example\n * ```ts\n * // On macOS:\n * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'\n * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'\n * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'\n * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'\n *\n * // On Windows:\n * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'\n * formatKeyForDebuggingDisplay('Meta')    // 'Win'\n *\n * // Special keys (all platforms):\n * formatKeyForDebuggingDisplay('ArrowUp') // '↑'\n * formatKeyForDebuggingDisplay('Escape')  // 'Esc'\n * formatKeyForDebuggingDisplay('Space')   // '␣'\n *\n * // Regular keys pass through:\n * formatKeyForDebuggingDisplay('A')       // 'A'\n *\n * // With source: 'code', values pass through unchanged:\n * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'\n * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'\n * ```\n */\nexport function formatKeyForDebuggingDisplay(\n  key: string,\n  options: FormatKeyDebuggingOptions = {},\n): string {\n  // For event.code values, pass through unchanged — they're already\n  // descriptive for debugging (e.g. \"MetaLeft\", \"KeyA\", \"ShiftRight\").\n  if (options.source === 'code') {\n    return key\n  }\n\n  const platform = options.platform ?? detectPlatform()\n\n  // Check if it's a modifier key\n  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]\n  if (modLabel) {\n    // On Mac, prefix modifier labels with their symbol\n    if (platform === 'mac') {\n      const symbol =\n        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]\n      if (symbol) {\n        return `${symbol} ${modLabel}`\n      }\n    }\n    return modLabel\n  }\n\n  // Check if it's a special key with a display symbol\n  const symbol = KEY_DISPLAY_SYMBOLS[key]\n  if (symbol) {\n    return symbol\n  }\n\n  // Regular key — pass through\n  return key\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYA,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CACrD,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,aAAa,MACf,QAAO,aAAa,OAAO;AAG7B,QAAO,kBAAkB,OAAO;;;;;AAMlC,SAAS,aAAa,QAA8B;CAClD,MAAM,QAAuB,EAAE;AAI/B,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKG,uCAAqB,UAAU;CAK9C,MAAM,aAAaC,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,GAAG;;;;;AAMvB,SAAS,kBAAkB,QAA8B;CACvD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYJ,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKK,2CAAyB,UAAU;CAKlD,MAAM,aAAaD,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;AAWxB,SAAgB,iBACd,QACA,WAAwCH,kCAAgB,EAChD;CACR,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,QAAuB,EAAE;CAG/B,MAAM,SAAiC;EACrC,SAAS;EACT,KAAK,aAAa,QAAQ,WAAW;EACrC,OAAO;EACP,MAAM,aAAa,QAAQ,QAAQ;EACpC;AAED,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,OAAO,aAAa,SAAS;AAK5C,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;AAUxB,MAAM,wBAAgE;CACpE,KAAK;EAAE,MAAM;EAAa,SAAS;EAAQ,KAAK;EAAO,OAAO;EAAS;CACvE,SAAS;EAAE,SAAS;EAAc,MAAM;EAAO,KAAK;EAAO,OAAO;EAAS;CAC3E,OAAO;EAAE,SAAS;EAAc,MAAM;EAAS,KAAK;EAAO,OAAO;EAAS;CAC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DD,SAAgB,6BACd,KACA,UAAqC,EAAE,EAC/B;AAGR,KAAI,QAAQ,WAAW,OACrB,QAAO;CAGT,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CAGrD,MAAM,WAAW,sBAAsB,YAAY;AACnD,KAAI,UAAU;AAEZ,MAAI,aAAa,OAAO;GACtB,MAAM,SACJE,uCAAqB;AACvB,OAAI,OACF,QAAO,GAAG,OAAO,GAAG;;AAGxB,SAAO;;CAIT,MAAM,SAASC,sCAAoB;AACnC,KAAI,OACF,QAAO;AAIT,QAAO"}