@workday/canvas-kit-docs 6.0.0-alpha.0-next.31 → 6.0.0-alpha.0-next.37

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 '../../..';
+import {VStack} from '@workday/canvas-kit-labs-react';
+
+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>
+  );
+};

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

@@ -1,16 +1,24 @@
+/** @jsx jsx */
+import {jsx} from '@emotion/core';
 import React from 'react';
+
+import {CSSProperties} from '@workday/canvas-kit-react/tokens';
+import {Box, useThemeRTL} from '@workday/canvas-kit-labs-react/common';
 import {Banner} from '@workday/canvas-kit-react/banner';
-import {Box} from '@workday/canvas-kit-labs-react/common';
+
+const styles: CSSProperties = {
+  position: 'absolute',
+  right: 0,
+};
 
 export default () => {
   return (
     <Box height={64}>
-      <Banner
-        error={Banner.ErrorType.Error}
-        label="3 Errors"
-        variant={Banner.Variant.Sticky}
-        style={{position: 'absolute', right: 0}}
-      />
+      <Banner hasError={true} isSticky={true} css={styles}>
+        <Banner.Icon />
+        <Banner.Label>3 Errors</Banner.Label>
+        <Banner.ActionText />
+      </Banner>
     </Box>
   );
 };

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

@@ -0,0 +1,62 @@
+/** @jsx jsx */
+import {jsx, keyframes} from '@emotion/core';
+import React from 'react';
+
+import {CSSProperties} from '@workday/canvas-kit-react/tokens';
+import {Box, useThemeRTL} from '@workday/canvas-kit-labs-react/common';
+import {loopIcon} from '@workday/canvas-system-icons-web';
+import {Banner} from '@workday/canvas-kit-react/banner';
+
+const containerStyles: CSSProperties = {
+  position: 'absolute',
+  right: 0,
+  overflow: 'hidden',
+};
+
+export default () => {
+  const {themeRTL, theme} = useThemeRTL();
+  const bannerRef = React.useRef<HTMLButtonElement>(null);
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const [styles, setStyles] = React.useState<CSSProperties>();
+
+  const [rerun, setRerun] = React.useState(1); // Only needed for demo purposes
+
+  React.useLayoutEffect(() => {
+    let width = bannerRef.current.offsetWidth;
+    if (theme.canvas.direction === 'rtl') {
+      width *= -1;
+    }
+    const slideInKeyframes = keyframes({
+      '0%': {
+        transform: `translateX(${width}px)`,
+      },
+      '100%': {
+        transform: `translateX(0 * ${rerun})`,
+      },
+    });
+
+    setStyles({
+      margin: '4px 0px 4px 4px', // Room for focus outline since container is overflow hidden
+      animation: `${slideInKeyframes} .3s ease-out forwards`,
+    });
+  }, [theme.canvas.direction, rerun]);
+
+  return (
+    <Box height={64}>
+      <div css={containerStyles} ref={containerRef}>
+        <div css={themeRTL(styles)}>
+          <Banner
+            onClick={() => setRerun(r => r + 1)}
+            hasError={true}
+            isSticky={true}
+            ref={bannerRef}
+          >
+            <Banner.Icon icon={loopIcon} />
+            <Banner.Label>Click to run animation</Banner.Label>
+            <Banner.ActionText />
+          </Banner>
+        </div>
+      </div>
+    </Box>
+  );
+};

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

@@ -0,0 +1,38 @@
+/** @jsx jsx */
+import {jsx} from '@emotion/core';
+import React from 'react';
+
+import {CSSProperties} from '@workday/canvas-kit-react/tokens';
+import {Box, useThemeRTL} from '@workday/canvas-kit-labs-react/common';
+import {
+  CanvasProvider,
+  ContentDirection,
+  PartialEmotionCanvasTheme,
+} from '@workday/canvas-kit-react/common';
+import {Banner} from '@workday/canvas-kit-react/banner';
+
+const styles: CSSProperties = {
+  position: 'absolute',
+  left: 0,
+};
+
+const theme: PartialEmotionCanvasTheme = {
+  canvas: {
+    direction: ContentDirection.RTL,
+  },
+};
+
+export default () => {
+  const {themeRTL} = useThemeRTL();
+  return (
+    <CanvasProvider theme={theme}>
+      <Box height={64}>
+        <Banner isSticky={true} css={styles}>
+          <Banner.Icon />
+          <Banner.Label>3 אזהרות</Banner.Label>
+          <Banner.ActionText />
+        </Banner>
+      </Box>
+    </CanvasProvider>
+  );
+};

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

