Merge branch 'main' into FF_Overview,FAQ

src/pages/components/menu-buttons/accessibility.mdx

@@ -27,7 +27,7 @@ incorporates accessibility.
 ## What Carbon provides
 
 Carbon bakes keyboard operation into its components, improving the experience of
-blind users and others who operate via keyboard. Carbon also incorporates other
+blind users and others who operate via keyboard. Carbon incorporates other
 accessibility considerations, some of which are described below.
 
 ### Keyboard interaction

src/pages/components/menu/accessibility.mdx

@@ -6,10 +6,85 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 import A11yStatus from 'components/A11yStatus';
 
-<InlineNotification>
+<PageDescription>
 
-**Coming soon!** This page is a work in progress.
+No accessibility annotations are needed for menus, but keep these considerations
+in mind if you are modifying Carbon or creating a custom component.
 
-</InlineNotification>
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
+
+</AnchorLinks>
+
+## What Carbon provides
+
+Carbon bakes keyboard operation into its components, improving the experience of
+blind users and others who operate via keyboard. Carbon incorporates many other
+accessibility considerations, some of which are described below.
+
+### Keyboard interaction
+
+The menu is reached by `Tab`. When the menu is open, the first item takes focus.
+Use the `Up` and `Down` arrow keys to navigate between menu items.
+
+<Row>
+
+<Column colLg={8}>
+
+![example of menu keyboard interaction](images/accessibility-menu-1.png)
+
+<Caption>
+  Menu is reached by Tab and when opened, the first menu item takes focus. Arrow
+  keys move focus.
+</Caption>
+
+</Column>
+</Row>
+
+Pressing `Space` or `Enter` on a focused menu item activates it and collapses
+the menu. Pressing `Space` or `Enter` on a submenu opens it. A submenu can also
+be opened and closed using the right and left arrow keys respectively. When the
+menu or submenu is open, the first item takes focus. An activated menu item can
+have different results depending on its functionality. If the item is a link, it
+launches the selection. If the item is selectable, it selects or deselects the
+item. The menu item retains its selected or unselected state when the menu is
+opened again.
+
+<Row>
+<Column colLg={12}>
+
+![example of menu keyboard interaction](images/accessibility-menu-2.png)
+
+<Caption>
+  Space and Enter keys activates, selects, or deselects the menu item with
+  focus. A submenu is opened and closed with the right and left arrow keys
+  respectively.
+</Caption>
+
+</Column>
+</Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Each menu, including nested menus, are `ul` elements with `role="menu"`.
+- Menu items are `li` elements with `role="menuitem"`.
+- If a Menu item contains a sub-menu, it is given `aria-haspopup="true"` and
+  `aria-expanded` of true or false depending on if the sub-menu is open/visible.
+- Selectable menu items are given `role="menuitemcheckbox"`.
+- Menu item groups are `li` elements with `role="group"`.
+- Menu item radio groups get `role="menuitemradio"`.
+- Menu items with really long labels can get truncated depending on the screen
+  size. This label will be exposed by a browser rendered tooltip on hover or
+  focus.
+- Menu implements the
+  [menu design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)
+  defined in the ARIA Authoring Practices Guide (APG).
 
 <A11yStatus layout="table" components="Menu" />

src/pages/components/menu/usage.mdx

@@ -328,7 +328,8 @@ including the direction of the caret and keyboard shortcuts.
 #### Overflow
 
 Consider using short and precise labels for menu items. However, when deciding
-to truncate long menu items, use a tooltip on hover to reveal the full text.
+to truncate long menu items, a browser rendered title tooltip will reveal the
+full text on hover.
 
 <Row>
 <Column colLg={8}>

src/pages/components/pagination/usage.mdx

@@ -96,9 +96,9 @@ Pagination can be used with a data table or on a page.
 ### Variants
 
 | Variant                           | Usage                                                                                                                           |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --- |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | [Pagination](#pagination)         | The pagination variant is typically connected at the bottom of the data table component to help paginate large amounts of data. |
-| [Pagination nav](#pagination-nav) | The pagination nav variant is mainly used in on-page situations to help paginate either a whole page or sections of a page.     |     |
+| [Pagination nav](#pagination-nav) | The pagination nav variant is mainly used in on-page situations to help paginate either a whole page or sections of a page.     |
 
 ## Formatting
 

src/pages/data-visualization/flow-charts/index.mdx

@@ -75,21 +75,8 @@ your own layouts.
 - [React](https://carbon-design-system.github.io/carbon-charts/react/?path=/story/diagrams--start-here)
 - [Angular](https://carbon-design-system.github.io/carbon-charts/angular/?path=/story/diagrams--start-here)
 
-Here's an example using elkjs in react
-
-<iframe
-  src="https://codesandbox.io/embed/carbon-charts-react-elkjs-diagram-b9xyp?fontsize=14&hidenavigation=1&theme=dark"
-  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
-  style={{
-    width: '100%',
-    height: '500px',
-    border: '0',
-    borderRadius: '4px',
-    overflow: 'hidden',
-  }}
-  title="carbon-charts-react-elkjs-diagram"
-  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>
+Here's an
+[example using elkjs in react](https://codesandbox.io/p/sandbox/carbon-charts-react-elkjs-diagram-b9xyp?file=%2Fsrc%2Findex.js&from-embed).
 
 <Row>
 <Column  colLg={12} colMd={8} colSm={4} >