From abcf14877039de81ff5e44621e8a06b5eff21021 Mon Sep 17 00:00:00 2001
From: Kiarokh Moattar <kiarokh@icloud.com>
Date: Mon, 2 Mar 2026 15:44:24 +0100
Subject: [PATCH] feat(select): add `hotkey` prop for items & improve keyboard
 navigation

---
 etc/lime-elements.api.md                      |   1 +
 .../select/examples/select-hotkeys.tsx        |  89 ++++++++++++
 src/components/select/option.types.ts         |   6 +
 src/components/select/select.template.tsx     |  27 +++-
 src/components/select/select.tsx              | 130 ++++++++++++++++++
 5 files changed, 250 insertions(+), 3 deletions(-)
 create mode 100644 src/components/select/examples/select-hotkeys.tsx

diff --git a/etc/lime-elements.api.md b/etc/lime-elements.api.md
index 1c496524ed..dfe2fa7afd 100644
--- a/etc/lime-elements.api.md
+++ b/etc/lime-elements.api.md
@@ -4224,6 +4224,7 @@ export type OpenDirection = 'left-start' | 'left' | 'left-end' | 'right-start' |
 // @public
 interface Option_2<T extends string = string> {
     disabled?: boolean;
+    hotkey?: string;
     icon?: string | Icon;
     // @deprecated
     iconColor?: Color;
diff --git a/src/components/select/examples/select-hotkeys.tsx b/src/components/select/examples/select-hotkeys.tsx
new file mode 100644
index 0000000000..e8768ad371
--- /dev/null
+++ b/src/components/select/examples/select-hotkeys.tsx
@@ -0,0 +1,89 @@
+import {
+    LimelSelectCustomEvent,
+    Option,
+    ListSeparator,
+} from '@limetech/lime-elements';
+import { Component, h, Host, State } from '@stencil/core';
+
+/**
+ * Select with option hotkeys.
+ *
+ * Use `hotkey` on options to bind keyboard interaction while the select
+ * dropdown is open.
+ *
+ * :::note
+ * 1. Hotkeys work only while the custom dropdown is open.
+ * 2. On mobile/iOS, `limel-select` uses a native `<select>`, so option
+ * hotkeys are not active.
+ * 3. Some keys are reserved for dropdown navigation and are ignored as
+ * option hotkeys: `tab` and arrow keys are always reserved; `enter`, `escape`,
+ * and `space` are reserved unless used with a modifier (for example
+ * `alt+enter`).
+ * :::
+ *
+ * :::important
+ * `meta` means the Meta key.
+ * It is rendered as <kbd>⌘</kbd> on Apple devices and <kbd>⊞ Win</kbd> on
+ * Windows/Linux. (`cmd`, `command`, `win`, `windows` are aliases for `meta`.)
+ *
+ * `ctrl` means the Control key on all platforms.
+ *
+ * Choose hotkeys that do not conflict with common browser shortcuts.
+ * :::
+ */
+@Component({
+    shadow: true,
+    tag: 'limel-example-select-hotkeys',
+})
+export class SelectHotkeysExample {
+    @State()
+    private value: Option;
+
+    private readonly options: (Option | ListSeparator)[] = [
+        {
+            text: 'Started',
+            value: 'started',
+            hotkey: 's',
+        },
+        {
+            text: 'In progress',
+            value: 'in-progress',
+            hotkey: 'p',
+        },
+        {
+            text: 'Blocked',
+            value: 'blocked',
+            hotkey: 'b',
+        },
+        {
+            text: 'Done',
+            value: 'done',
+            hotkey: 'd',
+        },
+        { separator: true },
+        {
+            text: 'Closed',
+            secondaryText: 'as not planned',
+            value: 'closed',
+            hotkey: 'cmd+d',
+        },
+    ];
+
+    public render() {
+        return (
+            <Host>
+                <limel-select
+                    label="Task status"
+                    value={this.value}
+                    options={this.options}
+                    onChange={this.handleChange}
+                />
+                <limel-example-value value={this.value} />
+            </Host>
+        );
+    }
+
+    private readonly handleChange = (event: LimelSelectCustomEvent<Option>) => {
+        this.value = event.detail;
+    };
+}
diff --git a/src/components/select/option.types.ts b/src/components/select/option.types.ts
index cf59ef0980..5be565206e 100644
--- a/src/components/select/option.types.ts
+++ b/src/components/select/option.types.ts
@@ -29,6 +29,12 @@ export interface Option<T extends string = string> {
      */
     value: T;
 
+    /**
+     * Optional keyboard shortcut for selecting this option when the custom
+     * dropdown is open.
+     */
+    hotkey?: string;
+
     /**
      * Set to `true` to make this option disabled and not possible to select.
      */
diff --git a/src/components/select/select.template.tsx b/src/components/select/select.template.tsx
index d627607517..0c1112a8ee 100644
--- a/src/components/select/select.template.tsx
+++ b/src/components/select/select.template.tsx
@@ -189,7 +189,12 @@ const SelectDropdown: FunctionalComponent<SelectTemplateProps> = (props) => {
 };
 
 const MenuDropdown: FunctionalComponent<SelectTemplateProps> = (props) => {
-    const items = createMenuItems(props.options, props.value, props.required);
+    const items = createMenuItems(
+        props.options,
+        props.value,
+        props.required,
+        props.isOpen
+    );
 
     return (
         <limel-portal
@@ -274,7 +279,8 @@ function isSelected(option: Option, value: Option | Option[]): boolean {
 function createMenuItems(
     options: Array<Option | ListSeparator>,
     value: Option | Option[],
-    selectIsRequired = false
+    selectIsRequired = false,
+    isOpen = false
 ): Array<ListItem<Option> | ListSeparator> {
     const menuOptionFilter = getMenuOptionFilter(selectIsRequired);
 
@@ -287,17 +293,31 @@ function createMenuItems(
         }
 
         const selected = isSelected(option, value);
-        const { text, secondaryText, disabled } = option;
+        const { text, secondaryText, disabled, hotkey } = option;
         const name = getIconName(option.icon);
 
         const color = getIconColor(option.icon, option.iconColor);
 
+        const primaryComponent = hotkey
+            ? {
+                  name: 'limel-hotkey',
+                  props: {
+                      value: hotkey,
+                      disabled: !isOpen || disabled,
+                      style: {
+                          order: '2',
+                      },
+                  },
+              }
+            : undefined;
+
         if (!name) {
             return {
                 text: text,
                 secondaryText: secondaryText,
                 selected: selected,
                 disabled: disabled,
+                primaryComponent,
                 value: option,
             };
         }
@@ -307,6 +327,7 @@ function createMenuItems(
             secondaryText: secondaryText,
             selected: selected,
             disabled: disabled,
+            primaryComponent,
             value: option,
             icon: {
                 name: name,
diff --git a/src/components/select/select.tsx b/src/components/select/select.tsx
index 17ab2f02f0..5bfbbe4fb2 100644
--- a/src/components/select/select.tsx
+++ b/src/components/select/select.tsx
@@ -14,6 +14,11 @@ import {
 } from '@stencil/core';
 import { isMobileDevice } from '../../util/device';
 import { ENTER, SPACE } from '../../util/keycodes';
+import {
+    hotkeyFromKeyboardEvent,
+    normalizeHotkeyString,
+    tokenizeHotkeyString,
+} from '../../util/hotkeys';
 import { isMultiple } from '../../util/multiple';
 import { createRandomString } from '../../util/random-string';
 import { SelectTemplate, triggerIconColorWarning } from './select.template';
@@ -28,6 +33,7 @@ import { SelectTemplate, triggerIconColorWarning } from './select.template';
  * @exampleComponent limel-example-select-with-empty-option
  * @exampleComponent limel-example-select-preselected
  * @exampleComponent limel-example-select-change-options
+ * @exampleComponent limel-example-select-hotkeys
  * @exampleComponent limel-example-select-dialog
  */
 @Component({
@@ -126,6 +132,7 @@ export class Select {
     private portalId: string;
     private focusObserver: IntersectionObserver;
     private focusTimeoutId: ReturnType<typeof setTimeout>;
+    private readonly normalizedHotkeyCache = new Map<string, string | null>();
 
     constructor() {
         this.handleMenuChange = this.handleMenuChange.bind(this);
@@ -174,6 +181,11 @@ export class Select {
     }
 
     public disconnectedCallback() {
+        document.removeEventListener(
+            'keydown',
+            this.handleDocumentKeyDown,
+            true
+        );
         this.cancelPendingFocus();
 
         if (this.mdcFloatingLabel) {
@@ -224,6 +236,20 @@ export class Select {
 
     @Watch('menuOpen')
     protected watchOpen(newValue: boolean, oldValue: boolean) {
+        if (newValue) {
+            document.addEventListener(
+                'keydown',
+                this.handleDocumentKeyDown,
+                true
+            );
+        } else {
+            document.removeEventListener(
+                'keydown',
+                this.handleDocumentKeyDown,
+                true
+            );
+        }
+
         if (this.checkValid) {
             return;
         }
@@ -234,6 +260,11 @@ export class Select {
         }
     }
 
+    @Watch('options')
+    protected watchOptions() {
+        this.normalizedHotkeyCache.clear();
+    }
+
     private setMenuFocus() {
         if (this.isMobileDevice) {
             return;
@@ -367,6 +398,105 @@ export class Select {
         this.setTriggerFocus();
     }
 
+    private readonly handleDocumentKeyDown = (event: KeyboardEvent) => {
+        if (
+            this.isMobileDevice ||
+            !this.menuOpen ||
+            event.defaultPrevented ||
+            event.repeat
+        ) {
+            return;
+        }
+
+        const pressedHotkey = hotkeyFromKeyboardEvent(event);
+        if (!pressedHotkey || this.isReservedSelectHotkey(pressedHotkey)) {
+            return;
+        }
+
+        const matchedOption = this.findOptionByHotkey(pressedHotkey);
+        if (!matchedOption || matchedOption.disabled) {
+            return;
+        }
+
+        event.stopPropagation();
+        event.preventDefault();
+
+        if (this.multiple) {
+            const currentValue = isMultiple(this.value) ? this.value : [];
+            const hasSelectedOption = currentValue.some(
+                (option) => option.value === matchedOption.value
+            );
+
+            const nextValue = hasSelectedOption
+                ? currentValue.filter(
+                      (option) => option.value !== matchedOption.value
+                  )
+                : [...currentValue, matchedOption];
+
+            this.change.emit(nextValue);
+
+            return;
+        }
+
+        this.change.emit(matchedOption);
+        this.menuOpen = false;
+        this.setTriggerFocus();
+    };
+
+    private isReservedSelectHotkey(hotkey: string): boolean {
+        const tokens = tokenizeHotkeyString(hotkey);
+        const key = tokens.at(-1);
+        if (!key) {
+            return false;
+        }
+
+        if (
+            key === 'arrowup' ||
+            key === 'arrowdown' ||
+            key === 'arrowleft' ||
+            key === 'arrowright'
+        ) {
+            return true;
+        }
+
+        if (key === 'tab') {
+            return true;
+        }
+
+        const hasModifiers = tokens.length > 1;
+        return (
+            !hasModifiers &&
+            (key === 'enter' || key === 'space' || key === 'escape')
+        );
+    }
+
+    private findOptionByHotkey(pressedHotkey: string): Option | null {
+        for (const option of this.getOptionsExcludingSeparators()) {
+            if (option.disabled || !option.hotkey) {
+                continue;
+            }
+
+            const normalized = this.getNormalizedHotkey(option.hotkey);
+            if (normalized && normalized === pressedHotkey) {
+                return option;
+            }
+        }
+
+        return null;
+    }
+
+    private getNormalizedHotkey(raw: string): string | null {
+        const cacheKey = raw.trim();
+        if (this.normalizedHotkeyCache.has(cacheKey)) {
+            return this.normalizedHotkeyCache.get(cacheKey) ?? null;
+        }
+
+        const normalized = normalizeHotkeyString(cacheKey);
+        this.normalizedHotkeyCache.set(cacheKey, normalized);
+
+        return normalized;
+    }
+
     private openMenu() {
         const autoSelectOption = this.getFirstNativeAutoSelectOption();
         if (autoSelectOption) {