@workday/canvas-kit-docs 5.2.11 → 5.3.0-next.18

package/dist/mdx/COMPOUND_COMPONENTS.mdx

@@ -78,8 +78,8 @@ const Tabs = ({children, model, ...config}) => {
 
 ## Subcomponents
 
-A subcomponent typically follows ARIA roles. For the `Tabs` example, these are the `tablist`,
-`tab`, and `tabpanel` roles. A subcomponent provides direct access to semantic or key elements of a
+A subcomponent typically follows ARIA roles. For the `Tabs` example, these are the `tablist`, `tab`,
+and `tabpanel` roles. A subcomponent provides direct access to semantic or key elements of a
 compound component. In the `IconButton` example, the icon is not semantic and might be hidden from
 screen readers while the `IconButton.Text` content is instead used for a tooltip and as the
 accessible name while being visibly hidden.
@@ -175,35 +175,35 @@ Components that directly wrap an element (most of them) will have the following
 
 Compound components are also made up of [models](#models) that accept [guards](#guards) to
 conditionally prevent state changes and [callbacks](#callbacks) to attach listeners. For example, in
-our Tabs component clicking a Tab will activate that tab. The `Tabs` container component will accept
-a `shouldActivate` and a `onActivate` for the event called `activate`.
+our Tabs component clicking a Tab will select that tab. The `Tabs` container component will accept a
+`shouldSelect` and a `onSelect` for the event called `select`.
 
 ```tsx
 const MyComponent = () => {
-  // `data` is all event data from the `activate` event
+  // `data` is all event data from the `select` event
 
   // `state` is the current state of the `Tabs` component
-  const shouldActivate = ({data, state}) => {
-    // for some reason, we only want to allow activation the 'first' tab
-    // Clicking on the first tab will activate it, but clicking on the
+  const shouldSelect = ({data, state}) => {
+    // for some reason, we only want to allow selection the 'first' tab
+    // Clicking on the first tab will select it, but clicking on the
     // second tab will do nothing
     return data.tab === 'first' ? true : false;
 
     // returning true allows the event to trigger a state change and will
-    // also call the `onActivate` callback
+    // also call the `onSelect` callback
   };
 
   // `prevState` is the previous state of the model. Callbacks are called _before_ state has resolved.
   // This means the passed state hasn't updated yet. It also means it is safe to call `setState` without
   // triggering extra renders. `setState` calls will add to React's batching system before a state changes
   // are flushed and render functions are called.
-  const onActivate = ({data, prevState}) => {
-    // called any time the `activate` event is triggered
-    console.log('onActivate', data, prevState);
+  const onSelect = ({data, prevState}) => {
+    // called any time the `select` event is triggered
+    console.log('onSelect', data, prevState);
   };
 
   return (
-    <Tabs shouldActivate={shouldActivate} onActivate={onActivate}>
+    <Tabs shouldSelect={shouldSelect} onSelect={onSelect}>
       <Tabs.List>
         <Tabs.Item name="first">First</Tabs.Item>
         <Tabs.Item name="second">Second</Tabs.Item>
@@ -324,20 +324,20 @@ const useEllipsisTooltipModel = (config = {}) => {
 
 Models are meant to be composable. For example, a `TabsModel` uses a `CursorModel` (which itself
 uses `ListModel`) and a `ListModel` for a list of panels. `TabsModel` also keeps track of which tab
-is currently active. This might look like the following:
+is currently selected. This might look like the following:
 
 ```ts
 const useTabsModel = (config = {}) => {
   // id is used for ARIA attributes
   const id = useUniqueId(config.id);
-  const [activeTab, setActiveTab] = React.useState('');
+  const [selectedTab, setSelectedTab] = React.useState('');
   const cursor = useCursorModel(config);
   const panels = useListModel(config);
 
   const state = {
     ...cursor.state, // extend the CursorModel state
     id,
-    activeTab,
+    selectedTab,
     panels: panels.state.items, // we only care about
   };
 
@@ -346,12 +346,12 @@ const useTabsModel = (config = {}) => {
     registerPanel: panels.events.registerItem,
     unregisterPanel: panels.events.unregisterItem,
 
-    activate(data) {
-      if (config.shouldActivate?.({data, prevState: state}) === false) {
+    select(data) {
+      if (config.shouldSelect?.({data, prevState: state}) === false) {
         return;
       }
-      setActiveTab(data.tab);
-      config.onActivate?.({data, prevState: state});
+      setSelectedTab(data.tab);
+      config.onSelect?.({data, prevState: state});
     },
   };
 
@@ -362,10 +362,11 @@ const useTabsModel = (config = {}) => {
 Model composition allows for components to share functionality with other components. In the Tabs
 example, `ListModel` is in charge of maintaining a list of tab elements. The `CursorModel` is in
 charge of maintaining a current cursor position of the tab list. The `Tabs.List` component uses the
-cursor to allow keyboard navigation of the tabs. The `TabsModel` also maintains the currently active
-tab to ensure the correct `TabPanel` is visible. The `TabsModel` is also using a `ListModel` to
-maintain a list of tab panels. The `TabsModel` is in charge of composing all this and providing data
-and events to the `Tabs` compound component - coordination state between subcomponents.
+cursor to allow keyboard navigation of the tabs. The `TabsModel` also maintains the currently
+selected tab to ensure the correct `TabPanel` is visible. The `TabsModel` is also using a
+`ListModel` to maintain a list of tab panels. The `TabsModel` is in charge of composing all this and
+providing data and events to the `Tabs` compound component - coordination state between
+subcomponents.
 
 Many other components like `Select`, `Breadcrumbs`, or dropdown menus can also use the `ListModel`
 and/or the `CursorModel`. These models could be thought of as abstract models where they do not
@@ -463,11 +464,11 @@ const TabList = ({children, ...elemProps}) => {
 
 A container component can either accept model configuration _or_ a model. Passing model
 configuration allows for simpler model configuration of guards, callbacks, or any other model
-configuration. The following example provides an `onActivate` callback that fetches some data from
-the server:
+configuration. The following example provides an `onSelect` callback that fetches some data from the
+server:
 
 ```tsx
-<Tabs onActivate={({data}) => fetch('/api/activate' + data.id)}>...</Tabs>
+<Tabs onSelect={({data}) => fetch('/api/selectTab' + data.id)}>...</Tabs>
 ```
 
 If you need direct access to a model's state or events, you can hoist the model into your component
@@ -479,15 +480,15 @@ look like this:
 const MyTabs = () => {
   const model = useTabsModel({
     // we can still load data from the server
-    onActivate: ({data}) => fetch('/api/activate' + data.id),
+    onSelect: ({data}) => fetch('/api/selectTab' + data.id),
   });
 
   return (
     <>
       <Tabs model={model}>...</Tabs>
-      // direct access to the model's state Currently selected tab: {model.state.activeTab}
+      // direct access to the model's state Currently selected tab: {model.state.selectedTab}
       // Now we can send events directly to the model
-      <button onClick={() => model.events.activate({tab: 'third'})}>Activate third tab</button>
+      <button onClick={() => model.events.select({tab: 'third'})}>Select third tab</button>
     </>
   );
 };

package/dist/mdx/labs-react/search-form/SearchForm.mdx

@@ -0,0 +1,64 @@
+import {SearchForm} from '@workday/canvas-kit-labs-react/search-form';
+// examples
+import Basic from './examples/Basic';
+import CustomTheme from './examples/CustomTheme';
+import Grow from './examples/Grow';
+import RTL from './examples/RTL';
+import Theming from './examples/Theming';
+import ThemeAttributes from './examples/PropTables.splitProps';
+
+
+# Canvas Kit Search Form
+
+`SearchForm` is a search form that contains a `Combobox` for rendering search results. It's
+primarily intended to be used within a `Header`.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-labs-react
+```
+
+## Usage
+
+### Basic Example
+
+You will most likely use `SearchForm` within the context of a `Header` component, but it's helpful
+to see its functionality as a standalone component. Below is a basic example that filters results
+based on search input.
+
+<ExampleCodeBlock code={Basic} />
+
+### Grow
+
+If you'd like `SearchForm` to grow to the width of its container, set the `grow` prop to
+`true`.
+
+<ExampleCodeBlock code={Grow} />
+
+### Theming
+
+`SearchForm` can be themed to use one of the preset `SearchThemes`: `Light`, `Dark`, or
+`Transparent`. Below is an example of `SearchForm` using the `Dark` theme.
+
+<ExampleCodeBlock code={Theming} />
+
+You can also provide more specific theming values by providing specific `SearchThemeAttributes`.
+
+<ExampleCodeBlock code={CustomTheme} />
+
+Below is a table of attributes that can be supplied to `SearchForm`:
+
+<ArgsTable of={ThemeAttributes} />
+
+
+### RTL (Right-To-Left)
+
+`SearchForm` provides bidirectional support out of the box. You shouldn't need to provide any
+additional configuration.
+
+<ExampleCodeBlock code={RTL} />
+
+## Props
+
+<ArgsTable of={SearchForm} />

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

@@ -0,0 +1,61 @@
+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}
+        onInputChange={filterMenuItems}
+        onSubmit={handleSubmit}
+      />
+    </Flex>
+  );
+};

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

@@ -0,0 +1,72 @@
+import * as React from 'react';
+import {MenuItem} from '@workday/canvas-kit-preview-react/menu';
+import {SearchForm, SearchThemeAttributes} from '@workday/canvas-kit-labs-react/search-form';
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
+import {colors} from '@workday/canvas-kit-react/tokens';
+
+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 customTheme = {
+    background: colors.cinnamon600,
+    backgroundFocus: colors.frenchVanilla100,
+    placeholderColor: colors.frenchVanilla100,
+    placeholderColorFocus: colors.blackPepper400,
+  } as SearchThemeAttributes;
+
+  return (
+    <Flex minHeight={200} alignItems="flex-start">
+      <Flex padding="xs" backgroundColor="cinnamon500" flex={1} flexBasis="auto">
+        <SearchForm
+          searchTheme={customTheme}
+          autocompleteItems={menuItems}
+          onInputChange={filterMenuItems}
+          onSubmit={handleSubmit}
+        />
+      </Flex>
+    </Flex>
+  );
+};

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/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>
+  );
+};