@workday/canvas-kit-docs 5.3.0-next.2 → 5.3.0-next.24

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,65 @@
 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,
 } 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);
 
   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>
   );

package/dist/mdx/preview-react/text-area/TextArea.mdx

@@ -0,0 +1,122 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+import Alert from './examples/Alert';
+import Basic from './examples/Basic';
+import Disabled from './examples/Disabled';
+import Error from './examples/Error';
+import Grow from './examples/Grow';
+import LabelPositionVertical from './examples/LabelPositionVertical';
+import LabelPositionHorizontal from './examples/LabelPositionHorizontal';
+import HiddenLabel from './examples/HiddenLabel';
+import Placeholder from './examples/Placeholder';
+import RefForwarding from './examples/RefForwarding';
+import Required from './examples/Required';
+import ResizeConstraints from './examples/ResizeConstraints';
+
+
+# Canvas Kit Text Area
+
+TextArea's allow users to enter and edit multiple lines of text.
+
+[> Workday Design Reference](https://design.workday.com/components/inputs/text-area)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Basic Example
+
+<ExampleCodeBlock code={Basic} />
+
+### Disabled
+
+Use `TextArea.Field`'s `disabled` prop to prevent users from interacting with the field.
+
+<ExampleCodeBlock code={Disabled} />
+
+### Placeholder
+
+Use `TextArea.Field`'s `placeholder` prop to display a sample of its expected format or value before
+a value has been provided.
+
+<ExampleCodeBlock code={Placeholder} />
+
+### Required
+
+Use `TextArea.Field`'s `isRequired` prop (or use with the `useTextAreaModel` hook) to indicate that
+the field is required. This will also add a red asterisk to `TextArea.Label`.
+
+<ExampleCodeBlock code={Required} />
+
+### Ref Forwarding
+
+`TextArea` supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
+`ref` to its underlying `<textarea>` element.
+
+<ExampleCodeBlock code={RefForwarding} />
+
+### Resize Constraints
+
+Use the `resize` css attribute to restrict resizing of it to certain dimensions.
+
+<ExampleCodeBlock code={ResizeConstraints} />
+
+### Grow
+
+There are lots of ways to accomplish this. The `TextArea.Field` extends from Box so it is easy to
+extend full width, e.g. setting width prop to 100%, or you can set the `alignItems` prop to
+`stretch` on `TextArea`, etc.
+
+<ExampleCodeBlock code={Grow} />
+
+### Label Position
+
+Use the `orientation` property to set `TextArea.Label`'s position. You can override the default
+spacing using the `spacing` prop. Below are examples of both positions:
+
+#### Horizontal
+
+<ExampleCodeBlock code={LabelPositionHorizontal} />
+
+#### Vertical
+
+<ExampleCodeBlock code={LabelPositionVertical} />
+
+### Visually Hiding The Label
+
+If your label is just for screen reader users you can use the `accessibleHide` utility class from
+`@workday/canvas-kit-react/common`. You will likely want to set the `spacing` prop on `TextArea` to
+`zero`.
+
+<ExampleCodeBlock code={HiddenLabel} />
+
+### Error States
+
+Use the `hasError` property from `useTextAreaModel` to set the `TextArea` to the Error state. If you
+have an accompanying hint you can use the `TextArea.Hint` subcomponent.
+
+<ExampleCodeBlock code={Error} />
+
+### Other Visual States
+
+Use the `useThemedRing` hook to change the visual state of the `<textarea>` element.
+
+#### Alert
+
+<ExampleCodeBlock code={Alert} />
+
+## Props
+
+Undocumented props are spread to the underlying `<textarea>` element.
+
+<ArgsTable of={TextArea} />
+
+## Specifications
+
+<Specifications file="TextAreaPreview.spec.ts" name="Text Area" />