@workday/canvas-kit-docs 12.0.0-alpha.918-next.0 → 12.0.0-alpha.919-next.0

package/dist/mdx/12.0-UPGRADE-GUIDE.mdx

@@ -43,16 +43,17 @@ A note to the reader:
 - [Component Updates](#component-updates)
   - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
   - [Avatar](#avatar)
+  - [Collections](#collections)
   - [Combobox](#combmbox)
   - [Form Field](#form-field)
     - [Form Field Group](#form-field-group)
     - [Form Field Field](#form-field-field)
   - [Menu Item](#menu-item)
+  - [MultiSelect](#multiselect)
   - [Search Form](#search-form)
   - [Select](#select)
   - [Text Area](#text-area)
   - [Text Input](#text-input)
-  - [Collections](#collections)
 - [Utility Updates](#utility-updates)
 - [Troubleshooting](#troubleshooting)
 - [Glossary](#glossary)
@@ -487,9 +488,9 @@ this sub-component when using `FormField`. This component also exists on `FormFi
 
 ### Menu Item
 
-**PR: ** [2969](https://github.com/Workday/canvas-kit/pull/2969)
+**PR:** [2969](https://github.com/Workday/canvas-kit/pull/2969)
 
-`Menu.Item` was converted to use Stencils for styling and uses SystemIcon stencil variables to
+`Menu.Item` was converted to use Stencils for styling and uses `SystemIcon` stencil variables to
 change icon color instead of deeply nested selectors. We also added `Menu.Option` component for
 menus that have a selected visual state. `Menu.Option` will need more accessibility affordances that
 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`.
 polymorphic components. The `never` means "don't add element props". The second parameter is used to
 pass the interface that the `as` prop is pointing to.
 
+`Menu.Item` no longer sets `aria-selected` since that attribute is not valid on a `role=menuitem`.
+The `Menu.Option` was added to support the role of a `role=option` for going inside a
+`role=listbox`. The `Combobox` family of components uses a `role=listbox` for menu options. The
+`Menu.Option` renders a checkmark for a visual indication of selected options.
+
+### MultiSelect
+
+**PR:** [2911](https://github.com/Workday/canvas-kit/pull/2911)
+
+Added the `MultiSelect` component to select more than one option from a list of options. The
+`MultiSelect` is similar in API to the `Select` component, except the values are comma delimited
+with a space. If the ids represented are `['1', '2']`, then the string value of the form field is
+`'1, 2'`.
+
 ### Search Form (Labs)
 
 **PRs:** [#2934](https://github.com/Workday/canvas-kit/pull/2934),

package/dist/mdx/preview-react/multi-select/MultiSelect.mdx

@@ -0,0 +1,98 @@
+import {
+  ExampleCodeBlock,
+  InformationHighlight,
+  SymbolDoc,
+  Specifications,
+} from '@workday/canvas-kit-docs';
+
+import Basic from './examples/Basic';
+import Complex from './examples/Complex';
+import Icons from './examples/Icons';
+import Controlled from './examples/Controlled';
+import Searching from './examples/Searching';
+
+
+# Canvas Kit MultiSelect
+
+MultiSelect inputs allow users to choose multiple options from a list of items.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Basic Example
+
+`MultiSelect` supports a
+[dynamic API](/getting-started/for-developers/resources/collection-api/#dynamic-items) where you
+pass an array of items via the `items` prop and provide a render function to display the items. The
+items may be provided as an
+[array of strings](/getting-started/for-developers/resources/collection-api/#array-of-strings) or an
+[array of objects](/getting-started/for-developers/resources/collection-api/#array-of-objects).
+
+`MultiSelect` should be used in tandem with [Form Field](/components/inputs/form-field/) where the
+`MultiSelect` wraps the `FormField` element and the `FormField` element wraps the children of
+`MultiSelect` to meet accessibility standards. This ensures the `label` text from `FormField` is
+attached to the `MultiSelect.Input` and read out as a group for voiceover.
+
+```tsx
+<MultiSelect items={options}>
+  <FormField label="Your Label">
+    <MultiSelect.Input onChange={e => handleChange(e)} id="contact-multi-select" />
+    <MultiSelect.Popper>
+      <MultiSelect.Card>
+        <MultiSelect.List>
+          {item => <MultiSelect.Item>{item.id}</MultiSelect.Item>}
+        </MultiSelect.List>
+      </MultiSelect.Card>
+    </MultiSelect.Popper>
+  </FormField>
+</MultiSelect>
+```
+
+<ExampleCodeBlock code={Basic} />
+
+### Complex
+
+When registering items in an array of objects, it's common to have the text that is displayed to the
+user be different than an id. In this example, `serverId` and `label` properties need to be remapped
+to `id` and `text` hence the usage of `getId` and `getTextValue`. If your object has the properties
+`text` and `id`, there would be no need for this.
+
+<ExampleCodeBlock code={Complex} />
+
+### With Icons
+
+Use `MultiSelect.Item.Icon` to render an icon for a `MultiSelect.Item`. The `icon` prop for
+`MultiSelect.Item.Icon` accepts [system icons](/assets/system-icons/) from
+`@workday/canvas-system-icons-web`.
+
+> **Note: `data-id` on `MultiSelect.Item` must match the `id` property in your array of objects.
+> This ensures proper keyboard handling and type-ahead.**
+
+<ExampleCodeBlock code={Icons} />
+
+### Controlled
+
+The MultiSelect can be a controlled input component by passing the `value` and `onChange` to either
+the `<MultiSelect>` component or the `<MultiSelect.Input>` component. Internally, the
+`MultiSelect.Input` watches for changes on the `value` React prop as well as the `value` DOM
+property and will update the model accordingly.
+
+<ExampleCodeBlock code={Controlled} />
+
+### Searching
+
+A MultiSelect input can be used as a filter for results. Most likely this also means there are many
+items that may not be all be loaded from the server at once. The `useComboboxLoader` can be used to
+dynamically load items as the user navigates the available options.
+
+> **Note:** The behavior of search is experimental. The example should continue to work without
+> modification, but how the searchable input is presented to the user may change with user testing.
+> Don't rely too much on the exact behavior of the search input. For example, the search input may
+> be cleared when the user blurs the field.
+
+<ExampleCodeBlock code={Searching} />

package/dist/mdx/preview-react/multi-select/examples/Basic.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
+
+const items = ['Cheese', 'Olives', 'Onions', 'Pepperoni', 'Peppers'];
+
+export default () => {
+  return (
+    <>
+      <MultiSelect items={items}>
+        <FormField orientation="horizontal">
+          <FormField.Label>Toppings</FormField.Label>
+          <FormField.Input as={MultiSelect.Input} placeholder="Select Multiple" />
+          <MultiSelect.Popper>
+            <MultiSelect.Card>
+              <MultiSelect.List>
+                {item => (
+                  <MultiSelect.Item data-id={item}>
+                    <MultiSelect.Item.Text>{item}</MultiSelect.Item.Text>
+                  </MultiSelect.Item>
+                )}
+              </MultiSelect.List>
+            </MultiSelect.Card>
+          </MultiSelect.Popper>
+        </FormField>
+      </MultiSelect>
+    </>
+  );
+};

package/dist/mdx/preview-react/multi-select/examples/Complex.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+import {system} from '@workday/canvas-tokens-web';
+
+import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
+
+const mainContentStyles = createStyles({
+  padding: system.space.x4,
+});
+
+const items = [
+  {id: '1', text: 'Cheese'},
+  {id: '2', text: 'Olives'},
+  {id: '3', text: 'Onions'},
+  {id: '4', text: 'Pepperoni'},
+  {id: '5', text: 'Peppers'},
+];
+
+export default () => {
+  const [value, setValue] = React.useState('');
+  const [label, setLabel] = React.useState('');
+  return (
+    <CanvasProvider>
+      <>
+        <form
+          onSubmit={e => {
+            console.log('form submitted');
+            e.preventDefault();
+          }}
+        >
+          <main className={mainContentStyles}>
+            <MultiSelect items={items} getId={i => i.id} getTextValue={i => i.text}>
+              <FormField orientation="horizontal">
+                <FormField.Label>Toppings</FormField.Label>
+                <FormField.Input
+                  as={MultiSelect.Input}
+                  placeholder="Select Multiple"
+                  name="toppings"
+                  onChange={e => {
+                    const value = e.currentTarget.value;
+                    setValue(value);
+                    setLabel(
+                      value
+                        .split(', ')
+                        .map(item => items.find(i => i.id === item)?.text || 'Not Found')
+                        .join(', ')
+                    );
+                  }}
+                  value={value}
+                />
+                <MultiSelect.Popper>
+                  <MultiSelect.Card>
+                    <MultiSelect.List>
+                      {item => (
+                        <MultiSelect.Item data-id={item.id}>
+                          <MultiSelect.Item.Text>{item.text}</MultiSelect.Item.Text>
+                        </MultiSelect.Item>
+                      )}
+                    </MultiSelect.List>
+                  </MultiSelect.Card>
+                </MultiSelect.Popper>
+              </FormField>
+            </MultiSelect>
+          </main>
+        </form>
+        <div>Selected IDs: {value}</div>
+        <div>Selected Labels: {label}</div>
+      </>
+    </CanvasProvider>
+  );
+};

package/dist/mdx/preview-react/multi-select/examples/Controlled.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {Flex} from '@workday/canvas-kit-react/layout';
+
+import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
+
+const items = [
+  {id: '1', text: 'Cheese'},
+  {id: '2', text: 'Olives'},
+  {id: '3', text: 'Onions'},
+  {id: '4', text: 'Pepperoni'},
+  {id: '5', text: 'Peppers'},
+];
+
+export default () => {
+  const formRef = React.useRef<HTMLFormElement>(null);
+  const [value, setValue] = React.useState('1');
+  const [label, setLabel] = React.useState('Cheese');
+
+  function handleOnChange(event: React.ChangeEvent<HTMLInputElement>) {
+    const value = event.currentTarget.value;
+    setValue(value);
+    setLabel(
+      value
+        .split(', ')
+        .map(item => items.find(i => i.id === item)?.text || 'Not Found')
+        .join(', ')
+    );
+  }
+
+  return (
+    <>
+      <form
+        onSubmit={e => {
+          console.log('form submitted');
+          e.preventDefault();
+        }}
+        ref={formRef}
+      >
+        <Flex gap="s" flexDirection="column">
+          <MultiSelect items={items}>
+            <FormField orientation="horizontal">
+              <FormField.Label>Toppings</FormField.Label>
+              <FormField.Input
+                as={MultiSelect.Input}
+                placeholder="Select Multiple"
+                name="toppings"
+                onChange={handleOnChange}
+                value={value}
+              />
+              <MultiSelect.Popper>
+                <MultiSelect.Card>
+                  <MultiSelect.List>
+                    {item => (
+                      <MultiSelect.Item data-id={item.id}>
+                        <MultiSelect.Item.Text>{item.text}</MultiSelect.Item.Text>
+                      </MultiSelect.Item>
+                    )}
+                  </MultiSelect.List>
+                </MultiSelect.Card>
+              </MultiSelect.Popper>
+            </FormField>
+          </MultiSelect>
+          <Flex gap="s">
+            <SecondaryButton
+              onClick={e => {
+                setValue('1, 2, 3');
+              }}
+            >
+              Set to "Cheese, Olives, Onions" via React `value`
+            </SecondaryButton>
+            <SecondaryButton
+              onClick={e => {
+                const input = formRef.current.querySelector('[name=toppings]') as HTMLInputElement;
+                input.value = '1, 2';
+              }}
+            >
+              Set to "Cheese, Olives" via DOM `value`
+            </SecondaryButton>
+          </Flex>
+          <div>
+            <PrimaryButton type="submit">Submit</PrimaryButton>
+          </div>
+          <div>Selected ID: {value}</div>
+          <div>Selected Label: {label}</div>
+        </Flex>
+      </form>
+    </>
+  );
+};

package/dist/mdx/preview-react/multi-select/examples/Icons.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {
+  mediaPauseIcon,
+  mediaPlayIcon,
+  mediaTopicsIcon,
+  skipIcon,
+  previousIcon,
+} from '@workday/canvas-system-icons-web';
+
+import {MultiSelect} from '@workday/canvas-kit-preview-react/multi-select';
+
+const items = [
+  {id: '1', text: 'Pause', icon: mediaPauseIcon},
+  {id: '2', text: 'Play', icon: mediaPlayIcon},
+  {id: '3', text: 'Skip', icon: skipIcon},
+  {id: '4', text: 'Previous', icon: previousIcon},
+];
+
+export default () => {
+  return (
+    <MultiSelect items={items}>
+      <FormField orientation="horizontal">
+        <FormField.Label>Controls</FormField.Label>
+        <FormField.Input as={MultiSelect.Input} placeholder="Select Multiple" />
+        <MultiSelect.Popper>
+          <MultiSelect.Card>
+            <MultiSelect.List>
+              {item => (
+                <MultiSelect.Item data-id={item.id}>
+                  <MultiSelect.Item.Icon icon={item.icon} />
+                  <MultiSelect.Item.Text>{item.text}</MultiSelect.Item.Text>
+                  <MultiSelect.Item.Icon icon={mediaTopicsIcon} />
+                </MultiSelect.Item>
+              )}
+            </MultiSelect.List>
+          </MultiSelect.Card>
+        </MultiSelect.Popper>
+      </FormField>
+    </MultiSelect>
+  );
+};

package/dist/mdx/preview-react/multi-select/examples/Searching.tsx

@@ -0,0 +1,123 @@
+import React from 'react';
+
+import {system} from '@workday/canvas-tokens-web';
+
+import {createStyles} from '@workday/canvas-kit-styling';
+import {LoadReturn} from '@workday/canvas-kit-react/collection';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {useComboboxLoader} from '@workday/canvas-kit-react/combobox';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+import {MultiSelect, useMultiSelectModel} from '@workday/canvas-kit-preview-react/multi-select';
+import {StyledMenuItem} from '@workday/canvas-kit-react/menu';
+
+const mainContentStyles = createStyles({
+  padding: system.space.x4,
+});
+
+const colors = ['Red', 'Blue', 'Purple', 'Green', 'Pink'];
+const fruits = ['Apple', 'Orange', 'Banana', 'Grape', 'Lemon', 'Lime'];
+const options = Array(1000)
+  .fill('')
+  .map((_, index) => {
+    return {
+      id: `${index + 1}`,
+      text: `${colors[index % colors.length]} ${fruits[index % fruits.length]} ${index + 1}`,
+    };
+  });
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const {model, loader} = useComboboxLoader(
+    {
+      // You can start with any number that makes sense.
+      total: 0,
+
+      // Pick whatever number makes sense for your API
+      pageSize: 20,
+
+      // A load function that will be called by the loader. You must return a promise that returns
+      // an object like `{items: [], total: 0}`. The `items` will be merged into the loader's cache
+      async load({pageNumber, pageSize, filter}) {
+        return new Promise<LoadReturn<(typeof options)[0]>>(resolve => {
+          // simulate a server response by resolving after a period of time
+          setTimeout(() => {
+            // simulate paging and filtering based on pre-computed items
+            const start = (pageNumber - 1) * pageSize;
+            const end = start + pageSize;
+            const filteredItems = options.filter(item => {
+              if (filter === '' || typeof filter !== 'string') {
+                return true;
+              }
+              return item.text.toLowerCase().includes(filter.toLowerCase());
+            });
+
+            const total = filteredItems.length;
+            const items = filteredItems.slice(start, end);
+
+            resolve({
+              items,
+              total,
+            });
+          }, 300);
+        });
+      },
+      onShow() {
+        // The `shouldLoad` cancels while the combobox menu is hidden, so let's load when it is
+        // visible
+        loader.load();
+      },
+    },
+    useMultiSelectModel
+  );
+
+  return (
+    <CanvasProvider>
+      <>
+        <form
+          onSubmit={e => {
+            console.log('form submitted');
+            e.preventDefault();
+          }}
+        >
+          <main className={mainContentStyles}>
+            <MultiSelect model={model}>
+              <FormField orientation="horizontal">
+                <FormField.Label>Fruits</FormField.Label>
+                <FormField.Input
+                  as={MultiSelect.SearchInput}
+                  placeholder="Search"
+                  name="toppings"
+                  onChange={e => {
+                    setValue(e.currentTarget.value);
+                  }}
+                  value={value}
+                />
+                <MultiSelect.Popper>
+                  <MultiSelect.Card>
+                    {model.state.items.length === 0 && (
+                      <StyledMenuItem as="span">No Results Found</StyledMenuItem>
+                    )}
+                    {model.state.items.length > 0 && (
+                      <MultiSelect.List maxHeight={200}>
+                        {item =>
+                          item ? (
+                            <MultiSelect.Item data-id={item.id}>
+                              <MultiSelect.Item.Text>{item.text}</MultiSelect.Item.Text>
+                            </MultiSelect.Item>
+                          ) : undefined
+                        }
+                      </MultiSelect.List>
+                    )}
+                  </MultiSelect.Card>
+                </MultiSelect.Popper>
+              </FormField>
+            </MultiSelect>
+          </main>
+        </form>
+        <div>Selected: {value}</div>
+      </>
+    </CanvasProvider>
+  );
+};

package/dist/mdx/react/action-bar/examples/OverflowActionBar.tsx

@@ -66,6 +66,7 @@ export default () => {
             </SegmentedControl.Item>
           </SegmentedControl.List>
         </SegmentedControl>
+        <p>Selected: {containerWidth}</p>
       </footer>
     </div>
   );

package/dist/mdx/react/button/button/Button.mdx

@@ -78,7 +78,8 @@ on a dark or colorful background such as `blueberry400`.
 
 ### Grow Prop
 
-The example below shows the use of the `grow` prop on different variants of buttons. This will set the width of the button to the width of its container.
+The example below shows the use of the `grow` prop on different variants of buttons. This will set
+the width of the button to the width of its container.
 
 <ExampleCodeBlock code={Grow} />
 
@@ -106,4 +107,4 @@ should be used for navigation.
 
 ## Specifications
 
-<Specifications file="Button.spec.ts" name="Button" />
+<Specifications file="Button.spec.tsx" name="Button" />

package/dist/mdx/react/combobox/Combobox.mdx

@@ -36,13 +36,16 @@ two separate `input` elements.
   the same as the user input. Any prop related to the function of forms will be passed here. For
   example, the `name` attribute will be passed here. The `ref` will be pointed to this element.
 
+`Select` and `MultiSelect` are examples of constrained comboboxes.
+
 ### Arbitrary
 
 An arbitrary combobox allows the user to enter any value. The list of options are presented as
 suggestions and selecting an option will prefill the combobox with the value of the option. The user
 is still allowed to modify the combobox even after an option is entered. With arbitrary comboboxes,
 there is only one `input` element. Arbitrary combobox inputs should use the
-[useComboboxInputArbitrary](#usecomboboxinputarbirary) hook.
+[useComboboxInputArbitrary](#usecomboboxinputarbirary) hook. Typeahead or `Autocomplete` are
+examples are arbitrary value comboboxes.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "12.0.0-alpha.918-next.0",
+  "version": "12.0.0-alpha.919-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -44,10 +44,10 @@
   "dependencies": {
     "@emotion/styled": "^11.6.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^12.0.0-alpha.918-next.0",
-    "@workday/canvas-kit-preview-react": "^12.0.0-alpha.918-next.0",
-    "@workday/canvas-kit-react": "^12.0.0-alpha.918-next.0",
-    "@workday/canvas-kit-styling": "^12.0.0-alpha.918-next.0",
+    "@workday/canvas-kit-labs-react": "^12.0.0-alpha.919-next.0",
+    "@workday/canvas-kit-preview-react": "^12.0.0-alpha.919-next.0",
+    "@workday/canvas-kit-react": "^12.0.0-alpha.919-next.0",
+    "@workday/canvas-kit-styling": "^12.0.0-alpha.919-next.0",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/canvas-tokens-web": "^2.0.1",
     "markdown-to-jsx": "^7.2.0",
@@ -60,5 +60,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "3f21a8c474728598369595c8978854dab2355235"
+  "gitHead": "4fa21d7c07d138e03daf228f4a6a17fcbf379a3f"
 }