@spectrum-web-components/picker 0.41.1 → 0.42.0

package/README.md

@@ -357,6 +357,44 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
+### Side Label
+
+```html
+<sp-field-label side-aligned="start" for="picker-sideLabel">
+    Standard:
+</sp-field-label>
+<sp-picker
+    label="Select a Country with a very long label, too long in fact"
+    id="picker-sideLabel"
+>
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+<br />
+<br />
+<sp-field-label side-aligned="start" for="picker-sideLabel-quiet">
+    Quiet:
+</sp-field-label>
+<sp-picker
+    label="Select a Country with a very long label, too long in fact"
+    quiet
+    id="picker-sideLabel-quiet"
+>
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
 ### Disabled
 
 ```html
@@ -376,7 +414,7 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 <br />
 <br />
-<sp-field-label for="picker-disabled">Quiet:</sp-field-label>
+<sp-field-label for="picker-disabled-quiet">Quiet:</sp-field-label>
 <sp-picker
     label="Select a Country with a very long label, too long in fact"
     disabled
@@ -393,6 +431,34 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
+### Pending
+
+When in pending state, `<sp-picker>` elements will not respond to click events and will be delivered with a `<sp-progress-circle>` to visually outline that it is pending. It will not toggle open or display its `<sp-menu-item>` descendants until the attribute is removed.
+
+```html
+<sp-field-label for="picker-loading">Standard:</sp-field-label>
+<sp-picker id="picker-loading" label="Loading blending modes..." pending>
+    <sp-menu-item>Pass through</sp-menu-item>
+    <sp-menu-item>Normal</sp-menu-item>
+    <sp-menu-item>Multiply</sp-menu-item>
+    <sp-menu-item>Screen</sp-menu-item>
+</sp-picker>
+<br />
+<br />
+<sp-field-label for="picker-loading-quiet">Quiet:</sp-field-label>
+<sp-picker
+    id="picker-loading-quiet"
+    label="Loading blending modes..."
+    pending
+    quiet
+>
+    <sp-menu-item>Pass through</sp-menu-item>
+    <sp-menu-item>Normal</sp-menu-item>
+    <sp-menu-item>Multiply</sp-menu-item>
+    <sp-menu-item>Screen</sp-menu-item>
+</sp-picker>
+```
+
 ## Accessibility
 
 To render accessibly, an `<sp-picker>` element should be paired with an `<sp-field-label>` element that has a `for` attribute referencing the `id` of the `<sp-picker>` element. For an accessible label that renders within the bounds of the picker itself, but still fulfills the accessibility contract, use the `label` attribute or a `<span slot="label">` as a child element of `<sp-picker>`.

package/custom-elements.json

@@ -113,6 +113,29 @@
               "attribute": "invalid",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "pending",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the items are currently loading.",
+              "attribute": "pending",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "pendingLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "'Pending'",
+              "description": "Defines a string value that labels the Picker while it is in pending state.",
+              "attribute": "pending-label"
+            },
             {
               "kind": "field",
               "name": "label",
@@ -153,6 +176,14 @@
               "privacy": "public",
               "default": "'single'"
             },
+            {
+              "kind": "field",
+              "name": "labelAlignment",
+              "type": {
+                "text": "'inline' | undefined"
+              },
+              "privacy": "public"
+            },
             {
               "kind": "field",
               "name": "menuItems",
@@ -534,6 +565,24 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "handleBeforetoggle",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event & {\n            target: Overlay;\n            newState: 'open' | 'closed';\n        }"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "renderLabelContent",
@@ -834,6 +883,24 @@
               "default": "false",
               "fieldName": "invalid"
             },
+            {
+              "name": "pending",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the items are currently loading.",
+              "fieldName": "pending"
+            },
+            {
+              "name": "pending-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Pending'",
+              "description": "Defines a string value that labels the Picker while it is in pending state.",
+              "fieldName": "pendingLabel"
+            },
             {
               "name": "label",
               "type": {
@@ -1035,6 +1102,37 @@
                 "module": "src/Picker.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "pending",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the items are currently loading.",
+              "attribute": "pending",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "pendingLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "'Pending'",
+              "description": "Defines a string value that labels the Picker while it is in pending state.",
+              "attribute": "pending-label",
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.js"
+              }
+            },
             {
               "kind": "field",
               "name": "label",
@@ -1091,6 +1189,18 @@
                 "module": "src/Picker.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "labelAlignment",
+              "type": {
+                "text": "'inline' | undefined"
+              },
+              "privacy": "public",
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.js"
+              }
+            },
             {
               "kind": "field",
               "name": "menuItems",
@@ -1578,6 +1688,28 @@
                 "module": "src/Picker.js"
               }
             },
