Merge branch 'main' into callout

.github/workflows/update-carbon-gatsby-deps.yml

@@ -24,11 +24,8 @@ jobs:
       - name: Update dependencies
         run: |
           yarn up \
-            @carbon/react@next \
-            @carbon/elements@next \
             @carbon/pictograms@next \
             @carbon/pictograms-react@next \
-            @carbon/icons@next \
             @carbon/icons-react@next \
             gatsby-theme-carbon@latest \
       - name: Generate token

.husky/pre-commit

@@ -0,0 +1 @@
+npx --no-install lint-staged

package.json

@@ -19,7 +19,8 @@
     "lint:js": "NODE_ENV=test eslint . --fix",
     "format": "prettier --write 'src/**/*.{css,scss,json,html,yaml,md,mdx,js}'",
     "format:check": "prettier --check 'src/**/*.{css,scss,json,html,yaml,md,mdx,js}'",
-    "update-browserslist": "npx browserslist-ga"
+    "update-browserslist": "npx browserslist-ga",
+    "prepare": "husky"
   },
   "engines": {
     "node": ">=18.x"
@@ -69,11 +70,6 @@
     "prettier": "^2.0.2",
     "typescript": "^4.8.4"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
   "lint-staged": {
     "*.js": [
       "eslint --fix"

src/pages/all-about-carbon/what-is-carbon.mdx

@@ -93,7 +93,7 @@ primary maintainers:
 - [Elements](https://github.com/carbon-design-system/carbon): Carbon team
 - [React](https://github.com/carbon-design-system/carbon/tree/main/packages/react):
   Carbon team
-- [Web Components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components):
+- [Web Components](https://github.com/carbon-design-system/carbon/tree/main/packages/web-components):
   Carbon team
 - [Angular](https://angular.carbondesignsystem.com/): Community maintained
 - [Vue](https://github.com/carbon-design-system/carbon-components-vue):

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

@@ -10,39 +10,105 @@ import A11yStatus from 'components/A11yStatus';
 
 <PageDescription>
 
-No accessibility annotations are needed for overflow menus, but keep these
-considerations in mind if you are modifying Carbon or creating a custom
-component.
+Design annotations are needed for specific instances shown below, but for the
+standard menu button, combo button, and overflow menu, Carbon already
+incorporates accessibility.
 
 </PageDescription>
 
-<InlineNotification>
-
-**Coming soon!** The accessibility information for the menu button and combo
-button is going to be updated soon.
-
-</InlineNotification>
-
 <AnchorLinks>
 
 <AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Design recommendations</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 also incorporates other
+blind users and others who operate via keyboard. Carbon incorporates other
 accessibility considerations, some of which are described below.
 
 ### Keyboard interaction
 
+#### Menu button
+
+The menu button is set in the tab order and is activated by `Space` or `Enter`.
+When the menu is open, the first item takes focus. Focus is moved between menu
+items with the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item
+with focus, which causes focus to go somewhere else and the menu to close. `Esc`
+collapses the menu and puts focus back onto the menu button.
+
+<Row>
+<Column colLg={8}>
+
+![example of menu button keyboard interaction](images/menu-button-accessibility-1.png)
+
+<Caption>
+  Menu button is reached by Tab. Space and Enter keys open the menu as well as
+  activating menu items with focus.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={8}>
+
+![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/menu-button-accessibility-2.png)
+
+<Caption>
+  When opened, the first item in the menu takes focus. Arrow keys move focus and
+  Esc closes the menu.
+</Caption>
+
+</Column>
+</Row>
+
+#### Combo button
+
+The combo button is set in the tab order where the first tab brings focus on the
+primary button and the second tab brings focus on the icon button that contains
+the menu. The respective buttons are activated by `Space` or `Enter`. When the
+menu is open, the first item takes focus. Focus is moved between menu items with
+the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item with
+focus, which causes focus to go somewhere else and the menu to close. `Esc`
+collapses the menu and puts focus back onto the icon button.
+
+<Row>
+<Column colLg={8}>
+
+![example of combo button keyboard interaction](images/combo-button-accessibility-1.png)
+
+<Caption>
+  Combo button items are reached by two Tab stops. Space and Enter keys open the
+  menu as well as activating menu items with focus.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={8}>
+
+![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/combo-button-accessibility-2.png)
+
+<Caption>
+  When opened, the first item in the menu takes focus. Arrow keys move focus and
+  Esc closes the menu.
+</Caption>
+
+</Column>
+</Row>
+
+#### Overflow menu
+
 Each overflow menu is in the tab order and is activated by `Space` or `Enter`.
 When the menu is open, the first item takes focus. Focus is moved between menu
 items with the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item
-with focus (which causes focus to go somewhere else and the menu to close).
-`Esc` collapses the menu and puts focus onto the menu button.
+with focus, which causes focus to go somewhere else and the menu to close. `Esc`
+collapses the menu and puts focus onto the menu button.
 
 <Row>
 <Column colLg={8}>
@@ -63,24 +129,83 @@ with focus (which causes focus to go somewhere else and the menu to close).
 ![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/overflow-menu-accessibility-2.png)
 
 <Caption>
-  When opened, the first item in the menu takes focus. Arrow keys move focus,
+  When opened, the first item in the menu takes focus. Arrow keys move focus and
   Esc closes the menu.
 </Caption>
 
 </Column>
 </Row>
 
+## Design recommendations
+
+Design annotations are needed for the following instances.
+
+### Labeling
+
+#### Combo button
+
+Combo button has a prop that can be used to change the tooltip label and is only
+intended to be changed to translate _"Additional actions"_ into other languages.
+If translation is required, the translation must be annotated with a label that
+is exposed on hover or focus.
+
+<Row>
+<Column colLg={8}>
+
+![a combo button which is a part of a translated page that has an annotation 'label=अतिरिक्त कार्रवाइयां'](images/combo-button-accessibility-3.png)
+
+<Caption>
+  Annotate the label for combo button so the proper tooltip appears, which
+  should only be used for translation purposes.
+</Caption>
+
+</Column>
+</Row>
+
+#### Overflow menu
+
+Overflow menu’s
+[custom icon variant](https://react.carbondesignsystem.com/?path=/story/components-overflowmenu--render-custom-icon)
+has a prop that can be used to change the tooltip label. If the tooltip label is
+changed, they must be annotated with a label that will be exposed on hover or
+focus.
+
+<Row>
+<Column colLg={8}>
+
+![a custom icon over flow menu with a share icon that has an annotation 'label=sharing options'](images/overflow-menu-accessibility-3.png)
+
+<Caption>
+  Annotate the label for overflow menu’s custom icon variant so the proper
+  tooltip appears.
+</Caption>
+
+</Column>
+</Row>
+
 ## Development considerations
 
 Keep these considerations in mind if you are modifying Carbon or creating a
 custom component.
 
-- Overflow menus are buttons with `aria-haspopup` set to "true".
-- The overflow menu is named with `aria-label`.
-- Each menu item is an `li` in a `ul`.
-- Each list item contains a button with `role="menuitem"` and `tabindex="-1"`.
-  See the
+- Menu button, combo button, and the overflow menu are buttons with
+  `aria-haspopup` set to "true".
+- The menu button, combo button, and the overflow menu is named with
+  `aria-label`.
+- Each menu item across menu button, combo button, and overflow menu is an `li`
+  in a `ul`.
+- Each list item across menu button, combo button, and overflow menu contains a
+  button with `role="menuitem"` and `tabindex="-1"`. See the
   [ARIA authoring practices on menubutton](https://w3c.github.io/aria-practices/#menubutton)
   for more considerations.
+- Combo button and overflow menu has an `iconDescription` prop that can be used
+  to change the tooltip label. See the
+  [design recommendations](#design-recommendations) for more guidelines on
+  tooltip labels.
+- For combo button, the menu is given an `id`. When the menu is open, the icon
+  button is given `aria-controls` with a value of the menu `id`. `aria-expanded`
+  is also set based on the open state.
+- When the combo button menu is open, the element (`div`) wrapping the entire
+  combo button is given `aria-owns` with a value of the menu `id`.
 
 <A11yStatus layout="table" components="Menu buttons" />

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

@@ -102,19 +102,19 @@ avoids cluttering the main interface with too many options.
 
 #### 1. Menu button
 
-A. Primary button <br /> C. Menu <br />
+A. Primary button <br /> B. Menu <br />
 
 #### 2. Combo button
 
-A. Primary button <br /> B. Icon button <br /> C. Menu <br />
+A. Primary button <br /> B. Menu <br /> C. Icon button <br />
 
 </Column>
 
 <Column colSm={2} colMd={4} colLg={4}>
 
 #### 3. Overflow menu
 
-A. Icon button <br /> C. Menu <br />
+A. Icon button <br /> B. Menu <br />
 
 </Column>
 </Row>

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/components/progress-bar/usage.mdx

@@ -112,8 +112,8 @@ representing the progress. The indeterminate variant is visualized as a track on
 which a bar is moving along in constant speed, repeating over time.
 
 | Variant                                                                    | Purpose                                                                                                                                                                                                                          |
-| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
-| [Determinate](Determinate)                                                 | Use determinate progress bars where there is clear information about the progression — they convey exact and qualitative information about the progression.                                                                      |     |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Determinate](Determinate)                                                 | Use determinate progress bars where there is clear information about the progression — they convey exact and qualitative information about the progression.                                                                      |
 | [Indeterminate](/components/progress-bar/usage#indeterminate-progress-bar) | Use indeterminate progress bars where there is unclear information about the progression — they convey that users’ request, action, or data is being processed at the moment without indicating how long the activity will take. |
 
 <Row>