Toolbar docs updates (#5363)

Author: devongovett

packages/@react-aria/toolbar/docs/useToolbar.mdx

@@ -40,40 +40,39 @@ keywords: [toolbar, aria]
 
 ## Features
 
-There is no native element to implement a toolbar in HTML without Javascript. `useToolbar`
+There is no native element to implement a toolbar in HTML. `useToolbar`
 helps achieve accessible toolbar components that can be styled as needed.
 
-* Exposed to assistive technology as a `toolbar` or `group` element via ARIA
-* Support for keyboard navigation
+* Exposed to assistive technology as a `toolbar` element via ARIA
+* Support for arrow key navigation
 * Support for both horizontal and vertical orientations
-* Support for React Aria based children: button, togglebutton, menu, checkbox, and link
+* Support for interactive children including button, toggle button, menu, checkbox, and link
 * Automatic scrolling support during keyboard navigation
 
 ## Anatomy
 
 <Anatomy />
 
-A toolbar consists of a wrapper element with role `toolbar` and groups of interactive children.
+A toolbar consists of a container element for a set of interactive controls.
 `useToolbar` handles exposing this to assistive technology using ARIA, along with
- handling keyboard, mouse, and interactions to support navigation behavior.
+ handling arrow key navigation between children.
 
 `useToolbar` returns props that you should spread onto the appropriate element:
 
 <TypeContext.Provider value={docs.links}>
   <InterfaceType properties={docs.links[docs.exports.useToolbar.return.id].properties} />
 </TypeContext.Provider>
 
-If a toolbar does not have a visible label, an `aria-label` or `aria-labelledby`
-prop must be passed instead to identify the element to assistive technology.
+An `aria-label` or `aria-labelledby` prop must be provided to identify the toolbar to assistive technology.
 
 ## Example
 
 ### Toolbar
 
-This uses the <TypeLink links={docs.links} type={docs.exports.useToolbar} /> hook, spread on a container to handle
+This example uses the <TypeLink links={docs.links} type={docs.exports.useToolbar} /> hook, spread on a container to handle
 navigation of components inside it.
 
-```tsx example export=true render=false
+```tsx example
 import {useToolbar} from '@react-aria/toolbar';
 import {useRef} from 'react';
 
@@ -91,11 +90,7 @@ function Toolbar(props) {
     </div>
   );
 }
-```
 
-Now we can render a simple toolbar with actionable items:
-
-```tsx example
 <Toolbar aria-label="Actions">
   <Button>Copy</Button>
   <Button>Cut</Button>
@@ -112,8 +107,6 @@ Now we can render a simple toolbar with actionable items:
   display: flex;
   flex-wrap: wrap;
   gap: 5px;
-  padding: 15px;
-  border: 1px solid var(--separator-color);
 }
 ```
 
@@ -141,12 +134,10 @@ function Button(props) {
     <span
       {...buttonProps}
       style={{
-        background: isPressed ? 'darkgreen' : 'green',
-        color: 'white',
-        padding: 10,
-        cursor: 'pointer',
-        userSelect: 'none',
-        WebkitUserSelect: 'none'
+        background: isPressed ? '#bbb' : '#aaa',
+        color: 'black',
+        cursor: 'default',
+        padding: '5px 10px'
       }}
       ref={ref}>
       {children}

packages/@react-aria/toolbar/src/useToolbar.ts

@@ -32,7 +32,8 @@ export interface ToolbarAria {
 }
 
 /**
- * Handles interactions for toolbar elements, such as keyboard navigation between elements.
+ * Provides the behavior and accessibility implementation for a toolbar.
+ * A toolbar is a container for a set of interactive controls with arrow key navigation.
  * @param props - Props to be applied to the toolbar.
  * @param ref - A ref to a DOM element for the toolbar.
  */

packages/react-aria-components/docs/Toolbar.mdx

@@ -12,7 +12,7 @@ export default Layout;
 
 import docs from 'docs:react-aria-components';
 import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
-import {PropTable, HeaderInfo, TypeLink, PageDescription, ContextTable} from '@react-spectrum/docs';
+import {PropTable, HeaderInfo, TypeLink, PageDescription, ContextTable, StateTable} from '@react-spectrum/docs';
 import styles from '@react-spectrum/docs/src/docs.css';
 import packageData from 'react-aria-components/package.json';
 import Anatomy from '@react-aria/toolbar/docs/toolbar-anatomy.svg';
@@ -38,27 +38,20 @@ type: component
 ## Example
 
 ```tsx example
