@workday/canvas-kit-docs 15.0.0-alpha.0064-next.0 → 15.0.0-alpha.0074-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/dist/es6/lib/docs.js +90 -2575
  2. package/dist/es6/lib/stackblitzFiles/packageJSONFile.js +5 -5
  3. package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts +5 -5
  4. package/dist/mdx/14.0-UPGRADE-GUIDE.mdx +4 -4
  5. package/dist/mdx/15.0-UPGRADE-GUIDE.mdx +39 -2
  6. package/dist/mdx/CODEMODS.mdx +2 -2
  7. package/dist/mdx/react/action-bar/ActionBar.mdx +3 -3
  8. package/dist/mdx/react/button/button/Button.mdx +6 -7
  9. package/dist/mdx/react/expandable/Expandable.mdx +49 -2
  10. package/dist/mdx/react/expandable/examples/HoistedModel.tsx +24 -17
  11. package/dist/mdx/react/menu/Menu.mdx +63 -26
  12. package/dist/mdx/react/menu/examples/SelectableMenu.tsx +13 -2
  13. package/package.json +6 -6
  14. package/dist/mdx/labs-react/combobox/Combobox.mdx +0 -68
  15. package/dist/mdx/labs-react/combobox/examples/Basic.tsx +0 -88
  16. package/dist/mdx/labs-react/combobox/examples/DisabledItem.tsx +0 -88
  17. package/dist/mdx/labs-react/combobox/examples/GroupOfResult.tsx +0 -88
  18. package/dist/mdx/labs-react/combobox/examples/Grow.tsx +0 -88
  19. package/dist/mdx/labs-react/combobox/examples/NoClearButton.tsx +0 -88
  20. package/dist/mdx/labs-react/combobox/examples/RTL.tsx +0 -90
  21. package/dist/mdx/labs-react/search-form/SearchForm.mdx +0 -92
  22. package/dist/mdx/labs-react/search-form/examples/Basic.tsx +0 -63
  23. package/dist/mdx/labs-react/search-form/examples/Collapsed.tsx +0 -64
  24. package/dist/mdx/labs-react/search-form/examples/CustomStyles.tsx +0 -91
  25. package/dist/mdx/labs-react/search-form/examples/CustomTheme.tsx +0 -73
  26. package/dist/mdx/labs-react/search-form/examples/Grow.tsx +0 -64
  27. package/dist/mdx/labs-react/search-form/examples/RTL.tsx +0 -66
  28. package/dist/mdx/labs-react/search-form/examples/Theming.tsx +0 -66
@@ -18,11 +18,11 @@ export const packageJSONFile = `{
18
18
  "@emotion/react": "11.11.4",
19
19
  "@types/react": "18.2.60",
20
20
  "@types/react-dom": "18.2.19",
21
- "@workday/canvas-kit-labs-react": "14.2.0",
22
- "@workday/canvas-kit-preview-react": "14.2.0",
23
- "@workday/canvas-kit-react": "14.2.0",
24
- "@workday/canvas-kit-react-fonts": "^14.2.0",
25
- "@workday/canvas-kit-styling": "14.2.0",
21
+ "@workday/canvas-kit-labs-react": "14.2.2",
22
+ "@workday/canvas-kit-preview-react": "14.2.2",
23
+ "@workday/canvas-kit-react": "14.2.2",
24
+ "@workday/canvas-kit-react-fonts": "^14.2.2",
25
+ "@workday/canvas-kit-styling": "14.2.2",
26
26
  "@workday/canvas-system-icons-web": "3.0.36",
27
27
  "@workday/canvas-tokens-web": "3.1.2"
28
28
  },
@@ -18,11 +18,11 @@ export const packageJSONFile = `{
18
18
  "@emotion/react": "11.11.4",
19
19
  "@types/react": "18.2.60",
20
20
  "@types/react-dom": "18.2.19",
21
- "@workday/canvas-kit-labs-react": "14.2.0",
22
- "@workday/canvas-kit-preview-react": "14.2.0",
23
- "@workday/canvas-kit-react": "14.2.0",
24
- "@workday/canvas-kit-react-fonts": "^14.2.0",
25
- "@workday/canvas-kit-styling": "14.2.0",
21
+ "@workday/canvas-kit-labs-react": "14.2.2",
22
+ "@workday/canvas-kit-preview-react": "14.2.2",
23
+ "@workday/canvas-kit-react": "14.2.2",
24
+ "@workday/canvas-kit-react-fonts": "^14.2.2",
25
+ "@workday/canvas-kit-styling": "14.2.2",
26
26
  "@workday/canvas-system-icons-web": "3.0.36",
27
27
  "@workday/canvas-tokens-web": "3.1.2"
28
28
  },
