@vuetify/nightly 3.9.0-beta.1-dev.2025-06-26 → 3.9.0-beta.1-dev.2025-06-28

package/dist/vuetify.js

@@ -1,5 +1,5 @@
 /*!
-* Vuetify v3.9.0-beta.1-dev.2025-06-26
+* Vuetify v3.9.0-beta.1-dev.2025-06-28
 * Forged by John Leider
 * Released under the MIT License.
 */
@@ -1836,7 +1836,18 @@
     treeviewExpand: 'mdi-menu-right',
     eyeDropper: 'mdi-eyedropper',
     upload: 'mdi-cloud-upload',
-    color: 'mdi-palette'
+    color: 'mdi-palette',
+    command: 'mdi-apple-keyboard-command',
+    ctrl: 'mdi-apple-keyboard-control',
+    space: 'mdi-keyboard-space',
+    shift: 'mdi-apple-keyboard-shift',
+    alt: 'mdi-apple-keyboard-option',
+    enter: 'mdi-keyboard-return',
+    arrowup: 'mdi-arrow-up',
+    arrowdown: 'mdi-arrow-down',
+    arrowleft: 'mdi-arrow-left',
+    arrowright: 'mdi-arrow-right',
+    backspace: 'mdi-backspace'
   };
   const mdi = {
     // Not using mergeProps here, functional components merge props by default (?)
@@ -2632,6 +2643,24 @@
       exclude: 'The {0} character is not allowed',
       notEmpty: 'Please choose at least one value',
       pattern: 'Invalid format'
+    },
+    hotkey: {
+      then: 'then',
+      ctrl: 'Ctrl',
+      command: 'Command',
+      space: 'Space',
+      shift: 'Shift',
+      alt: 'Alt',
+      enter: 'Enter',
+      escape: 'Escape',
+      upArrow: 'Up Arrow',
+      downArrow: 'Down Arrow',
+      leftArrow: 'Left Arrow',
+      rightArrow: 'Right Arrow',
+      backspace: 'Backspace',
+      option: 'Option',
+      plus: 'plus',
+      shortcut: 'Keyboard shortcut: {0}'
     }
   };
 
@@ -18355,6 +18384,317 @@
     return createInstance(options, locale);
   }
 