-import {Toolbar, Button, ToggleButton, Separator, Popover, MenuTrigger, Menu, MenuItem, Checkbox} from 'react-aria-components';
-
-<Toolbar>
-  <ToggleButton><strong>B</strong></ToggleButton>
-  <ToggleButton><div style={{textDecoration: 'underline'}}>U</div></ToggleButton>
-  <ToggleButton><i>I</i></ToggleButton>
+import {Toolbar, Button, ToggleButton, Separator, Checkbox, Group} from 'react-aria-components';
+
+<Toolbar aria-label="Text formatting">
+  <Group aria-label="Style">
+    <ToggleButton aria-label="Bold"><b>B</b></ToggleButton>
+    <ToggleButton aria-label="Italic"><i>I</i></ToggleButton>
+    <ToggleButton aria-label="Underline"><u>U</u></ToggleButton>
+  </Group>
   <Separator orientation="vertical" />
-  <Button>Copy</Button>
-  <Button>Paste</Button>
-  <Button>Cut</Button>
-  <Separator orientation="vertical" />
-  <MenuTrigger>
-    <Button>Alignment</Button>
-    <Popover>
-      <Menu>
-        <MenuItem>Left</MenuItem>
-        <MenuItem>Center</MenuItem>
-        <MenuItem>Right</MenuItem>
-      </Menu>
-    </Popover>
-  </MenuTrigger>
+  <Group aria-label="Clipboard">
+    <Button>Copy</Button>
+    <Button>Paste</Button>
+    <Button>Cut</Button>
+  </Group>
   <Separator orientation="vertical" />
   <Checkbox>
     <div className="checkbox">
