@workday/canvas-kit-docs 5.3.0-next.3 → 5.3.0-next.32

package/dist/mdx/labs-react/search-form/examples/Grow.tsx

@@ -0,0 +1,62 @@
+import * as React from 'react';
+import {MenuItem} from '@workday/canvas-kit-preview-react/menu';
+import {SearchForm} from '@workday/canvas-kit-labs-react/search-form';
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
+
+const initialWineList = [
+  'Beaujolais',
+  'Bordeaux',
+  'Cabernet Sauvignon',
+  'Champagne',
+  'Chardonnay',
+  'Chianti',
+  'Malbec',
+  'Merlot',
+  'Pinot Grigio',
+  'Pinot Gris',
+  'Pinot Noir',
+  'Primitivo',
+  'Prosecco',
+  'Riesling',
+  'Rioja',
+  'Rosé',
+  'Sauvignon Blanc',
+  'Syrah',
+  'Zinfandel',
+];
+
+export default () => {
+  const [wineList, setWineList] = React.useState(initialWineList);
+  // Tracking the input value for onSubmit
+  const [searchInput, setSearchInput] = React.useState('');
+  const menuItems = wineList.map(wine => <MenuItem key={wine}>{wine}</MenuItem>);
+
+  const filterMenuItems = e => {
+    setSearchInput(e.target.value);
+    const formattedValue = e.target.value.toLowerCase();
+
+    // Reset the list if the input is cleared
+    if (!formattedValue.length) {
+      setWineList(initialWineList);
+    } else {
+      const filteredItems = wineList.filter(wine => wine.toLowerCase().startsWith(formattedValue));
+      setWineList(filteredItems);
+    }
+  };
+
+  const handleSubmit = () => {
+    // We don't need to prevent the default event because SearchForm handles that internally
+    console.log(`Searching for: ${searchInput}`);
+  };
+
+  return (
+    <Flex minHeight={200} alignItems="flex-start" padding="xs">
+      <SearchForm
+        autocompleteItems={menuItems}
+        grow
+        onInputChange={filterMenuItems}
+        onSubmit={handleSubmit}
+      />
+    </Flex>
+  );
+};

package/dist/mdx/labs-react/search-form/examples/PropTables.splitProps.tsx

@@ -0,0 +1,4 @@
+import * as React from 'react';
+import {SearchThemeAttributes} from '@workday/canvas-kit-labs-react/search-form';
+
+export default (props: SearchThemeAttributes) => <div />;

package/dist/mdx/labs-react/search-form/examples/RTL.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import {MenuItem} from '@workday/canvas-kit-preview-react/menu';
+import {SearchForm} from '@workday/canvas-kit-labs-react/search-form';
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
+import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';
+
+const initialWineList = [
+  'Beaujolais',
+  'Bordeaux',
+  'Cabernet Sauvignon',
+  'Champagne',
+  'Chardonnay',
+  'Chianti',
+  'Malbec',
+  'Merlot',
+  'Pinot Grigio',
+  'Pinot Gris',
+  'Pinot Noir',
+  'Primitivo',
+  'Prosecco',
+  'Riesling',
+  'Rioja',
+  'Rosé',
+  'Sauvignon Blanc',
+  'Syrah',
+  'Zinfandel',
+];
+
+export default () => {
+  const [wineList, setWineList] = React.useState(initialWineList);
+  // Tracking the input value for onSubmit
+  const [searchInput, setSearchInput] = React.useState('');
+  const menuItems = wineList.map(wine => <MenuItem key={wine}>{wine}</MenuItem>);
+
+  const filterMenuItems = e => {
+    setSearchInput(e.target.value);
+    const formattedValue = e.target.value.toLowerCase();
+
+    // Reset the list if the input is cleared
+    if (!formattedValue.length) {
+      setWineList(initialWineList);
+    } else {
+      const filteredItems = wineList.filter(wine => wine.toLowerCase().startsWith(formattedValue));
+      setWineList(filteredItems);
+    }
+  };
+
+  const handleSubmit = () => {
+    // We don't need to prevent the default event because SearchForm handles that internally
+    console.log(`Searching for: ${searchInput}`);
+  };
+
+  const theme = {
+    canvas: {
+      direction: ContentDirection.RTL,
+    },
+  };
+
+  return (
+    <CanvasProvider theme={theme}>
+      <Flex minHeight={200} alignItems="flex-start" padding="xs">
+        <SearchForm
+          autocompleteItems={menuItems}
+          onInputChange={filterMenuItems}
+          onSubmit={handleSubmit}
+        />
+      </Flex>
+    </CanvasProvider>
+  );
+};

