feat(combobox): add pending state

.circleci/config.yml

@@ -10,7 +10,7 @@ executors:
 parameters:
     current_golden_images_hash:
         type: string
-        default: c5a1a42567a3c179a5e89f57c99e12c1058d682a
+        default: 3630c6386d7406d2884c1fd0bf2b9093832a6e67
     wireit_cache_name:
         type: string
         default: wireit

packages/combobox/README.md

@@ -174,6 +174,28 @@ The popup menu items are filtered to only those completing the currently-input v
 </sp-combobox>
 ```
 
+### Quiet
+
+```html
+<sp-field-label for="color">Color</sp-field-label>
+<sp-combobox id="color" quiet>
+    <sp-menu-item value="red">Red</sp-menu-item>
+    <sp-menu-item value="green">Green</sp-menu-item>
+    <sp-menu-item value="blue">Blue</sp-menu-item>
+</sp-combobox>
+```
+
+### Pending
+
+```html
+<sp-field-label for="color">Color</sp-field-label>
+<sp-combobox id="color" pending>
+    <sp-menu-item value="red">Red</sp-menu-item>
+    <sp-menu-item value="green">Green</sp-menu-item>
+    <sp-menu-item value="blue">Blue</sp-menu-item>
+</sp-combobox>
+```
+
 ## Focus and Accessibility
 
 The combobox supports both mouse and keyboard navigation.

packages/combobox/package.json

@@ -65,6 +65,7 @@
         "@spectrum-web-components/overlay": "^0.42.4",
         "@spectrum-web-components/picker-button": "^0.42.4",
         "@spectrum-web-components/popover": "^0.42.4",
+        "@spectrum-web-components/progress-circle": "^0.42.4",
         "@spectrum-web-components/textfield": "^0.42.4"
     },
     "devDependencies": {

packages/combobox/src/Combobox.ts

@@ -13,6 +13,7 @@ governing permissions and limitations under the License.
 import {
     CSSResultArray,
     html,
+    nothing,
     PropertyValues,
     type SpectrumElement,
     TemplateResult,
@@ -26,6 +27,7 @@ import {
     ifDefined,
     live,
     repeat,
+    when,
 } from '@spectrum-web-components/base/src/directives.js';
 import '@spectrum-web-components/overlay/sp-overlay.js';
 import '@spectrum-web-components/icons-ui/icons/sp-icon-chevron100.js';
@@ -73,6 +75,14 @@ export class Combobox extends Textfield {
     @property({ type: Boolean, reflect: true })
     public open = false;
 
+    /** Whether the items are currently loading. */
+    @property({ type: Boolean, reflect: true })
+    public pending = false;
+
+    /** Defines a string value that labels the Combobox while it is in pending state. */
+    @property({ type: String, attribute: 'pending-label' })
+    public pendingLabel = 'Pending';
+
     @query('slot:not([name])')
     private optionSlot!: HTMLSlotElement;
 
@@ -120,7 +130,7 @@ export class Combobox extends Textfield {
     }
 
     public handleComboboxKeydown(event: KeyboardEvent): void {
-        if (this.readonly) {
+        if (this.readonly || this.pending) {
             return;
         }
         if (event.altKey && event.code === 'ArrowDown') {
@@ -223,7 +233,7 @@ export class Combobox extends Textfield {
     }
 
     public filterAvailableOptions(): void {
-        if (this.autocomplete === 'none') {
+        if (this.autocomplete === 'none' || this.pending) {
             return;
         }
         const valueLowerCase = this.value.toLowerCase();
@@ -237,8 +247,10 @@ export class Combobox extends Textfield {
 
     public override handleInput(event: Event): void {
         super.handleInput(event);
-        this.activeDescendant = undefined;
-        this.open = true;
+        if (!this.pending) {
+            this.activeDescendant = undefined;
+            this.open = true;
+        }
     }
 
     protected handleMenuChange(event: PointerEvent & { target: Menu }): void {
@@ -264,7 +276,7 @@ export class Combobox extends Textfield {
     }
 
     public toggleOpen(): void {
-        if (this.readonly) {
+        if (this.readonly || this.pending) {
             this.open = false;
             return;
         }
@@ -311,6 +323,17 @@ export class Combobox extends Textfield {
         const appliedLabel = this.label || this.appliedLabel;
 
         return html`
+            ${this.pending
+                ? html`
+                      <span
+                          aria-hidden="true"
+                          class="visually-hidden"
+                          id="pending-label"
+                      >
+                          ${this.pendingLabel}
+                      </span>
+                  `
+                : nothing}
             ${this.value
                 ? html`
                       <span
@@ -332,6 +355,20 @@ export class Combobox extends Textfield {
         `;
     }
 
+    protected renderLoader(): TemplateResult {
+        import(
+            '@spectrum-web-components/progress-circle/sp-progress-circle.js'
+        );
+        return html`
+            <sp-progress-circle
+                size="s"
+                indeterminate
+                aria-hidden="true"
+                class="progress-circle"
+            ></sp-progress-circle>
+        `;
+    }
+
     protected override renderField(): TemplateResult {
         return html`
             ${this.renderStateIcons()}
@@ -350,7 +387,7 @@ export class Combobox extends Textfield {
                 aria-describedby="${this.helpTextId} tooltip"
                 aria-expanded="${this.open ? 'true' : 'false'}"
                 aria-label=${ifDefined(this.label || this.appliedLabel)}
-                aria-labelledby="applied-label label"
+                aria-labelledby="pending-label applied-label label"
                 aria-invalid=${ifDefined(this.invalid || undefined)}
                 autocomplete="off"
                 @click=${this.toggleOpen}
@@ -378,6 +415,7 @@ export class Combobox extends Textfield {
                 ?required=${this.required}
                 ?readonly=${this.readonly}
             />
+            ${when(this.pending, () => this.renderLoader())}
         `;
     }
 