@@ -0,0 +1,28 @@
+import React from 'react';
+
+import {Banner} from '@workday/canvas-kit-react/banner';
+import {CanvasProvider, PartialEmotionCanvasTheme} from '@workday/canvas-kit-react/common';
+import {colors} from '@workday/canvas-kit-react/tokens';
+
+export default () => {
+  const theme: PartialEmotionCanvasTheme = {
+    canvas: {
+      palette: {
+        alert: {
+          main: colors.kiwi200,
+          dark: colors.kiwi300,
+        },
+      },
+    },
+  };
+
+  return (
+    <CanvasProvider theme={theme}>
+      <Banner>
+        <Banner.Icon />
+        <Banner.Label>3 Items</Banner.Label>
+        <Banner.ActionText />
+      </Banner>
+    </CanvasProvider>
+  );
+};

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

@@ -0,0 +1,29 @@
+import React from 'react';
+
+import {Banner} from '@workday/canvas-kit-react/banner';
+import {CanvasProvider, PartialEmotionCanvasTheme} from '@workday/canvas-kit-react/common';
+import {colors} from '@workday/canvas-kit-react/tokens';
+
+export default () => {
+  const theme: PartialEmotionCanvasTheme = {
+    canvas: {
+      palette: {
+        error: {
+          main: colors.islandPunch500,
+          dark: colors.islandPunch600,
+          contrast: colors.berrySmoothie100,
+        },
+      },
+    },
+  };
+
+  return (
+    <CanvasProvider theme={theme}>
+      <Banner hasError={true}>
+        <Banner.Icon />
+        <Banner.Label>3 Items</Banner.Label>
+        <Banner.ActionText />
+      </Banner>
+    </CanvasProvider>
+  );
+};

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

@@ -51,7 +51,7 @@ when you need to place a Primary Button on a dark or colorful background such as
 
 #### Props
 
-Undocumented props are spread to the underlying `button` element.
+Undocumented props are spread to the underlying `<button>` element.
 
 <ArgsTable of={PrimaryButton} />
 
@@ -73,7 +73,7 @@ a dark or colorful background such as `blueberry400`.
 
 #### Props
 
-Undocumented props are spread to the underlying `button` element.
+Undocumented props are spread to the underlying `<button>` element.
 
 <ArgsTable of={SecondaryButton} />
 
@@ -97,7 +97,7 @@ a dark or colorful background such as `blueberry400`.
 
 #### Props
 
-Undocumented props are spread to the underlying `button` element.
+Undocumented props are spread to the underlying `<button>` element.
 
 <ArgsTable of={TertiaryButton} />
 
@@ -111,16 +111,16 @@ before deleting.
 
 #### Props
 
-Undocumented props are spread to the underlying `button` element.
+Undocumented props are spread to the underlying `<button>` element.
 
 <ArgsTable of={DeleteButton} />
 
 ### Accessible Use of the `as` Prop
 
 Like many of our components, Buttons accept an `as` prop, which lets you change the underlying
-semantic element - usually an `a` (anchor), or a `button`. This should be done with caution to
-ensure the best accessibility. Generally, `button` elements should be used for actions, and `a`
-(anchor) elements should be used for navigation.
+semantic element - usually an `<a>`, or a `<button>`. This should be done with caution to ensure the
+best accessibility. Generally, `<button>` elements should be used for actions, and `<a>` elements
+should be used for navigation.
 
 ## Specifications
 

package/dist/mdx/react/button/icon-button/IconButton.mdx

@@ -98,6 +98,6 @@ The `toggle` prop can be used to make icon buttons toggleable.
 
 ## Props
 
-Undocumented props are spread to the underlying `button` element.
+Undocumented props are spread to the underlying `<button>` element.
 
 <ArgsTable of={IconButton} />

package/dist/mdx/react/loading-animation/LoadingAnimation.mdx

@@ -1,6 +1,7 @@
 import {LoadingAnimation} from '@workday/canvas-kit-react/loading-animation';
 
 import Basic from './examples/Basic';
+import RTL from './examples/RTL';
 
 
 # Canvas Kit Loading Animation
@@ -22,6 +23,10 @@ yarn add @workday/canvas-kit-react
 
 <ExampleCodeBlock code={Basic} />
 
+### Right-to-Left (RTL)
+
+<ExampleCodeBlock code={RTL} />
+
 ## Props
 
 Loading Animation does not have any documented props. Undocumented props are spread to its outermost

package/dist/mdx/react/loading-animation/examples/RTL.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+import {LoadingAnimation} from '@workday/canvas-kit-react/loading-animation';
+import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';
+
+export default () => {
+  const theme = {
+    canvas: {
+      direction: ContentDirection.RTL,
+    },
+  };
+  return (
+    <CanvasProvider theme={theme}>
+      <LoadingAnimation />
+    </CanvasProvider>
+  );
+};