package/dist/mdx/labs-react/search-form/examples/Theming.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import {MenuItem} from '@workday/canvas-kit-preview-react/menu';
+import {SearchForm, SearchTheme} from '@workday/canvas-kit-labs-react/search-form';
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
+
+const initialWineList = [
+  'Beaujolais',
+  'Bordeaux',
+  'Cabernet Sauvignon',
+  'Champagne',
+  'Chardonnay',
+  'Chianti',
+  'Malbec',
+  'Merlot',
+  'Pinot Grigio',
+  'Pinot Gris',
+  'Pinot Noir',
+  'Primitivo',
+  'Prosecco',
+  'Riesling',
+  'Rioja',
+  'Rosé',
+  'Sauvignon Blanc',
+  'Syrah',
+  'Zinfandel',
+];
+
+export default () => {
+  const [wineList, setWineList] = React.useState(initialWineList);
+  // Tracking the input value for onSubmit
+  const [searchInput, setSearchInput] = React.useState('');
+  const menuItems = wineList.map(wine => <MenuItem key={wine}>{wine}</MenuItem>);
+
+  const filterMenuItems = e => {
+    setSearchInput(e.target.value);
+    const formattedValue = e.target.value.toLowerCase();
+
+    // Reset the list if the input is cleared
+    if (!formattedValue.length) {
+      setWineList(initialWineList);
+    } else {
+      const filteredItems = wineList.filter(wine => wine.toLowerCase().startsWith(formattedValue));
+      setWineList(filteredItems);
+    }
+  };
+
+  const handleSubmit = () => {
+    // We don't need to prevent the default event because SearchForm handles that internally
+    console.log(`Searching for: ${searchInput}`);
+  };
+
+  return (
+    <Flex minHeight={200} alignItems="flex-start">
+      <Flex padding="xs" backgroundColor="blueberry500" flex={1} flexBasis="auto">
+        <SearchForm
+          searchTheme={SearchTheme.Dark}
+          autocompleteItems={menuItems}
+          onInputChange={filterMenuItems}
+          onSubmit={handleSubmit}
+        />
+      </Flex>
+    </Flex>
+  );
+};

package/dist/mdx/preview-react/breadcrumbs/Breadcrumbs.mdx

@@ -46,7 +46,7 @@ you'll need to add `buttonAriaLabel` to `Breadcrumbs.CollapsibleList`.
 
 <ExampleCodeBlock code={CollapsibleList} />
 
-### Right-to-Left Example
+### Right-to-Left (RTL)
 
 Breadcrumbs has bidirectional support out of the box. That means outside of setting the content
 direction in your application's Canvas theme, you don't need to do anything else to make it work.

package/dist/mdx/preview-react/form-field/FormField.mdx

@@ -0,0 +1,27 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {FormField} from '@workday/canvas-kit-preview-react/form-field';
+
+import Custom from './examples/Custom';
+
+
+# Canvas Kit Form Field
+
+FormField allows users to wrap input components to make them accessible. You usually won't want to
+use FormField directly but instead should use the specific component you need, e.g. `TextInput`.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Customizing With Behavior Hooks Example
+
+If you need full customization you can use the form field behavior hooks to build your own solution.
+It is also easy it work with custom components or third party libraries and get the CKR
+accessibility guarantees by using the `as` prop.
+
+<ExampleCodeBlock code={Custom} />