@@ -333,7 +333,7 @@ specificity.
333
333
 
334
334
  ### useIsRTL
335
335
 
336
- **PR:** [#3480](https://github.com/Workday/canvas-kit/pull/3477)
336
+ **PR:** [#3477](https://github.com/Workday/canvas-kit/pull/3477)
337
337
 
338
338
  The `useIsRTL` hook has been deprecated. Please use
339
339
  [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
@@ -865,7 +865,7 @@ import {BaseAvatar} from '@workday/canvas-kit-preview-react/avatar';
865
865
  ### Combobox (Labs)
866
866
 
867
867
  The Combobox component in `@workday/canvas-kit-labs-react/combobox` has been deprecated. Please
868
- migrate to the [Combobox](/get-started/for-developers/resources/combobox/) in
868
+ migrate to the [Combobox](/get-started/for-developers/guides/combobox/) in
869
869
  `@workday/canvas-kit-react`.
870
870
 
871
871
  ### Radio (Main)
@@ -879,7 +879,7 @@ and API consistency.
879
879
  **PR:** [#3469](https://github.com/Workday/canvas-kit/pull/3469)
880
880
 
881
881
  The `SearchForm` in `@workday/canvas-kit-labs-react/search-form` has been deprecated. Please migrate
882
- to the [Combobox](/get-started/for-developers/resources/combobox/) in `@workday/canvas-kit-react`.
882
+ to the [Combobox](/get-started/for-developers/guides/combobox/) in `@workday/canvas-kit-react`.
883
883
 
884
884
  ### Segmented Control (Main)
885
885
 
@@ -908,7 +908,7 @@ replaced the removed component or utility.
908
908
 
909
909
  ### Deprecated Buttons
910
910
 
911
- **PR:** [#3429](https://github.com/Workday/canvas-kit/pull/3439)
911
+ **PR:** [#3439](https://github.com/Workday/canvas-kit/pull/3439)
912
912
 
913
913
  Long overdue, but a sign of moving forward, we've removed our `DeprecatedButton`. Our design system
914
914
  supported this for quite some time, but with the advancement in theming, our components API and our
@@ -18,15 +18,27 @@ space tokens, the new tokens aim to add more semantic meaning to allow for bette
18
18
  - [Codemod](#codemod)
19
19
  - [Instructions](#instructions)
20
20
  - [Component Promotions](#component-promotions)
21
- - [Segmented Control](#segmented-control-)
22
- - [Information Highlight](#information-highlight-)
21
+ - [Segmented Control ⚡️](#segmented-control-️)
22
+ - [API Differences](#api-differences)
23
+ - [Structure Changes](#structure-changes)
24
+ - [Prop Changes](#prop-changes)
25
+ - [Code Migration](#code-migration)
26
+ - [New Features](#new-features)
27
+ - [Information Highlight ⚡️](#information-highlight-️)
23
28
  - [Component Updates](#component-updates)
24
29
  - [Buttons](#buttons)
25
30
  - [Removals](#removals)
26
31
  - [Segmented Control (Deprecated)](#segmented-control-deprecated)
32
+ - [Search Form (Labs)](#search-form-labs)
33
+ - [Combobox (Labs)](#combobox-labs)
27
34
  - [Glossary](#glossary)
28
35
  - [Main](#main)
29
36
  - [Preview](#preview)
37
+ - [Codemod Reference](#codemod-reference)
38
+ - [What is a Codemod?](#what-is-a-codemod)
39
+ - [Running a Codemod](#running-a-codemod)
40
+ - [Instructions](#instructions-1)
41
+ - [Codemod Transformations for v15](#codemod-transformations-for-v15)
30
42
 
31
43
  ## Codemod
32
44
 
@@ -231,6 +243,31 @@ Please migrate to the new `SegmentedControl` component (promoted from Preview) w
231
243
  component pattern with `SegmentedControl.List` and `SegmentedControl.Item`. See the
232
244
  [API Differences](#api-differences) section above for migration guidance.
233
245
 
246
+ ### Search Form (Labs)
247
+
248
+ The deprecated `SearchForm` component has been removed from `@workday/canvas-kit-labs-react`.
249
+
250
+ The following exports are no longer available:
251
+ - `SearchForm`
252
+ - `SearchFormProps`
253
+ - `SearchFormState`
254
+ - `SearchTheme`
255
+ - `SearchThemeAttributes`
256
+
257
+ Please migrate to the [Combobox](/get-started/for-developers/guides/combobox/) in `@workday/canvas-kit-react`.
258
+
259
+ ### Combobox (Labs)
260
+
261
+ The deprecated `Combobox` component has been removed from `@workday/canvas-kit-labs-react`.
262
+
263
+ The following exports are no longer available:
264
+ - `Combobox`
265
+ - `ComboboxProps`
266
+ - `AutocompleteList`
267
+ - `Status`
268
+
269
+ Please migrate to the [Combobox](/get-started/for-developers/guides/combobox/) in `@workday/canvas-kit-react`.
270
+
234
271
  ## Glossary
235
272
 
236
273
  For an overview of the different packages we provide, please view our docs
@@ -16,7 +16,7 @@ things you'll want to keep in mind.
16
16
  dependencies on your own.
17
17
  - We recommend upgrading dependencies before running the codemod.
18
18
  - Always review your `package.json` files to make sure your dependency versions look correct.
19
- - The codemod will not handle every breaking change in v13. You will likely need to make some manual
19
+ - The codemod will not handle every breaking change in this upgrade. You will likely need to make some manual
20
20
  changes to be compatible. Use our Upgrade Guide as a checklist.
21
21
  - Codemods are not bulletproof.
22
22
  - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
@@ -48,7 +48,7 @@ finished.
48
48
 
49
49
  ```sh
50
50
  yarn add @workday/canvas-kit-codemod --dev
51
- yarn canvas-kit-codemod v${canvasKitMajorVersion} [path]
51
+ yarn canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
52
52
  yarn remove @workday/canvas-kit-codemod
53
53
  ```
54
54
 
@@ -75,9 +75,9 @@ Grouping the actions into an HTML `<section>` element with an `aria-label` strin
75
75
  This can be useful for helping screen reader users quickly jump down to the actions at the bottom of
76
76
  a page.
77
77
 
78
- Refer to [Button](?path=/docs/components-buttons--docs#accessibility) and
79
- [Menus](?path=/docs/components-popups-menu--docs#accessibility) for more information about
80
- accessibiliy of these components in the Action Bar.
78
+ Refer to [Button](/components/buttons/button/#accessibility) and
79
+ [Menus](/components/popups/menu/#accessibility) for more information about accessibiliy of these
80
+ components in the Action Bar.
81
81
 
82
82
  ## Component API
83
83
 
@@ -115,13 +115,13 @@ Enter and Space keys for keyboard interactions.
115
115
  [Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
116
116
 
117
117
  - An `aria-label` is only necessary for icon-only buttons in most cases. Using
118
- [Canvas Kit's tooltip component](?path=/docs/components-popups-tooltip--docs) will handle this for
119
- you, and all users will be able to see the label for the button.
118
+ [Canvas Kit's tooltip component](/components/popups/tooltip/) will handle this for you, and all
119
+ users will be able to see the label for the button.
120
120
  - When button designs have 2 toggle states, an `aria-pressed={true | false}` property is required
121
121
  for screen reader support. For example, see Canvas Kit's
122
- [Segmented Control component](?path=/docs/preview-segmented-control--docs).
123
- - When buttons have an attached menu, an `aria-haspopup=”true”` property is required. Using
124
- [Canvas Kit's Menu component](?path=/docs/components-menus-menu--docs) will handle this for you.
122
+ [Segmented Control component](/components/buttons/segmented-control/).
123
+ - When buttons have an attached menu, an `aria-haspopup="true"` property is required. Using
124
+ [Canvas Kit's Menu component](/components/popups/menu/) will handle this for you.
125
125
  - The icons used in text buttons are decorative in most cases and include ARIA `role="presentation"`
126
126
  and `focusable="false"`. In some special cases where an icon does add meaning, you may be required
127
127
  to change the `role` and add an `aria-label` to the icon for equivalent screen reader support.
@@ -136,8 +136,7 @@ Enter and Space keys for keyboard interactions.
136
136
  - Button text content is announced along with the button role (e.g., "Primary, button").
137
137
  - Icon-only buttons announce the `aria-label` value along with the button role.
138
138
  - Toggle buttons announce their pressed/unpressed state (e.g., "Activity Stream, toggle button,
139
- pressed" and check out the
140
- [Segmented Control component](?path=/docs/preview-segmented-control--docs)).
139
+ pressed" and check out the [Segmented Control component](/components/buttons/segmented-control/)).
141
140
 
142
141
  ### Touch Target Size
143
142
 
@@ -48,6 +48,11 @@ to `Expandable.Icon` depending on whether the `Expandable.Icon` is placed before
48
48
 
49
49
  <ExampleCodeBlock code={Avatar} />
50
50
 
51
+ > **Accessibility Note:** In this situation, the Avatar is decorative and should not be announced to
52
+ > screen readers. The `<Expandable.Avatar>` component has `isDecorative` set to `true` by default to
53
+ > hide it from screen readers, as avatars in expandable headers are typically decorative when paired
54
+ > with adjacent text.
55
+
51
56
  ### Right to Left (RTL)
52
57
 
53
58
  Expandable container has bidirectional support and should function as expected with RTL languages as
@@ -72,11 +77,53 @@ You can also have direct access to the model if
72
77
 
73
78
  ### Hoisted Model
74
79
 
75
- If you you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In
76
- the example below, we're hoisting the models to expand and collapse all three containers at once.
80
+ If you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In the
81
+ example below, we're hoisting the models to expand and collapse all three containers at once.
77
82
 
78
83
  <ExampleCodeBlock code={HoistedModel} />
79
84
 
85
+ > **Accessibility Note:** When using multiple Expandable Containers on a page, use the `as` prop to
86
+ > render the `<Expandable.Content>` sub-component as an HTML `<section>` element. Then, use
87
+ > `aria-labelledby` to reference the unique `id` of the `<Expandable.Title>` element. This practice
88
+ > can be useful to screen reader users when multiple Expandable Containers are opened at one time
89
+ > for uniquely describing the boundaries of the expandable content.
90
+
91
+ ## Accessibility
92
+
93
+ Our Expandable component renders a semantic HTML `<button>` element to the DOM, with an optional
94
+ parent heading element as defined by the `headingLevel` prop. The `aria-expanded` property is
95
+ included on the button to indicate the state of the content to screen readers.
96
+
97
+ [Accordion Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
98
+
99
+ - Use the `headingLevel` prop to assign an appropriate heading level based on the context of the
100
+ page content.
101
+ - When using Expandable Container for navigation elements, then we don't recommend using the
102
+ `headingLevel` prop. This will render only expandable buttons to the DOM, reserving headings for
103
+ organizing content in the main body of the page.
104
+ - The `as` prop may also be used on `<Expandable.Content>` to render an HTML `<ul>` element for
105
+ displaying a list of items. For example, check out
106
+ [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
107
+
108
+ ### Navigation
109
+
110
+ - **Tab key**: Moves focus to the next expandable button or focusable element
111
+ - **Shift + Tab**: Moves focus to the previous focusable element
112
+ - **Enter or Space**: Toggles the expanded/collapsed state
113
+
114
+ ### Screen Reader Experience
115
+
116
+ - The expandable button will be announced with its title text followed by the button role
117
+ - The current state will be announced as either "collapsed" or "expanded" (For example: "Usage
118
+ Guidance, button, collapsed" or "Usage Guidance, button, expanded")
119
+ - **State Changes:** When activating the button to expand content, screen readers will announce the
120
+ new "expanded" state and vice versa when collapsing content.
121
+ - **Content Regions:** Screen reader users can use landmark navigation to jump between sections and
122
+ each section will be announced with its associated title (For example: "Usage Guidance, landmark
123
+ region")
124
+ - **Heading Structure:** Using heading levels with expandable buttons allows screen reader users to
125
+ navigate by headings, making the document structure and hierarchy easier to understand.
126
+
80
127
  ## Component API
81
128
 
82
129
  <SymbolDoc name="Expandable" fileName="/react/" />
@@ -3,12 +3,27 @@ import React from 'react';
3
3
  import {Expandable, useExpandableModel} from '@workday/canvas-kit-react/expandable';
4
4
  import {Flex} from '@workday/canvas-kit-react/layout';
5
5
  import {SecondaryButton} from '@workday/canvas-kit-react/button';
6
+ import {useUniqueId} from '@workday/canvas-kit-react/common';
7
+ import {createStyles} from '@workday/canvas-kit-styling';
8
+ import {system} from '@workday/canvas-tokens-web';
9
+
10
+ const listStyles = createStyles({
11
+ flexDirection: 'column',
12
+ gap: system.space.x2,
13
+ padding: system.space.zero,
14
+ marginX: system.space.x4,
15
+ marginY: system.space.zero,
16
+ });
6
17
 
7
18
  export default () => {
8
19
  const modelOne = useExpandableModel();
9
20
  const modelTwo = useExpandableModel();
10
21
  const modelThree = useExpandableModel();
11
22
 
23
+ const idOne = useUniqueId();
24
+ const idTwo = useUniqueId();
25
+ const idThree = useUniqueId();
26
+
12
27
  const handleExpandAll = () => {
13
28
  modelOne.events.show();
14
29
  modelTwo.events.show();
@@ -22,19 +37,19 @@ export default () => {
22
37
  };
23
38
 
24
39
  return (
25
- <Flex gap="m" flexDirection="column">
26
- <Flex gap="s">
40
+ <Flex gap={system.space.x6} flexDirection="column">
41
+ <Flex gap={system.space.x4}>
27
42
  <SecondaryButton onClick={handleExpandAll}>Expand All</SecondaryButton>
28
43
  <SecondaryButton onClick={handleCollapseAll}>Collapse All</SecondaryButton>
29
44
  </Flex>
30
45
  <Flex flexDirection="column">
31
46
  <Expandable model={modelOne}>
32
47
  <Expandable.Target headingLevel="h4">
33
- <Expandable.Title>Usage Guidance</Expandable.Title>
48
+ <Expandable.Title id={idOne}>Usage Guidance</Expandable.Title>
34
49
  <Expandable.Icon iconPosition="end" />
35
50
  </Expandable.Target>
36
51
 
37
- <Expandable.Content>
52
+ <Expandable.Content as="section" aria-labelledby={idOne}>
38
53
  This component highlights the most important details of a section and reveals more when
39
54
  a user taps or clicks on the header part of the container. Enabling users to hide and
40
55
  show information ensures the design remains focused and relevant to their expectations.
@@ -44,20 +59,12 @@ export default () => {
44
59
  </Expandable>
45
60
  <Expandable model={modelTwo}>
46
61
  <Expandable.Target headingLevel="h4">
47
- <Expandable.Title>Accessibility Guidelines</Expandable.Title>
62
+ <Expandable.Title id={idTwo}>Accessibility Guidelines</Expandable.Title>
48
63
  <Expandable.Icon iconPosition="end" />
49
64
  </Expandable.Target>
50
65
 
51
- <Expandable.Content>
52
- <Flex
53
- flexDirection="column"
54
- as="ul"
55
- gap="xxs"
56
- maxWidth="60ch"
57
- padding="zero"
58
- marginX="s"
59
- marginY="zero"
60
- >
66
+ <Expandable.Content as="section" aria-labelledby={idTwo}>
67
+ <Flex as="ul" cs={listStyles}>
61
68
  <li>
62
69
  The state of a component being open or closed must be conveyed to assistive
63
70
  technologies.
@@ -92,10 +99,10 @@ export default () => {
92
99
  </Expandable>
93
100
  <Expandable model={modelThree}>
94
101
  <Expandable.Target headingLevel="h4">
95
- <Expandable.Title>Content Guidelines</Expandable.Title>
102
+ <Expandable.Title id={idThree}>Content Guidelines</Expandable.Title>
96
103
  <Expandable.Icon iconPosition="end" />
97
104
  </Expandable.Target>
98
- <Expandable.Content>
105
+ <Expandable.Content as="section" aria-labelledby={idThree}>
99
106
  Titles should be short and concise, yet long enough to explain what the user would
100
107
  expect to see when the content is expanded. If titles must be long, make sure it doesn't
101
108
  wrap more than two lines.
@@ -32,23 +32,18 @@ yarn add @workday/canvas-kit-react
32
32
  `Menu` will automatically focus on the cursor item (first item by default). The `Menu` uses a menu
33
33
  model which composes a list model and a popup model and sets up accessibility features for you.
34
34
 
35
- `Menu` follows the
36
- [Actions Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions/)
37
- using roving tabindex. Below is table of supported keyboard shortcuts and associated actions.
38
-
39
- | Key | Action |
40
- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
41
- | `Enter` or `Space` | Activates the menu item and then closes the menu |
42
- | `Escape` | Closes the menu |
43
- | `Up Arrow` | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
44
- | `Down Arrow` | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item |
45
- | `Home` | Moves focus to the first menu item |
46
- | `End` | Moves focus to the last menu item |
47
-
48
35
  ### Context Menu
49
36
 
50
37
  <ExampleCodeBlock code={ContextMenu} />
51
38
 
39
+ > **Accessibility Note**: This variation relies on the `contextmenu` browser event, which has
40
+ > varying levels of support across different operating systems. On Windows, this feature is better
41
+ > supported and users can typically trigger context menus using the **Shift + F10** keyboard
42
+ > shortcut or the dedicated **Context Menu** key (if available on their keyboard). However, on
43
+ > macOS, context menu support is limited and may require users to enable specific accessibility
44
+ > settings in their system preferences to function properly. Consider providing alternative access
45
+ > methods for critical functionality.
46
+
52
47
  ### Icons
53
48
 
54
49
  Menu supports more complex children, including icons, but the text of the item will no longer be
@@ -60,18 +55,10 @@ about the text of the item.
60
55
 
61
56
  <ExampleCodeBlock code={Icons} />
62
57
 
63
- ### Selectable Menu
64
-
65
- The `Menu.Item` renders a `role=menuitem` element which does not have `aria-selected` and thus no
66
- selected state. If you wish your menu to have selectable menu items, use `Menu.Option` instead of
67
- `Menu.Item`. The `Menu.Option` is meant to be used when the `Menu.Card` has a role of `listbox` and
68
- is controlled via `aria-activedescendant`. This example uses `Menu.Option` to should what the
69
- checkmark looks like, but the example is not keyboard or screen reader accessible. There are many
70
- other behaviors that need to be composed into the `Menu.Target` and `Menu.List` components and the
71
- behaviors depend on many other things. To see a full example of all these behaviors, look at the
72
- `<Combobox>` and `<Select>` component source code as examples.
73
-
74
- <ExampleCodeBlock code={SelectableMenu} />
58
+ > **Accessibility Note**: Icons in menu items do not inherently provide text alternatives to
59
+ > assistive technologies. However, in most cases, icons are used decoratively alongside text labels,
60
+ > and additional text alternatives are not necessary since the menu item text itself provides the
61
+ > accessible name.
75
62
 
76
63
  ### Grouping
77
64
 
@@ -84,6 +71,14 @@ and are not selectable with the keyboard or mouse.
84
71
 
85
72
  <ExampleCodeBlock code={Grouping} />
86
73
 
74
+ > **Accessibility Note**: Menu groups use `role="group"` with appropriate labeling to provide
75
+ > semantic structure for assistive technologies. When navigating through grouped menu items, screen
76
+ > readers will announce the group label when users enter a new group, providing important context
77
+ > about the organization of the menu. Group headers are not part of the keyboard navigation
78
+ > sequence, allowing users to efficiently move between actionable menu items. This semantic grouping
79
+ > helps all users, including those using assistive technologies, understand the hierarchy and
80
+ > categorization of menu options.
81
+
87
82
  ### Nested
88
83
 
89
84
  Menus support nesting. If you only have a few items and not very many nesting levels, the menu can
@@ -94,6 +89,10 @@ indicate this dual role.
94
89
 
95
90
  <ExampleCodeBlock code={Nested} />
96
91
 
92
+ > **Accessibility Note**: When a menu item has an attached submenu, the `<Menu.Submenu.TargetItem>`
93
+ > includes `aria-haspopup="true"` and `aria-expanded={true | false}` properties. These properties
94
+ > will alert screen reader users to the available submenu systems.
95
+
97
96
  ### Nested Dynamic Items
98
97
 
99
98
  Menu nesting is simpler with the dynamic API. In this example, a `renderItem` function is defined to
@@ -106,7 +105,45 @@ submenus.
106
105
 
107
106
  ## Accessibility
108
107
 
109
- This content is coming soon!
108
+ Our Menu component is based on the Menu Button pattern on the ARIA Authoring Practices Guide from
109
+ the W3C and relies on the roving tabindex technique for managing focus within the opened menu. This
110
+ means that the minimum requirements for screen reader support and keyboard navigation are included
111
+ in the component.
112
+
113
+ [Menu Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
114
+
115
+ - The `<Menu.Target>` sub-component uses `aria-haspopup="true"` and `aria-expanded={true | false}`
116
+ properties. This benefits screen reader users by indicating when a button element has an attached
117
+ menu.
118
+ - The `<Menu.List>` sub-component uses `role="menu"` and `<Menu.Item>` uses `role="menuitem"` ARIA
119
+ roles. These roles allow screen readers to pass through arrow key events to the web application.
120
+ - The `<Menu.List>` sub-component includes an `aria-labelledby` ID reference to the `<Menu.Target>`
121
+ sub-component. This assigns a label to the menu for context.
122
+
123
+ ### Navigation
124
+
125
+ - **Enter or Space**: When focused on the menu button, opens the menu and moves focus to the first
126
+ menu item. When focused on a menu item, activates the item and closes the menu
127
+ - **Escape**: Closes the menu and returns focus to the menu button
128
+ - **Up & Down Arrow**: Moves focus up and down the menu items
129
+ - **Home & End**: Moves focus to the first or last menu item
130
+ - **Right & Left Arrow**: When focused on a menu item with a submenu, opens the submenu and moves
131
+ focus to the first item in the submenu or closes the submenu and returns focus to the parent menu
132
+ item
133
+
134
+ ### Screen Reader Experience
135
+
136
+ - The menu button will be announced with its label text followed by the button role, a notification
137
+ that it has a popup menu, and the current state of the menu (For example: "Actions, button, menu
138
+ popup, collapsed")
139
+ - **Opening the Menu:** When the menu button is activated, screen readers will announce the menu
140
+ opening, the number of menu items available, and the currently focused item (For example:
141
+ "Actions, menu, First Action, menu item, 1 of 4.")
142
+ - **Navigating Menu Items:** As focus moves between menu items, screen readers will announce the
143
+ item name and its position in the list (For example: "Second Action, menu item, 2 of 4.")
144
+ - **Menu Items with Submenus:** When focused on a menu item that has a submenu, screen readers will
145
+ announce that it has a submenu and provide the expanded/collapsed state (For example: "More
146
+ Actions, menu item, has submenu, collapsed, 3 of 4.")
110
147
 
111
148
  ## Component API
112
149
 
@@ -3,14 +3,25 @@ import React from 'react';
3
3
  import {Menu} from '@workday/canvas-kit-react/menu';
4
4
  import {BodyText} from '@workday/canvas-kit-react/text';
5
5
 
6
+ /**
7
+ * The `Menu.Item` renders a `role=menuitem` element, and `aria-selected` is not a valid attribute for
8
+ * the `menuitem` role, so it cannot have a selected state. If you wish your menu to have selectable
9
+ * menu items, use `Menu.Option` instead of `Menu.Item`. This is meant to be used when overriding the
10
+ * default role of the `Menu.List` to `listbox`. This example uses `Menu.Option` to show what the
11
+ * checkmark looks like, but the example is not keyboard or screen reader accessible. There are many
12
+ * other behaviors that need to be composed into the `Menu.Target` and `Menu.List` components and the
13
+ * behaviors depend on many other things. To see a full example of all these behaviors, look at the
14
+ * `<Combobox>` and `<Select>` component source code as examples.
15
+ */
16
+
6
17
  export default () => {
7
18
  const [selected, setSelected] = React.useState('');
8
19
  return (
9
20
  <Menu onSelect={data => setSelected(data.id)}>
10
21
  <Menu.Target>Open Menu</Menu.Target>
11
22
  <Menu.Popper>
12
- <Menu.Card role="listbox">
13
- <Menu.List as="ul">
23
+ <Menu.Card>
24
+ <Menu.List role="listbox">
14
25
  <Menu.Option>First Item</Menu.Option>
15
26
  <Menu.Option>Second Item</Menu.Option>
16
27
  <Menu.Divider />
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workday/canvas-kit-docs",
3
- "version": "15.0.0-alpha.0064-next.0",
3
+ "version": "15.0.0-alpha.0074-next.0",
4
4
  "description": "Documentation components of Canvas Kit components",
5
5
  "author": "Workday, Inc. (https://www.workday.com)",
6
6
  "license": "Apache-2.0",
@@ -45,10 +45,10 @@
45
45
  "@emotion/styled": "^11.6.0",
46
46
  "@stackblitz/sdk": "^1.11.0",
47
47
  "@storybook/csf": "0.0.1",
48
- "@workday/canvas-kit-labs-react": "^15.0.0-alpha.0064-next.0",
49
- "@workday/canvas-kit-preview-react": "^15.0.0-alpha.0064-next.0",
50
- "@workday/canvas-kit-react": "^15.0.0-alpha.0064-next.0",
51
- "@workday/canvas-kit-styling": "^15.0.0-alpha.0064-next.0",
48
+ "@workday/canvas-kit-labs-react": "^15.0.0-alpha.0074-next.0",
49
+ "@workday/canvas-kit-preview-react": "^15.0.0-alpha.0074-next.0",
50
+ "@workday/canvas-kit-react": "^15.0.0-alpha.0074-next.0",
51
+ "@workday/canvas-kit-styling": "^15.0.0-alpha.0074-next.0",
52
52
  "@workday/canvas-system-icons-web": "^3.0.36",
53
53
  "@workday/canvas-tokens-web": "4.0.0-alpha.3",
54
54
  "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
61
61
  "mkdirp": "^1.0.3",
62
62
  "typescript": "5.0"
63
63
  },
64
- "gitHead": "74d356998c8a3fe27e6a54ef1db7128320b4b2ed"
64
+ "gitHead": "3fbdd82f3f92e4c6aaebd87c84fcdcd6b39f87cc"
65
65
  }
@@ -1,68 +0,0 @@
1
- import {
2
- ExampleCodeBlock,
3
- StorybookStatusIndicator,
4
- SymbolDoc,
5
- Specifications,
6
- } from '@workday/canvas-kit-docs';
7
- import {InformationHighlight} from '@workday/canvas-kit-react/information-highlight';
8
- import Basic from './examples/Basic';
9
- import DisabledItem from './examples/DisabledItem';
10
- import GroupOfResult from './examples/GroupOfResult';
11
- import Grow from './examples/Grow';
12
- import NoClearButton from './examples/NoClearButton';
13
- import RTL from './examples/RTL';
14
-
15
-
16
- # Combobox <StorybookStatusIndicator type="deprecated" />
17
-
18
- <InformationHighlight className="sb-unstyled" variant="caution" cs={{p: {marginBlock: 0}}}>
19
- <InformationHighlight.Icon />
20
- <InformationHighlight.Body>
21
- `Combobox` in Labs has been deprecated and will be removed in a future major version. Please
22
- use `Combobox` in Main instead.
23
- </InformationHighlight.Body>
24
- <InformationHighlight.Link href="https://workday.github.io/canvas-kit/?path=/docs/features-combobox--docs">
25
- Combobox Docs
26
- </InformationHighlight.Link>
27
- </InformationHighlight>
28
-
29
- The term "Combobox" is based on the
30
- [Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) as defined in the ARIA
31
- Authoring Practices Guide (APG):
32
-
33
- > A [combobox](https://w3c.github.io/aria/#combobox) is an input widget with an associated popup
34
- > that enables users to select a value for the combobox from a collection of possible values.
35
-
36
- Examples of a "combobox" would be date pickers, autocomplete, and select components.
37
-
38
- ## Installation
39
-
40
- ```sh
41
- yarn add @workday/canvas-kit-react
42
- ```
43
-
44
- ## Usage
45
-
46
- ### Autocomplete
47
-
48
- <ExampleCodeBlock code={Basic} />
49
-
50
- ### Grow
51
-
52
- <ExampleCodeBlock code={Grow} />
53
-
54
- ### No Clear Button
55
-
56
- <ExampleCodeBlock code={NoClearButton} />
57
-
58
- ### Group Of Result
59
-
60
- <ExampleCodeBlock code={GroupOfResult} />
61
-
62
- ### Disabled Item
63
-
64
- <ExampleCodeBlock code={DisabledItem} />
65
-
66
- ### RTL
67
-
68
- <ExampleCodeBlock code={RTL} />