diff --git a/packages/@react-spectrum/actiongroup/docs/ActionGroup.mdx b/packages/@react-spectrum/actiongroup/docs/ActionGroup.mdx
index 9b02fed44c6..1a9e732708d 100644
--- a/packages/@react-spectrum/actiongroup/docs/ActionGroup.mdx
+++ b/packages/@react-spectrum/actiongroup/docs/ActionGroup.mdx
@@ -22,6 +22,20 @@ import Edit from '@spectrum-icons/workflow/Edit';
import RegionSelect from '@spectrum-icons/workflow/RegionSelect';
import Select from '@spectrum-icons/workflow/Select';
import {Flex} from '@react-spectrum/layout';
+import {View} from '@react-spectrum/view';
+import ViewList from '@spectrum-icons/workflow/ViewList';
+import ViewGrid from '@spectrum-icons/workflow/ViewGrid';
+import ViewCard from '@spectrum-icons/workflow/ViewCard';
+import Move from '@spectrum-icons/workflow/Move';
+import Duplicate from '@spectrum-icons/workflow/Duplicate';
+import TagBold from '@spectrum-icons/workflow/TagBold';
+import TagItalic from '@spectrum-icons/workflow/TagItalic';
+import TagUnderline from '@spectrum-icons/workflow/TagUnderline';
+import TextStrikethrough from '@spectrum-icons/workflow/TextStrikethrough';
+import TextAlignCenter from '@spectrum-icons/workflow/TextAlignCenter';
+import TextAlignJustify from '@spectrum-icons/workflow/TextAlignJustify';
+import TextAlignLeft from '@spectrum-icons/workflow/TextAlignLeft';
+import TextAlignRight from '@spectrum-icons/workflow/TextAlignRight';
```
---
@@ -35,7 +49,10 @@ keywords: [toolbar, actiongroup, collections]
+ componentNames={['ActionGroup', 'Item']}
+ sourceData={[
+ {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/action-group/'}
+ ]} />
## Example
@@ -72,9 +89,58 @@ const items = [
```
+### Icons
+
+Icons can be added to ActionGroup items by wrapping the label in a [Text](Text.html) element, and adding the icon as a sibling.
+
+```tsx example
+import Draw from '@spectrum-icons/workflow/Draw';
+import Copy from '@spectrum-icons/workflow/Copy';
+import Delete from '@spectrum-icons/workflow/Delete';
+import {Text} from '@react-spectrum/text';
+
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+
+```
+
+You can also hide the label text within the buttons using the `buttonLabelBehavior` prop. When set to `"hide"`, the label is
+hidden and automatically shown in a tooltip on hover.
+
+```tsx example
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+
+```
+
### Accessibility
-If no visible label is provided (e.g. an icon only) to each item, an alternative text label must be provided to identify the control for accessibility.
+Icon only ActionGroups should usually include a tooltip to describe the button via the `buttonLabelBehavior` prop as described above. This also automatically handles
+labeling the button for assistive technology users.
+
+In rare cases where no tooltip is desired, an alternative text label must be provided to identify the control for accessibility.
This should be added using the `aria-label` prop to each Item.
```tsx example
@@ -160,6 +226,177 @@ function Example() {
}
```
+## Collapsing behavior
+
+By default, ActionGroup items wrap to form a new line when horizontal space is limited. However, this can cause content to shift below the
+ActionGroup. If the ActionGroup should always appear in a single line, the `overflowMode` prop can be set to `collapse`. In this mode, when
+horizontal space is limited, the ActionGroup will collapse into a menu. The exact behavior depends on the `selectionMode`.
+
+### Non-selectable
+
+When selection is not enabled, ActionGroup displays as many items as possible and collapses the remaining items into a more actions menu.
+
+```tsx example
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+ -
+
+ Move
+
+ -
+
+ Duplicate
+
+
+```
+
+### Selection
+
+When selection is enabled, ActionGroup collapses all items into a menu together when space is limited. The menu button indicates when one of
+the options within it is selected by showing a highlighted state. A `summaryIcon` should be specified to visually communicate the purpose of
+the ActionGroup when collapsed, and an `aria-label` should be provided to describe the ActionGroup to assistive technology.
+
+This example shows a multi-selectable ActionGroup that can be used to select text styles. When space is limited, it collapses into a dropdown
+menu, and displays the `TextStyle` icon passed to the `summaryIcon` prop.
+
+```tsx example
+import TextStyle from '@spectrum-icons/workflow/TextStyle';
+
+}
+ maxWidth={100}>
+ -
+
+ Bold
+
+ -
+
+ Italic
+
+ -
+
+ Underline
+
+ -
+
+ Strikethrough
+
+
+```
+
+### Single selection
+
+A special case where a `summaryIcon` is not needed is a single selectable ActionGroup (`selectionMode="single"`) which enforces that an item
+is always selected (`disallowEmptySelection`). In this case, the selected item is displayed inside the menu button when collapsed.
+
+```tsx example
+
+ -
+
+ Align Left
+
+ -
+
+ Align Center
+
+ -
+
+ Align Right
+
+ -
+
+ Justify
+
+
+```
+
+### Collapsing button labels
+
+In addition to collapsing items that don't fit into a menu, the button labels can also be automatically hidden when space is limited.
+This keeps more buttons visible at a time before needing to collapse into a menu. This behavior can be enabled by setting the
+`buttonLabelBehavior` prop to `"collapse"`. The labels will be automatically shown in tooltips when collapsed.
+
+```tsx example
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+ -
+
+ Move
+
+ -
+
+ Duplicate
+
+
+```
+
+### Vertical collapsing behavior
+
+Non-selectable vertical ActionGroups also support collapsing when the height is too small to fit all of the buttons.
+The behavior is the same as for horizontal ActionGroups, except for the positioning of the tooltips and menu.
+
+Vertical ActionGroups with selection do not currently support collapsing. When selection is enabled, we recommend placing
+the ActionGroup in a scrollable container so that the user can access all items.
+
+```tsx example
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+ -
+
+ Move
+
+ -
+
+ Duplicate
+
+
+```
+
## Props
@@ -176,7 +413,7 @@ function Example() {
```
-### Emphasize
+### Emphasized
The additional styling provided by the `isEmphasized` prop is only applied when items are selected.
@@ -191,6 +428,56 @@ The additional styling provided by the `isEmphasized` prop is only applied when
```
+### Static color
+
+The `staticColor` prop can be used when the ActionGroup is displayed over a color background. When selected, the icon and text in each
+button automatically take on the color of the background. You are responsible for choosing the static color variant that ensures the
+text meets an [accessible contrast ratio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast)
+with the background.
+
+```tsx example
+
+
+
+ -
+
+ Edit
+
+ -
+
+ Copy
+
+ -
+
+ Delete
+
+
+
+
+
+ -
+
+ List view
+
+ -
+
+ Grid view
+
+ -
+
+ Gallery view
+
+
+
+
+```
+
### Disabled
To disable the entire ActionGroup, use the `isDisabled` prop on the root.
diff --git a/packages/@react-spectrum/button/docs/ActionButton.mdx b/packages/@react-spectrum/button/docs/ActionButton.mdx
index e6fddf6af5a..183e8d39a77 100644
--- a/packages/@react-spectrum/button/docs/ActionButton.mdx
+++ b/packages/@react-spectrum/button/docs/ActionButton.mdx
@@ -16,6 +16,8 @@ import packageData from '@react-spectrum/button/package.json';
```jsx import
import {ActionButton} from '@react-spectrum/button';
+import {View} from '@react-spectrum/view';
+import {Flex} from '@react-spectrum/layout';
```
---
@@ -107,3 +109,27 @@ function Example() {
```tsx example
Action!
```
+
+### Static color
+
+The `staticColor` prop can be used when an ActionButton is displayed over a color background. You are responsible for
+choosing the static color variant that ensures the text meets an
+[accessible contrast ratio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast)
+with the background.
+
+```tsx example
+
+
+
+
+ Edit
+
+
+
+
+
+ Edit
+
+
+
+```
diff --git a/packages/@react-spectrum/button/docs/ToggleButton.mdx b/packages/@react-spectrum/button/docs/ToggleButton.mdx
index 99da23781a6..4cb6501a154 100644
--- a/packages/@react-spectrum/button/docs/ToggleButton.mdx
+++ b/packages/@react-spectrum/button/docs/ToggleButton.mdx
@@ -17,6 +17,7 @@ import packageData from '@react-spectrum/button/package.json';
```jsx import
import {Flex} from '@react-spectrum/layout';
import {ToggleButton} from '@react-spectrum/button';
+import {View} from '@react-spectrum/view';
```
---
@@ -129,3 +130,27 @@ function Example() {
```tsx example
Pin
```
+
+### Static color
+
+The `staticColor` prop can be used when a ToggleButton is displayed over a color background. When selected, the icon and text
+automatically take on the color of the background. You are responsible for choosing the static color variant that ensures the
+text meets an [accessible contrast ratio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast)
+with the background.
+
+```tsx example
+
+
+
+
+ Pin
+
+
+
+
+
+ Pin
+
+
+
+```