@@ -77,8 +70,6 @@ import {Toolbar, Button, ToggleButton, Separator, Popover, MenuTrigger, Menu, Me
 @import './Checkbox.mdx' layer(checkbox);
 @import './Button.mdx' layer(button);
 @import './ToggleButton.mdx' layer(togglebutton);
-@import './Popover.mdx' layer(popover);
-@import './Menu.mdx' layer(menu);
 ```
 
 ```css
@@ -87,46 +78,104 @@ import {Toolbar, Button, ToggleButton, Separator, Popover, MenuTrigger, Menu, Me
   display: flex;
   flex-wrap: wrap;
   gap: 5px;
-  padding: 15px;
-  border: 1px solid var(--separator-color);
-
-  &[data-orientation=vertical] {
-    flex-direction: column;
-  }
 
   &[data-orientation=horizontal] {
     flex-direction: row;
   }
-}
 
-.react-aria-ToggleButton {
-  width: 32px;
+  .react-aria-Group {
+    display: contents;
+  }
+
+  .react-aria-ToggleButton {
+    width: 32px;
+  }
 }
 
+
 .react-aria-Separator {
-  width: 2px;
-  margin: 0px 10px;
   align-self: stretch;
   background-color: var(--separator-color);
+
+  &[aria-orientation=vertical] {
+    width: 1px;
+    margin: 0px 10px;
+  }
 }
 ```
 
 </details>
 
 ## Features
 
-Toolbar provides keyboard navigation and announcements for groups of interactive elements.
-`Toolbar` helps implement these in an accessible way.
+There is no built-in HTML toolbar element. `Toolbar` helps achieve accessible toolbars with arrow key navigation that can be styled as needed.
 
-* **Flexible** – Support for various RAC or Aria Hooks implemented components.
-* **Accessible** – Follows the [ARIA toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) with support for keyboard arrow key navigation and is a single tab stop.
-* **Styleable** – Can be styled in any custom way, including extra DOM structure between the Toolbar and the interactive children.
+* **Flexible** – Support for interactive children such as buttons, checkboxes, dropdown menus, etc. in a horizontal or vertical orientation.
+* **Accessible** – Follows the [ARIA toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) with support for arrow key navigation as a single tab stop.
 
 ## Anatomy
 
 <Anatomy />
 
-Toolbar consists of a wrapping element which controls arrow key navigation depending on the orientation and children.
+A toolbar consists of a container element for a set of interactive controls. It provides arrow key navigation between its children, in either horizontal or vertical orientation.
+
+```tsx
+import {Toolbar} from 'react-aria-components';
+
+<Toolbar>
+  {/* ... */}
+</Toolbar>
+```
+
+## Orientation
+
+By default, toolbars are horizontally oriented. The `orientation` prop can be set to `"vertical"` to change the arrow key navigation behavior.
+
+```tsx example
+import Move from '@spectrum-icons/workflow/Move';
+import Select from '@spectrum-icons/workflow/Select';
+import Polygon from '@spectrum-icons/workflow/PolygonSelect';
+import Brush from '@spectrum-icons/workflow/Brush';
+import Pencil from '@spectrum-icons/workflow/Edit';
+
+<Toolbar aria-label="Tools" orientation="vertical">
+  <Group aria-label="Select">
+    <Button aria-label="Move"><Move size="S" /></Button>
+    <Button aria-label="Rectangle"><Select size="S" /></Button>
+    <Button aria-label="Polygon"><Polygon size="S" /></Button>
+  </Group>
+  <Separator orientation="horizontal" />
+  <Group aria-label="Draw">
+    <Button aria-label="Brush"><Brush size="S" /></Button>
+    <Button aria-label="Pencil"><Pencil size="S" /></Button>
+  </Group>
+</Toolbar>
+```
+
+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>
+
+```css
+.react-aria-Toolbar {
+  width: fit-content;
+
+  &[data-orientation=vertical] {
+    flex-direction: column;
+    align-items: start;
+  }
+}
+
+.react-aria-Separator {
+  &:not([aria-orientation=vertical]) {
+    border: none;
+    height: 1px;
+    width: 100%;
+    margin: 10px 0;
+  }
+}
+```
+
+</details>
 
 ## Props
 
@@ -163,6 +212,22 @@ A custom `className` can also be specified on any component. This overrides the
 </Toolbar>
 ```
 
+The `className` and `style` props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like [Tailwind](https://tailwindcss.com/).
+
+```jsx
+<Toolbar className={({orientation}) => orientation === 'vertical' ? 'flex-col' : 'flex-row'}>
+  {/* ... */}
+</Toolbar>
+```
+
+The selectors and render props for each component used in a `Toolbar` are documented below.
+
+### Toolbar
+
+A `Toolbar` can be targeted with the `.react-aria-Toolbar` CSS selector, or by overriding with a custom `className`. It supports the following states and render props:
+
+<StateTable properties={docs.exports.ToolbarRenderProps.properties} />
+
 ### Separator
 
 A `Separator` can be targeted with the `.react-aria-Separator` CSS selector, or by overriding with a custom `className`.

packages/react-aria-components/src/Toolbar.tsx

@@ -53,7 +53,8 @@ function Toolbar(props: ToolbarProps, ref: ForwardedRef<HTMLDivElement>) {
 }
 
 /**
- * A toolbar is a container for grouping a set of controls, such as buttons, menubuttons, or checkboxes.
+ * A toolbar is a container for a set of interactive controls, such as buttons, dropdown menus, or checkboxes,
+ * with arrow key navigation.
  */
 const _Toolbar = /*#__PURE__*/ (forwardRef as forwardRefType)(Toolbar);
 export {_Toolbar as Toolbar};