@workday/canvas-kit-react 8.0.0-alpha.253-next.22 → 8.0.0-alpha.428-next.2

package/text/lib/TypeLevelComponents.tsx

@@ -1,15 +1,42 @@
 import * as React from 'react';
 import {createComponent} from '@workday/canvas-kit-react/common';
-import {Text, TextProps} from '@workday/canvas-kit-react/text';
+import {Text, TextProps} from './Text';
 
 /**
- * Props interface for type level specific component:
+ * Prop interface for type level specific components:
  * Title, Heading, BodyText, Subtext.
  */
 export interface TypeLevelProps extends Omit<TextProps, 'typeLevel'> {
+  /**
+   * Each type level has three sizes: `large`, `medium`, and `small`.
+   */
   size: 'large' | 'medium' | 'small';
 }
 
+/**
+ * This component is intended to be used for small subtext content or in tight spaces.
+ * By default, it renders a semantic `p` element, but you can adjust this as needed with the `as` prop.
+ * It has three sizes: large, medium, and small.
+ * Here's a quick reference for font-sizes and weights:
+ *
+ * - `large`
+ *   - font-size: 14px (0.875rem)
+ *   - font-weight: regular (400)
+ * - `medium`
+ *   - font-size: 12px (0.75rem)
+ *   - font-weight: regular (400)
+ * - `small`
+ *   - font-size: 10px (0.625rem)
+ *   - font-weight: regular (400)
+ *
+ * ```tsx
+ * import { Subtext } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomSubtext = () => (
+ *   <Subtext size="small">Subtext</Subtext>
+ * );
+ * ```
+ */
 export const Subtext = createComponent('p')({
   displayName: 'Subtext',
   Component: ({size, ...elemProps}: TypeLevelProps, ref, Element) => {
@@ -18,6 +45,30 @@ export const Subtext = createComponent('p')({
   },
 });
 
+/**
+ * This component is intended to be used for standard body text.
+ * By default, it renders a semantic `p` element, but you can adjust this as needed with the `as` prop.
+ * It has three sizes: large, medium, and small.
+ * Here's a quick reference for font-sizes and weights:
+ *
+ * - `large`
+ *   - font-size: 20px (1.25rem)
+ *   - font-weight: regular (400)
+ * - `medium`
+ *   - font-size: 18px (1.125rem)
+ *   - font-weight: regular (400)
+ * - `small`
+ *   - font-size: 16px (1rem)
+ *   - font-weight: regular (400)
+ *
+ * ```tsx
+ * import { BodyText } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomBodyText = () => (
+ *   <BodyText size="small">Body Text</BodyText>
+ * );
+ * ```
+ */
 export const BodyText = createComponent('p')({
   displayName: 'BodyText',
   Component: ({size, ...elemProps}: TypeLevelProps, ref, Element) => {
@@ -26,6 +77,30 @@ export const BodyText = createComponent('p')({
   },
 });
 
+/**
+ * This component is intended to be used for headings and large text.
+ * By default, it renders a semantic `h2` element, but you can adjust this as needed with the `as` prop.
+ * It has three sizes: large, medium, and small.
+ * Here's a quick reference for font-sizes and weights:
+ *
+ * - `large`
+ *   - font-size: 32px (2rem)
+ *   - font-weight: bold (700)
+ * - `medium`
+ *   - font-size: 28px (1.75rem)
+ *   - font-weight: bold (700)
+ * - `small`
+ *   - font-size: 24px (1.5rem)
+ *   - font-weight: bold (700)
+ *
+ * ```tsx
+ * import { Heading } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomHeading = () => (
+ *   <Heading size="small">Heading Text</Heading>
+ * );
+ * ```
+ */
 export const Heading = createComponent('h2')({
   displayName: 'Heading',
   Component: ({size, ...elemProps}: TypeLevelProps, ref, Element) => {
@@ -34,6 +109,30 @@ export const Heading = createComponent('h2')({
   },
 });
 
+/**
+ * This component is intended to be used large page titles.
+ * By default, it renders a semantic `h1` element, but you can adjust this as needed with the `as` prop.
+ * It has three sizes: large, medium, and small.
+ * Here's a quick reference for font-sizes and weights:
+ *
+ * - `large`
+ *   - font-size: 56px (3/5rem)
+ *   - font-weight: bold (700)
+ * - `medium`
+ *   - font-size: 48px (3rem)
+ *   - font-weight: bold (700)
+ * - `small`
+ *   - font-size: 40px (2.5rem)
+ *   - font-weight: bold (700)
+ *
+ * ```tsx
+ * import { Title } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomTitle = () => (
+ *   <Title size="small">Title Text</Title>
+ * );
+ * ```
+ */
 export const Title = createComponent('h1')({
   displayName: 'Title',
   Component: ({size, ...elemProps}: TypeLevelProps, ref, Element) => {

package/text-input/index.ts

@@ -1,2 +1,3 @@
 export * from './lib/InputIconContainer';
 export * from './lib/TextInput';
+export {InputGroup, useInputGroupModel} from './lib/InputGroup';

package/text-input/lib/InputGroup.tsx

@@ -0,0 +1,250 @@
+import React from 'react';
+
+import {space} from '@workday/canvas-kit-react/tokens';
+import {
+  createContainer,
+  createElemPropsHook,
+  createModelHook,
+  createSubcomponent,
+  dispatchInputEvent,
+  ExtractProps,
+  useForkRef,
+  useIsRTL,
+} from '@workday/canvas-kit-react/common';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {xSmallIcon} from '@workday/canvas-system-icons-web';
+
+import {TextInput} from './TextInput';
+
+export const useInputGroupModel = createModelHook({})(() => {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  return {
+    state: {
+      inputRef,
+    },
+    events: {},
+  };
+});
+
+export const InputGroupInnerStart = createSubcomponent('div')({
+  modelHook: useInputGroupModel,
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
+  return (
+    <Flex
+      as={Element}
+      position="absolute"
+      alignItems="center"
+      justifyContent="center"
+      height="xl"
+      width="xl"
+      {...elemProps}
+    />
+  );
+});
+
+export const InputGroupInnerEnd = createSubcomponent('div')({
+  modelHook: useInputGroupModel,
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
+  return (
+    <Flex
+      as={Element}
+      position="absolute"
+      alignItems="center"
+      justifyContent="center"
+      height="xl"
+      width="xl"
+      {...elemProps}
+    />
+  );
+});
+
+const useInputGroupInput = createElemPropsHook(useInputGroupModel)((model, ref) => {
+  const elementRef = useForkRef(ref, model.state.inputRef);
+
+  return {
+    ref: elementRef,
+  };
+});
+
+export const InputGroupInput = createSubcomponent(TextInput)({
+  modelHook: useInputGroupModel,
+  elemPropsHook: useInputGroupInput,
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
+  return <Flex as={Element} width="100%" {...elemProps} />;
+});
+
+export const useClearButton = createElemPropsHook(useInputGroupModel)(model => {
+  const [inputHasValue, setInputHasValue] = React.useState(false);
+
+  React.useLayoutEffect(() => {
+    const input = model.state.inputRef.current;
+
+    if (input) {
+      input.addEventListener('input', () => {
+        setInputHasValue(!!input.value);
+      });
+    }
+  }, [model.state.inputRef]);
+
+  return {
+    // This element does not need to be accessible via screen reader. The user can already clear
+    // an input
+    role: 'presentation',
+    // A clear input button doesn't need focus. There's already keyboard keys to clear an input
+    tabIndex: -1,
+    icon: xSmallIcon,
+    // "small" is needed to render correctly within a `TextInput`
+    size: 'small',
+    transition: 'opacity 300ms ease',
+    // prevent a focus change to the button. Focus should stay in the input.
+    onMouseDown(event: React.MouseEvent) {
+      event.preventDefault();
+    },
+    onClick() {
+      // This will clear the input's value
+      dispatchInputEvent(model.state.inputRef.current, '');
+    },
+    style: {
+      opacity: inputHasValue ? 1 : 0,
+      pointerEvents: inputHasValue ? 'auto' : 'none',
+    },
+  } as const;
+});
+
+/**
+ * A clear input button. This can be a component later.
+ */
+export const ClearButton = createSubcomponent(TertiaryButton)({
+  modelHook: useInputGroupModel,
+  elemPropsHook: useClearButton,
+})<ExtractProps<typeof TertiaryButton, never>>((elemProps, Element) => {
+  return <Element {...elemProps} />;
+});
+
+// make sure we always use pixels if the input is a number - this is required for `calc`
+const toPx = (input: string | number): string => {
+  return typeof input === 'number' ? `${input}px` : input;
+};
+
+// wrap an array of widths into something the browser can understand, including `calc` for multiple
+// values
+const wrapInCalc = (values: (string | number)[]): string | number | undefined => {
+  if (values.length === 0) {
+    return undefined;
+  }
+  if (values.length === 1) {
+    return values[0];
+  }
+  return `calc(${values.map(toPx).join(' + ')})`;
+};
+
+/**
+ * An `InputGroup` is a container around a {@link TextInput} with optional inner start and end
+ * elements. The inner start and end elements are usually icons or icon buttons visually represented
+ * inside the input. The `InputGroup` will add padding to the input so the icons/buttons display
+ * correctly. This component uses `React.Children.map` and `React.cloneElement` from the
+ * [React.Children](https://react.dev/reference/react/Children) API. This means all children must be
+ * `InputGroup.*` components. Any other direct children will cause issues. You can add different
+ * elements/components inside the {@link InputGroupInnerStart InputGroup.InnerStart} and
+ * {@link InputGroupInnerEnd InputGroup.InnerEnd} subcomponents.
+ *
+ * ```tsx
+ * <InputGroup>
+ *   <InputGroup.InnerStart as={SystemIcon} pointerEvents="none" icon={searchIcon} />
+ *   <InputGroup.Input />
+ *   <InputGroup.InnerEnd>
+ *     <TertiaryButton tabIndex={-1} icon={xIcon} size="small" />
+ *   </InputGroup.InnerEnd>
+ * </InputGroup>
+ * ```
+ */
+export const InputGroup = createContainer('div')({
+  displayName: 'InputGroup',
+  modelHook: useInputGroupModel,
+  subComponents: {
+    /**
+     * A component to show inside and at the start of the input. The input's padding will be
+     * adjusted to not overlap with this element. Use `width` (number of pixels only) to adjust the
+     * width offset. The width defaults to 40px which is the correct width for icons or icon
+     * buttons.
+     */
+    InnerStart: InputGroupInnerStart,
+    /**
+     * The input to render. By default, this is a {@link TextInput}. Use the `as` prop to change the
+     * component to be rendered.
+     */
+    Input: InputGroupInput,
+    /**
+     * A component to show inside and at the end of the input. The input's padding will be adjusted
+     * to not overlap with this element. Use `width` (number of pixels only) to adjust the width
+     * offset. The width defaults to 40px which is the correct width for icons or icon buttons
+     * within the input.
+     */
+    InnerEnd: InputGroupInnerEnd,
+    /**
+     * A component that can be added to an input group that will clear the input. It will only render
+     * when the input has a value and will fade when a value is entered.
+     */
+    ClearButton: ClearButton,
+  },
+})<ExtractProps<typeof Flex, never>>(({children, ...elemProps}, Element) => {
+  const isRTL = useIsRTL();
+  const offsetsStart: (string | number)[] = [];
+  const offsetsEnd: (string | number)[] = [];
+
+  // Collect the widths of the `InnerStart` and `InnerEnd` components into `offsetStart` and
+  // `offsetEnd` arrays
+  React.Children.forEach(children, child => {
+    if (React.isValidElement<any>(child) && child.type === InputGroupInnerStart) {
+      const width = child.props.width || space.xl;
+      offsetsStart.push(width);
+    }
+    if (React.isValidElement<any>(child) && child.type === InputGroupInnerEnd) {
+      const width = child.props.width || space.xl;
+      offsetsEnd.push(width);
+    }
+  });
+
+  // keep track of the index offsets to make sure we calculate the correct position offset
+  let indexStart = 0;
+  let indexEnd = 0;
+
+  // Loop over all the children and set the correct padding and positions
+  const mappedChildren = React.Children.map(children, child => {
+    if (React.isValidElement<any>(child)) {
+      if (child.type === InputGroupInput) {
+        return React.cloneElement(child, {
+          paddingInlineStart: wrapInCalc(offsetsStart),
+          paddingInlineEnd: wrapInCalc(offsetsEnd),
+        });
+      }
+      if (child.type === InputGroupInnerStart) {
+        const offset = wrapInCalc(offsetsStart.slice(0, indexStart)) || 0;
+        indexStart++;
+
+        return React.cloneElement(child, {
+          left: isRTL ? undefined : offset,
+          right: isRTL ? offset : undefined,
+        });
+      }
+      if (child.type === InputGroupInnerEnd) {
+        const offset = wrapInCalc(offsetsEnd.slice(indexEnd, -1)) || 0;
+        indexEnd++;
+
+        return React.cloneElement(child, {
+          left: isRTL ? offset : undefined,
+          right: isRTL ? undefined : offset,
+        });
+      }
+    }
+    return child;
+  });
+
+  return (
+    <Flex as={Element} position="relative" {...elemProps}>
+      {mappedChildren}
+    </Flex>
+  );
+});

package/toast/LICENSE

@@ -45,6 +45,7 @@ END OF TERMS AND CONDITIONS
 
 ©2020. Workday, Inc. All rights reserved. Workday and the Workday logo are registered trademarks of Workday, Inc. All other brand and product names are trademarks or registered trademarks of their respective holders.
 
+
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 http://www.apache.org/licenses/LICENSE-2.0
 

package/toast/README.md

@@ -1,7 +1,5 @@
 # Canvas Kit Toast
 
-Canvas-styled React toast component. Allows for a brief message to be be shown about a process or
-action occurring in the app.
-
-For more detailed information on this component, please refer to the
-[storybook documentation](https://workday.github.io/canvas-kit/?path=/docs/components-popups-toast-react--with-popper#canvas-kit-toast)
+View the
+[documentation for Toast](https://workday.github.io/canvas-kit/?path=/docs/components-popups-toast-react--with-popper#canvas-kit-toast)
+on Storybook.

package/toast/index.ts

@@ -1 +1,2 @@
 export * from './lib/Toast';
+export * from './lib/hooks/useToastModel';

package/toast/lib/Toast.tsx

@@ -1,118 +1,113 @@
-import * as React from 'react';
+import React from 'react';
 
+import {createContainer, ExtractProps} from '@workday/canvas-kit-react/common';
+import {Flex} from '@workday/canvas-kit-react/layout';
 import {Popup} from '@workday/canvas-kit-react/popup';
-import {space, colors, type, CanvasColor} from '@workday/canvas-kit-react/tokens';
-import {SystemIcon} from '@workday/canvas-kit-react/icon';
-import {checkIcon, exclamationCircleIcon} from '@workday/canvas-system-icons-web';
-import {CanvasSystemIcon} from '@workday/design-assets-types';
-import {createComponent, ExtractProps, styled, StyledType} from '@workday/canvas-kit-react/common';
-import {Hyperlink} from '@workday/canvas-kit-react/button';
 
-export interface ToastProps extends ExtractProps<typeof Popup.Card, never> {
-  /**
-   * The icon of the Toast.
-   * @default checkIcon
-   */
-  icon?: CanvasSystemIcon;
-  /**
-   * The color of the Toast icon.
-   * @default colors.greenApple400
-   */
-  iconColor?: CanvasColor | string; // TODO: Fix
-  /**
-   * The text of the Toast message.
-   */
-  children: string;
-  /**
-   * The function called when the Toast is closed.
-   */
-  onClose?: () => void;
-  /**
-   * The function called when the Toast action is clicked.
-   */
-  onActionClick?: () => void;
-  /**
-   * The text of the Toast action.
-   */
-  actionText?: string;
-}
-const toastWidth = 360;
+import {ToastCloseIcon} from './ToastCloseIcon';
+import {ToastIcon} from './ToastIcon';
+import {ToastMessage} from './ToastMessage';
+import {ToastLink} from './ToastLink';
+import {ToastBody} from './ToastBody';
+import {useToastModel} from './hooks/useToastModel';
 
-const ToastContentContainer = styled('div')<Pick<ToastProps, 'onClose'>>(
-  {
-    display: 'flex',
-    alignItems: 'center',
-    ...type.levels.subtext.large,
-  },
-  ({onClose}) => ({
-    marginRight: onClose ? space.m : undefined,
-  })
-);
-
-const ToastSystemIcon = styled(SystemIcon)({
-  marginRight: space.s,
-  alignSelf: 'start',
-});
-
-const {color, ...subTextLargeStyles} = type.levels.subtext.large;
+export interface ToastProps extends Omit<ExtractProps<typeof Popup.Card, never>, 'model'> {}
 
-const StyledActionButton = styled(Hyperlink)<StyledType>({
-  ...subTextLargeStyles,
-  display: 'block',
-  backgroundColor: 'transparent', // To prevent Safari from rendering grey 'buttonface' as bgcolor
-  border: 'none',
-  marginTop: space.xxxs,
-});
-
-const Message = styled('div')({
-  wordBreak: 'break-word',
-});
+/**
+ * The function helps set the correct aria attributes based on the mode
+ * @param mode Defines what aria attributes will be added to the main container
+ * @param id Used to tie the Toast to Toast.Message for screen readers
+ */
+const getAriaAttributes = (mode: string, id: string): React.HtmlHTMLAttributes<HTMLDivElement> => {
+  switch (mode) {
+    case 'dialog':
+      return {
+        'aria-describedby': id,
+        // This is added by Popup.Card, so overwriting to remove it
+        'aria-labelledby': undefined,
+        role: 'dialog',
+      };
+    case 'alert':
+      return {
+        role: 'alert',
+        'aria-live': 'assertive',
+        'aria-atomic': true,
+      };
+    case 'status':
+      return {
+        role: 'status',
+        'aria-live': 'polite',
+        'aria-atomic': true,
+      };
+    default: {
+      return {};
+    }
+  }
+};
 
-export const Toast = createComponent('div')({
+/**
+ * Toast is a compound component that has different modes based on its contents. The modes add the proper aria attributes for accessibility
+ *
+ * ```tsx
+ * import { Toast } from "@workday/canvas-kit-react/toast";
+ *
+ * const MyToast = (props: CardProps) => (
+ *    <Toast mode="dialog" aria-label="notifcation">
+ *      <Toast.Icon icon={checkIcon} color={colors.greenApple400} />
+ *      <Toast.Body>
+ *        <Toast.Message>Your workbook was successfully processed.</Toast.Message>
+ *        <Toast.Link href="#hreflink">Custom Link</Toast.Link>
+ *      </Toast.Body>
+ *      <Toast.CloseIcon aria-label="Close" onClick={handleClose} />
+ *    </Toast>
+ * );
+ *```
+ */
+export const Toast = createContainer('div')({
   displayName: 'Toast',
-  Component: (
-    {
-      icon = checkIcon, // needed for TS2742 - https://github.com/microsoft/TypeScript/issues/29808
-      iconColor = colors.greenApple400,
-      onClose,
-      onActionClick,
-      actionText,
-      children,
-      ...elemProps
-    }: ToastProps,
-    ref,
-    Element
-  ) => {
-    const isInteractive = onClose || onActionClick;
-    const isError = iconColor === colors.cinnamon500 && icon === exclamationCircleIcon;
-
-    return (
-      <Popup.Card
-        ref={ref}
-        as={Element}
-        width={toastWidth}
-        depth={5}
-        role={isInteractive ? 'dialog' : isError ? 'alert' : 'status'}
-        aria-live={isInteractive ? 'off' : isError ? 'assertive' : 'polite'}
-        aria-atomic={!isInteractive}
-        padding="xxs"
-        {...elemProps}
-      >
-        {onClose && <Popup.CloseIcon aria-label="Close" onClick={onClose} size="small" />}
-        <Popup.Body>
-          <ToastContentContainer onClose={onClose}>
-            {icon && <ToastSystemIcon color={iconColor} colorHover={iconColor} icon={icon} />}
-            <Message>
-              {children}
-              {onActionClick && (
-                <StyledActionButton as="button" onClick={onActionClick}>
-                  {actionText}
-                </StyledActionButton>
-              )}
-            </Message>
-          </ToastContentContainer>
-        </Popup.Body>
-      </Popup.Card>
-    );
+  modelHook: useToastModel,
+  subComponents: {
+    /**
+     * `Toast.Body` should container `Toast.Message` and `Toast.Link`. This ensures proper styling and spacing between elements.
+     *
+     * ```tsx
+     * <Toast.Body>
+     *  <Toast.Message>Your workbook was successfully processed.</Toast.Message>
+     *  <Toast.Link href="#hreflink">Custom Link</Toast.Link>
+     * </Toast.Body>
+     * ```
+     */
+    Body: ToastBody,
+    /**
+     * `Toast.CloseIcon` renders a {@link PopupCloseIcon}. You can pass an `onClick` when used with `Popper` to dismiss the `Toast`.
+     */
+    CloseIcon: ToastCloseIcon,
+    /**
+     * `ToastIcon` renders a `SystemIcon` where you have access to all styling properties from `SystemIcon`.
+     */
+    Icon: ToastIcon,
+    /**
+     * `Toast.Message` renders our `Subtext` component where you can style however way you'd like with style properties.
+     * This component also has an `id` so that when the `Toast` has a prop of `mode="dialog"` the message is read out by screen readers by adding an `aria-describedby` on the main `Toast` component.
+     */
+    Message: ToastMessage,
+    /**
+     * `Toast.Link` renders our `Hyperlink` component. If you need to link to more information, use this component.
+     */
+    Link: ToastLink,
   },
+})<ToastProps>(({children, ...elemProps}, _, model) => {
+  return (
+    <Popup.Card
+      as={Flex}
+      width={360}
+      padding="0"
+      {...getAriaAttributes(model.state.mode, model.state.id)}
+      flexDirection="row"
+      gap="xxxs"
+      {...elemProps}
+    >
+      {children}
+    </Popup.Card>
+  );
 });

package/toast/lib/ToastBody.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+
+import {createComponent, ExtractProps} from '@workday/canvas-kit-react/common';
+import {Popup} from '@workday/canvas-kit-react/popup';
+import {Flex} from '@workday/canvas-kit-react/layout';
+
+export interface ToastBodyProps extends ExtractProps<typeof Popup.Body> {}
+
+export const ToastBody = createComponent('div')({
+  displayName: 'Toast.Body',
+  Component: ({children, ...elemProps}: ToastBodyProps, ref, Element) => {
+    return (
+      <Flex
+        alignItems="flex-start"
+        flexDirection="column"
+        justifyContent="center"
+        paddingY="s"
+        ref={ref}
+        as={Element}
+        flexGrow={1}
+        gap="xxxs"
+        {...elemProps}
+      >
+        {children}
+      </Flex>
+    );
+  },
+});

package/toast/lib/ToastCloseIcon.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import {createComponent, ExtractProps} from '@workday/canvas-kit-react/common';
+import {Popup} from '@workday/canvas-kit-react/popup';
+
+export interface ToastCloseIconProps extends ExtractProps<typeof Popup.CloseIcon, never> {}
+
+export const ToastCloseIcon = createComponent('button')({
+  displayName: 'Toast.CloseIcon',
+  Component: (elemProps: ToastCloseIconProps, ref, Element) => {
+    return (
+      <Popup.CloseIcon as={Element} ref={ref} size="small" position="relative" {...elemProps} />
+    );
+  },
+});