+            {
+              "kind": "method",
+              "name": "handleBeforetoggle",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event & {\n            target: Overlay;\n            newState: 'open' | 'closed';\n        }"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.js"
+              }
+            },
             {
               "kind": "method",
               "name": "renderLabelContent",
@@ -2009,6 +2141,32 @@
                 "module": "src/Picker.ts"
               }
             },
+            {
+              "name": "pending",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the items are currently loading.",
+              "fieldName": "pending",
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.ts"
+              }
+            },
+            {
+              "name": "pending-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Pending'",
+              "description": "Defines a string value that labels the Picker while it is in pending state.",
+              "fieldName": "pendingLabel",
+              "inheritedFrom": {
+                "name": "PickerBase",
+                "module": "src/Picker.ts"
+              }
+            },
             {
               "name": "label",
               "type": {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spectrum-web-components/picker",
-    "version": "0.41.1",
+    "version": "0.42.0",
     "publishConfig": {
         "access": "public"
     },
@@ -65,21 +65,23 @@
         "lit-html"
     ],
     "dependencies": {
-        "@spectrum-web-components/base": "^0.41.1",
-        "@spectrum-web-components/button": "^0.41.1",
-        "@spectrum-web-components/icon": "^0.41.1",
-        "@spectrum-web-components/icons-ui": "^0.41.1",
-        "@spectrum-web-components/icons-workflow": "^0.41.1",
-        "@spectrum-web-components/menu": "^0.41.1",
-        "@spectrum-web-components/overlay": "^0.41.1",
-        "@spectrum-web-components/popover": "^0.41.1",
-        "@spectrum-web-components/reactive-controllers": "^0.41.1",
-        "@spectrum-web-components/shared": "^0.41.1",
-        "@spectrum-web-components/tooltip": "^0.41.1",
-        "@spectrum-web-components/tray": "^0.41.1"
+        "@spectrum-web-components/base": "^0.42.0",
+        "@spectrum-web-components/button": "^0.42.0",
+        "@spectrum-web-components/field-label": "^0.42.0",
+        "@spectrum-web-components/icon": "^0.42.0",
+        "@spectrum-web-components/icons-ui": "^0.42.0",
+        "@spectrum-web-components/icons-workflow": "^0.42.0",
+        "@spectrum-web-components/menu": "^0.42.0",
+        "@spectrum-web-components/overlay": "^0.42.0",
+        "@spectrum-web-components/popover": "^0.42.0",
+        "@spectrum-web-components/progress-circle": "^0.42.0",
+        "@spectrum-web-components/reactive-controllers": "^0.42.0",
+        "@spectrum-web-components/shared": "^0.42.0",
+        "@spectrum-web-components/tooltip": "^0.42.0",
+        "@spectrum-web-components/tray": "^0.42.0"
     },
     "devDependencies": {
-        "@spectrum-css/picker": "^7.2.3"
+        "@spectrum-css/picker": "^7.2.6"
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",
@@ -89,5 +91,5 @@
         "./sync/index.js",
         "./sync/sp-*.js"
     ],
-    "gitHead": "1eded35d98d01973b40990486b86840ba464a2da"
+    "gitHead": "9b3bd55ff8e8f9438817255976e77fd456b19d72"
 }

package/src/Picker.d.ts

@@ -8,7 +8,8 @@ import '@spectrum-web-components/menu/sp-menu.js';
 import type { Menu, MenuItem, MenuItemChildren } from '@spectrum-web-components/menu';
 import { Placement } from '@spectrum-web-components/overlay';
 import { MatchMediaController } from '@spectrum-web-components/reactive-controllers/src/MatchMedia.js';