package/dist/mdx/preview-react/form-field/examples/Custom.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import {
+  useFormFieldHint,
+  useFormFieldInput,
+  useFormFieldLabel,
+  useFormFieldModel,
+  useFormFieldOrientation,
+  FormFieldModelContext,
+} from '@workday/canvas-kit-preview-react/form-field';
+import {useModelContext} from '@workday/canvas-kit-react/common';
+import {Stack} from '@workday/canvas-kit-labs-react/layout';
+
+const Label = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldLabel(localModel);
+
+  return (
+    <label {...props}>
+      {children}
+      {model.state.isRequired ? '*' : ''}
+    </label>
+  );
+};
+
+const Hint = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldHint(localModel);
+
+  return <span {...props}>{children}</span>;
+};
+
+const Input = ({model, ...elementProps}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldInput(localModel, elementProps);
+
+  return <input type="text" required={model.state.isRequired ? true : false} {...props} />;
+};
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(event.target.value);
+  };
+
+  const model = useFormFieldModel({isRequired: true});
+
+  const layoutProps = useFormFieldOrientation('vertical')
+
+  return (
+    <Stack {...layoutProps}>
+      <Label model={model}>My Custom Field</Label>
+      <Input model={model} value={value} onChange={handleChange} />
+      <Hint model={model}>You can be anything</Hint>
+    </Stack>
+  );
+};

package/dist/mdx/preview-react/menu/Menu.mdx

@@ -3,7 +3,6 @@ import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
 
 import Basic from './examples/Basic';
 import ContextMenu from './examples/ContextMenu';
-import ControlButton from './examples/ControlButton';
 import CustomMenuItem from './examples/CustomMenuItem';
 import Icons from './examples/Icons';
 import ManyItems from './examples/ManyItems';
@@ -11,7 +10,7 @@ import ManyItems from './examples/ManyItems';
 
 # Canvas Kit Menu
 
