@workday/canvas-kit-docs 6.3.5 → 7.0.0-alpha.0-next.3

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,21 @@
 import React from 'react';
-import {Banner} from '@workday/canvas-kit-react/banner';
 import {Box} from '@workday/canvas-kit-labs-react/common';
+import {Banner} from '@workday/canvas-kit-react/banner';
+import {styled} from '@workday/canvas-kit-react/common';
+
+const StyledBanner = styled(Banner)({
+  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}}
-      />
+      <StyledBanner hasError={true} isSticky={true}>
+        <Banner.Icon />
+        <Banner.Label>3 Errors</Banner.Label>
+        <Banner.ActionText />
+      </StyledBanner>
     </Box>
   );
 };

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

@@ -0,0 +1,63 @@
+/** @jsxRuntime classic */
+/** @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,36 @@
+import React from 'react';
+
+import {Box, useThemeRTL} from '@workday/canvas-kit-labs-react/common';
+import {
+  CanvasProvider,
+  ContentDirection,
+  PartialEmotionCanvasTheme,
+  styled,
+} from '@workday/canvas-kit-react/common';
+import {Banner} from '@workday/canvas-kit-react/banner';
+
+const theme: PartialEmotionCanvasTheme = {
+  canvas: {
+    direction: ContentDirection.RTL,
+  },
+};
+
+const StyledStickyBanner = styled(Banner)({
+  position: 'absolute',
+  left: 0,
+});
+
+export default () => {
+  const {themeRTL} = useThemeRTL();
+  return (
+    <CanvasProvider theme={theme}>
+      <Box height={64}>
+        <StyledStickyBanner isSticky={true}>
+          <Banner.Icon />
+          <Banner.Label>3 אזהרות</Banner.Label>
+          <Banner.ActionText />
+        </StyledStickyBanner>
+      </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/icon-button/examples/Inverse.tsx

@@ -1,20 +1,17 @@
-/** @jsx jsx */
-import {jsx} from '@emotion/core';
 import React from 'react';
 
-import {space, colors, borderRadius} from '@workday/canvas-kit-react/tokens';
+import {colors} from '@workday/canvas-kit-react/tokens';
 import {IconButton} from '@workday/canvas-kit-react/button';
 import {activityStreamIcon} from '@workday/canvas-system-icons-web';
-
-const blueBackground = {
-  backgroundColor: colors.blueberry400,
-  borderRadius: borderRadius.m,
-  padding: space.xxs,
-  display: 'inline-block',
-};
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
 
 export default () => (
-  <div css={blueBackground}>
+  <Flex
+    display="inline-flex"
+    backgroundColor={colors.blackPepper400}
+    borderRadius="m"
+    padding="xxs"
+  >
     <IconButton icon={activityStreamIcon} aria-label="Activity Stream" variant="inverse" />
-  </div>
+  </Flex>
 );

package/dist/mdx/react/button/icon-button/examples/InverseFilled.tsx

@@ -1,20 +1,17 @@
-/** @jsx jsx */
-import {jsx} from '@emotion/core';
 import React from 'react';
 
-import {space, colors, borderRadius} from '@workday/canvas-kit-react/tokens';
+import {colors} from '@workday/canvas-kit-react/tokens';
 import {IconButton} from '@workday/canvas-kit-react/button';
 import {activityStreamIcon} from '@workday/canvas-system-icons-web';
-
-const blueBackground = {
-  backgroundColor: colors.blueberry400,
-  borderRadius: borderRadius.m,
-  padding: space.xxs,
-  display: 'inline-block',
-};
+import {Flex} from '@workday/canvas-kit-labs-react/layout';
 
 export default () => (
-  <div css={blueBackground}>
+  <Flex
+    display="inline-flex"
+    backgroundColor={colors.blackPepper400}
+    borderRadius="m"
+    padding="xxs"
+  >
     <IconButton icon={activityStreamIcon} aria-label="Activity Stream" variant="inverseFilled" />
-  </div>
+  </Flex>
 );

package/dist/mdx/react/skeleton/examples/Simulation.tsx

@@ -1,6 +1,5 @@
-/** @jsx jsx */
 import React from 'react';
-import {jsx, keyframes} from '@emotion/core';
+import {keyframes} from '@emotion/core';
 
 import {
   Card,
@@ -9,6 +8,7 @@ import {
   SecondaryButton,
   SystemIconCircle,
   TextInput,
+  styled,
 } from '@workday/canvas-kit-react';
 
 import {Box, Flex} from '@workday/canvas-kit-labs-react';
@@ -16,6 +16,7 @@ import {Box, Flex} from '@workday/canvas-kit-labs-react';
 import {Skeleton} from '@workday/canvas-kit-react/skeleton';
 import {borderRadius, space, type} from '@workday/canvas-kit-react/tokens';
 import {patternIcon} from '@workday/canvas-system-icons-web';
+import {StyledType} from '@workday/canvas-kit-react/common';
 
 const fadeOut = keyframes`
   from {
@@ -27,6 +28,10 @@ const fadeOut = keyframes`
   }
 `;
 
+const StyledSimulation = styled(Box)<StyledType>({
+  pointerEvents: 'none',
+});
+
 export default () => {
   const [loading, setLoading] = React.useState(true);
   const [loadTime, setLoadTime] = React.useState('3000');
@@ -96,16 +101,12 @@ export default () => {
               </Box>
             )}
 
-            <Box
+            <StyledSimulation
               position="absolute"
               top={0}
               left={0}
               width="100%"
-              css={{
-                pointerEvents: 'none',
-                animation: !loading ? `${fadeOut} 150ms ease-out` : undefined,
-                animationFillMode: !loading ? 'forwards' : undefined,
-              }}
+              animation={!loading ? `${fadeOut} 150ms ease-out forwards` : undefined}
             >
               <Skeleton>
                 <Flex alignItems="center">
@@ -120,7 +121,7 @@ export default () => {
                 </Flex>
                 <Skeleton.Text lineCount={3} />
               </Skeleton>
-            </Box>
+            </StyledSimulation>
           </Box>
         </Card.Body>
       </Card>