@workday/canvas-kit-docs 16.2.0-0604-next.0 → 16.2.0-0612-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.
|
@@ -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": "16.1.
|
|
22
|
-
"@workday/canvas-kit-preview-react": "16.1.
|
|
23
|
-
"@workday/canvas-kit-react": "16.1.
|
|
24
|
-
"@workday/canvas-kit-react-fonts": "^16.1.
|
|
25
|
-
"@workday/canvas-kit-styling": "16.1.
|
|
21
|
+
"@workday/canvas-kit-labs-react": "16.1.2",
|
|
22
|
+
"@workday/canvas-kit-preview-react": "16.1.2",
|
|
23
|
+
"@workday/canvas-kit-react": "16.1.2",
|
|
24
|
+
"@workday/canvas-kit-react-fonts": "^16.1.2",
|
|
25
|
+
"@workday/canvas-kit-styling": "16.1.2",
|
|
26
26
|
"@workday/canvas-system-icons-web": "^5.0.3",
|
|
27
27
|
"@workday/canvas-expressive-icons-web": "1.0.1",
|
|
28
28
|
"@workday/canvas-tokens-web": "4.4.0-beta.11"
|
|
@@ -19,11 +19,11 @@ export const packageJSONFile = `{
|
|
|
19
19
|
"@emotion/react": "11.11.4",
|
|
20
20
|
"@types/react": "18.2.60",
|
|
21
21
|
"@types/react-dom": "18.2.19",
|
|
22
|
-
"@workday/canvas-kit-labs-react": "16.1.
|
|
23
|
-
"@workday/canvas-kit-preview-react": "16.1.
|
|
24
|
-
"@workday/canvas-kit-react": "16.1.
|
|
25
|
-
"@workday/canvas-kit-react-fonts": "^16.1.
|
|
26
|
-
"@workday/canvas-kit-styling": "16.1.
|
|
22
|
+
"@workday/canvas-kit-labs-react": "16.1.2",
|
|
23
|
+
"@workday/canvas-kit-preview-react": "16.1.2",
|
|
24
|
+
"@workday/canvas-kit-react": "16.1.2",
|
|
25
|
+
"@workday/canvas-kit-react-fonts": "^16.1.2",
|
|
26
|
+
"@workday/canvas-kit-styling": "16.1.2",
|
|
27
27
|
"@workday/canvas-system-icons-web": "^5.0.3",
|
|
28
28
|
"@workday/canvas-expressive-icons-web": "1.0.1",
|
|
29
29
|
"@workday/canvas-tokens-web": "4.4.0-beta.11"
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
|
|
2
2
|
|
|
3
|
-
import StartIcon from './examples/StartIcon';
|
|
4
|
-
import EndIcon from './examples/EndIcon';
|
|
5
3
|
import Avatar from './examples/Avatar';
|
|
6
4
|
import Depth from './examples/Depth';
|
|
7
|
-
import
|
|
8
|
-
import LongTitle from './examples/LongTitle';
|
|
5
|
+
import EndIcon from './examples/EndIcon';
|
|
9
6
|
import HoistedModel from './examples/HoistedModel';
|
|
7
|
+
import LongTitle from './examples/LongTitle';
|
|
8
|
+
import RTL from './examples/RTL';
|
|
9
|
+
import StartIcon from './examples/StartIcon';
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
# Canvas Kit Expandable
|
|
@@ -23,8 +23,8 @@ yarn add @workday/canvas-kit-react
|
|
|
23
23
|
|
|
24
24
|
### Start Icon
|
|
25
25
|
|
|
26
|
-
For a basic expandable container with a chevron icon before the title, place`Expandable.Icon`
|
|
27
|
-
`Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
|
|
26
|
+
For a basic expandable container with a chevron icon before the title, place `Expandable.Icon`
|
|
27
|
+
before `Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
|
|
28
28
|
`Expandable.Icon` with a value of `start`. `Expandable.Icon` will use a right chevron icon when
|
|
29
29
|
collapsed and a down chevron icon when expanded.
|
|
30
30
|
|
|
@@ -46,18 +46,12 @@ To include an avatar image, `Expandable.Avatar` should be placed between `Expand
|
|
|
46
46
|
to `Expandable.Icon` depending on whether the `Expandable.Icon` is placed before or after
|
|
47
47
|
`Expandable.Title`.
|
|
48
48
|
|
|
49
|
-
**Note:** If using an avatar image, do not also include an Icon component in addition to the
|
|
50
|
-
This component is meant to have either an avatar image or an icon in addition to
|
|
51
|
-
an avatar image nor an extra icon.
|
|
52
|
-
|
|
49
|
+
**Note:** If using an avatar image, do not also include an Icon component in addition to the
|
|
50
|
+
Expandable.Icon. This component is meant to have either an avatar image or an icon in addition to
|
|
51
|
+
the Expandable.Icon, or neither an avatar image nor an extra icon.
|
|
53
52
|
|
|
54
53
|
<ExampleCodeBlock code={Avatar} />
|
|
55
54
|
|
|
56
|
-
> **Accessibility Note:** In this situation, the Avatar is decorative and should not be announced to
|
|
57
|
-
> screen readers. The `<Expandable.Avatar>` component has `isDecorative` set to `true` by default to
|
|
58
|
-
> hide it from screen readers, as avatars in expandable headers are typically decorative when paired
|
|
59
|
-
> with adjacent text.
|
|
60
|
-
|
|
61
55
|
### Right to Left (RTL)
|
|
62
56
|
|
|
63
57
|
Expandable container has bidirectional support and should function as expected with RTL languages as
|
|
@@ -78,8 +72,6 @@ Long titles will wrap to the next line and increase the height of the container.
|
|
|
78
72
|
|
|
79
73
|
<ExampleCodeBlock code={LongTitle} />
|
|
80
74
|
|
|
81
|
-
You can also have direct access to the model if
|
|
82
|
-
|
|
83
75
|
### Hoisted Model
|
|
84
76
|
|
|
85
77
|
If you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In the
|
|
@@ -87,47 +79,161 @@ example below, we're hoisting the models to expand and collapse all three contai
|
|
|
87
79
|
|
|
88
80
|
<ExampleCodeBlock code={HoistedModel} />
|
|
89
81
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
> `aria-labelledby` to reference the unique `id` of the `<Expandable.Title>` element. This practice
|
|
93
|
-
> can be useful to screen reader users when multiple Expandable Containers are opened at one time
|
|
94
|
-
> for uniquely describing the boundaries of the expandable content.
|
|
82
|
+
For the accordion composition (named regions on each panel), see
|
|
83
|
+
[Accessibility Requirements](#accessibility-requirements).
|
|
95
84
|
|
|
96
85
|
## Accessibility
|
|
97
86
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
87
|
+
Ensure users of assistive technology can find the control, understand whether related content is
|
|
88
|
+
shown or hidden, and reveal or hide that content from the keyboard. **`Expandable`** is an inline
|
|
89
|
+
[disclosure (show/hide)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) widget: a button
|
|
90
|
+
toggles content that stays in the document flow.
|
|
91
|
+
|
|
92
|
+
Use **`Expandable`** for show/hide sections in the page. Compose multiple instances to build an
|
|
93
|
+
[accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) — see
|
|
94
|
+
[Hoisted Model](#hoisted-model). For a navigation accordion, see
|
|
95
|
+
[Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
|
|
96
|
+
|
|
97
|
+
### Minimum Accessible Structure
|
|
98
|
+
|
|
99
|
+
The following matches the [Start Icon](#start-icon) example layout: **`Expandable.Icon`** before
|
|
100
|
+
**`Expandable.Title`** inside **`Expandable.Target`**, then **`Expandable.Content`**.
|
|
101
|
+
**`headingLevel`** is omitted here on purpose — add it only after asking which level matches the
|
|
102
|
+
page outline (see **Accessibility Requirements**). The Basic Example code uses `headingLevel="h4"`
|
|
103
|
+
as a sample, not a default.
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
import {Expandable} from '@workday/canvas-kit-react/expandable';
|
|
107
|
+
|
|
108
|
+
<Expandable>
|
|
109
|
+
<Expandable.Target>
|
|
110
|
+
<Expandable.Icon iconPosition="start" />
|
|
111
|
+
<Expandable.Title>Title</Expandable.Title>
|
|
112
|
+
</Expandable.Target>
|
|
113
|
+
<Expandable.Content>Content</Expandable.Content>
|
|
114
|
+
</Expandable>;
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Built-in Behaviors
|
|
118
|
+
|
|
119
|
+
Canvas Kit applies these automatically via `useExpandableModel` (a `DisclosureModel`) and Expandable
|
|
120
|
+
subcomponents. **Do not duplicate them** in consuming code.
|
|
121
|
+
|
|
122
|
+
**ARIA and DOM** (_applied by hooks/subcomponents_):
|
|
123
|
+
|
|
124
|
+
- **`Expandable.Target`**: native `<button>` with `aria-expanded` (`true` when
|
|
125
|
+
`visibility !== 'hidden'`) and `aria-controls` set to the disclosure `id`. `onClick` toggles
|
|
126
|
+
`events.show()` / `events.hide()`.
|
|
127
|
+
- **`headingLevel`**: when set (`'h1'`–`'h6'`), wraps the button in **`Heading`** rendered as that
|
|
128
|
+
heading element. When omitted, the button is not wrapped in a heading.
|
|
129
|
+
- **`Expandable.Content`**: `id` set to the same disclosure `id`. Collapsed content stays in the DOM
|
|
130
|
+
with `display: none` (not unmounted). Default element is a `<div>`.
|
|
131
|
+
- **`Expandable.Title`**: styled `<div>` for the visible name. It does **not** receive an `id` from
|
|
132
|
+
the model.
|
|
133
|
+
- **`Expandable.Icon`**: decorative chevron that rotates from `visibility`. Expanded/collapsed state
|
|
134
|
+
for assistive technology comes from `aria-expanded`, not from the icon.
|
|
135
|
+
- **`Expandable.Avatar`**: `isDecorative={true}` by default so the image is hidden from assistive
|
|
136
|
+
technology when paired with **`Expandable.Title`**.
|
|
137
|
+
- Disclosure `id`: generated with `useUniqueId` unless you pass `id` to **`useExpandableModel`**.
|
|
138
|
+
Default `initialVisibility` is `'hidden'`.
|
|
139
|
+
|
|
140
|
+
**Keyboard** (_native button behavior_):
|
|
141
|
+
|
|
142
|
+
**`Expandable.Target`** uses native `<button>` keyboard behavior (tab order, <kbd>Enter</kbd> /
|
|
143
|
+
|
|
144
|
+
<kbd>Space</kbd> to toggle). Collapsed content is not in the tab order (`display: none`). Focus
|
|
145
|
+
stays on the button; Canvas Kit does not move focus into **`Expandable.Content`**.
|
|
146
|
+
|
|
147
|
+
**Screen reader expectations** (_when built-in behaviors are used as intended_):
|
|
148
|
+
|
|
149
|
+
- On focus, assistive technology announces the title text, the button role, and expanded/collapsed
|
|
150
|
+
state from `aria-expanded` (for example, "Title, button, collapsed")
|
|
151
|
+
- Activating the button announces the updated expanded/collapsed state from `aria-expanded`
|
|
152
|
+
- While collapsed, content is removed from the accessibility tree (`display: none`)
|
|
153
|
+
- While expanded, content follows the button in reading order
|
|
154
|
+
- When **`headingLevel`** is set, heading navigation includes the heading that wraps the button
|
|
155
|
+
- When **`Expandable.Content as="section"`** is used with `aria-labelledby` pointing at
|
|
156
|
+
**`Expandable.Title`**, region/landmark navigation can name each open section
|
|
157
|
+
|
|
158
|
+
### Accessibility Requirements
|
|
159
|
+
|
|
160
|
+
Required in application code for an accessible Expandable. Hoist **`useExpandableModel`** when you
|
|
161
|
+
need programmatic show/hide (for example, expand all) or a stable disclosure `id`. Rows marked
|
|
162
|
+
_(conditional)_ apply only when the situation matches—otherwise omit.
|
|
163
|
+
|
|
164
|
+
**If no design spec is provided:** use the **single disclosure** composition
|
|
165
|
+
([Basic Example](#basic-example)). If the spec is several related headers, use the **accordion**
|
|
166
|
+
composition. Omit **`Expandable.Avatar`**, **`initialVisibility`**, and a custom **`id`**.
|
|
167
|
+
|
|
168
|
+
**Choose a composition** (pick one; **`Expandable.Content as="section"`** and **`as="ul"`** are
|
|
169
|
+
mutually exclusive):
|
|
170
|
+
|
|
171
|
+
- **Single disclosure** — one show/hide section. [Basic Example](#basic-example) /
|
|
172
|
+
[Minimum Accessible Structure](#minimum-accessible-structure). Default Content is a `<div>`.
|
|
173
|
+
- **Accordion** — several related headers. [Hoisted Model](#hoisted-model): unique `id` on
|
|
174
|
+
**`Expandable.Title`**, **`Expandable.Content as="section"`** with `aria-labelledby`.
|
|
175
|
+
- **Navigation list** — disclosed links.
|
|
176
|
+
[Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs):
|
|
177
|
+
**`as="ul"`**, omit **`headingLevel`**.
|
|
178
|
+
|
|
179
|
+
**Heading level:** Ask which heading (`h1`–`h6`) belongs in the document outline before setting
|
|
180
|
+
**`headingLevel`**. Omit **`headingLevel`** for navigation. Do not generate **`headingLevel`** by
|
|
181
|
+
default — the Basic Example code uses `h4` only as a sample.
|
|
182
|
+
|
|
183
|
+
| Requirement | How to satisfy |
|
|
184
|
+
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
185
|
+
| Accessible name | Non-empty **`Expandable.Title`** inside **`Expandable.Target`**. |
|
|
186
|
+
| Keyboard-operable toggle | **`Expandable.Target`** (native `<button>`). |
|
|
187
|
+
| Visual expanded/collapsed indicator | **`Expandable.Icon`** with `iconPosition` matching layout (`start` or `end`). |
|
|
188
|
+
| Heading in the document outline _(conditional)_ | **`headingLevel`** on **`Expandable.Target`** when the control titles body content (single disclosure or accordion). Omit **`headingLevel`** for the navigation-list composition. Ask which level. |
|
|
189
|
+
| Accordion named regions _(conditional)_ | Accordion composition: **`Expandable.Content as="section"`** plus `aria-labelledby` referencing a unique `id` on **`Expandable.Title`**. |
|
|
190
|
+
| List markup _(conditional)_ | Navigation-list composition: **`Expandable.Content as="ul"`** (and list items as children). |
|
|
191
|
+
| Decorative avatar _(conditional)_ | **`Expandable.Avatar`** when the design includes an avatar. Keep **`isDecorative`** at the default `true`. |
|
|
192
|
+
| Start expanded _(conditional)_ | `initialVisibility: 'visible'` on **`useExpandableModel`** (or the equivalent model config). |
|
|
193
|
+
| Programmatic expand/collapse _(conditional)_ | Hoist **`useExpandableModel`** and call `model.events.show()` / `model.events.hide()`. |
|
|
194
|
+
|
|
195
|
+
**Summary for code generation:**
|
|
196
|
+
|
|
197
|
+
- **REQUIRED:** **`Expandable.Target`**, non-empty **`Expandable.Title`**, **`Expandable.Content`**,
|
|
198
|
+
**`Expandable.Icon`**
|
|
199
|
+
- **CONDITIONAL:** composition (single disclosure vs accordion vs navigation list),
|
|
200
|
+
**`headingLevel`** (ask which; omit for navigation), accordion **`as="section"`** +
|
|
201
|
+
`aria-labelledby`, navigation **`as="ul"`**, **`Expandable.Avatar`**, hoisted
|
|
202
|
+
**`useExpandableModel`**, **`initialVisibility`**
|
|
203
|
+
|
|
204
|
+
### Anti-Patterns
|
|
205
|
+
|
|
206
|
+
Do **not** generate code that does the following (see **Accessibility Requirements** above for what
|
|
207
|
+
to supply instead):
|
|
208
|
+
|
|
209
|
+
- Manually set `aria-expanded`, `aria-controls`, or the disclosure `id` on **`Expandable.Target`**
|
|
210
|
+
or **`Expandable.Content`** — `useExpandableTarget` and `useExpandableContent` wire these
|
|
211
|
+
- Rely on **`Expandable.Icon`** or **`Expandable.Avatar`** for the accessible name — use
|
|
212
|
+
**`Expandable.Title`**
|
|
213
|
+
- Override **`Expandable.Target`** with a custom **`as`** — **`Expandable.Target`** already renders
|
|
214
|
+
a native `<button>`
|
|
215
|
+
- Set `id` on **`Expandable`** to identify the outer wrapper — `id` is model config **and** is
|
|
216
|
+
forwarded to the container element, while **`Expandable.Content`** also uses `state.id`, which can
|
|
217
|
+
produce duplicate IDs. For a stable content `id`, hoist **`useExpandableModel({id: '…'})`**.
|
|
218
|
+
**`Expandable.Title`** still needs its own `id` when you set `aria-labelledby` on
|
|
219
|
+
**`Expandable.Content`**
|
|
220
|
+
- Wrap **`Expandable.Target`** in your own heading — use **`headingLevel`** instead
|
|
221
|
+
- Default **`headingLevel`** to `h4` (or any level) without asking, or set **`headingLevel`** on
|
|
222
|
+
navigation disclosures
|
|
223
|
+
- Generate several Basic Example disclosures with default `div` Content when the spec is an
|
|
224
|
+
accordion — use the **accordion** composition (see **Choose a composition**)
|
|
225
|
+
- Set **`as="section"`** and **`as="ul"`** on the same **`Expandable.Content`** — pick one
|
|
226
|
+
composition
|
|
227
|
+
- Change **`Expandable.Title`** to encode state (for example "Collapsed" / "Expanded" or "Show" /
|
|
228
|
+
"Hide") — `aria-expanded` already exposes state
|
|
229
|
+
- Unmount **`Expandable.Content`** when collapsed, or add `aria-hidden` on it — the library uses
|
|
230
|
+
`display: none`
|
|
231
|
+
- Set **`isDecorative={false}`** on **`Expandable.Avatar`** by default, or pair an avatar with an
|
|
232
|
+
extra non-chevron icon
|
|
233
|
+
- Use **`open`**, **`expanded`**, or **`onToggle`** props on **`Expandable`** — visibility is
|
|
234
|
+
`initialVisibility` plus **`useExpandableModel`** events
|
|
235
|
+
- Assume default **`Expandable.Content`** is a landmark region — that is only true with
|
|
236
|
+
**`as="section"`**
|
|
131
237
|
|
|
132
238
|
## Component API
|
|
133
239
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workday/canvas-kit-docs",
|
|
3
|
-
"version": "16.2.0-
|
|
3
|
+
"version": "16.2.0-0612-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",
|
|
@@ -47,10 +47,10 @@
|
|
|
47
47
|
"@stackblitz/sdk": "^1.11.0",
|
|
48
48
|
"@storybook/csf": "0.0.1",
|
|
49
49
|
"@workday/canvas-expressive-icons-web": "1.0.2",
|
|
50
|
-
"@workday/canvas-kit-labs-react": "^16.2.0-
|
|
51
|
-
"@workday/canvas-kit-preview-react": "^16.2.0-
|
|
52
|
-
"@workday/canvas-kit-react": "^16.2.0-
|
|
53
|
-
"@workday/canvas-kit-styling": "^16.2.0-
|
|
50
|
+
"@workday/canvas-kit-labs-react": "^16.2.0-0612-next.0",
|
|
51
|
+
"@workday/canvas-kit-preview-react": "^16.2.0-0612-next.0",
|
|
52
|
+
"@workday/canvas-kit-react": "^16.2.0-0612-next.0",
|
|
53
|
+
"@workday/canvas-kit-styling": "^16.2.0-0612-next.0",
|
|
54
54
|
"@workday/canvas-system-icons-web": "^5.0.3",
|
|
55
55
|
"@workday/canvas-tokens-web": "^4.4.0",
|
|
56
56
|
"markdown-to-jsx": "^7.2.0",
|
|
@@ -63,5 +63,5 @@
|
|
|
63
63
|
"mkdirp": "^1.0.3",
|
|
64
64
|
"typescript": "5.0"
|
|
65
65
|
},
|
|
66
|
-
"gitHead": "
|
|
66
|
+
"gitHead": "11919e5ffbe1b947f0e5d156e1efc91dfeffd259"
|
|
67
67
|
}
|