@spectrum-web-components/menu 1.3.0-testing.0 → 1.3.1-beta.0

package/README.md

@@ -1,6 +1,6 @@
-## Description
+## Overview
 
-An `<sp-menu>` is used for creating a menu list. The various elements inside a menu are given as `<sp-menu-group>`, `<sp-menu-item>`, or `<sp-menu-divider>`. Often a `<sp-menu>` element will appear in a `<sp-popover>` element so that it displays as a togglig menu.
+An `<sp-menu>` is used for creating a menu list. The various elements inside a menu are given as [`<sp-menu-group>`](../menu-group), [`<sp-menu-item>`](../menu-item), or `<sp-menu-divider>`. Often a `<sp-menu>` element will appear in a [`<sp-popover>`](../popover) element so that it displays as a toggling menu.
 
 ### Usage
 
@@ -32,11 +32,11 @@ import {
 } from '@spectrum-web-components/menu';
 ```
 
-## Example
+### Anatomy
 
 <!-- prettier-ignore -->
 ```html
-<sp-menu>
+<sp-menu label="Selection type">
     <sp-menu-item>
         Deselect
     </sp-menu-item>
@@ -58,10 +58,12 @@ import {
 </sp-menu>
 ```
 
+#### Popover menus
+
 Often an `<sp-menu>` element will be delivered inside of an `<sp-popover>` element when displaying it above other content.
 
 ```html
-<sp-popover open style="position: relative">
+<sp-popover open style="position: relative" label="Selection type">
     <sp-menu>
         <sp-menu-item value="item-1">Deselect</sp-menu-item>
         <sp-menu-item value="item-2">Select inverse</sp-menu-item>
@@ -73,15 +75,175 @@ Often an `<sp-menu>` element will be delivered inside of an `<sp-popover>` eleme
 </sp-popover>
 ```
 
-## Managing a selection
+#### Labels
+
+To render accessibly, an `<sp-menu>` element or its parent `<sp-popover>` must have a label. For an accessible label that is visibly hidden, but can still be read by assistive technology, use the `label` attribute.
+
+<sp-tabs selected="sp-field-label" auto label="Label options">
+<sp-tab value="sp-field-label">Menu with label</sp-tab>
+<sp-tab-panel value="sp-field-label">
+
+```html demo
+<sp-menu id="menu-label-attribute" label="Selection type">
+    <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-menu>
+```
+
+</sp-tab-panel>
+<sp-tab value="label-attribute">Popover with label</sp-tab>
+<sp-tab-panel value="label-attribute">
+
+```html demo
+<sp-popover open style="position: relative" label="Selection type:">
+    <sp-menu id="popover-label-attribute">
+        <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-menu>
+</sp-popover>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+### Options
+
+#### Sizes
+
+<sp-tabs selected="m" auto label="Size attribute options">
+<sp-tab value="s">Small</sp-tab>
+<sp-tab-panel value="s">
+
+```html demo
+<sp-menu id="menu-s" size="s" label="Selection type">
+    <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-menu>
+<sp-popover open style="position: relative" label="Selection type:">
+    <sp-menu id="menu-s-popover" size="s">
+        <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-menu>
+</sp-popover>
+```
+
+</sp-tab-panel>
+<sp-tab value="m">Medium</sp-tab>
+<sp-tab-panel value="m">
+
+```html demo
+<sp-menu id="menu-m" size="m" label="Selection type">
+    <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-menu>
+<sp-popover open style="position: relative" label="Selection type:">
+    <sp-menu id="menu-m-popover" size="m">
+        <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-menu>
+</sp-popover>
+```
+
+</sp-tab-panel>
+<sp-tab value="l">Large</sp-tab>
+<sp-tab-panel value="l">
+
+```html demo
+<sp-menu id="menu-l" size="l" label="Selection type">
+    <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-menu>
+<sp-popover open style="position: relative" label="Selection type:">
+    <sp-menu id="menu-l-popover" size="l">
+        <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-menu>
+</sp-popover>
+```
+
+</sp-tab-panel>
+<sp-tab value="xl">Extra Large</sp-tab>
+<sp-tab-panel value="xl">
+
+```html demo
+<sp-menu id="menu-xl" size="xl" label="Selection type">
+    <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-menu>
+<sp-popover open style="position: relative" label="Selection type:">
+    <sp-menu id="menu-xl-popover" size="xl">
+        <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-menu>
+</sp-popover>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Selection
 
 The `<sp-menu>` element can be instructed to maintain a selection via the `selects` attribute. Depending on the chosen algorithm, the `<sp-menu>` element will hold a `value` property and manage the `selected` state of its `<sp-menu-item>` descendants.
 
-### selects="single"
+-   When `selects="single"`, the `<sp-menu>` element will maintain one selected item after an initial selection is made.
+-   When `selects` is set to `multiple`, the `<sp-menu>` element will maintain zero or more selected items.
+-   When `selects` is set to `inherit`, the `<sp-menu>` element will allow its `<sp-menu-item>` children to participate in the selection of its nearest `<sp-menu>` ancestor.
 
-When `selects` is set to `single`, the `<sp-menu>` element will maintain one selected item after an initial selection is made.
+<sp-tabs selected="selects-single" auto label="Selects attribute">
+<sp-tab value="selects-single">Single</sp-tab>
+<sp-tab-panel value="selects-single">
 
-```html
+```html demo
 <p>
     The value of the `&lt;sp-menu&gt;` element is:
     <span id="single-value"></span>
@@ -92,7 +254,7 @@ When `selects` is set to `single`, the `<sp-menu>` element will maintain one sel
     onchange="this.previousElementSibling.querySelector('#single-value').textContent=this.value"
 >
     <sp-menu-item value="item-1">Square</sp-menu-item>
-    <sp-menu-item value="item-2">Triangle</sp-menu-item>
+    <sp-menu-item value="item-2" selected>Triangle</sp-menu-item>
     <sp-menu-item value="item-3">Parallelogram</sp-menu-item>
     <sp-menu-item value="item-4">Star</sp-menu-item>
     <sp-menu-item value="item-5">Hexagon</sp-menu-item>
@@ -100,11 +262,11 @@ When `selects` is set to `single`, the `<sp-menu>` element will maintain one sel
 </sp-menu>
 ```
 
-### selects="multiple"
-
-When `selects` is set to `multiple`, the `<sp-menu>` element will maintain zero or more selected items.
+</sp-tab-panel>
+<sp-tab value="selects-multiple">Multiple</sp-tab>
+<sp-tab-panel value="selects-multiple">
 
-```html
+```html demo
 <p>
     The value of the `&lt;sp-menu&gt;` element is:
     <span id="multiple-value">item-3,item-4</span>
@@ -123,11 +285,11 @@ When `selects` is set to `multiple`, the `<sp-menu>` element will maintain zero
 </sp-menu>
 ```
 
-### selects="inherit"
-
-When `selects` is set to `inherit`, the `<sp-menu>` element will allow its `<sp-menu-item>` children to participate in the selection of its nearest `<sp-menu>` ancestor.
+</sp-tab-panel>
+<sp-tab value="selects-inherit">Inherit</sp-tab>
+<sp-tab-panel value="selects-inherit">
 
-```html
+```html demo
 <p>
     The value of the `&lt;sp-menu&gt;` element is:
     <span id="inherit-value">item-3 || item-4 || item-8 || item-11</span>
@@ -157,8 +319,21 @@ When `selects` is set to `inherit`, the `<sp-menu>` element will allow its `<sp-
 </sp-menu>
 ```
 
-## "change" event
+</sp-tab-panel>
+</sp-tabs>
 
-Whether `<sp-menu>` carries a selection or not, when one of the `<sp-menu-item>` children that it manages is activated the `<sp-menu>` element will dispatch a `change` event. At dispatch time, even when a selection is not held due to the absence of the `selects` attribute, the `value` of the `<sp-menu>` will correspond to the `<sp-menu-item>` that was activated. When the `selects` attribute is present, this `value` will be persisted beyond the lifecycle of the `change` event. When `selects="multiple"` the values of multiple items will be comma separated unless otherwise set via the `value-separator` attribute.
+### Behaviors
+
+#### "change" event
+
+Regardless of whether or not `<sp-menu>` carries a selection, when one of the `<sp-menu-item>` children that it manages is activated, the `<sp-menu>` element will dispatch a `change` event. At dispatch time, even when a selection is not held due to the absence of the `selects` attribute, the `value` of the `<sp-menu>` will correspond to the `<sp-menu-item>` that was activated. When the `selects` attribute is present, this `value` will persist beyond the lifecycle of the `change` event. When `selects="multiple"`, the values of multiple items will be comma separated, unless otherwise set via the `value-separator` attribute.
 
 Note: The `change` event is only dispatched on a left mouse click or Enter/Space keypress. Right/Middle mouse clicks will not dispatch the `change` event.
+
+### Accessibility
+
+Review the accessibility guidelines for the [menu-item](../menu-item#accessibility-guidelines) and [menu-group](../menu-group#accessibility-guidelines) descendants.
+
+#### Include a label
+
+A menu is required to have an accessible label.

package/custom-elements.json

@@ -421,6 +421,24 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "method",
+              "name": "handleMouseover",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "MouseEvent"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "handleFocusout",
@@ -1442,6 +1460,28 @@
                 "module": "src/Menu.js"
               }
             },
+            {
+              "kind": "method",
+              "name": "handleMouseover",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "MouseEvent"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "Menu",
+                "module": "src/Menu.js"
+              }
+            },
             {
               "kind": "method",
               "name": "handleFocusout",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spectrum-web-components/menu",
-    "version": "1.3.0-testing.0",
+    "version": "1.3.1-beta.0",
     "publishConfig": {
         "access": "public"
     },
@@ -90,18 +90,18 @@
     ],
     "dependencies": {
         "@lit-labs/observers": "^2.0.2",
-        "@spectrum-web-components/action-button": "^1.3.0-testing.0",
-        "@spectrum-web-components/base": "^1.3.0-testing.0",
-        "@spectrum-web-components/divider": "^1.3.0-testing.0",
-        "@spectrum-web-components/icon": "^1.3.0-testing.0",
-        "@spectrum-web-components/icons-ui": "^1.3.0-testing.0",
-        "@spectrum-web-components/overlay": "^1.3.0-testing.0",
-        "@spectrum-web-components/popover": "^1.3.0-testing.0",
-        "@spectrum-web-components/reactive-controllers": "^1.3.0-testing.0",
-        "@spectrum-web-components/shared": "^1.3.0-testing.0"
+        "@spectrum-web-components/action-button": "1.3.1-beta.0",
+        "@spectrum-web-components/base": "1.3.1-beta.0",
+        "@spectrum-web-components/divider": "1.3.1-beta.0",
+        "@spectrum-web-components/icon": "1.3.1-beta.0",
+        "@spectrum-web-components/icons-ui": "1.3.1-beta.0",
+        "@spectrum-web-components/overlay": "1.3.1-beta.0",
+        "@spectrum-web-components/popover": "1.3.1-beta.0",
+        "@spectrum-web-components/reactive-controllers": "1.3.1-beta.0",
+        "@spectrum-web-components/shared": "1.3.1-beta.0"
     },
     "devDependencies": {
-        "@spectrum-css/menu": "8.0.0-s2-foundations.17"
+        "@spectrum-css/menu": "9.1.1"
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",

package/src/Menu.d.ts

@@ -121,6 +121,7 @@ export declare class Menu extends Menu_base {
     focusOnFirstSelectedItem({ preventScroll, }?: FocusOptions): void;
     focus({ preventScroll }?: FocusOptions): void;
     private pointerUpTarget;
+    private handleMouseover;
     private handleFocusout;
     private handleClick;
     private handlePointerup;

package/src/Menu.dev.js

@@ -98,6 +98,7 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
       }
     );
     this.addEventListener("click", this.handleClick);
+    this.addEventListener("mouseover", this.handleMouseover);
     this.addEventListener("focusout", this.handleFocusout);
     this.addEventListener("sp-menu-item-keydown", this.handleKeydown);
     this.addEventListener("pointerup", this.handlePointerup);
@@ -305,6 +306,14 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
       this.rovingTabindexController.focus({ preventScroll });
     }
   }
+  handleMouseover(event) {
+    var _a;
+    const { target } = event;
+    const menuItem = target;
+    if (this.childItems.includes(menuItem) && this.isFocusableElement(menuItem)) {
+      (_a = this.rovingTabindexController) == null ? void 0 : _a.focusOnItem(menuItem);
+    }
+  }
   handleFocusout() {
     var _a;
     if (!this.matches(":focus-within"))