+  /**
+   * Centralized key alias mapping for consistent key normalization across the hotkey system.
+   *
+   * This maps various user-friendly aliases to canonical key names that match
+   * KeyboardEvent.key values (in lowercase) where possible.
+   */
+  const keyAliasMap = {
+    // Modifier aliases (from vue-use, other libraries, and current implementation)
+    control: 'ctrl',
+    command: 'cmd',
+    option: 'alt',
+    // Arrow key aliases (common abbreviations)
+    up: 'arrowup',
+    down: 'arrowdown',
+    left: 'arrowleft',
+    right: 'arrowright',
+    // Other common key aliases
+    esc: 'escape',
+    spacebar: ' ',
+    space: ' ',
+    return: 'enter',
+    del: 'delete',
+    // Symbol aliases (existing from hotkey-parsing.ts)
+    minus: '-',
+    hyphen: '-'
+  };
+
+  /**
+   * Normalizes a key string to its canonical form using the alias map.
+   *
+   * @param key - The key string to normalize
+   * @returns The canonical key name in lowercase
+   */
+  function normalizeKey(key) {
+    const lowerKey = key.toLowerCase();
+    return keyAliasMap[lowerKey] || lowerKey;
+  }
+
+  // Utilities
+
+  /**
+   * Splits a single combination string into individual key parts.
+   *
+   * A combination is a set of keys that must be pressed simultaneously.
+   * e.g. `ctrl+k`, `shift--`
+   */
+  function splitKeyCombination(combination) {
+    let isInternal = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    if (!combination) {
+      if (!isInternal) consoleWarn('Invalid hotkey combination: empty string provided');
+      return [];
+    }
+
+    // --- VALIDATION ---
+    const startsWithPlusOrUnderscore = combination.startsWith('+') || combination.startsWith('_');
+    const hasInvalidLeadingSeparator =
+    // Starts with a single '+' or '_' followed by a non-separator character (e.g. '+a', '_a')
+    startsWithPlusOrUnderscore && !(combination.startsWith('++') || combination.startsWith('__'));
+    const hasInvalidStructure =
+    // Invalid leading separator patterns
+    combination.length > 1 && hasInvalidLeadingSeparator ||
+    // Disallow literal + or _ keys (they require shift)
+    combination.includes('++') || combination.includes('__') || combination === '+' || combination === '_' ||
+    // Ends with a separator that is not part of a doubled literal
+    combination.length > 1 && (combination.endsWith('+') || combination.endsWith('_')) && combination.at(-2) !== combination.at(-1) ||
+    // Stand-alone doubled separators (dangling)
+    combination === '++' || combination === '--' || combination === '__';
+    if (hasInvalidStructure) {
+      if (!isInternal) consoleWarn(`Invalid hotkey combination: "${combination}" has invalid structure`);
+      return [];
+    }
+    const keys = [];
+    let buffer = '';
+    const flushBuffer = () => {
+      if (buffer) {
+        keys.push(normalizeKey(buffer));
+        buffer = '';
+      }
+    };
+    for (let i = 0; i < combination.length; i++) {
+      const char = combination[i];
+      const nextChar = combination[i + 1];
+      if (char === '+' || char === '_' || char === '-') {
+        if (char === nextChar) {
+          flushBuffer();
+          keys.push(char);
+          i++;
+        } else if (char === '+' || char === '_') {
+          flushBuffer();
+        } else {
+          buffer += char;
+        }
+      } else {
+        buffer += char;
+      }
+    }
+    flushBuffer();
+
+    // Within a combination, `-` is only valid as a literal key (e.g., `ctrl+-`).
+    // `-` cannot be part of a longer key name within a combination.
+    const hasInvalidMinus = keys.some(key => key.length > 1 && key.includes('-') && key !== '--');
+    if (hasInvalidMinus) {
+      if (!isInternal) consoleWarn(`Invalid hotkey combination: "${combination}" has invalid structure`);
+      return [];
+    }
+    if (keys.length === 0 && combination) {
+      return [normalizeKey(combination)];
+    }
+    return keys;
+  }
+
+  /**
+   * Splits a hotkey string into its constituent combination groups.
+   *
+   * A sequence is a series of combinations that must be pressed in order.
+   * e.g. `a-b`, `ctrl+k-p`
+   */
+  function splitKeySequence(str) {
+    if (!str) {
+      consoleWarn('Invalid hotkey sequence: empty string provided');
+      return [];
+    }
+
+    // A sequence is invalid if it starts or ends with a separator,
+    // unless it is part of a combination (e.g., `shift+-`).
+    const hasInvalidStart = str.startsWith('-') && !['---', '--+'].includes(str);
+    const hasInvalidEnd = str.endsWith('-') && !str.endsWith('+-') && !str.endsWith('_-') && str !== '-' && str !== '---';
+    if (hasInvalidStart || hasInvalidEnd) {
+      consoleWarn(`Invalid hotkey sequence: "${str}" contains invalid combinations`);
+      return [];
+    }
+    const result = [];
+    let buffer = '';
+    let i = 0;
+    while (i < str.length) {
+      const char = str[i];
+      if (char === '-') {
+        // Determine if this hyphen is part of the current combination
+        const prevChar = str[i - 1];
+        const prevPrevChar = i > 1 ? str[i - 2] : undefined;
+        const precededBySinglePlusOrUnderscore = (prevChar === '+' || prevChar === '_') && prevPrevChar !== '+';
+        if (precededBySinglePlusOrUnderscore) {
+          // Treat as part of the combination (e.g., 'ctrl+-')
+          buffer += char;
+          i++;
+        } else {
+          // Treat as sequence separator
+          if (buffer) {
+            result.push(buffer);
+            buffer = '';
+          } else {
+            // Empty buffer means we have a literal '-' key
+            result.push('-');
+          }
+          i++;
+        }
+      } else {
+        buffer += char;
+        i++;
+      }
+    }
+
+    // Add final buffer if it exists
+    if (buffer) {
+      result.push(buffer);
+    }
+
+    // Collapse runs of '-' so that every second '-' is removed
+    const collapsed = [];
+    let minusCount = 0;
+    for (const part of result) {
+      if (part === '-') {
+        if (minusCount % 2 === 0) collapsed.push('-');
+        minusCount++;
+      } else {
+        minusCount = 0;
+        collapsed.push(part);
+      }
+    }
+
+    // Validate that each part of the sequence is a valid combination
+    const areAllValid = collapsed.every(s => splitKeyCombination(s, true).length > 0);
+    if (!areAllValid) {
+      consoleWarn(`Invalid hotkey sequence: "${str}" contains invalid combinations`);
+      return [];
+    }
+    return collapsed;
+  }
+
+  // Composables
+
+  // Types
+
+  function useHotkey(keys, callback) {
+    let options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    if (!IN_BROWSER) return function () {};
+    const {
+      event = 'keydown',
+      inputs = false,
+      preventDefault = true,
+      sequenceTimeout = 1000
+    } = options;
+    const isMac = navigator?.userAgent?.includes('Macintosh') ?? false;
+    let timeout = 0;
+    let keyGroups;
+    let isSequence = false;
+    let groupIndex = 0;
+    function clearTimer() {
+      if (!timeout) return;
+      clearTimeout(timeout);
+      timeout = 0;
+    }
+    function isInputFocused() {
+      if (vue.toValue(inputs)) return false;
+      const activeElement = document.activeElement;
+      return activeElement && (activeElement.tagName === 'INPUT' || activeElement.tagName === 'TEXTAREA' || activeElement.isContentEditable || activeElement.contentEditable === 'true');
+    }
+    function resetSequence() {
+      groupIndex = 0;
+      clearTimer();
+    }
+    function handler(e) {
+      const group = keyGroups[groupIndex];
+      if (!group || isInputFocused()) return;
+      if (!matchesKeyGroup(e, group)) {
+        if (isSequence) resetSequence();
+        return;
+      }
+      if (vue.toValue(preventDefault)) e.preventDefault();
+      if (!isSequence) {
+        callback(e);
+        return;
+      }
+      clearTimer();
+      groupIndex++;
+      if (groupIndex === keyGroups.length) {
+        callback(e);
+        resetSequence();
+        return;
+      }
+      timeout = window.setTimeout(resetSequence, vue.toValue(sequenceTimeout));
+    }
+    function cleanup() {
+      window.removeEventListener(vue.toValue(event), handler);
+      clearTimer();
+    }
+    vue.watch(() => vue.toValue(keys), function (unrefKeys) {
+      cleanup();
+      if (unrefKeys) {
+        const groups = splitKeySequence(unrefKeys.toLowerCase());
+        isSequence = groups.length > 1;
+        keyGroups = groups;
+        resetSequence();
+        window.addEventListener(vue.toValue(event), handler);
+      }
+    }, {
+      immediate: true
+    });
+
+    // Watch for changes in the event type to re-register the listener
+    vue.watch(() => vue.toValue(event), function (newEvent, oldEvent) {
+      if (oldEvent && keyGroups && keyGroups.length > 0) {
+        window.removeEventListener(oldEvent, handler);
+        window.addEventListener(newEvent, handler);
+      }
+    });
+    try {
+      getCurrentInstance('useHotkey');
+      vue.onBeforeUnmount(cleanup);
+    } catch {
+      // Not in Vue setup context
+    }
+    function parseKeyGroup(group) {
+      const MODIFIERS = ['ctrl', 'shift', 'alt', 'meta', 'cmd'];
+
+      // Use the shared combination splitting logic
+      const parts = splitKeyCombination(group.toLowerCase());
+
+      // If the combination is invalid, return empty result
+      if (parts.length === 0) {
+        return {
+          modifiers: Object.fromEntries(MODIFIERS.map(m => [m, false])),
+          actualKey: undefined
+        };
+      }
+      const modifiers = Object.fromEntries(MODIFIERS.map(m => [m, false]));
+      let actualKey;
+      for (const part of parts) {
+        if (MODIFIERS.includes(part)) {
+          modifiers[part] = true;
+        } else {
+          actualKey = part;
+        }
+      }
+      return {
+        modifiers,
+        actualKey
+      };
+    }
+    function matchesKeyGroup(e, group) {
+      const {
+        modifiers,
+        actualKey
+      } = parseKeyGroup(group);
+      const expectCtrl = modifiers.ctrl || !isMac && (modifiers.cmd || modifiers.meta);
+      const expectMeta = isMac && (modifiers.cmd || modifiers.meta);
+      return e.ctrlKey === expectCtrl && e.metaKey === expectMeta && e.shiftKey === modifiers.shift && e.altKey === modifiers.alt && e.key.toLowerCase() === actualKey?.toLowerCase();
+    }
+    return cleanup;
+  }
+
   // Types
 
   const makeVColorPickerProps = propsFactory({
@@ -30897,7 +31237,7 @@
       };
     });
   }
-  const version$1 = "3.9.0-beta.1-dev.2025-06-26";
+  const version$1 = "3.9.0-beta.1-dev.2025-06-28";
   createVuetify$1.version = version$1;
 
   // Vue's inject() can only be used in setup
@@ -30922,7 +31262,7 @@
       ...options
     });
   };
-  const version = "3.9.0-beta.1-dev.2025-06-26";
+  const version = "3.9.0-beta.1-dev.2025-06-28";
   createVuetify.version = version;
 
   exports.blueprints = index;
@@ -30933,6 +31273,7 @@
   exports.useDefaults = useDefaults;
   exports.useDisplay = useDisplay;
   exports.useGoTo = useGoTo;
+  exports.useHotkey = useHotkey;
   exports.useLayout = useLayout;
   exports.useLocale = useLocale;
   exports.useRtl = useRtl;