-Menus display a list of options when triggered by an action or UI element like an icon or button.
+`Menu` displays a list of options when triggered by an action or UI element like an icon or button.
 
 [> Workday Design Reference](https://design.workday.com/components/popups/menus)
 
@@ -25,8 +24,15 @@ yarn add @workday/canvas-kit-preview-react
 
 ### Basic Example
 
+`Menu` is typically triggered by an action such as pressing a button. Here's an example of how you
+might implement that behavior using a [`Popup`](/components/popups/popup/).
+
 <ExampleCodeBlock code={Basic} />
 
+`Menu` will automatically assign focus to itself when it appears provided you set the `isOpen` prop
+correctly, so you do **not** need to use the `useInitialFocus` `Popup` hook. You **will**, however,
+need to use `useReturnFocus` to return focus back to the triggering button after closing the `Menu`.
+
 `Menu` follows the
 [Actions Menu pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions-active-descendant.html)
 using `aria-activedescendant`. Below is table of supported keyboard shortcuts and associated
@@ -42,10 +48,8 @@ actions.
 | `End`              | Moves focus to the last menu item                                                                                                                |
 | `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 |
 
-If you're using a menu button, you will need to add your own keyboard shortcuts, aria attributes,
-and focus management. See the example below.
-
-<ExampleCodeBlock code={ControlButton} />
+Note that although `Menu` includes support for keyboard shortcuts for the menu itself, you'll need
+to add your own keyboard handling and aria attributes to the triggering button.
 
 ### Context Menu
 
@@ -59,7 +63,6 @@ custom menu items, be sure to use semantic `<li>` elements with the following at
 
 - `role="menuitem"`
 - `tabindex={-1}`
-- `id`s following this pattern: `${MenuId}-${index}`
 
 Below is an example:
 
@@ -79,19 +82,22 @@ Below is an example:
 
 #### Usage
 
-`Menu` renders a styled `<ul>` element with a role of `menu` and follows the
+`Menu` renders a styled `<ul role="menu">` element within a [`Card`](/components/containers/card/)
+and follows the
 [Active Menu pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions-active-descendant.html)
 using `aria-activedescendant`.
 
 #### Props
 
+Undocumented props are spread to the underlying `<ul>` element.
+
 <ArgsTable of={Menu} />
 
 ### MenuItem
 
 #### Usage
 
-`MenuItem` renders a `<li>` element with the correct attributes to ensure it is accessible. If you
+`MenuItem` renders an `<li>` element with the correct attributes to ensure it is accessible. If you
 choose to implement your own custom menu items, be sure to use semantic `<li>` elements with the
 following attributes:
 
@@ -101,6 +107,8 @@ following attributes:
 
 #### Props
 
+Undocumented props are spread to the underlying `<li>` element.
+
 <ArgsTable of={MenuItem} />
 
 ## Specifications

package/dist/mdx/preview-react/menu/examples/Basic.tsx

@@ -1,17 +1,72 @@
 import React from 'react';
-
 import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {
+  Popup,
+  usePopupModel,
+  useAlwaysCloseOnOutsideClick,
+  useReturnFocus,
+  useCloseOnEscape,
+} from '@workday/canvas-kit-react/popup';
+
+const menuId = 'basic-menu';
 
 export default () => {
+  const model = usePopupModel();
+
+  useAlwaysCloseOnOutsideClick(model);
+  useCloseOnEscape(model);
+  useReturnFocus(model);
+
+  const isOpen = model.state.visibility !== 'hidden';
+
+  const handleButtonKeyDown = (event: React.KeyboardEvent) => {
+    let isShortcut = false;
+    if (event.key === `Spacebar` || event.key === ` ` || event.key === `Enter`) {
+      isShortcut = true;
+      if (isOpen) {
+        model.events.hide();
+      } else {
+        model.events.show();
+      }
+    } else if (event.key === `ArrowDown` || event.key === `ArrowUp`) {
+      isShortcut = true;
+      model.events.show();
+    }
+
+    if (isShortcut) {
+      // Prevent ArrowDown and ArrowUp keys from scrolling the entire page
+      event.preventDefault();
+    }
+  };
+
   return (
-    <Menu title="Menu Title">
-      <MenuItem>First Item</MenuItem>
-      <MenuItem>Second Item (with a really really really long label)</MenuItem>
-      <MenuItem isDisabled>Third Item (disabled)</MenuItem>
-      <MenuItem>
-        Fourth Item (<b>with markup</b>)
-      </MenuItem>
-      <MenuItem hasDivider>Fifth Item (with divider)</MenuItem>
-    </Menu>
+    <Popup model={model}>
+      <Popup.Target
+        as={SecondaryButton}
+        onKeyDown={handleButtonKeyDown}
+        aria-expanded={isOpen}
+        aria-haspopup={true}
+        aria-controls={isOpen ? menuId : undefined}
+      >
+        Open Menu
+      </Popup.Target>
+      <Popup.Popper placement="bottom-start">
+        {/*
+          isOpen must be set for focus to be properly assigned to the Menu;
+          onClose must be set in order to the Menu to close properly after
+          selecting a MenuItem
+        */}
+        <Menu id={menuId} isOpen={isOpen} onClose={model.events.hide}>
+          <MenuItem>First Item</MenuItem>
+          <MenuItem>Second Item (with a really really really long label)</MenuItem>
+          <MenuItem isDisabled>Third Item (disabled)</MenuItem>
+          <MenuItem>
+            Fourth Item (<b>with markup</b>)
+          </MenuItem>
+          <MenuItem hasDivider>Fifth Item (with divider)</MenuItem>
+        </Menu>
+      </Popup.Popper>
+    </Popup>
   );
 };

package/dist/mdx/preview-react/menu/examples/ContextMenu.tsx

@@ -1,49 +1,67 @@
 import * as React from 'react';
 
-import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';
+import {createComponent, useForkRef} from '@workday/canvas-kit-react/common';
 import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
 import {
   Popup,
+  PopupModelContext,
   usePopupModel,
   useAlwaysCloseOnOutsideClick,
   useCloseOnEscape,
+  useTransferOnFullscreenExit,
 } from '@workday/canvas-kit-react/popup';
 
-import {ContextMenuTarget} from './ContextMenuTarget';
+const ContextMenuTarget = createComponent('div')({
+  displayName: 'Popup.ContextMenuTarget',
+  Component: ({children, ...elemProps}, ref, Element) => {
+    const model = React.useContext(PopupModelContext);
+    const elementRef = useForkRef(ref, model.state.targetRef as any);
 
-export default () => {
-  const canvasTheme = {
-    canvas: {
-      direction: ContentDirection.LTR,
-    },
-  };
+    const onContextMenu = (event: React.MouseEvent) => {
+      if (model.state.visibility === 'visible') {
+        model.events.hide({event});
+      } else if (model.state.visibility === 'hidden') {
+        model.events.show({event});
+      }
+
+      // Prevent the default context menu from showing to avoid double menus
+      event.preventDefault();
+    };
 
+    return (
+      <Element ref={elementRef} onContextMenu={onContextMenu} {...elemProps}>
+        {children}
+      </Element>
+    );
+  },
+});
+
+export default () => {
   const model = usePopupModel();
 
   useAlwaysCloseOnOutsideClick(model);
   useCloseOnEscape(model);
+  useTransferOnFullscreenExit(model);
 
   return (
-    <CanvasProvider theme={canvasTheme}>
-      <Popup model={model}>
-        <ContextMenuTarget style={{display: 'inline'}} tabIndex={0}>
-          Right click on this text (Context menu target)
-        </ContextMenuTarget>
-        <Popup.Popper>
-          <Menu onClose={model.events.hide}>
-            <MenuItem>Back</MenuItem>
-            <MenuItem>Forward</MenuItem>
-            <MenuItem>Reload</MenuItem>
-            <MenuItem hasDivider>Bookmark Page</MenuItem>
-            <MenuItem>Save Page As...</MenuItem>
-            <MenuItem>Select All</MenuItem>
-            <MenuItem hasDivider>Take Screenshot</MenuItem>
-            <MenuItem hasDivider>View Page Source</MenuItem>
-            <MenuItem>Inspect Accessibility Properties</MenuItem>
-            <MenuItem>Inspect</MenuItem>
-          </Menu>
-        </Popup.Popper>
-      </Popup>
-    </CanvasProvider>
+    <Popup model={model}>
+      <ContextMenuTarget style={{display: 'inline'}} tabIndex={0}>
+        Right click on this text (Context menu target)
+      </ContextMenuTarget>
+      <Popup.Popper>
+        <Menu onClose={model.events.hide}>
+          <MenuItem>Back</MenuItem>
+          <MenuItem>Forward</MenuItem>
+          <MenuItem>Reload</MenuItem>
+          <MenuItem hasDivider>Bookmark Page</MenuItem>
+          <MenuItem>Save Page As...</MenuItem>
+          <MenuItem>Select All</MenuItem>
+          <MenuItem hasDivider>Take Screenshot</MenuItem>
+          <MenuItem hasDivider>View Page Source</MenuItem>
+          <MenuItem>Inspect Accessibility Properties</MenuItem>
+          <MenuItem>Inspect</MenuItem>
+        </Menu>
+      </Popup.Popper>
+    </Popup>
   );
 };

package/dist/mdx/preview-react/menu/examples/CustomMenuItem.tsx

@@ -4,10 +4,10 @@ import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
 
 export default () => {
   return (
-    <Menu title="Menu Title">
+    <Menu>
       <MenuItem>First Item</MenuItem>
       <MenuItem>Second Item</MenuItem>
-      <li role="menuItem" id="customMenu-3" tabIndex={-1} style={{listStyle: 'none'}}>
+      <li role="menuitem" tabIndex={-1} style={{listStyle: 'none'}}>
         Third Item (custom)
       </li>
     </Menu>

package/dist/mdx/preview-react/menu/examples/Icons.tsx

@@ -10,7 +10,7 @@ import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
 
 export default () => {
   return (
-    <Menu title="Menu Title">
+    <Menu>
       <MenuItem icon={uploadCloudIcon}>First Item</MenuItem>
       <MenuItem icon={setupIcon}>Second Item (with a really really really long label)</MenuItem>
       <MenuItem isDisabled icon={uploadCloudIcon} secondaryIcon={taskContactIcon}>

package/dist/mdx/preview-react/menu/examples/ManyItems.tsx

@@ -4,11 +4,11 @@ import {Menu, MenuItem} from '@workday/canvas-kit-preview-react/menu';
 
 export default () => {
   return (
-    <Menu title="Menu Titles">
+    <Menu>
       {'One Two Three Four Five Six Seven Eight Nine Ten Eleven Twelve Thirteen Fourteen Fifteen'
         .split(' ')
         .map(item => {
-          return <MenuItem>Item {item}</MenuItem>;
+          return <MenuItem key={item}>Item {item}</MenuItem>;
         })}
     </Menu>
   );