@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.
- package/dist/es6/lib/docs.js +90 -2575
- package/dist/es6/lib/stackblitzFiles/packageJSONFile.js +5 -5
- package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts +5 -5
- package/dist/mdx/14.0-UPGRADE-GUIDE.mdx +4 -4
- package/dist/mdx/15.0-UPGRADE-GUIDE.mdx +39 -2
- package/dist/mdx/CODEMODS.mdx +2 -2
- package/dist/mdx/react/action-bar/ActionBar.mdx +3 -3
- package/dist/mdx/react/button/button/Button.mdx +6 -7
- package/dist/mdx/react/expandable/Expandable.mdx +49 -2
- package/dist/mdx/react/expandable/examples/HoistedModel.tsx +24 -17
- package/dist/mdx/react/menu/Menu.mdx +63 -26
- package/dist/mdx/react/menu/examples/SelectableMenu.tsx +13 -2
- package/package.json +6 -6
- package/dist/mdx/labs-react/combobox/Combobox.mdx +0 -68
- package/dist/mdx/labs-react/combobox/examples/Basic.tsx +0 -88
- package/dist/mdx/labs-react/combobox/examples/DisabledItem.tsx +0 -88
- package/dist/mdx/labs-react/combobox/examples/GroupOfResult.tsx +0 -88
- package/dist/mdx/labs-react/combobox/examples/Grow.tsx +0 -88
- package/dist/mdx/labs-react/combobox/examples/NoClearButton.tsx +0 -88
- package/dist/mdx/labs-react/combobox/examples/RTL.tsx +0 -90
- package/dist/mdx/labs-react/search-form/SearchForm.mdx +0 -92
- package/dist/mdx/labs-react/search-form/examples/Basic.tsx +0 -63
- package/dist/mdx/labs-react/search-form/examples/Collapsed.tsx +0 -64
- package/dist/mdx/labs-react/search-form/examples/CustomStyles.tsx +0 -91
- package/dist/mdx/labs-react/search-form/examples/CustomTheme.tsx +0 -73
- package/dist/mdx/labs-react/search-form/examples/Grow.tsx +0 -64
- package/dist/mdx/labs-react/search-form/examples/RTL.tsx +0 -66
- 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.
|
|
22
|
-
"@workday/canvas-kit-preview-react": "14.2.
|
|
23
|
-
"@workday/canvas-kit-react": "14.2.
|
|
24
|
-
"@workday/canvas-kit-react-fonts": "^14.2.
|
|
25
|
-
"@workday/canvas-kit-styling": "14.2.
|
|
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.
|
|
22
|
-
"@workday/canvas-kit-preview-react": "14.2.
|
|
23
|
-
"@workday/canvas-kit-react": "14.2.
|
|
24
|
-
"@workday/canvas-kit-react-fonts": "^14.2.
|
|
25
|
-
"@workday/canvas-kit-styling": "14.2.
|
|
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:** [#
|
|
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/
|
|
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/
|
|
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:** [#
|
|
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
|
-
|
|
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
|
package/dist/mdx/CODEMODS.mdx
CHANGED
|
@@ -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
|
|
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${
|
|
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](
|
|
79
|
-
[Menus](
|
|
80
|
-
|
|
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](
|
|
119
|
-
|
|
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](
|
|
123
|
-
- When buttons have an attached menu, an `aria-haspopup
|
|
124
|
-
[Canvas Kit's Menu component](
|
|
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
|
|
76
|
-
|
|
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=
|
|
26
|
-
<Flex gap=
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
|
13
|
-
<Menu.List
|
|
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.
|
|
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.
|
|
49
|
-
"@workday/canvas-kit-preview-react": "^15.0.0-alpha.
|
|
50
|
-
"@workday/canvas-kit-react": "^15.0.0-alpha.
|
|
51
|
-
"@workday/canvas-kit-styling": "^15.0.0-alpha.
|
|
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": "
|
|
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} />
|