@workday/canvas-kit-docs 12.0.0-alpha.918-next.0 → 12.0.0-alpha.921-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 +9890 -308
- package/dist/mdx/10.0-UPGRADE-GUIDE.mdx +3 -14
- package/dist/mdx/12.0-UPGRADE-GUIDE.mdx +18 -3
- package/dist/mdx/5.0-UPGRADE-GUIDE.mdx +36 -62
- package/dist/mdx/6.0-UPGRADE-GUIDE.mdx +5 -12
- package/dist/mdx/7.0-UPGRADE-GUIDE.mdx +8 -15
- package/dist/mdx/MAINTAINING.mdx +5 -12
- package/dist/mdx/preview-react/menu/Menu.mdx +7 -13
- package/dist/mdx/preview-react/multi-select/MultiSelect.mdx +98 -0
- package/dist/mdx/preview-react/multi-select/examples/Basic.tsx +30 -0
- package/dist/mdx/preview-react/multi-select/examples/Complex.tsx +75 -0
- package/dist/mdx/preview-react/multi-select/examples/Controlled.tsx +92 -0
- package/dist/mdx/preview-react/multi-select/examples/Icons.tsx +43 -0
- package/dist/mdx/preview-react/multi-select/examples/Searching.tsx +123 -0
- package/dist/mdx/react/action-bar/examples/OverflowActionBar.tsx +1 -0
- package/dist/mdx/react/button/button/Button.mdx +3 -2
- package/dist/mdx/react/combobox/Combobox.mdx +4 -1
- package/dist/mdx/react/menu/Menu.mdx +6 -12
- package/dist/mdx/react/status-indicator/StatusIndicator.mdx +6 -12
- package/package.json +6 -6
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
|
-
|
|
4
1
|
# Canvas Kit 10.0 Upgrade Guide
|
|
5
2
|
|
|
6
3
|
This guide contains an overview of the changes in Canvas Kit v10. Please
|
|
@@ -161,8 +158,6 @@ updated on a 1:1 basis. None of the base values have changed, only the unit.
|
|
|
161
158
|
The table below shows what each token value is, what it corresponds to, and what the new `rem` value
|
|
162
159
|
is in `px`:
|
|
163
160
|
|
|
164
|
-
<Markdown>
|
|
165
|
-
{`
|
|
166
161
|
| px Value | rem Value | space Token |
|
|
167
162
|
| -------- | --------- | ----------- |
|
|
168
163
|
| 0 | 0 | zero |
|
|
@@ -175,23 +170,17 @@ is in `px`:
|
|
|
175
170
|
| 40px | 2.5rem | xl |
|
|
176
171
|
| 64px | 4rem | xxl |
|
|
177
172
|
| 80px | 5rem | xxxl |
|
|
178
|
-
`}
|
|
179
|
-
</Markdown>
|
|
180
173
|
|
|
181
174
|
You can convert a `px` value to a `rem` value by dividing your `px` value by `16`(if your default
|
|
182
175
|
browser font size hasn't been updated, the value will be `16`).
|
|
183
176
|
|
|
184
177
|
For example:
|
|
185
178
|
|
|
186
|
-
<Markdown>
|
|
187
|
-
{`
|
|
188
179
|
| Equation | rem Value |
|
|
189
180
|
| ----------- | --------- |
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
`}
|
|
194
|
-
</Markdown>
|
|
181
|
+
| `16px/16px` | `1rem` |
|
|
182
|
+
| `32px/16px` | `2rem` |
|
|
183
|
+
| `8px/16px` | `0.5rem` |
|
|
195
184
|
|
|
196
185
|
#### Why Did We Make This Change?
|
|
197
186
|
|
|
@@ -43,16 +43,17 @@ A note to the reader:
|
|
|
43
43
|
- [Component Updates](#component-updates)
|
|
44
44
|
- [Styling API and CSS Tokens](#styling-api-and-css-tokens)
|
|
45
45
|
- [Avatar](#avatar)
|
|
46
|
+
- [Collections](#collections)
|
|
46
47
|
- [Combobox](#combmbox)
|
|
47
48
|
- [Form Field](#form-field)
|
|
48
49
|
- [Form Field Group](#form-field-group)
|
|
49
50
|
- [Form Field Field](#form-field-field)
|
|
50
51
|
- [Menu Item](#menu-item)
|
|
52
|
+
- [MultiSelect](#multiselect)
|
|
51
53
|
- [Search Form](#search-form)
|
|
52
54
|
- [Select](#select)
|
|
53
55
|
- [Text Area](#text-area)
|
|
54
56
|
- [Text Input](#text-input)
|
|
55
|
-
- [Collections](#collections)
|
|
56
57
|
- [Utility Updates](#utility-updates)
|
|
57
58
|
- [Troubleshooting](#troubleshooting)
|
|
58
59
|
- [Glossary](#glossary)
|
|
@@ -487,9 +488,9 @@ this sub-component when using `FormField`. This component also exists on `FormFi
|
|
|
487
488
|
|
|
488
489
|
### Menu Item
|
|
489
490
|
|
|
490
|
-
**PR
|
|
491
|
+
**PR:** [2969](https://github.com/Workday/canvas-kit/pull/2969)
|
|
491
492
|
|
|
492
|
-
`Menu.Item` was converted to use Stencils for styling and uses SystemIcon stencil variables to
|
|
493
|
+
`Menu.Item` was converted to use Stencils for styling and uses `SystemIcon` stencil variables to
|
|
493
494
|
change icon color instead of deeply nested selectors. We also added `Menu.Option` component for
|
|
494
495
|
menus that have a selected visual state. `Menu.Option` will need more accessibility affordances that
|
|
495
496
|
depend on the nature of your use of the `Menu` component. For example, `<Combobox>` and `<Select>`
|
|
@@ -505,6 +506,20 @@ We've removed the `MenuItemProps` export from `@workday/canvas-kit-react/menu`.
|
|
|
505
506
|
polymorphic components. The `never` means "don't add element props". The second parameter is used to
|
|
506
507
|
pass the interface that the `as` prop is pointing to.
|
|
507
508
|
|
|
509
|
+
`Menu.Item` no longer sets `aria-selected` since that attribute is not valid on a `role=menuitem`.
|
|
510
|
+
The `Menu.Option` was added to support the role of a `role=option` for going inside a
|
|
511
|
+
`role=listbox`. The `Combobox` family of components uses a `role=listbox` for menu options. The
|
|
512
|
+
`Menu.Option` renders a checkmark for a visual indication of selected options.
|
|
513
|
+
|
|
514
|
+
### MultiSelect
|
|
515
|
+
|
|
516
|
+
**PR:** [2911](https://github.com/Workday/canvas-kit/pull/2911)
|
|
517
|
+
|
|
518
|
+
Added the `MultiSelect` component to select more than one option from a list of options. The
|
|
519
|
+
`MultiSelect` is similar in API to the `Select` component, except the values are comma delimited
|
|
520
|
+
with a space. If the ids represented are `['1', '2']`, then the string value of the form field is
|
|
521
|
+
`'1, 2'`.
|
|
522
|
+
|
|
508
523
|
### Search Form (Labs)
|
|
509
524
|
|
|
510
525
|
**PRs:** [#2934](https://github.com/Workday/canvas-kit/pull/2934),
|
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
|
-
|
|
4
1
|
# Canvas Kit 5.0 Upgrade Guide
|
|
5
2
|
|
|
6
3
|
Below are the breaking changes made in Canvas Kit v5. Please
|
|
@@ -123,51 +120,43 @@ updated as you expect.
|
|
|
123
120
|
tokens in `@workday/canvas-kit-labs-react-core`, but some are using the Legacy type in
|
|
124
121
|
`@workday/canvas-kit-react-core`.
|
|
125
122
|
|
|
126
|
-
<Markdown>{`
|
|
127
123
|
| Legacy Type (px) | Responsive Type (rem) |
|
|
128
124
|
| ----------------- | ---------------------------------------- |
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
|
|
|
135
|
-
|
|
|
136
|
-
|
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
`}</Markdown>
|
|
125
|
+
| `dataViz1` (56px) | `levels.title.large` (3.5rem \ 56px) |
|
|
126
|
+
| `dataViz2` (34px) | `levels.heading.large` (2rem \ 32px) |
|
|
127
|
+
| `h1` (28px) | `levels.heading.medium` (1.75rem \ 28px) |
|
|
128
|
+
| `h2` (24px) | `levels.heading.small` (1.5rem \ 24px) |
|
|
129
|
+
| `h3` (20px) | `levels.body.large` (1.25rem,) \ 20px |
|
|
130
|
+
| `h4` (16px) | `levels.body.small` (1rem \ 16px) |
|
|
131
|
+
| `h5` (16px) | `levels.body.small` (1rem \ 16px) |
|
|
132
|
+
| `body` (14px) | `levels.subtext.large` (0.875rem \ 14px) |
|
|
133
|
+
| `body2` (13px) | `levels.subtext.medium` (0.75rem \ 12px) |
|
|
134
|
+
| `small` (12px) | `levels.subtext.medium` (0.75rem \ 12px) |
|
|
140
135
|
|
|
141
136
|
- 🤖 Property Updates
|
|
142
137
|
|
|
143
138
|
All `fontFamily`, `fontSize`, and `fontWeight` property updates are handled by the codemod.
|
|
144
139
|
|
|
145
|
-
|
|
146
|
-
{`| CSS Property | Corresponding Token | Notes |
|
|
140
|
+
| CSS Property | Corresponding Token | Notes |
|
|
147
141
|
| ------------ | ------------------------------ | --------------------------------------------------------------- |
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
</Markdown>
|
|
142
|
+
| `fontFamily` | `type.properties.fontFamilies` | `default` (Roboto) and `monospace` (Roboto Mono) are available |
|
|
143
|
+
| `fontSize` | `type.properties.fontSizes` | please consult the type hierarchies above to map values |
|
|
144
|
+
| `fontWeight` | `type.properties.fontWeights` | `regular` (400), `medium` (500), and `bold` (700) are available |
|
|
152
145
|
|
|
153
146
|
- 🤖 Variant Updates
|
|
154
147
|
|
|
155
148
|
All `variant` updates _except `link`_ are handled by the codemod. Please see the
|
|
156
149
|
[variants](#variants) section below for more information.
|
|
157
150
|
|
|
158
|
-
<Markdown>
|
|
159
|
-
{`
|
|
160
151
|
| Variant | Transformation | Notes |
|
|
161
152
|
| ---------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
|
169
|
-
`}
|
|
170
|
-
</Markdown>
|
|
153
|
+
| `type.variant.error` | `type.variants.error` | name change only |
|
|
154
|
+
| `type.variant.hint` | `type.variants.hint` | name change only |
|
|
155
|
+
| `type.variant.inverse` | `type.variants.inverse` | name change only |
|
|
156
|
+
| `type.variant.button` | `{fontWeight: type.properties.fontWeights.bold}` | variant deprecated, use type properties |
|
|
157
|
+
| `type.variant.caps` | `{textTransform: 'uppercase', fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties |
|
|
158
|
+
| `type.variant.label` | `{fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties |
|
|
159
|
+
| `type.variant.mono` | `{fontFamily: type.properties.fontFamilies.monospace}` | variant deprecated, use type properties |
|
|
171
160
|
|
|
172
161
|
#### Manual Updates
|
|
173
162
|
|
|
@@ -635,20 +624,14 @@ types (which were too generic) and their JSDoc hints.
|
|
|
635
624
|
|
|
636
625
|
The following table describes each update:
|
|
637
626
|
|
|
638
|
-
<Markdown>
|
|
639
|
-
{`
|
|
640
627
|
| Before | After | Change Description |
|
|
641
628
|
| --------------------- | ------------------------- | -------------------------------- |
|
|
642
|
-
|
|
|
643
|
-
|
|
|
644
|
-
|
|
|
645
|
-
|
|
|
646
|
-
|
|
|
647
|
-
|
|
|
648
|
-
|
|
649
|
-
`}
|
|
650
|
-
|
|
651
|
-
</Markdown>
|
|
629
|
+
| `spacing` | `space` | name change only |
|
|
630
|
+
| `spacingNumbers` | `spaceNumbers` | name change only |
|
|
631
|
+
| `CanvasSpacing` | `CanvasSpace` | name change and improved types\* |
|
|
632
|
+
| `CanvasSpacingValue` | `CanvasSpaceValues` | name change only |
|
|
633
|
+
| `CanvasSpacingNumber` | `CanvasSpaceNumbers` | name change and improved types\* |
|
|
634
|
+
| `n/a` | `CanvasSpaceNumberValues` | new type! |
|
|
652
635
|
|
|
653
636
|
\* Before, the types were too generic and not very useful. They now better reflect the values they
|
|
654
637
|
represent.
|
|
@@ -1201,18 +1184,14 @@ Pass a `css` prop or a styled button instead to have a custom styled button. You
|
|
|
1201
1184
|
|
|
1202
1185
|
If you were using `usePopup` before, here's a list of equivalent APIs:
|
|
1203
1186
|
|
|
1204
|
-
<Markdown>
|
|
1205
|
-
{`
|
|
1206
1187
|
| Before | After |
|
|
1207
1188
|
| ----------------------------------------------------------------------- | ------------------------------------- |
|
|
1208
|
-
|
|
|
1209
|
-
|
|
|
1210
|
-
|
|
|
1211
|
-
|
|
|
1212
|
-
|
|
|
1213
|
-
|
|
|
1214
|
-
`}
|
|
1215
|
-
</Markdown>
|
|
1189
|
+
| `const { popperProps, targetProps, closePopup, stackRef } = usePopup()` | `const model = usePopupModel()` |
|
|
1190
|
+
| `popperProps.open` | `model.state.visibility !== 'hidden'` |
|
|
1191
|
+
| `closePopup()` | `model.events.hide()` |
|
|
1192
|
+
| `stackRef` or `popperProps.ref` | `model.state.stackRef` |
|
|
1193
|
+
| `popperProps.anchorElement` | `model.state.targetRef.current` |
|
|
1194
|
+
| `targetProps.onClick` | `usePopupTarget(model).onClick` |
|
|
1216
1195
|
|
|
1217
1196
|
#### New Focus Management
|
|
1218
1197
|
|
|
@@ -1287,16 +1266,11 @@ model and behaviors, the following is equivalent:
|
|
|
1287
1266
|
|
|
1288
1267
|
`Popup.Card` uses `Card`, which is now using `Box`. Consequently, the following props have changed:
|
|
1289
1268
|
|
|
1290
|
-
<Markdown>
|
|
1291
|
-
{`
|
|
1292
1269
|
| Before | After |
|
|
1293
1270
|
| ------------------------------ | ------------------------------------------ |
|
|
1294
|
-
|
|
|
1295
|
-
|
|
|
1296
|
-
|
|
|
1297
|
-
`}
|
|
1298
|
-
|
|
1299
|
-
</Markdown>
|
|
1271
|
+
| `padding={Popup.Padding.zero}` | `padding="zero"` or `padding={space.zero}` |
|
|
1272
|
+
| `depth={depth[0]}` | `depth={0}` |
|
|
1273
|
+
| `popupRef={ref}` | `ref={ref}` |
|
|
1300
1274
|
|
|
1301
1275
|
#### Transitioning
|
|
1302
1276
|
|
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
|
-
|
|
4
1
|
# Canvas Kit 6.0 Upgrade Guide
|
|
5
2
|
|
|
6
3
|
Below are the breaking changes made in Canvas Kit v6. Please
|
|
@@ -368,17 +365,13 @@ layout. If you have questions about this testing, please reach out to our team.
|
|
|
368
365
|
|
|
369
366
|
Below is a reference table for the V5 and V6 breakpoint values.
|
|
370
367
|
|
|
371
|
-
<Markdown>
|
|
372
|
-
{`
|
|
373
368
|
| Breakpoint Name | V5 Value (px) | V6 Value (px) |
|
|
374
369
|
| --------------- | ------------- | ------------- |
|
|
375
|
-
|
|
|
376
|
-
|
|
|
377
|
-
|
|
|
378
|
-
|
|
|
379
|
-
|
|
|
380
|
-
`}
|
|
381
|
-
</Markdown>
|
|
370
|
+
| `zero` | 0 | 0 |
|
|
371
|
+
| `s` | 600 | 320 |
|
|
372
|
+
| `m` | 900 | 768 |
|
|
373
|
+
| `l` | 1280 | 1024 |
|
|
374
|
+
| `xl` | 1920 | 1440 |
|
|
382
375
|
|
|
383
376
|
Also for reference, these are our viewport ranges:
|
|
384
377
|
|
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
|
-
|
|
4
1
|
# Canvas Kit 7.0 Upgrade Guide
|
|
5
2
|
|
|
6
3
|
This guide contains breaking changes in Canvas Kit v7. Please
|
|
@@ -562,19 +559,15 @@ To consolidate Button APIs, we've removed `IconButton` in favor of `SecondaryBut
|
|
|
562
559
|
`TertiaryButton`. The following table shows how `IconButton` variants in v6 map to their
|
|
563
560
|
corresponding buttons in v7.
|
|
564
561
|
|
|
565
|
-
|
|
566
|
-
{`
|
|
567
|
-
| v6 \`IconButton\` variant | v7 button (and variant, if necessary) |
|
|
562
|
+
| v6 `IconButton` variant | v7 button (and variant, if necessary) |
|
|
568
563
|
| -------------------------- | ---------------------------------------- |
|
|
569
|
-
|
|
|
570
|
-
|
|
|
571
|
-
|
|
|
572
|
-
|
|
|
573
|
-
|
|
|
574
|
-
|
|
|
575
|
-
|
|
|
576
|
-
`}
|
|
577
|
-
</Markdown>
|
|
564
|
+
| `circle` (default variant) | `TertiaryButton` |
|
|
565
|
+
| `circleFilled` | `SecondaryButton` |
|
|
566
|
+
| `inverse` | `TertiaryButton` with `inverse` variant |
|
|
567
|
+
| `inverseFilled` | `SecondaryButton` with `inverse` variant |
|
|
568
|
+
| `plain` | Unsupported |
|
|
569
|
+
| `square` | Unsupported |
|
|
570
|
+
| `squareFilled` | Unsupported |
|
|
578
571
|
|
|
579
572
|
> Note: See below for more information about how to manually migrate from
|
|
580
573
|
> [unsupported v6 variants](#unsupported-iconbutton-variants).
|
package/dist/mdx/MAINTAINING.mdx
CHANGED
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
|
-
|
|
4
1
|
# Maintaining Canvas Kit
|
|
5
2
|
|
|
6
3
|
If you're a Canvas Kit core maintainer, this doc is for you! Consider this a field guide to help you
|
|
@@ -51,17 +48,13 @@ runs on `support`, `master`, and `prerelease/minor` branches. Forward merges for
|
|
|
51
48
|
starts with `chore: Release`, and that's how the forward merge workflow identifies them. Forward
|
|
52
49
|
merges will run on every merge to `prerelease/minor` regardless of the commit message.
|
|
53
50
|
|
|
54
|
-
<Markdown>
|
|
55
|
-
{`
|
|
56
51
|
| Run Forward Merge? | Branch | Commit Message |
|
|
57
52
|
| ------------------ | ------------------ | --------------------------------------- |
|
|
58
|
-
| ✅ |
|
|
59
|
-
| ⛔️ |
|
|
60
|
-
| ✅ |
|
|
61
|
-
| ⛔️ |
|
|
62
|
-
| ✅ |
|
|
63
|
-
`}
|
|
64
|
-
</Markdown>
|
|
53
|
+
| ✅ | `support` | `chore: Release v6.8.14 [skip release]` |
|
|
54
|
+
| ⛔️ | `support` | `fix: Remove unused props` |
|
|
55
|
+
| ✅ | `master` | `chore: Release v7.3.0 [skip release]` |
|
|
56
|
+
| ⛔️ | `master` | `fix: Update Popup types` |
|
|
57
|
+
| ✅ | `prerelease/minor` | `feat: Add new Layout components` |
|
|
65
58
|
|
|
66
59
|
If the forward merge workflow fails and cannot automatically merge the update to the next branch, it
|
|
67
60
|
will generate a PR with instructions on how to handle the forward merge manually. For a more
|
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
import {Markdown} from '@storybook/blocks';
|
|
2
|
-
|
|
3
1
|
import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
|
|
4
2
|
import {StatusIndicator} from '@workday/canvas-kit-preview-react/status-indicator';
|
|
5
3
|
import Basic from './examples/Basic';
|
|
@@ -50,19 +48,15 @@ closing the `DeprecatedMenu`.
|
|
|
50
48
|
using `aria-activedescendant`. Below is table of supported keyboard shortcuts and associated
|
|
51
49
|
actions.
|
|
52
50
|
|
|
53
|
-
<Markdown>
|
|
54
|
-
{`
|
|
55
51
|
| Key | Action |
|
|
56
52
|
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
|
|
|
64
|
-
`}
|
|
65
|
-
</Markdown>
|
|
53
|
+
| `Enter` or `Space` | Activates the menu item and then closes the menu |
|
|
54
|
+
| `Escape` | Closes the menu |
|
|
55
|
+
| `Up Arrow` | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
|
|
56
|
+
| `Down Arrow` | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item |
|
|
57
|
+
| `Home` | Moves focus to the first menu item |
|
|
58
|
+
| `End` | Moves focus to the last menu item |
|
|
59
|
+
| `A-Z / a-z` | Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists – otherwise, focus does not move |
|
|
66
60
|
|
|
67
61
|
Note that although `DeprecatedMenu` includes support for keyboard shortcuts for the menu itself,
|
|
68
62
|
you'll need to add your own keyboard handling and aria attributes to the triggering button.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import {
|
|
2
|
+
ExampleCodeBlock,
|
|
3
|
+
InformationHighlight,
|
|
4
|
+
SymbolDoc,
|
|
5
|
+
Specifications,
|
|
6
|
+
} from '@workday/canvas-kit-docs';
|
|
7
|
+
|
|
8
|
+
import Basic from './examples/Basic';
|
|
9
|
+
import Complex from './examples/Complex';
|
|
10
|
+
import Icons from './examples/Icons';
|
|
11
|
+
import Controlled from './examples/Controlled';
|
|
12
|
+
import Searching from './examples/Searching';
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
# Canvas Kit MultiSelect
|
|
16
|
+
|
|
17
|
+
MultiSelect inputs allow users to choose multiple options from a list of items.
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
yarn add @workday/canvas-kit-preview-react
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
### Basic Example
|
|
28
|
+
|
|
29
|
+
`MultiSelect` supports a
|
|
30
|
+
[dynamic API](/getting-started/for-developers/resources/collection-api/#dynamic-items) where you
|
|
31
|
+
pass an array of items via the `items` prop and provide a render function to display the items. The
|
|
32
|
+
items may be provided as an
|
|
33
|
+
[array of strings](/getting-started/for-developers/resources/collection-api/#array-of-strings) or an
|
|
34
|
+
[array of objects](/getting-started/for-developers/resources/collection-api/#array-of-objects).
|
|
35
|
+
|
|
36
|
+
`MultiSelect` should be used in tandem with [Form Field](/components/inputs/form-field/) where the
|
|
37
|
+
`MultiSelect` wraps the `FormField` element and the `FormField` element wraps the children of
|
|
38
|
+
`MultiSelect` to meet accessibility standards. This ensures the `label` text from `FormField` is
|
|
39
|
+
attached to the `MultiSelect.Input` and read out as a group for voiceover.
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
<MultiSelect items={options}>
|
|
43
|
+
<FormField label="Your Label">
|
|
44
|
+
<MultiSelect.Input onChange={e => handleChange(e)} id="contact-multi-select" />
|
|
45
|
+
<MultiSelect.Popper>
|
|
46
|
+
<MultiSelect.Card>
|
|
47
|
+
<MultiSelect.List>
|
|
48
|
+
{item => <MultiSelect.Item>{item.id}</MultiSelect.Item>}
|
|
49
|
+
</MultiSelect.List>
|
|
50
|
+
</MultiSelect.Card>
|
|
51
|
+
</MultiSelect.Popper>
|
|
52
|
+
</FormField>
|
|
53
|
+
</MultiSelect>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
<ExampleCodeBlock code={Basic} />
|
|
57
|
+
|
|
58
|
+
### Complex
|
|
59
|
+
|
|
60
|
+
When registering items in an array of objects, it's common to have the text that is displayed to the
|
|
61
|
+
user be different than an id. In this example, `serverId` and `label` properties need to be remapped
|
|
62
|
+
to `id` and `text` hence the usage of `getId` and `getTextValue`. If your object has the properties
|
|
63
|
+
`text` and `id`, there would be no need for this.
|
|
64
|
+
|
|
65
|
+
<ExampleCodeBlock code={Complex} />
|
|
66
|
+
|
|
67
|
+
### With Icons
|
|
68
|
+
|
|
69
|
+
Use `MultiSelect.Item.Icon` to render an icon for a `MultiSelect.Item`. The `icon` prop for
|
|
70
|
+
`MultiSelect.Item.Icon` accepts [system icons](/assets/system-icons/) from
|
|
71
|
+
`@workday/canvas-system-icons-web`.
|
|
72
|
+
|
|
73
|
+
> **Note: `data-id` on `MultiSelect.Item` must match the `id` property in your array of objects.
|
|
74
|
+
> This ensures proper keyboard handling and type-ahead.**
|
|
75
|
+
|
|
76
|
+
<ExampleCodeBlock code={Icons} />
|
|
77
|
+
|
|
78
|
+
### Controlled
|
|
79
|
+
|
|
80
|
+
The MultiSelect can be a controlled input component by passing the `value` and `onChange` to either
|
|
81
|
+
the `<MultiSelect>` component or the `<MultiSelect.Input>` component. Internally, the
|
|
82
|
+
`MultiSelect.Input` watches for changes on the `value` React prop as well as the `value` DOM
|
|
83
|
+
property and will update the model accordingly.
|
|
84
|
+
|
|
85
|
+
<ExampleCodeBlock code={Controlled} />
|
|
86
|
+
|
|
87
|
+
### Searching
|
|
88
|
+
|
|
89
|
+
A MultiSelect input can be used as a filter for results. Most likely this also means there are many
|
|
90
|
+
items that may not be all be loaded from the server at once. The `useComboboxLoader` can be used to
|
|
91
|
+
dynamically load items as the user navigates the available options.
|
|
92
|
+
|
|
93
|
+
> **Note:** The behavior of search is experimental. The example should continue to work without
|
|
94
|
+
> modification, but how the searchable input is presented to the user may change with user testing.
|
|
95
|
+
> Don't rely too much on the exact behavior of the search input. For example, the search input may
|
|
96
|
+
> be cleared when the user blurs the field.
|
|
97
|
+
|
|
98
|
+
<ExampleCodeBlock code={Searching} />
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
|
|
3
|
+
import {FormField} from '@workday/canvas-kit-react/form-field';
|
|
4
|
+
import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
|
|
5
|
+
|
|
6
|
+
const items = ['Cheese', 'Olives', 'Onions', 'Pepperoni', 'Peppers'];
|
|
7
|
+
|
|
8
|
+
export default () => {
|
|
9
|
+
return (
|
|
10
|
+
<>
|
|
11
|
+
<MultiSelect items={items}>
|
|
12
|
+
<FormField orientation="horizontal">
|
|
13
|
+
<FormField.Label>Toppings</FormField.Label>
|
|
14
|
+
<FormField.Input as={MultiSelect.Input} placeholder="Select Multiple" />
|
|
15
|
+
<MultiSelect.Popper>
|
|
16
|
+
<MultiSelect.Card>
|
|
17
|
+
<MultiSelect.List>
|
|
18
|
+
{item => (
|
|
19
|
+
<MultiSelect.Item data-id={item}>
|
|
20
|
+
<MultiSelect.Item.Text>{item}</MultiSelect.Item.Text>
|
|
21
|
+
</MultiSelect.Item>
|
|
22
|
+
)}
|
|
23
|
+
</MultiSelect.List>
|
|
24
|
+
</MultiSelect.Card>
|
|
25
|
+
</MultiSelect.Popper>
|
|
26
|
+
</FormField>
|
|
27
|
+
</MultiSelect>
|
|
28
|
+
</>
|
|
29
|
+
);
|
|
30
|
+
};
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
|
|
3
|
+
import {CanvasProvider} from '@workday/canvas-kit-react/common';
|
|
4
|
+
import {createStyles} from '@workday/canvas-kit-styling';
|
|
5
|
+
import {FormField} from '@workday/canvas-kit-react/form-field';
|
|
6
|
+
|
|
7
|
+
import {system} from '@workday/canvas-tokens-web';
|
|
8
|
+
|
|
9
|
+
import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
|
|
10
|
+
|
|
11
|
+
const mainContentStyles = createStyles({
|
|
12
|
+
padding: system.space.x4,
|
|
13
|
+
});
|
|
14
|
+
|
|
15
|
+
const items = [
|
|
16
|
+
{id: '1', text: 'Cheese'},
|
|
17
|
+
{id: '2', text: 'Olives'},
|
|
18
|
+
{id: '3', text: 'Onions'},
|
|
19
|
+
{id: '4', text: 'Pepperoni'},
|
|
20
|
+
{id: '5', text: 'Peppers'},
|
|
21
|
+
];
|
|
22
|
+
|
|
23
|
+
export default () => {
|
|
24
|
+
const [value, setValue] = React.useState('');
|
|
25
|
+
const [label, setLabel] = React.useState('');
|
|
26
|
+
return (
|
|
27
|
+
<CanvasProvider>
|
|
28
|
+
<>
|
|
29
|
+
<form
|
|
30
|
+
onSubmit={e => {
|
|
31
|
+
console.log('form submitted');
|
|
32
|
+
e.preventDefault();
|
|
33
|
+
}}
|
|
34
|
+
>
|
|
35
|
+
<main className={mainContentStyles}>
|
|
36
|
+
<MultiSelect items={items} getId={i => i.id} getTextValue={i => i.text}>
|
|
37
|
+
<FormField orientation="horizontal">
|
|
38
|
+
<FormField.Label>Toppings</FormField.Label>
|
|
39
|
+
<FormField.Input
|
|
40
|
+
as={MultiSelect.Input}
|
|
41
|
+
placeholder="Select Multiple"
|
|
42
|
+
name="toppings"
|
|
43
|
+
onChange={e => {
|
|
44
|
+
const value = e.currentTarget.value;
|
|
45
|
+
setValue(value);
|
|
46
|
+
setLabel(
|
|
47
|
+
value
|
|
48
|
+
.split(', ')
|
|
49
|
+
.map(item => items.find(i => i.id === item)?.text || 'Not Found')
|
|
50
|
+
.join(', ')
|
|
51
|
+
);
|
|
52
|
+
}}
|
|
53
|
+
value={value}
|
|
54
|
+
/>
|
|
55
|
+
<MultiSelect.Popper>
|
|
56
|
+
<MultiSelect.Card>
|
|
57
|
+
<MultiSelect.List>
|
|
58
|
+
{item => (
|
|
59
|
+
<MultiSelect.Item data-id={item.id}>
|
|
60
|
+
<MultiSelect.Item.Text>{item.text}</MultiSelect.Item.Text>
|
|
61
|
+
</MultiSelect.Item>
|
|
62
|
+
)}
|
|
63
|
+
</MultiSelect.List>
|
|
64
|
+
</MultiSelect.Card>
|
|
65
|
+
</MultiSelect.Popper>
|
|
66
|
+
</FormField>
|
|
67
|
+
</MultiSelect>
|
|
68
|
+
</main>
|
|
69
|
+
</form>
|
|
70
|
+
<div>Selected IDs: {value}</div>
|
|
71
|
+
<div>Selected Labels: {label}</div>
|
|
72
|
+
</>
|
|
73
|
+
</CanvasProvider>
|
|
74
|
+
);
|
|
75
|
+
};
|