-import type { Overlay } from '@spectrum-web-components/overlay/src/Overlay.js';
+import { Overlay } from '@spectrum-web-components/overlay/src/Overlay.js';
+import type { FieldLabel } from '@spectrum-web-components/field-label';
 export declare const DESCRIPTION_ID = "option-picker";
 declare const PickerBase_base: typeof Focusable & {
     new (...args: any[]): import("@spectrum-web-components/base").SizedElementInterface;
@@ -23,10 +24,15 @@ export declare class PickerBase extends PickerBase_base {
     focused: boolean;
     icons?: 'only' | 'none';
     invalid: boolean;
+    /** Whether the items are currently loading. */
+    pending: boolean;
+    /** Defines a string value that labels the Picker while it is in pending state. */
+    pendingLabel: string;
     label?: string;
     open: boolean;
     readonly: boolean;
     selects: undefined | 'single';
+    labelAlignment?: 'inline';
     protected get menuItems(): MenuItem[];
     protected optionsMenu: Menu;
     protected overlayElement: Overlay;
@@ -67,9 +73,13 @@ export declare class PickerBase extends PickerBase_base {
     protected handleTooltipSlotchange(event: Event & {
         target: HTMLSlotElement;
     }): void;
+    protected handleBeforetoggle(event: Event & {
+        target: Overlay;
+        newState: 'open' | 'closed';
+    }): void;
     protected renderLabelContent(content: Node[]): TemplateResult | Node[];
     protected get buttonContent(): TemplateResult[];
-    applyFocusElementLabel: (value?: string) => void;
+    applyFocusElementLabel: (value: string, labelElement: FieldLabel) => void;
     protected renderOverlay(menu: TemplateResult): TemplateResult;
     protected get renderDescriptionSlot(): TemplateResult;
     protected render(): TemplateResult;

package/src/Picker.dev.js

@@ -18,7 +18,8 @@ import {
 import {
   classMap,
   ifDefined,
-  styleMap
+  styleMap,
+  when
 } from "@spectrum-web-components/base/src/directives.js";
 import {
   property,
@@ -50,6 +51,8 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
     this.disabled = false;
     this.focused = false;
     this.invalid = false;
+    this.pending = false;
+    this.pendingLabel = "Pending";
     this.open = false;
     this.readonly = false;
     this.selects = "single";
@@ -69,8 +72,9 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
       event.preventDefault();
       this.toggle(true);
     };
-    this.applyFocusElementLabel = (value) => {
+    this.applyFocusElementLabel = (value, labelElement) => {
       this.appliedLabel = value;
+      this.labelAlignment = labelElement.sideAligned ? "inline" : void 0;
     };
     this.dependenciesLoaded = false;
     this.dependenciesToLoad = {};
@@ -141,15 +145,21 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
     }
     this.pointerdownState = this.open;
     this.preventNextToggle = "maybe";
+    let cleanupAction = 0;
     const cleanup = () => {
-      document.removeEventListener("pointerup", cleanup);
-      document.removeEventListener("pointercancel", cleanup);
-      requestAnimationFrame(() => {
-        this.preventNextToggle = "no";
+      cancelAnimationFrame(cleanupAction);
+      cleanupAction = requestAnimationFrame(async () => {
+        document.removeEventListener("pointerup", cleanup);
+        document.removeEventListener("pointercancel", cleanup);
+        this.button.removeEventListener("click", cleanup);
+        requestAnimationFrame(() => {
+          this.preventNextToggle = "no";
+        });
       });
     };
     document.addEventListener("pointerup", cleanup);
     document.addEventListener("pointercancel", cleanup);
+    this.button.addEventListener("click", cleanup);
     this.handleActivate();
   }
   handleButtonFocus(event) {
@@ -180,6 +190,7 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
     this.button.focus();
   }
   handleChange(event) {
+    this.preventNextToggle = "no";
     const target = event.target;
     const [selected] = target.selectedItems;
     event.stopPropagation();
@@ -232,7 +243,7 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
     item.selected = value;
   }
   toggle(target) {
-    if (this.readonly) {
+    if (this.readonly || this.pending) {
       return;
     }
     this.open = typeof target !== "undefined" ? target : !this.open;
@@ -264,6 +275,22 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
   handleTooltipSlotchange(event) {
     this.tooltipEl = event.target.assignedElements()[0];
   }
+  handleBeforetoggle(event) {
+    if (event.composedPath()[0] !== event.target) {
+      return;
+    }
+    if (event.newState === "closed") {
+      if (this.preventNextToggle === "no") {
+        this.open = false;
+      } else if (!this.pointerdownState) {
+        this.overlayElement.manuallyKeepOpen();
+      }
+    }
+    if (!this.open) {
+      this.optionsMenu.updateSelectedItemIndex();
+      this.optionsMenu.closeDescendentOverlays();
+    }
+  }
   renderLabelContent(content) {
     if (this.value && this.selectedItem) {
       return content;
@@ -312,11 +339,23 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
                       ` : html`
                           <span hidden id="applied-label">${appliedLabel}</span>
                       `}
-                ${this.invalid ? html`
+                ${this.invalid && !this.pending ? html`
                           <sp-icon-alert
                               class="validation-icon"
                           ></sp-icon-alert>
                       ` : nothing}
+                ${when(this.pending, () => {
+        import("@spectrum-web-components/progress-circle/sp-progress-circle.js");
+        return html`
+                        <sp-progress-circle
+                            id="loader"
+                            size="s"
+                            indeterminate
+                            aria-valuetext=${this.pendingLabel}
+                            class="progress-circle"
+                        ></sp-progress-circle>
+                    `;
+      })}
                 <sp-icon-chevron100
                     class="picker ${chevronClass[this.size]}"
                 ></sp-icon-chevron100>
@@ -342,18 +381,7 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
                 .type=${this.isMobile.matches ? "modal" : "auto"}
                 .receivesFocus=${"true"}
                 .willPreventClose=${this.preventNextToggle !== "no" && this.open && this.dependenciesLoaded}
-                @beforetoggle=${(event) => {
-      if (event.composedPath()[0] !== event.target) {
-        return;
-      }
-      if (event.newState === "closed") {
-        this.open = false;
-      }
-      if (!this.open) {
-        this.optionsMenu.updateSelectedItemIndex();
-        this.optionsMenu.closeDescendentOverlays();
-      }
-    }}
+                @beforetoggle=${this.handleBeforetoggle}
             >
                 ${container}
             </sp-overlay>
@@ -384,9 +412,11 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
                 aria-describedby="tooltip"
                 aria-expanded=${this.open ? "true" : "false"}
                 aria-haspopup="true"
-                aria-labelledby="icon label applied-label"
+                aria-labelledby="loader icon label applied-label"
                 id="button"
-                class="button"
+                class=${ifDefined(
+      this.labelAlignment ? `label-${this.labelAlignment}` : void 0
+    )}
                 @blur=${this.handleButtonBlur}
                 @click=${this.handleActivate}
                 @pointerdown=${this.handleButtonPointerdown}
@@ -411,6 +441,9 @@ export class PickerBase extends SizedMixin(Focusable, { noDefaultSize: true }) {
     if (changes.has("disabled") && this.disabled) {
       this.open = false;
     }
+    if (changes.has("pending") && this.pending) {
+      this.open = false;
+    }
     if (changes.has("value")) {
       this.shouldScheduleManageSelection();
     }
@@ -620,6 +653,12 @@ __decorateClass([
 __decorateClass([
   property({ type: Boolean, reflect: true })
 ], PickerBase.prototype, "invalid", 2);
+__decorateClass([
+  property({ type: Boolean, reflect: true })
+], PickerBase.prototype, "pending", 2);
+__decorateClass([
+  property({ type: String, attribute: "pending-label" })
+], PickerBase.prototype, "pendingLabel", 2);
 __decorateClass([
   property()
 ], PickerBase.prototype, "label", 2);
@@ -629,6 +668,9 @@ __decorateClass([
 __decorateClass([
   property({ type: Boolean, reflect: true })
 ], PickerBase.prototype, "readonly", 2);
+__decorateClass([
+  state()
+], PickerBase.prototype, "labelAlignment", 2);
 __decorateClass([
   query("sp-menu")
 ], PickerBase.prototype, "optionsMenu", 2);
@@ -659,7 +701,7 @@ export class Picker extends PickerBase {
     this.handleKeydown = (event) => {
       const { code } = event;
       this.focused = true;
-      if (!code.startsWith("Arrow") || this.readonly) {
+      if (!code.startsWith("Arrow") || this.readonly || this.pending) {
         return;
       }
       if (code === "ArrowUp" || code === "ArrowDown") {