From 54d636f0206e8fa7dd67a465de643e6dd9fc29cf Mon Sep 17 00:00:00 2001
From: Westbrook <westbrook.johnson@gmail.com>
Date: Thu, 29 Jul 2021 17:14:46 -0400
Subject: [PATCH] feat(action-menu): remove menu selection by default

Use the `selects` attribute set to `single` for previous functionality.
---
 packages/action-menu/README.md         | 25 ++++++++++++++++++++++++-
 packages/action-menu/src/ActionMenu.ts |  3 +++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/packages/action-menu/README.md b/packages/action-menu/README.md
index 8c9381a519..df4191f487 100644
--- a/packages/action-menu/README.md
+++ b/packages/action-menu/README.md
@@ -1,6 +1,6 @@
 ## Description
 
-An `<sp-action-menu>` is an action button with a Popover. Use an `<sp-menu>` element to outline the items that will be made available to the user when interacting with the `sp-action-menu` element.
+An `<sp-action-menu>` is an action button that triggers an overlay with `<sp-menu-items>` for activation. Use an `<sp-menu>` element to outline the items that will be made available to the user when interacting with the `<sp-action-menu>` element. By default `<sp-action-menu>` does not manage a selection. If you'd like for a selection to be held by the `<sp-menu>` that is presented in its overlay, use `selects="single"` to activate this functionality.
 
 ### Usage
 
@@ -219,6 +219,29 @@ A custom icon can be supplied via the `icon` slot in order to replace the defaul
 </sp-action-menu>
 ```
 
+### Selection.
+
+When `selects` is set to `single`, the `<sp-action-menu>` element will maintain one selected item after an initial selection is made.
+
+```html
+<p>
+    The value of the `&lt;sp-action-menu&gt;` element is:
+    <span id="single-value"></span>
+</p>
+<sp-action-menu
+    selects="single"
+    onchange="this.previousElementSibling.querySelector('#single-value').textContent=this.value"
+>
+    <span slot="label">Available shapes</span>
+    <sp-menu-item value="shape-1-square">Square</sp-menu-item>
+    <sp-menu-item value="shape-2-triangle">Triangle</sp-menu-item>
+    <sp-menu-item value="shape-3-parallelogram">Parallelogram</sp-menu-item>
+    <sp-menu-item value="shape-4-star">Star</sp-menu-item>
+    <sp-menu-item value="shape-5-hexagon">Hexagon</sp-menu-item>
+    <sp-menu-item value="shape-6-circle" disabled>Circle</sp-menu-item>
+</sp-action-menu>
+```
+
 ## Accessibility
 
 An `<sp-action-menu>` parent will ensure that the internal `<sp-menu>` features a role of `listbox` and contains children with the role `option`. Upon focusing the `<sp-action-menu>` using `ArrowDown` will also open the menu while throwing focus into first selected (or unselected when none are selected) menu item to assist in selecting of a new value.
diff --git a/packages/action-menu/src/ActionMenu.ts b/packages/action-menu/src/ActionMenu.ts
index 18aab61be3..a12839ecf8 100644
--- a/packages/action-menu/src/ActionMenu.ts
+++ b/packages/action-menu/src/ActionMenu.ts
@@ -30,6 +30,9 @@ import actionMenuStyles from './action-menu.css.js';
  * @element sp-action-menu
  * @slot icon - The icon to use for action button
  * @slot label - The label to use on for the action button
+ * @attr selects - By default `sp-action-menu` does not manage a selection. If
+ *   you'd like for a selection to be held by the `sp-menu` that it presents in
+ *   its overlay, use `selects="single" to activate this functionality.
  */
 export class ActionMenu extends ObserveSlotText(PickerBase, 'label') {
     public static get styles(): CSSResultArray {