@internetarchive/collection-browser 3.4.1-alpha-webdev7761.2 → 3.4.1-alpha-webdev7761.3

package/src/combo-box/ia-combo-box.ts

@@ -16,6 +16,7 @@ import { msg } from '@lit/localize';
 
 import {
   hasAnyOf,
+  isSubsequence,
   type IAComboBoxBehavior,
   type IAComboBoxFilterFunction,
   type IAComboBoxFilterOption,
@@ -23,36 +24,9 @@ import {
   type IAComboBoxOption,
 } from './models';
 
-import caretClosed from './caret-closed';
-import caretOpen from './caret-open';
-
-/**
- * Tests whether the given `haystack` string has the given `needle` as a subsequence.
- * Returns `true` if the characters of `needle` appear in order within `haystack`,
- * regardless of whether they are contiguous. Returns `false` otherwise.
- *
- * E.g., `ace` is a subsequence of `archive` (but not a contiguous substring).
- *
- * Note: The empty string is a subsequence of any string, including itself.
- *
- * @param needle The potential subsequence to check for inside `haystack`.
- * @param haystack The string to be tested for containing the `needle` subsequence.
- * @returns Whether `haystack` has `needle` as a subsequence.
- */
-const isSubsequence = (needle: string, haystack: string): boolean => {
-  const needleLen = needle.length;
-  const haystackLen = haystack.length;
-  if (needleLen === 0) return true;
-
-  let needleIdx = 0;
-  let haystackIdx = 0;
-  while (haystackIdx < haystackLen) {
-    if (haystack[haystackIdx] === needle[needleIdx]) needleIdx += 1;
-    if (needleIdx >= needleLen) return true;
-    haystackIdx += 1;
-  }
-  return false;
-};
+import caretClosedIcon from './caret-closed';
+import caretOpenIcon from './caret-open';
+import clearIcon from './clear';
 
 /**
  * Map from filter preset keys to their associated filtering function.
@@ -151,7 +125,8 @@ export class IAComboBox extends LitElement {
   caseSensitive = false;
 
   /**
-   * Whether the filtered options should be listed in lexicographically-sorted order.
+   * Whether the filtered options should be listed in lexicographically-sorted order,
+   * respecting the current `caseSensitive` setting.
    * Default is `false`, displaying them in the same order as the provided options array.
    */
   @property({ type: Boolean, reflect: true }) sort = false;
@@ -179,6 +154,12 @@ export class IAComboBox extends LitElement {
   @property({ type: Boolean, reflect: true, attribute: 'stay-open' })
   stayOpen = false;
 
+  /**
+   * Whether the combo box shows a clear button when a value is selected.
+   * Default is `false`.
+   */
+  @property({ type: Boolean, reflect: true }) clearable = false;
+
   /**
    * Whether the combo box's option menu is currently expanded. Default is `false`.
    */
@@ -233,8 +214,6 @@ export class IAComboBox extends LitElement {
 
   @query('#text-input') private textInput!: HTMLInputElement;
 
-  @query('#caret-button') private caretButton!: HTMLInputElement;
-
   @query('#options-list') private optionsList!: HTMLUListElement;
 
   static formAssociated = true;
@@ -279,19 +258,18 @@ export class IAComboBox extends LitElement {
   }
 
   render(): TemplateResult | typeof nothing {
+    const mainWidgetClasses = classMap({
+      disabled: this.disabled,
+      focused: this.hasFocus,
+    });
+
     return html`
-      <div
-        id="container"
-        class=${classMap({ focused: this.hasFocus })}
-        part="container"
-      >
+      <div id="container" part="container">
         ${this.labelTemplate}
-        <div
-          id="main-widget-row"
-          class=${classMap({ disabled: this.disabled })}
-          part="combo-box"
-        >
-          ${this.textInputTemplate} ${this.caretButtonTemplate}
+        <div id="main-widget-row" class=${mainWidgetClasses} part="combo-box">
+          ${this.textInputTemplate}
+          ${this.clearable ? this.clearButtonTemplate : nothing}
+          ${this.caretButtonTemplate}
         </div>
         ${this.optionsListTemplate}
       </div>
@@ -369,10 +347,14 @@ export class IAComboBox extends LitElement {
   /**
    * Template for the main label for the combo box.
    *
-   * Uses the contents of the default (unnamed) slot as the label text.
+   * Uses the contents of the `label` named slot as the label text.
    */
   private get labelTemplate(): TemplateResult {
-    return html`<label id="label" for="text-input"><slot></slot></label>`;
+    return html`
+      <label id="label" for="text-input">
+        <slot name="label"></slot>
+      </label>
+    `;
   }
 
   /**
@@ -381,7 +363,7 @@ export class IAComboBox extends LitElement {
    */
   private get textInputTemplate(): TemplateResult {
     const textInputClasses = classMap({
-      editable: this.behavior !== 'select-only',
+      'clear-padding': this.clearable && !this.shouldShowClearButton,
     });
 
     return html`
@@ -398,6 +380,7 @@ export class IAComboBox extends LitElement {
         aria-controls="options-list"
         aria-expanded=${this.open}
         aria-activedescendant=${ifDefined(this.highlightedOption?.id)}
+        ?readonly=${this.behavior === 'select-only'}
         ?disabled=${this.disabled}
         ?required=${this.required}
         @click=${this.handleComboBoxClick}
@@ -409,14 +392,40 @@ export class IAComboBox extends LitElement {
     `;
   }
 
+  /**
+   * Template for the clear button that is shown when the `clearable` property
+   * is true.
+   */
+  private get clearButtonTemplate(): TemplateResult {
+    return html`
+      <button
+        type="button"
+        id="clear-button"
+        part="clear-button"
+        tabindex="-1"
+        ?hidden=${!this.shouldShowClearButton}
+        @click=${this.handleClearButtonClick}
+      >
+        <span class="sr-only">${msg('Clear')}</span>
+        <slot name="clear-button">
+          ${clearIcon}
+        </slot>
+      </button>
+    `;
+  }
+
   /**
    * Template for the caret open/closed icons to show beside the text input.
    * The icons are wrapped in named slots to allow consumers to override them.
    */
   private get caretTemplate(): TemplateResult {
     return html`
-      <slot name="caret-closed" ?hidden=${this.open}> ${caretClosed} </slot>
-      <slot name="caret-open" ?hidden=${!this.open}> ${caretOpen} </slot>
+      <slot name="caret-closed" ?hidden=${this.open}>
+        ${caretClosedIcon}
+      </slot>
+      <slot name="caret-open" ?hidden=${!this.open}>
+        ${caretOpenIcon}
+      </slot>
     `;
   }
 
@@ -438,6 +447,7 @@ export class IAComboBox extends LitElement {
         @focus=${this.handleFocus}
         @blur=${this.handleBlur}
       >
+        <span class="sr-only">${msg('Toggle options')}</span>
         ${this.caretTemplate}
       </button>
     `;
@@ -452,6 +462,7 @@ export class IAComboBox extends LitElement {
         id="options-list"
         part="options-list"
         role="listbox"
+        tabindex="-1"
         popover
         ?hidden=${!this.open}
         @focus=${this.handleFocus}
@@ -485,6 +496,7 @@ export class IAComboBox extends LitElement {
           id=${opt.id}
           class=${optionClasses}
           part="option"
+          role="option"
           tabindex="-1"
           @pointerenter=${this.handleOptionPointerEnter}
           @pointermove=${this.handleOptionPointerMove}
@@ -525,7 +537,7 @@ export class IAComboBox extends LitElement {
    * Handler for when the pointer device is moved within an option in the dropdown.
    */
   private handleOptionPointerMove(e: PointerEvent): void {
-    const target = e.target as HTMLLIElement;
+    const target = e.currentTarget as HTMLLIElement;
     const option = this.getOptionFor(target.id);
     if (option) this.setHighlightedOption(option);
   }
@@ -534,7 +546,7 @@ export class IAComboBox extends LitElement {
    * Handler for when the user clicks on an option in the dropdown.
    */
   private handleOptionClick(e: PointerEvent): void {
-    const target = e.target as HTMLLIElement;
+    const target = e.currentTarget as HTMLLIElement;
     const option = this.getOptionFor(target.id);
     if (option) {
       this.setSelectedOption(option.id);
@@ -568,10 +580,15 @@ export class IAComboBox extends LitElement {
         }
         break;
       case 'Tab':
-        this.textInput.focus();
-        return;
+        this.handleTabPressed();
+        return; // Never cancel the default behavior for Tab
+      case ' ':
+        this.handleSpacePressed();
+        // In the specific case of picking an option in select-only, we skip the defaults
+        if (this.behavior === 'select-only' && this.highlightedOption) break;
+        return; // Otherwise, don't cancel the default behavior
       default:
-        // Do nothing and allow propagation otherwise
+        // Do nothing and allow propagation for all other keys
         return;
     }
 
@@ -659,6 +676,26 @@ export class IAComboBox extends LitElement {
     this.openOptionsMenu();
   }
 
+  /**
+   * Handler for when the Tab key is pressed
+   */
+  private handleTabPressed(): void {
+    if (this.highlightedOption) {
+      this.setSelectedOption(this.highlightedOption.id);
+      if (!this.stayOpen) this.open = false;
+    }
+  }
+
+  /**
+   * Handler for when the Space key is pressed
+   */
+  private handleSpacePressed(): void {
+    if (this.behavior === 'select-only' && this.highlightedOption) {
+      this.setSelectedOption(this.highlightedOption.id);
+      if (!this.stayOpen) this.open = false;
+    }
+  }
+
   /**
    * Handler for clicks on the combo box input field or caret button.
    */
@@ -666,13 +703,21 @@ export class IAComboBox extends LitElement {
     this.toggleOptionsMenu();
   }
 
+  /**
+   * Handler for when the clear button is clicked.
+   */
+  private handleClearButtonClick(): void {
+    this.clearSelectedOption();
+    this.textInput.focus();
+    this.openOptionsMenu();
+  }
+
   /**
    * Handler for when any part of the combo box receives focus.
    */
   private handleFocus(): void {
-    if (this.behavior === 'select-only') {
-      this.caretButton.focus();
-    } else {
+    if (this.behavior !== 'select-only') {
+      // Always keep focus on the text input if it's editable
       this.textInput.focus();
     }
     this.hasFocus = true;
@@ -685,11 +730,23 @@ export class IAComboBox extends LitElement {
   private handleBlur(): void {
     this.hasFocus = false;
     this.losingFocus = true;
+
+    // On the next tick, check whether we've actually lost focus to some other element,
+    // or just had a momentary internal focus switch. If it's the former, we should
+    // close the menu and possibly make a selection (depending on desired behavior).
     setTimeout(() => {
       if (this.losingFocus && !this.shadowRoot?.activeElement) {
         this.losingFocus = false;
         this.closeOptionsMenu();
-        if (this.behavior === 'freeform') this.setValue(this.enteredText);
+
+        if (this.behavior === 'list') {
+          this.setTextValue(this.selectedOption?.text ?? '', false);
+        } else if (
+          this.behavior === 'freeform' &&
+          (this.enteredText || this.value)
+        ) {
+          this.setValue(this.enteredText);
+        }
       }
     }, 0);
   }
@@ -798,7 +855,8 @@ export class IAComboBox extends LitElement {
     const prevValue = this.value;
     this.value = option.id;
     this.internals.setFormValue(this.value);
-    this.setTextValue(option.text);
+    this.setTextValue(option.text, false);
+    this.setFilterText('');
     if (this.value !== prevValue) this.emitChangeEvent();
 
     // Invoke the option's select callback if defined
@@ -843,10 +901,20 @@ export class IAComboBox extends LitElement {
   /**
    * Changes the value of the text input box, and updates the filter accordingly.
    */
-  private setTextValue(value: string): void {
+  private setTextValue(value: string, setFilter = true): void {
     this.textInput.value = value;
     this.enteredText = value;
-    this.setFilterText(value);
+    if (setFilter) this.setFilterText(value);
+  }
+
+  /**
+   * Sets the current filter text based on the provided string. The resulting filter
+   * text might not exactly match the provided value, depending on the current case
+   * sensitivity.
+   */
+  private setFilterText(baseFilterText: string): void {
+    const { caseTransform } = this;
+    this.filterText = caseTransform(baseFilterText);
   }
 
   openOptionsMenu(): void {
@@ -896,6 +964,21 @@ export class IAComboBox extends LitElement {
   // HELPERS
   //
 
+  /**
+   * True iff no selection has been made and no text has been entered.
+   */
+  private get isEmpty(): boolean {
+    return !this.selectedOption && !this.enteredText;
+  }
+
+  /**
+   * We only show the clear button when the `clearable` property is set
+   * and the combo box is neither empty nor disabled.
+   */
+  private get shouldShowClearButton(): boolean {
+    return this.clearable && !this.disabled && !this.isEmpty;
+  }
+
   /**
    * Sets the size and position of the options menu to match the size and position of
    * the combo box widget. Prefers to position below the main widget, but will flip
@@ -910,12 +993,12 @@ export class IAComboBox extends LitElement {
     const usableHeightBelow = innerHeight - mainWidgetRect.bottom;
 
     // We still want to respect any CSS var specified by the consumer
-    const maxHeightVar = 'var(--comboBoxListMaxHeight, 250px)';
+    const maxHeightVar = 'var(--combo-box-list-max-height, 250px)';
 
     const optionsListStyles: Record<string, string> = {
       top: `${mainWidgetRect.bottom + scrollY}px`,
       left: `${mainWidgetRect.left + scrollX}px`,
-      width: `var(--comboBoxListWidth, ${mainWidgetRect.width}px)`,
+      width: `var(--combo-box-list-width, ${mainWidgetRect.width}px)`,
       maxHeight: `min(${usableHeightBelow}px, ${maxHeightVar})`,
     };
 
@@ -942,16 +1025,6 @@ export class IAComboBox extends LitElement {
     return this.caseSensitive ? STRING_IDENTITY_FN : STRING_LOWER_CASE_FN;
   }
 
-  /**
-   * Sets the current filter text based on the provided string. The resulting filter
-   * text might not exactly match the provided value, depending on the current case
-   * sensitivity.
-   */
-  private setFilterText(baseFilterText: string): void {
-    const { caseTransform } = this;
-    this.filterText = caseTransform(baseFilterText);
-  }
-
   /**
    * Returns the combo box option having the given ID, or null if none exists.
    */
@@ -1075,6 +1148,11 @@ export class IAComboBox extends LitElement {
 
   static get styles(): CSSResultGroup {
     return css`
+      #container {
+        display: inline-block;
+        width: var(--combo-box-width, auto);
+      }
+
       #label {
         display: block;
         width: fit-content;
@@ -1086,9 +1164,15 @@ export class IAComboBox extends LitElement {
         flex-wrap: nowrap;
         background: white;
         border: 1px solid black;
+        width: 100%;
       }
 
-      .focused #main-widget-row {
+      #main-widget-row:not(.focused):hover,
+      #main-widget-row:not(.focused):active {
+        background: #fafafa;
+      }
+
+      #main-widget-row.focused {
         outline: black auto 1px;
         outline-offset: 3px;
       }
@@ -1097,27 +1181,47 @@ export class IAComboBox extends LitElement {
         appearance: none;
         background: transparent;
         border: none;
-        padding: var(--comboBoxPadding, 5px);
+        padding: var(--combo-box-padding, 5px);
+        padding-right: 0;
         width: 100%;
         font-size: inherit;
+        color: inherit;
         outline: none;
+        text-overflow: ellipsis;
+      }
+
+      #text-input.clear-padding {
+        padding-right: 30px;
       }
 
-      #text-input:not(.editable) {
+      #text-input:read-only {
         cursor: pointer;
       }
 
+      #clear-button,
       #caret-button {
         display: inline-flex;
         align-items: center;
         appearance: none;
         background: transparent;
         border: none;
-        padding: var(--comboBoxPadding, 5px);
+        padding: var(--combo-box-padding, 5px) 5px;
         outline: none;
         cursor: pointer;
       }
 
+      #clear-button {
+        flex: 0 0 30px;
+      }
+
+      #clear-button[hidden] {
+        display: none;
+      }
+
+      #caret-button {
+        padding-right: var(--combo-box-padding, 5px);
+      }
+
       #options-list {
         position: absolute;
         list-style-type: none;
@@ -1142,13 +1246,23 @@ export class IAComboBox extends LitElement {
         text-align: center;
       }
 
-      .caret {
+      #caret-button svg {
         width: 14px;
         height: 14px;
       }
 
+      #clear-button svg {
+        width: var(--combo-box-clear-icon-size, 16px);
+        height: var(--combo-box-clear-icon-size, 16px);
+      }
+
       .option {
-        padding: 5px;
+        padding: 7px 5px;
+        width: 100%;
+        box-sizing: border-box;
+        line-height: 1.1;
+        text-overflow: ellipsis;
+        overflow: hidden;
         cursor: pointer;
       }
 

package/src/combo-box/models.ts

@@ -81,3 +81,33 @@ export type IAComboBoxFilterOption =
 export function hasAnyOf<T>(map: Map<T, unknown>, keys: T[]): boolean {
   return keys.some((prop) => map.has(prop));
 }
+
+/**
+ * Tests whether the given `haystack` string has the given `needle` as a subsequence.
+ * Returns `true` if the characters of `needle` appear in order within `haystack`,
+ * regardless of whether they are contiguous. Returns `false` otherwise.
+ *
+ * E.g., `ace` is a subsequence of `archive` (but not a contiguous substring).
+ *
+ * Note: The empty string is a subsequence of any string, including itself.
+ *
+ * @param needle The potential subsequence to check for inside `haystack`.
+ * @param haystack The string to be tested for containing the `needle` subsequence.
+ * @returns Whether `haystack` has `needle` as a subsequence.
+ */
+export function isSubsequence(needle: string, haystack: string): boolean {
+  const needleChars = [...needle]; // Split out the full code points
+  const haystackChars = [...haystack];
+  const needleLen = needleChars.length;
+  const haystackLen = haystackChars.length;
+  if (needleLen === 0) return true;
+
+  let needleIdx = 0;
+  let haystackIdx = 0;
+  while (haystackIdx < haystackLen) {
+    if (haystackChars[haystackIdx] === needleChars[needleIdx]) needleIdx += 1;
+    if (needleIdx >= needleLen) return true;
+    haystackIdx += 1;
+  }
+  return false;
+}