@@ -402,6 +440,7 @@ export class Combobox extends Textfield {
                     : ''}"
                 ?disabled=${this.disabled}
                 ?focused=${this.focused}
+                ?quiet=${this.quiet}
                 size=${this.size}
             ></sp-picker-button>
             <sp-overlay
@@ -509,12 +548,15 @@ export class Combobox extends Textfield {
             this & { optionEls: MenuItem[]; activeDescendant: MenuItem }
         >
     ): void {
-        if (changed.has('open')) {
+        if (changed.has('open') && !this.pending) {
             this.manageListOverlay();
         }
         if (!this.focused && this.open) {
             this.open = false;
         }
+        if (changed.has('pending') && this.pending) {
+            this.open = false;
+        }
         if (changed.has('activeDescendant')) {
             const previouslyActiveDescendant = changed.get(
                 'activeDescendant'

packages/combobox/src/spectrum-combobox.css

@@ -393,7 +393,7 @@ governing permissions and limitations under the License.
     );
 }
 
-.spectrum-Combobox-progress-circle {
+.progress-circle {
     position: absolute;
     inset-block-start: var(
         --mod-combobox-block-spacing-edge-to-progress-circle,
@@ -415,8 +415,8 @@ governing permissions and limitations under the License.
     );
 }
 
-.spectrum-Combobox-progress-circle:dir(rtl),
-:host([dir='rtl']) .spectrum-Combobox-progress-circle {
+.progress-circle:dir(rtl),
+:host([dir='rtl']) .progress-circle {
     inset-inline-start: calc(
         var(
                 --mod-combobox-spacing-inline-icon-to-button,
@@ -708,7 +708,7 @@ governing permissions and limitations under the License.
 }
 
 :host([invalid]) #textfield #input,
-#textfield.is-loading #input {
+:host([pending]) #textfield #input {
     padding-inline-end: calc(
         var(--mod-combobox-button-width, var(--spectrum-combobox-button-width)) +
             var(
@@ -760,9 +760,9 @@ governing permissions and limitations under the License.
     );
 }
 
-:host([disabled]) .spectrum-Textfield .icon,
-.spectrum-Textfield.is-loading .icon,
-.spectrum-Textfield.is-readOnly .icon {
+:host([disabled]) #textfield .icon,
+:host([pending]) #textfield .icon,
+#textfield.is-readOnly .icon {
     display: none;
 }
 
@@ -814,7 +814,7 @@ governing permissions and limitations under the License.
 }
 
 :host([quiet][invalid]) #textfield #input,
-:host([quiet]) #textfield.is-loading #input {
+:host([quiet][pending]) #textfield #input {
     padding-inline-end: calc(
         var(--mod-combobox-button-width, var(--spectrum-combobox-button-width)) +
             var(

packages/combobox/src/spectrum-config.js

@@ -40,9 +40,11 @@ const config = {
                     'size'
                 ),
                 converter.classToAttribute('spectrum-Combobox--quiet'),
+                converter.classToClass('spectrum-Combobox-progress-circle'),
                 converter.classToClass('spectrum-Combobox-button'),
                 converter.classToAttribute('is-focused', 'focused'),
                 converter.classToAttribute('is-invalid', 'invalid'),
+                converter.classToAttribute('is-loading', 'pending'),
                 converter.classToAttribute(
                     'is-keyboardFocused',
                     'keyboard-focused'
@@ -102,6 +104,7 @@ const config = {
                 },
                 converter.classToId('spectrum-Combobox-input'),
                 converter.classToId('spectrum-Combobox-textfield'),
+                converter.classToId('spectrum-Textfield', 'textfield'),
                 converter.classToClass(
                     'spectrum-Textfield-validationIcon',
                     'icon'

packages/combobox/stories/args.ts

@@ -0,0 +1,88 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+export const argTypes = {
+    size: {
+        name: 'size',
+        type: { name: 'string', required: false },
+        table: {
+            defaultValue: { summary: 'm' },
+        },
+        control: {
+            labels: {
+                s: 'Small',
+                m: 'Medium',
+                l: 'Large',
+                xl: 'Extra large',
+            },
+            type: 'select',
+        },
+        options: ['s', 'm', 'l', 'xl'],
+    },
+    quiet: {
+        name: 'quiet',
+        type: { name: 'boolean', required: false },
+        table: {
+            type: { summary: 'boolean' },
+            defaultValue: { summary: false },
+        },
+        control: {
+            type: 'boolean',
+        },
+    },
+    disabled: {
+        name: 'disabled',
+        type: { name: 'boolean', required: false },
+        description:
+            'Disable this control. It will not receive focus or events.',
+        table: {
+            type: { summary: 'boolean' },
+            defaultValue: { summary: false },
+        },
+        control: {
+            type: 'boolean',
+        },
+    },
+    invalid: {
+        name: 'invalid',
+        type: { name: 'boolean', required: false },
+        table: {
+            type: { summary: 'boolean' },
+            defaultValue: { summary: false },
+        },
+        control: {
+            type: 'boolean',
+        },
+    },
+    pending: {
+        name: 'pending',
+        type: { name: 'boolean', required: false },
+        table: {
+            type: { summary: 'boolean' },
+            defaultValue: { summary: false },
+        },
+        control: {
+            type: 'boolean',
+        },
+    },
+    readonly: {
+        name: 'readonly',
+        type: { name: 'boolean', required: false },
+        table: {
+            type: { summary: 'boolean' },
+            defaultValue: { summary: false },
+        },
+        control: {
+            type: 'boolean',
+        },
+    },
+};