vira 33.0.0 → 33.2.0

package/dist/elements/popover/vira-menu-item.element.js

@@ -207,6 +207,15 @@ export const ViraMenuItem = defineViraElement()({
             }, {
                 capture: true,
             }),
+            listenTo(host, 'keydown', (event) => {
+                if (event instanceof KeyboardEvent &&
+                    event.target === host &&
+                    (event.key === 'Enter' || event.key === ' ')) {
+                    /** Prevents Space from scrolling the menu. */
+                    event.preventDefault();
+                    host.click();
+                }
+            }),
             listenTo(host, 'mouseenter', () => {
                 if (!inputs.disabled) {
                     host.focus();

package/dist/elements/popover/vira-popover-trigger.element.d.ts

@@ -45,5 +45,6 @@ export declare const ViraPopoverTrigger: import("element-vir").DeclarativeElemen
     openChange: import("element-vir").DefineElementEvent<boolean>;
     init: import("element-vir").DefineElementEvent<{
         navController: NavController;
+        popoverManager: PopoverManager;
     }>;
 }, "vira-popover-trigger-disabled" | "vira-popover-trigger-inside-focus" | "vira-popover-trigger-outside-focus", "vira-popover-trigger-offset-vertical" | "vira-popover-trigger-offset-left" | "vira-popover-trigger-offset-right", readonly ["vira-popover-trigger-trigger", "vira-popover-trigger-popover"], readonly []>;

package/dist/elements/popover/vira-popover-trigger.element.js

@@ -165,8 +165,13 @@ export const ViraPopoverTrigger = defineViraElement()({
                     it flip upwards when there is not much room below the trigger.
                 */
                 min-height: 200px;
-                /* Margins are not included in the percentage. */
-                max-height: calc(100% - ${cssVars['vira-popover-trigger-offset-vertical'].value});
+                /*
+                    Margins are not included in the percentage. The extra 4px keeps the popover off
+                    the window's top or bottom edge.
+                */
+                max-height: calc(
+                    100% - ${cssVars['vira-popover-trigger-offset-vertical'].value} - 4px
+                );
                 width: max-content;
                 min-width: calc(
                     anchor-size(width) - ${cssVars['vira-popover-trigger-offset-left'].value} -
@@ -225,6 +230,7 @@ export const ViraPopoverTrigger = defineViraElement()({
         dispatch(new events.init({
             detail: {
                 navController: state.navController,
+                popoverManager: state.popoverManager,
             },
         }));
     },

package/dist/elements/vira-dropdown.element.d.ts

@@ -1,6 +1,8 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
+import { type NavController } from 'device-navigation';
 import { type AttributeValues, type HtmlInterpolation } from 'element-vir';
 import { type ViraIconSvg } from '../icons/icon-svg.js';
+import { type PopoverManager } from '../util/popover-manager.js';
 import { type ViraDropdownOption, type ViraDropdownOptionGroup } from '../util/vira-dropdown-option.js';
 /**
  * A dropdown element that uses popover menus.
@@ -26,6 +28,11 @@ export declare const ViraDropdown: import("element-vir").DeclarativeElementDefin
      * multiple.
      */
     isMultiSelect: boolean;
+    /**
+     * Replaces the selection text with a text input. Opening the dropdown focuses it and typing
+     * into it filters the options to those whose labels fuzzy match the typed text.
+     */
+    isSearchable: boolean;
     icon: ViraIconSvg;
     selectionPrefix: string;
     isDisabled: boolean;
@@ -53,9 +60,13 @@ export declare const ViraDropdown: import("element-vir").DeclarativeElementDefin
      * provided.
      */
     randomId: string;
+    /** The text typed into the search input while the dropdown is open. */
+    searchText: string;
+    navController: undefined | NavController;
+    popoverManager: undefined | PopoverManager;
 }, {
     /** Emits all currently selected values. */
     selectedValuesChange: import("element-vir").DefineElementEvent<string[]>;
     /** `true` when the popover just opened, `false` when it just closed. */
     openChange: import("element-vir").DefineElementEvent<boolean>;
-}, "vira-dropdown-", "vira-dropdown-", readonly [], readonly ["leadingIcon", "prefixText", "trigger"]>;
+}, "vira-dropdown-", "vira-dropdown-", readonly [], readonly ["leadingIcon", "prefixText", "searchInput", "trigger"]>;

package/dist/elements/vira-dropdown.element.js

@@ -1,12 +1,15 @@
 import { check } from '@augment-vir/assert';
 import { filterMap, randomString } from '@augment-vir/common';
 import { extractEventTarget } from '@augment-vir/web';
+import { nav, NavDirection } from 'device-navigation';
 import { attributes, classMap, css, defineElementEvent, html, ifDefined, listen, nothing, testId, } from 'element-vir';
 import { ChevronUp16Icon } from '../icons/index.js';
+import { createFocusStyles } from '../styles/focus.js';
 import { viraFormCssVars } from '../styles/form-styles.js';
 import { ViraSize, viraSizeHeights } from '../styles/form-variants.js';
-import { noUserSelect, viraAnimationDurations } from '../styles/index.js';
+import { noNativeFormStyles, noUserSelect, viraAnimationDurations } from '../styles/index.js';
 import { defineViraElement } from '../util/define-vira-element.js';
+import { fuzzyMatch } from '../util/fuzzy-match.js';
 import { renderMenuItemEntries } from '../util/menu-helpers.js';
 import { isViraDropdownOptionGroup, } from '../util/vira-dropdown-option.js';
 import { ViraMenuItem } from './popover/vira-menu-item.element.js';
@@ -25,6 +28,7 @@ export const ViraDropdown = defineViraElement()({
     testIds: [
         'leadingIcon',
         'prefixText',
+        'searchInput',
         'trigger',
     ],
     styles: css `
@@ -46,6 +50,56 @@ export const ViraDropdown = defineViraElement()({
             white-space: nowrap;
         }
 
+        .option-label {
+            display: inline-flex;
+            align-items: center;
+            gap: 8px;
+            max-width: 100%;
+            vertical-align: bottom;
+        }
+
+        .option-icon {
+            flex-shrink: 0;
+        }
+
+        .option-label-text {
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+        }
+
+        .search-input {
+            ${noNativeFormStyles};
+            flex-grow: 1;
+            min-width: 0;
+            align-self: stretch;
+            text-overflow: ellipsis;
+            cursor: inherit;
+            user-select: text;
+            -webkit-user-select: text;
+            outline: none;
+
+            &::placeholder {
+                color: inherit;
+                opacity: 0.4;
+            }
+        }
+
+        .open .search-input {
+            cursor: text;
+        }
+
+        .dropdown-trigger:has(.search-input:focus-visible:not([disabled])) {
+            position: relative;
+
+            &::after {
+                ${createFocusStyles({
+        elementBorderSize: '1px',
+        noNesting: true,
+    })}
+            }
+        }
+
         .trigger-icon {
             width: 24px;
             aspect-ratio: 1;
@@ -155,9 +209,13 @@ export const ViraDropdown = defineViraElement()({
              * provided.
              */
             randomId: randomString(32),
+            /** The text typed into the search input while the dropdown is open. */
+            searchText: '',
+            navController: undefined,
+            popoverManager: undefined,
         };
     },
-    render({ state, inputs, dispatch, events, updateState, testIds }) {
+    render({ state, inputs, dispatch, events, updateState, testIds, host }) {
         const flatOptions = inputs.options.flatMap((entry) => {
             return isViraDropdownOptionGroup(entry) ? entry.options : [entry];
         });
@@ -184,6 +242,29 @@ export const ViraDropdown = defineViraElement()({
             : inputs.isMultiSelect && selectedOptions.length > 1
                 ? `${selectedOptions.length} Selected`
                 : selectedOptions[0]?.label || '';
+        function renderOptionLabel(option) {
+            return option.icon || option.labelTemplate
+                ? html `
+                      <span class="option-label">
+                          ${option.icon
+                    ? html `
+                                    <${ViraIcon.assign({
+                        icon: option.icon,
+                    })}
+                                        class="option-icon"
+                                    ></${ViraIcon}>
+                                `
+                    : nothing}
+                          <span class="option-label-text">
+                              ${option.labelTemplate ?? option.label}
+                          </span>
+                      </span>
+                  `
+                : option.label;
+        }
+        const selectionTemplate = check.isLengthExactly(selectedOptions, 1)
+            ? renderOptionLabel(selectedOptions[0])
+            : selectionDisplay;
         function selectOption(option) {
             const newSelectedValues = inputs.isMultiSelect
                 ? selectedOptions.includes(option)
@@ -197,6 +278,42 @@ export const ViraDropdown = defineViraElement()({
                 detail: newSelectedValues,
             }));
         }
+        const filteredOptions = state.searchText
+            ? filterMap(inputs.options, (entry) => {
+                return isViraDropdownOptionGroup(entry)
+                    ? {
+                        ...entry,
+                        options: entry.options.filter((option) => {
+                            return fuzzyMatch({
+                                search: state.searchText,
+                                text: option.label,
+                            });
+                        }),
+                    }
+                    : entry;
+            }, (entry) => {
+                return isViraDropdownOptionGroup(entry)
+                    ? !!entry.options.length
+                    : fuzzyMatch({
+                        search: state.searchText,
+                        text: entry.label,
+                    });
+            })
+            : inputs.options;
+        const filteredFlatOptions = filteredOptions.flatMap((entry) => {
+            return isViraDropdownOptionGroup(entry) ? entry.options : [entry];
+        });
+        function findSearchInput() {
+            const searchInput = host.shadowRoot.querySelector('.search-input');
+            return searchInput instanceof HTMLInputElement ? searchInput : undefined;
+        }
+        function clearSearch(searchInput) {
+            /** Set directly because the `.value` binding skips values it has already committed. */
+            searchInput.value = '';
+            updateState({
+                searchText: '',
+            });
+        }
         function toggleGroup(group) {
             const enabledGroupOptions = group.options.filter((option) => !option.disabled);
             const isGroupSelected = enabledGroupOptions.every((option) => {
@@ -220,6 +337,7 @@ export const ViraDropdown = defineViraElement()({
                     disablePointerStyles: true,
                 })}
                           class="option-group-label"
+                          ${state.navController ? nav(state.navController) : nothing}
                           ${listen('click', () => {
                     toggleGroup(group);
                 })}
@@ -232,7 +350,7 @@ export const ViraDropdown = defineViraElement()({
                   `;
         }
         /** Drag-select actions in the same order as the rendered menu items. */
-        const menuItemActions = inputs.options.flatMap((entry) => {
+        const menuItemActions = filteredOptions.flatMap((entry) => {
             const options = isViraDropdownOptionGroup(entry) ? entry.options : [entry];
             const optionActions = options.map((option) => {
                 return option.disabled
@@ -253,16 +371,16 @@ export const ViraDropdown = defineViraElement()({
         function renderOptionEntries(options) {
             return renderMenuItemEntries(options.map((option) => {
                 return {
-                    content: option.label,
+                    content: renderOptionLabel(option),
                     onClick() {
                         selectOption(option);
                     },
                     disabled: option.disabled,
                     selected: selectedOptions.includes(option),
                 };
-            }));
+            }), state.navController);
         }
-        const isMenuShown = state.isOpen && (!!flatOptions.length || !!inputs.noOptionsText);
+        const isMenuShown = state.isOpen && (!!filteredFlatOptions.length || !!inputs.noOptionsText);
         const menuTemplate = html `
             <${ViraMenu.assign({
             cornerStyle: ViraMenuCornerStyle.Round,
@@ -283,8 +401,8 @@ export const ViraDropdown = defineViraElement()({
             }
         })}
             >
-                ${flatOptions.length
-            ? inputs.options.map((entry) => {
+                ${filteredFlatOptions.length
+            ? filteredOptions.map((entry) => {
                 return isViraDropdownOptionGroup(entry)
                     ? html `
                                     ${renderGroupLabel(entry)} ${renderOptionEntries(entry.options)}
@@ -305,6 +423,12 @@ export const ViraDropdown = defineViraElement()({
                 vertical: -1,
                 right: 24,
             },
+        })}
+                ${listen(ViraPopoverTrigger.events.init, (event) => {
+            updateState({
+                navController: event.detail.navController,
+                popoverManager: event.detail.popoverManager,
+            });
         })}
                 ${listen(ViraPopoverTrigger.events.openChange, (event) => {
             if (state.isOpen !== event.detail) {
@@ -315,6 +439,37 @@ export const ViraDropdown = defineViraElement()({
             updateState({
                 isOpen: event.detail,
             });
+            const searchInput = findSearchInput();
+            if (!searchInput) {
+                return;
+            }
+            else if (event.detail) {
+                searchInput.focus();
+            }
+            else {
+                clearSearch(searchInput);
+            }
+        })}
+                ${listen('keydown', (event) => {
+            const searchInput = findSearchInput();
+            const isSearchKey = event.key === 'Backspace' ||
+                (event.key.length === 1 &&
+                    event.key !== ' ' &&
+                    !event.ctrlKey &&
+                    !event.metaKey &&
+                    !event.altKey);
+            if (!searchInput || !isSearchKey) {
+                return;
+            }
+            if (!state.isOpen) {
+                clearSearch(searchInput);
+            }
+            /**
+             * Focusing during keydown makes the browser type the pressed key into the
+             * search input, even when the key was pressed on the trigger or a menu item.
+             */
+            searchInput.focus();
+            state.popoverManager?.show();
         })}
                 ${listen('mouseup', () => {
             if (state.shouldSelectOnMouseUp) {
@@ -342,14 +497,93 @@ export const ViraDropdown = defineViraElement()({
         })}
                 >
                     ${leadingIconTemplate}
-                    <span
-                        class="selection-display ${classMap({
-            'using-placeholder': shouldUsePlaceholder,
-        })}"
-                        title=${ifDefined(shouldUsePlaceholder ? undefined : selectionDisplay)}
-                    >
-                        ${prefixTemplate} ${selectionDisplay}
-                    </span>
+                    ${inputs.isSearchable
+            ? html `
+                              ${state.isOpen ? nothing : prefixTemplate}
+                              <input
+                                  class="search-input"
+                                  ${testId(testIds.searchInput)}
+                                  tabindex="-1"
+                                  autocomplete="off"
+                                  spellcheck="false"
+                                  aria-label=${ifDefined((check.isString(inputs.label) && inputs.label) || undefined)}
+                                  ?disabled=${!!inputs.isDisabled}
+                                  title=${ifDefined(shouldUsePlaceholder || state.isOpen
+                ? undefined
+                : selectionDisplay)}
+                                  placeholder=${state.isOpen && !shouldUsePlaceholder
+                ? selectionDisplay
+                : inputs.placeholder || ''}
+                                  .value=${state.isOpen
+                ? state.searchText
+                : shouldUsePlaceholder
+                    ? ''
+                    : selectionDisplay}
+                                  ${listen('mousedown', (event) => {
+                /** Keeps the popover open when clicking into the input. */
+                if (state.isOpen) {
+                    event.stopPropagation();
+                }
+            })}
+                                  ${listen('input', (event) => {
+                updateState({
+                    searchText: extractEventTarget(event, HTMLInputElement)
+                        .value,
+                });
+                state.popoverManager?.show();
+            })}
+                                  ${listen('keydown', (event) => {
+                if (!state.isOpen) {
+                    return;
+                }
+                else if (event.key === 'ArrowDown' ||
+                    event.key === 'ArrowUp') {
+                    event.preventDefault();
+                    state.navController?.navigate({
+                        direction: event.key === 'ArrowDown'
+                            ? NavDirection.Down
+                            : NavDirection.Up,
+                        allowWrapping: false,
+                    });
+                }
+                else if (event.key === 'Tab' && !event.shiftKey) {
+                    /**
+                     * Without this, browsers move focus from this input past
+                     * the menu items (sometimes closing the menu).
+                     */
+                    const firstMenuItem = Array.from(host.shadowRoot.querySelectorAll(ViraMenuItem.tagName)).find((menuItem) => menuItem.tabIndex >= 0);
+                    if (firstMenuItem) {
+                        event.preventDefault();
+                        firstMenuItem.focus();
+                    }
+                }
+                else if (event.key === 'Enter') {
+                    const firstOption = filteredFlatOptions.find((option) => !option.disabled);
+                    if (!firstOption) {
+                        return;
+                    }
+                    event.preventDefault();
+                    selectOption(firstOption);
+                    if (inputs.isMultiSelect) {
+                        clearSearch(extractEventTarget(event, HTMLInputElement));
+                    }
+                    else {
+                        state.popoverManager?.hide();
+                    }
+                }
+            })}
+                              />
+                          `
+            : html `
+                              <span
+                                  class="selection-display ${classMap({
+                'using-placeholder': shouldUsePlaceholder,
+            })}"
+                                  title=${ifDefined(shouldUsePlaceholder ? undefined : selectionDisplay)}
+                              >
+                                  ${prefixTemplate} ${selectionTemplate}
+                              </span>
+                          `}
 
                     <span class="trigger-icon-wrapper">
                         <${ViraIcon.assign({
@@ -364,7 +598,7 @@ export const ViraDropdown = defineViraElement()({
         `;
         const contentTemplate = inputs.isReadonly
             ? html `
-                  <span class="readonly-value">${selectionDisplay}</span>
+                  <span class="readonly-value">${selectionTemplate}</span>
               `
             : triggerTemplate;
         if (inputs.label) {

package/dist/util/fuzzy-match.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Checks if every non-whitespace character of `search` appears in `text`, in order, ignoring case.
+ * An empty `search` matches everything.
+ *
+ * @category Internal
+ * @example
+ *
+ * ```ts
+ * fuzzyMatch({search: 'opa', text: 'Option A'}); // true
+ * fuzzyMatch({search: 'apo', text: 'Option A'}); // false
+ * ```
+ */
+export declare function fuzzyMatch({ search, text, }: Readonly<{
+    search: string;
+    text: string;
+}>): boolean;

package/dist/util/fuzzy-match.js

@@ -0,0 +1,24 @@
+/**
+ * Checks if every non-whitespace character of `search` appears in `text`, in order, ignoring case.
+ * An empty `search` matches everything.
+ *
+ * @category Internal
+ * @example
+ *
+ * ```ts
+ * fuzzyMatch({search: 'opa', text: 'Option A'}); // true
+ * fuzzyMatch({search: 'apo', text: 'Option A'}); // false
+ * ```
+ */
+export function fuzzyMatch({ search, text, }) {
+    const lowerText = text.toLowerCase();
+    return (search
+        .replaceAll(/\s/g, '')
+        .toLowerCase()
+        .split('')
+        .reduce((textIndex, character) => {
+        return textIndex < 0
+            ? textIndex
+            : lowerText.indexOf(character, textIndex) + 1 || -1;
+    }, 0) >= 0);
+}

package/dist/util/index.d.ts

@@ -2,6 +2,7 @@ export * from './anchored-popover.js';
 export * from './define-table.js';
 export * from './define-vira-element.js';
 export * from './dynamic-element.js';
+export * from './fuzzy-match.js';
 export * from './menu-helpers.js';
 export * from './overflow-observer.js';
 export * from './popover-manager.js';

package/dist/util/index.js

@@ -2,6 +2,7 @@ export * from './anchored-popover.js';
 export * from './define-table.js';
 export * from './define-vira-element.js';
 export * from './dynamic-element.js';
+export * from './fuzzy-match.js';
 export * from './menu-helpers.js';
 export * from './overflow-observer.js';
 export * from './popover-manager.js';

package/dist/util/menu-helpers.d.ts

@@ -1,4 +1,5 @@
 import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type NavController } from 'device-navigation';
 import { type HtmlInterpolation } from 'element-vir';
 import { ViraMenuItem } from '../elements/popover/vira-menu-item.element.js';
 /**
@@ -42,4 +43,6 @@ export type MenuItemClickCallback = (params: Readonly<{
  *
  * @category Popover
  */
-export declare function renderMenuItemEntries(items: ReadonlyArray<Readonly<ViraMenuItemEntry>>): import("lit-html").HTMLTemplateResult[];
+export declare function renderMenuItemEntries(items: ReadonlyArray<Readonly<ViraMenuItemEntry>>, 
+/** Enables arrow key navigation between the menu items. */
+navController?: NavController | undefined): import("lit-html").HTMLTemplateResult[];

package/dist/util/menu-helpers.js

@@ -1,5 +1,6 @@
 import { filterMap, joinWithFinalConjunction, } from '@augment-vir/common';
-import { html, listen } from 'element-vir';
+import { nav } from 'device-navigation';
+import { html, listen, nothing } from 'element-vir';
 import { ViraMenuItem } from '../elements/popover/vira-menu-item.element.js';
 /**
  * Verifies that all items have unique ids.
@@ -26,12 +27,19 @@ export function assertUniqueIdProps(items) {
  *
  * @category Popover
  */
-export function renderMenuItemEntries(items) {
+export function renderMenuItemEntries(items, 
+/** Enables arrow key navigation between the menu items. */
+navController) {
     return filterMap(items, (item, index) => {
         return html `
                 <${ViraMenuItem.assign({
             ...item,
         })}
+                    ${navController
+            ? nav(navController, {
+                disabled: item.disabled,
+            })
+            : nothing}
                     ${listen('click', async (event) => {
             if (item.disabled) {
                 event.stopImmediatePropagation();

package/dist/util/popover-manager.js

@@ -140,6 +140,8 @@ const anchorListeners = {
                         })
                             ?.focus({
                             preventScroll: true,
+                            /** Otherwise a mouse click shows the keyboard focus ring. */
+                            focusVisible: false,
                         });
                     }
                     popoverManager.toggle();

package/dist/util/vira-dropdown-option.d.ts

@@ -1,4 +1,6 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
+import { type HtmlInterpolation } from 'element-vir';
+import { type ViraIconSvg } from '../icons/icon-svg.js';
 /**
  * Options for `ViraDropdown`.
  *
@@ -8,9 +10,17 @@ import { type PartialWithUndefined } from '@augment-vir/common';
 export type ViraDropdownOption = {
     /** A value or id, used to keep track of which option is selected. */
     value: string;
+    /**
+     * Plain text for the option. Still used for search filtering, tooltips, and the search input's
+     * text when `labelTemplate` is set.
+     */
     label: string;
 } & PartialWithUndefined<{
     disabled: boolean;
+    /** Drawn before the label. Not drawn inside a searchable dropdown's text input. */
+    icon: ViraIconSvg;
+    /** Rendered instead of `label`. Not rendered inside a searchable dropdown's text input. */
+    labelTemplate: HtmlInterpolation;
 }>;
 /**
  * A group of options for `ViraDropdown`, rendered under a group label.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "33.0.0",
+    "version": "33.2.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",