@workday/canvas-kit-docs 6.8.9 → 6.9.0-next.5

package/dist/mdx/react/action-bar/ActionBar.mdx

@@ -2,11 +2,17 @@ import {ActionBar} from '@workday/canvas-kit-react/action-bar';
 import {Specifications} from '@workday/canvas-kit-docs';
 
 import Basic from './examples/Basic';
+import Icons from './examples/Icons';
+import DeleteAction from './examples/DeleteAction';
+import OverflowActionBar from './examples/OverflowActionBar';
 
 
 # Canvas Kit Action Bar
 
-Full width button toolbar fixed to bottom of screen.
+Action Bar is a [compound component](/getting-started/for-developers/resources/compound-components/)
+that contains primary and secondary actions related to a page or task.
+
+[> Workday Design Reference](https://design.workday.com/components/buttons/action-bar)
 
 ## Installation
 
@@ -18,39 +24,136 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
-Here is a basic example of an `ActionBar` with two buttons. Although not required,
-[buttons](../../button) are often used in in action bars. The primary action button should be left
-aligned followed by secondary buttons. The primary button is on the right only in "progression-based
-UIs" and on mobile devices.
+`ActionBar` includes a container `ActionBar` component and the following subcomponent:
+`ActionBar.List` which should contains `ActionBar.Item`.
+
+In a basic example of an `ActionBar` there are two buttons. The primary action button should be used
+only once and left aligned if content is left to right, followed by secondary buttons. Tertiary
+buttons should not be used in the Action Bar.
 
 <ExampleCodeBlock code={Basic} />
 
-### Fixed
+### Icons Example
+
+`ActionBar.Item` renders a `SecondaryButton` as default, so it's possible to use other Button props
+with `ActionBar.Item` such as `icon` or `size`.
+
+<ExampleCodeBlock code={Icons} />
+
+### Delete Action Example
+
+`ActionBar.Item` is a `SecondaryButton` by default but it's posible to change it to another element,
+such as `DeleteButton`, by using `as` prop.
+
+<ExampleCodeBlock code={DeleteAction} />
+
+### Overflow Example
+
+`ActionBar` container can contain up to 3 actions and an Overflow Menu if there are more than 3
+actions, the other remaining actions should be placed into an Overflow Menu that is launched by
+clicking the Overflow Button.
+
+Also, ActionBar is a responsive component based on the width of its container. If the rendered
+actions exceed the width of the `ActionBar.List`, an overflow menu will be rendered. This only works
+against the dynamic API where you give the `ActionBarModel` an array of items to be rendered. The
+dynamic API handles the React `key` for you based on the item's identifier. The dynamic API requires
+either an `id` on each item object or a `getId` function that returns an identifier based on the
+item. The below example uses an `id` property on each item.
+
+The dynamic API takes in any object, but since nothing is known about your object, a
+[render prop](https://reactjs.org/docs/render-props.html) is necessary to instruct a list how it
+should render.
+
+<ExampleCodeBlock code={OverflowActionBar} />
 
-The Action Bar generally lives at the bottom of the viewport. If you would like this behavior
-automatically (using `position: fixed`), you can use the `fixed` prop.
+## Components
+
+### ActionBar
+
+#### Usage
+
+`ActionBar` is a container component that is responsible for creating a `ActionBarModel` and sharing
+it with its subcomponents using React context. It does not represent a real element.
 
 ```tsx
-<ActionBar fixed={true}>
-  <PrimaryButton>Button</PrimaryButton>
-  <SecondaryButton>Button</SecondaryButton>
-</ActionBar>
+<ActionBar items={[]}>{/* Child components */}</ActionBar>
 ```
 
-## Responsive Behavior
+Alternatively, you may pass in a model using the hoisted model pattern.
 
-At 575px, responsive styles will take effect:
-
-- Applies a flex box to the buttons
-- Makes single-button groups full width
-- All buttons will become the same width (`flex: 1`).
-- Button order will become reversed, making left-aligned primary buttons right-aligned.
+```tsx
+const model = useActionBarModel({
+  items: [],
+});
 
-> When on a mobile form factor, the button placement should flip to have the primary button on the
-> far right.
+<ActionBar model={model}>{/* Child components */}</ActionBar>;
+```
 
 ## Props
 
-Undocumented props are spread to the underlying container `<div>` element.
+Note that if you pass in a `model` configured with `useActionBarModel`, configuration props passed
+to `ActionBar` will be ignored.
+
+<ArgsTable of={ActionBar} />
+
+### ActionBar.List
+
+#### Usage
+
+`ActionBar.List` is a `HStack` element. It is a container for `ActionBar.Item` subcomponents. To
+apply an overflow behavior for ActionBar `showOverflowButton` prop shold be true.
+
+```tsx
+<ActionBar.List>{/* ActionBar.Items */}</ActionBar.List>
+```
+
+#### Props
+
+Undocumented props are spread to the underlying `HStack` element.
+
+<ArgsTable of={ActionBar.List} />
+
+### ActionBar.Item
+
+#### Usage
+
+`ActionBar.Item` is a `button` element, by default it's a `SecondaryButton` unless an `as` prop
+passed.
+
+```tsx
+<ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
+  First Action
+</ActionBar.Item>
+```
+
+#### Props
+
+Undocumented props are spread to the underlying `SecondaryButton` component.
+
+<ArgsTable of={ActionBar.Item} />
+
+## Model
+
+If `ActionBar` was stripped of all its markup, attributes, and styling, what would remain is the
+[model](/getting-started/for-developers/resources/compound-components/#models). The model is an
+object composed of two parts: `state` which describes the current snapshot in time of the component
+and `events` which describes events that can be sent to the model.
+
+By default, `ActionBar` will create a model and share it internally with its subcomponents using
+React context. Alternatively, if you need direct access to the model's `state` and `events` outside
+of the `ActionBar` component, you may configure your own model with `useActionBarModel` and pass it
+to `ActionBar` via a pattern called
+[hoisting the model](/getting-started/for-developers/resources/compound-components/#configuring-a-model).
+
+```tsx
+const model = useActionBarModel({
+  items: [],
+});
+
+<ActionBar model={model}>{/* Child components */}</ActionBar>;
+```
+
+### Config
 
-<ArgsTable of={ActionBar} />
+`useActionBarModel` accepts a configuration object with the following properties and returns a
+`ActionBarModel` with `state` and `events` properties.

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

@@ -1,11 +1,14 @@
 import React from 'react';
-
 import {ActionBar} from '@workday/canvas-kit-react/action-bar';
-import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
 
 export default () => (
   <ActionBar>
-    <PrimaryButton>Button</PrimaryButton>
-    <SecondaryButton>Button</SecondaryButton>
+    <ActionBar.List position="relative">
+      <ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
+        First Action
+      </ActionBar.Item>
+      <ActionBar.Item>Second Action</ActionBar.Item>
+    </ActionBar.List>
   </ActionBar>
 );

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

@@ -0,0 +1,15 @@
+import React from 'react';
+
+import {ActionBar} from '@workday/canvas-kit-react/action-bar';
+import {DeleteButton} from '@workday/canvas-kit-react/button';
+
+export default () => {
+  return (
+    <ActionBar>
+      <ActionBar.List position="relative">
+        <ActionBar.Item as={DeleteButton}>Delete Action</ActionBar.Item>
+        <ActionBar.Item>Second Action</ActionBar.Item>
+      </ActionBar.List>
+    </ActionBar>
+  );
+};

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

@@ -0,0 +1,18 @@
+import React from 'react';
+
+import {ActionBar} from '@workday/canvas-kit-react/action-bar';
+import {notificationsIcon, alarmClockIcon} from '@workday/canvas-system-icons-web';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+export default () => {
+  return (
+    <ActionBar>
+      <ActionBar.List position="relative">
+        <ActionBar.Item as={PrimaryButton} icon={notificationsIcon}>
+          First Action
+        </ActionBar.Item>
+        <ActionBar.Item icon={alarmClockIcon}>Second Action</ActionBar.Item>
+      </ActionBar.List>
+    </ActionBar>
+  );
+};

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

@@ -0,0 +1,59 @@
+import React from 'react';
+
+import {ActionBar, useActionBarModel} from '@workday/canvas-kit-react/action-bar';
+import {HStack} from '@workday/canvas-kit-react/layout';
+import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+
+type MyActionItem = {
+  id: string;
+  text: React.ReactNode;
+};
+
+export default () => {
+  const [items] = React.useState<MyActionItem[]>([
+    {id: 'first', text: 'First Action'},
+    {id: 'second', text: 'Second Action'},
+    {id: 'third', text: 'Third Action'},
+    {id: 'fourth', text: 'Fourth Action'},
+    {id: 'fifth', text: 'Fifth Action'},
+  ]);
+
+  const model = useActionBarModel({items});
+  const [containerWidth, setContainerWidth] = React.useState('100%');
+
+  return (
+    <div style={{width: containerWidth}}>
+      <ActionBar model={model}>
+        <ActionBar.List position="relative">
+          {(item: MyActionItem, index) => (
+            <ActionBar.Item
+              as={index === 0 ? PrimaryButton : undefined}
+              onClick={() => console.log(item.id)}
+            >
+              {item.text}
+            </ActionBar.Item>
+          )}
+        </ActionBar.List>
+        <ActionBar.Menu.Popper>
+          <ActionBar.Menu.Card maxWidth={300} maxHeight={200}>
+            <ActionBar.Menu.List>
+              {(item: MyActionItem) => (
+                <ActionBar.Menu.Item onClick={() => console.log(item.id)}>
+                  {item.text}
+                </ActionBar.Menu.Item>
+              )}
+            </ActionBar.Menu.List>
+          </ActionBar.Menu.Card>
+        </ActionBar.Menu.Popper>
+      </ActionBar>
+      <hr />
+      <h4>Change action bar container size</h4>
+      <HStack spacing="xs">
+        <SecondaryButton onClick={() => setContainerWidth('100%')}>100%</SecondaryButton>
+        <SecondaryButton onClick={() => setContainerWidth('1023px')}>Medium</SecondaryButton>
+        <SecondaryButton onClick={() => setContainerWidth('767px')}>Small</SecondaryButton>
+        <SecondaryButton onClick={() => setContainerWidth('320px')}>Extra Small</SecondaryButton>
+      </HStack>
+    </div>
+  );
+};

package/dist/mdx/react/banner/Banner.mdx

@@ -4,11 +4,24 @@ import ActionText from './examples/ActionText';
 import Basic from './examples/Basic';
 import Error from './examples/Error';
 import Sticky from './examples/Sticky';
+import ThemedAlert from './examples/ThemedAlert';
+import ThemedError from './examples/ThemedError';
+import RefForwarding from './examples/RefForwarding';
+import StickyAnimation from './examples/StickyAnimation';
+import StickyRTL from './examples/StickyRTL';
+import {
+  BannerHoistedComponent,
+  BannerModelConfigComponent,
+  BannerIconComponent,
+  BannerLabelComponent,
+  BannerActionComponent,
+} from './PropTables.splitprops.tsx';
 
 
 # Canvas Kit Banner
 
-Banners surface important information and feedback to the user about a task, action, or state.
+`Banner` is a [compound component](/getting-started/for-developers/resources/compound-components/)
+used surface important information and feedback to the user about a task, action, or state.
 
 [> Workday Design Reference](https://design.workday.com/components/indicators/banners)
 
@@ -22,38 +35,209 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
+Use the children of `Banner.Label` to set the main text for the `Banner`.
+
 <ExampleCodeBlock code={Basic} />
 
-### Error Type
+### Action Text
 
-Set the `error` prop of the Banner to designate the severity of the message presented in the banner.
-`error` accepts the following values:
+Use the children of `Banner.ActionText` to customize the action text contained in the `Banner`. The
+text has default value of `View All`.
 
-- `Banner.ErrorType.Alert` (Default)
-- `Banner.ErrorType.Error`
+<ExampleCodeBlock code={ActionText} />
 
-<ExampleCodeBlock code={Error} />
+### Error Type
 
-### Variant
+Set the `hasError` prop of the `Banner` to designate the severity of the message presented in the
+banner. This will change the defualt icon to `exclamationCircleIcon`.
 
-Banner is available in two variants. `variant` accepts the following values:
+<ExampleCodeBlock code={Error} />
 
-- `Banner.Variant.Full` (Default)
-- `Banner.Variant.Sticky`
+### Sticky
 
-Use the `Sticky` variant if the Banner is to be displayed along the right edge of the page.
+Set the `isSticky` prop of the `Banner` to display it along the right edge of the page. When true,
+the `Banner.ActionText` will be hidden. Some basic styles will be applied, but you will still need
+to manually set the css `position` value.
 
 <ExampleCodeBlock code={Sticky} />
 
-#### Action Text
+You can use keyframes to animate the `Banner` in.
 
-Set the `actionText` prop to customize the text of the link contained in the Banner. `actionText` is
-only available in the `Full` variant and has a default value of `View All`.
+<ExampleCodeBlock code={StickyAnimation} />
 
-<ExampleCodeBlock code={ActionText} />
+### RefForwarding
+
+`Banner` supports ref forwarding. It will forward ref to its underlying button element.
+
+<ExampleCodeBlock code={RefForwarding} />
+
+### Right-to-Left (RTL)
+
+Banner supports right-to-left languages when specified in the CanvasProvider theme.
+
+<ExampleCodeBlock code={StickyRTL} />
+
+### Themed Banners
+
+Banners use the `useThemedPalette` hook for themeing. By default, your alert theme is used. `main`
+will be used for the background, `dark` for the hover background, and `contrast` for the text.
+
+<ExampleCodeBlock code={ThemedAlert} />
+
+If you set the `hasError` prop, the banner will use your error theme.
+
+<ExampleCodeBlock code={ThemedError} />
+
+## Components
+
+### Banner
+
+#### Usage
+
+`Banner` is a container component rendered as a `<button>` element that is responsible for creating
+a `BannerModel` and sharing it with its subcomponents using React context.
+
+```tsx
+<Banner
+	isSticky={true}
+	hasError={true} id:
+	'custom-banner-id'
+	onClick={() => console.log('clicked banner')}
+>
+  {/* Child components */}
+</Banner>
+```
+
+Alternatively, you may pass in a model using the hoisted model pattern.
+
+```tsx
+const model = useBannerModel({
+  isSticky: true,
+  hasError: true,
+  id: 'custom-banner-id',
+});
+
+return (
+  <Banner onClick={() => console.log('clicked banner')} model={model}>
+    {/* Child components */}
+  </Banner>
+);
+```
+
+#### Props
+
+Undocumented props are spread to the underlying `<button>` element.
+
+<ArgsTable of={BannerModelConfigComponent} />
+
+If you're using the hoisted model pattern, follow this table instead (refer to the [Model](#model)
+section for more information about `BannerModel`):
+
+<ArgsTable of={BannerHoistedComponent} />
+
+### Banner.Icon
+
+#### Usage
+
+`Banner.Icon` is a styled `<SystemIcon>`. The icon defaults to exclamationTriangleIcon or
+exclamationCircleIcon when the model's hasError is true.
+
+```tsx
+<Banner.Icon />
+```
+
+#### Props
+
+You can override the default icon if needed.
+
+Undocumented props are spread to the underlying `<SystemIcon>` element.
+
+<ArgsTable of={BannerIconComponent} />
+
+### Banner.Label
+
+#### Usage
+
+`Banner.Label` is a styled `<Flex>`. This component will get an id that will be used for the
+aria-describedby on the top level `<button>`.
+
+```tsx
+<Banner.Label>3 Warnings</Banner.Label>
+```
+
+#### Props
+
+The children prop will be used as the Primary text of the Banner.
+
+Undocumented props are spread to the underlying `<Flex>` element.
+
+<ArgsTable of={BannerLabelComponent} />
+
+### Banner.ActionText
+
+#### Usage
+
+`Banner.ActionText` is a styled `<Box>`. This component will get an id that will be used for the
+aria-labelledby on the top level `<button>`. This component will be visually hidden when the model's
+`isSticky` prop is set to true.
+
+```tsx
+<Banner.ActionText>Custom call to action</Banner.ActionText>
+```
+
+#### Props
+
+The children prop will be used as the 'call to action' text of the Banner.
+
+Undocumented props are spread to the underlying `<Box>` element.
+
+<ArgsTable of={BannerActionComponent} />
+
+## Model
+
+If `Banner` was stripped of all its markup, attributes, and styling, what would remain is the
+[model](/getting-started/for-developers/resources/compound-components/#models). The model is an
+object that holds the `state`, i.e. a description of the current snapshot in time of the component.
+
+By default, `Banner` will create a model and share it internally with its subcomponents using React
+context. You may subscribe to `BannerContext` if you wish to create a custom subcomponent for your
+implementation. Here's a simple example.
+
+```tsx
+import * as React from 'react';
+import {Banner, BannerModelContext} from '@workday/canvas-kit-react/banner';
+
+const CustomText = (props: React.HTMLAttributes<HTMLSpanElement>) => {
+  const model = React.useContext(BannerModelContext);
+
+  return <span {...props}>{model.state.hasError ? 'Error:' : 'Warning:'}</span>;
+};
+
+export const CustomBanner = () => {
+  return (
+    <Banner>
+      <CustomText />
+      {/* Other subcomponents */}
+    </Banner>
+  );
+};
+```
+
+Alternatively, if you need direct access to the model's `state` outside of the `Banner` component,
+you may configure your own model with `useBannerModel` and pass it to `Banner` via a pattern called
+[hoisting the model](/getting-started/for-developers/resources/compound-components/#configuring-a-model).
+
+```tsx
+const model = useBannerModel({
+  isError: true,
+});
+
+<Banner model={model}>{/* Child components */}</Banner>;
+```
 
-## Props
+### Config
 
-Undocumented props are spread to the outermost element rendered by Banner.
+`useBannerModel` accepts a configuration object with the following properties and returns a
+`BannerModel` with a `state` property.
 
-<ArgsTable of={Banner} />
+<ArgsTable of={BannerModelConfigComponent} />

package/dist/mdx/react/banner/PropTables.splitprops.tsx

@@ -0,0 +1,39 @@
+import {BannerModel, BannerModelConfig} from '@workday/canvas-kit-react/banner';
+import {CanvasSystemIcon} from '@workday/design-assets-types';
+import {BannerActionProps} from '../lib/BannerAction';
+
+// <ArgsTable of={Banner} /> generates a very large props table given that
+// BannerProps includes FlexProps. Use this dummy component instead to
+// limit the props shown.
+export const BannerHoistedComponent = (_: {model: BannerModel}) => <div />;
+
+// <ArgsTable of={Banner.Icon} /> generates a props table with
+// SystemIcon props. Use this dummy component instead to limit the props shown.
+export const BannerIconComponent = (_: {
+  /**
+   * Icon to show next to label
+   * @default `exclamationTriangleIcon` or `exclamationCircleIcon` when hasError is true
+   */
+  icon?: CanvasSystemIcon;
+}) => <div />;
+
+// <ArgsTable of={Banner.Label} /> generates a props table with
+// Flex props. Use this dummy component instead to limit the props shown.
+export const BannerLabelComponent = (_: {
+  /**
+   * The text of the Banner.
+   */
+  children: React.ReactNode;
+}) => <div />;
+
+// <ArgsTable of={Banner.ActionText} /> generates a props table with
+// Box props. Use this dummy component instead to limit the props shown.
+export const BannerActionComponent = (_: {
+  /**
+   * The text of the Banner action.
+   * @default 'View All'
+   */
+  children?: React.ReactNode;
+}) => <div />;
+
+export const BannerModelConfigComponent = (_: BannerModelConfig) => <div />;

package/dist/mdx/react/banner/examples/ActionText.tsx

@@ -1,6 +1,13 @@
 import React from 'react';
+
 import {Banner} from '@workday/canvas-kit-react/banner';
 
 export default () => {
-  return <Banner actionText="Show Details" label="3 Warnings" />;
+  return (
+    <Banner>
+      <Banner.Icon />
+      <Banner.Label>3 Warnings</Banner.Label>
+      <Banner.ActionText>Show Details</Banner.ActionText>
+    </Banner>
+  );
 };

package/dist/mdx/react/banner/examples/Basic.tsx

@@ -1,6 +1,13 @@
 import React from 'react';
+
 import {Banner} from '@workday/canvas-kit-react/banner';
 
 export default () => {
-  return <Banner label="3 Warnings" />;
+  return (
+    <Banner onClick={() => console.log('clicked banner')}>
+      <Banner.Icon />
+      <Banner.Label>3 Warnings</Banner.Label>
+      <Banner.ActionText />
+    </Banner>
+  );
 };

package/dist/mdx/react/banner/examples/Error.tsx

@@ -1,6 +1,13 @@
 import React from 'react';
+
 import {Banner} from '@workday/canvas-kit-react/banner';
 
 export default () => {
-  return <Banner error={Banner.ErrorType.Error} label="3 Errors" />;
+  return (
+    <Banner hasError={true}>
+      <Banner.Icon />
+      <Banner.Label>3 Errors</Banner.Label>
+      <Banner.ActionText />
+    </Banner>
+  );
 };

package/dist/mdx/react/banner/examples/RefForwarding.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+import {changeFocus} from '@workday/canvas-kit-react/common';
+import {Banner} from '@workday/canvas-kit-react/banner';
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {VStack} from '@workday/canvas-kit-react/layout';
+
+export default () => {
+  const bannerRef = React.useRef<HTMLButtonElement>(null);
+
+  const focusBanner = () => {
+    changeFocus(bannerRef.current);
+  };
+
+  return (
+    <VStack spacing="xs" alignItems="flex-start">
+      <Banner ref={bannerRef}>
+        <Banner.Icon />
+        <Banner.Label>3 Warnings</Banner.Label>
+        <Banner.ActionText />
+      </Banner>
+      <SecondaryButton onClick={focusBanner}>Focus Banner</SecondaryButton>
+    </VStack>
+  );
+};