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

package/skeleton/lib/skeleton.tsx

@@ -39,6 +39,19 @@ const SkeletonAnimator = styled('div')<SkeletonProps & StyledType>({
   position: 'relative',
 });
 
+/**
+ * Skeleton subcomponents **must** be wrapped by the `Skeleton` container component.
+ *
+ * ```tsx
+ * <Skeleton>
+ *   <Skeleton.Header />
+ *   <Skeleton.Text />
+ * </Skeleton>
+ * ```
+ *
+ * `Skeleton` places its children in a container element with `aria-hidden` set to `true` and
+ * announces itself using a visually hidden element.
+ */
 export const Skeleton = createComponent('div')({
   displayName: 'Skeleton',
   Component: (
@@ -53,8 +66,21 @@ export const Skeleton = createComponent('div')({
     </SkeletonAnimator>
   ),
   subComponents: {
+    /**
+     * `Skeleton.Header` renders a placeholder for header content such as headings.
+     */
     Header: SkeletonHeader,
-    Shape: SkeletonShape,
+    /**
+     * `Skeleton.Text` renders a placeholder for text content such as paragraphs. Each placeholder
+     * line has a width of `100%` and a fixed height of `21px`, with the last line having a width of
+     * `60%` if there are multiple lines.
+     */
     Text: SkeletonText,
+    /**
+     * `Skeleton.Shape` renders a placeholder for graphic elements such as icons, avatars and small
+     * images. Set the `height`, `width`, and `borderRadius` props of the `Skeleton.Shape` to create
+     * various rectangular and circular shapes.
+     */
+    Shape: SkeletonShape,
   },
 });

package/tabs/lib/Tabs.tsx

@@ -19,29 +19,121 @@ export interface TabsProps {
   children: React.ReactNode;
 }
 
+/**
+ * `Tabs` is a container component that is responsible for creating a {@link TabsModel} and sharing
+ * it with its subcomponents using React context. It does not represent a real element.
+ *
+ * ```tsx
+ * <Tabs onSelect={data => console.log('Selected tab', data.id)}>
+ *   {child components}
+ * </Tabs>
+ * ```
+ *
+ * Alternatively, you may pass in a model using the hoisted model pattern.
+ *
+ * ```tsx
+ * const model = useTabsModel({
+ *   onSelect(data) {
+ *     console.log('Activated Tab', data.id);
+ *   },
+ * });
+ *
+ * <Tabs model={model}>{child components}</Tabs>
+ * ```
+ *
+ * See [Configuring a
+ * Model](/getting-started/for-developers/resources/compound-components/#configuring-a-model) for
+ * more information on model configuration.
+ */
 export const Tabs = createContainer()({
   displayName: 'Tabs',
   modelHook: useTabsModel,
   subComponents: {
+    /**
+     * `Tabs.List` is a `<div role="tablist">` element. It is a container for {@link TabsItem Tabs.Item}
+     * subcomponents.
+     *
+     * ```tsx
+     * <Tabs.List>{Tabs.Items}</Tabs.List>
+     * ```
+     */
     List: TabsList,
+    /**
+     * `Tabs.Item` is a `<button role="tab">` element. Each `Tabs.Item` is associated with a
+     * `Tabs.Panel` either by a `data-id` attribute or by the position in the list. If a `data-id`
+     * is provided, it must match the `data-id` passed to the corresponding `Tabs.Panel` component.
+     *
+     * ```tsx
+     * <Tabs.Item data-id="first">First Tab</Tabs.Item>
+     * ```
+     */
     Item: TabsItem,
+    /**
+     * `Tabs.Panel` is a `<div role="tabpanel">` element. It is focusable by default. Each
+     * `Tabs.Panel` is controlled by a `Tabs.Item` either by a `data-id` attribute or by the
+     * position in the list. If a `data-id` is provided, it must match the `data-id` passed to the
+     * corresponding `Tabs.Item` component.
+     *
+     * ```tsx
+     * <Tabs.Panel data-id="first">
+     *   {contents of tab panel}
+     * </Tabs.Panel>
+     * ```
+     */
     Panel: TabsPanel,
+    /**
+     * Optional subcomponent of tabs that makes dealing with dynamic tabs easier. `Tabs.Panels` only
+     * works if the model is given an array of items.
+     *
+     * ```tsx
+     * const items = [{ id: '1', name: 'first' }]
+     * <Tabs items={items}>
+     *   {tab list}
+     *   <Tabs.Panels>
+     *     {item => <Tabs.Panel>Contents of {item.name}</Tabs.Panel>}
+     *   </Tabs.Panels>
+     * </Tabs>
+     * ```
+     */
     Panels: TabsPanels,
+    /**
+     * The overflow button of a `Tabs.List`. When a tab list overflows, this overflow button is
+     * rendered. Overflow only works when the model is given an array of `items`.
+     *
+     * ```tsx
+     * <Tabs items={items}>
+     *   <Tabs.List overflowButton={
+     *     <Tabs.OverflowButton>More</Tabs.OverflowButton>
+     *   }>
+     *     {dynamic tab items}
+     *   </Tabs.List>
+     * </Tabs>
+     * ```
+     */
     OverflowButton: TabsOverflowButton,
+    /**
+     * @deprecated Use `Tabs.Menu.Popper` instead
+     */
     MenuPopper: TabsMenuPopper,
     /**
      * The overflow menu of the Tabs component. If there isn't enough room to render all the tab
      * items, the extra tabs that don't fit will be overflowed into this menu.
-     * @example
+     *
+     * ```tsx
      * <Tabs.Menu.Popper>
      *   <Tabs.Menu.Card>
      *     <Tabs.Menu.List>
-     *       {(item: MyTabItem) => <Tabs.Menu.Item data-id={item.id}>{item.text}</Tabs.Menu.Item>}
+     *       {(item: MyTabItem) => <Tabs.Menu.Item data-id={item.id}>
+     *         {item.text}
+     *       </Tabs.Menu.Item>}
      *     </Tabs.Menu.List>
      *   </Tabs.Menu.Card>
      * </Tabs.Menu.Popper>
+     * ```
      */
-    Menu,
+    // We don't use shorthand here for documentation. The shorthand will give the `Tabs.Menu` the
+    // JSDoc of `Menu` instead of `Tabs.Menu`
+    Menu: Menu,
   },
 })<TabsProps>(({children}, _, model) => {
   return <Menu model={model.menu}>{children}</Menu>;

package/tabs/lib/TabsItem.tsx

@@ -14,7 +14,7 @@ import {
   createSubcomponent,
   useModalityType,
 } from '@workday/canvas-kit-react/common';
-import {Box, StackProps} from '@workday/canvas-kit-react/layout';
+import {Box, FlexProps} from '@workday/canvas-kit-react/layout';
 import {OverflowTooltip} from '@workday/canvas-kit-react/tooltip';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
 import {
@@ -28,7 +28,7 @@ import {
 import {useTabsModel} from './useTabsModel';
 export interface TabsItemProps
   extends ExtractProps<typeof Box, never>,
-    Partial<Pick<StackProps, 'spacing'>> {
+    Partial<Pick<FlexProps, 'gap'>> {
   /**
    * Optionally pass index to tab item. This should be done if `Tabs.Item` components were created
    * via a `Array::map` function. This index will ensure keyboard navigation works even if items are
@@ -81,12 +81,9 @@ export interface TabsItemProps
   tabIndex?: number;
 }
 
-export const StyledTabItem = styled(Box.as('button'))<StyledType & Pick<TabsItemProps, 'spacing'>>(
-  ({theme, spacing}) => ({
+export const StyledTabItem = styled(Box.as('button'))<StyledType & Pick<TabsItemProps, 'gap'>>(
+  ({theme}) => ({
     ...type.levels.subtext.large,
-    '& > *:not(style) ~ *:not(style)': {
-      marginLeft: spacing || space.xxs,
-    },
     fontWeight: type.properties.fontWeights.medium,
     border: 'none',
     backgroundColor: 'transparent',
@@ -160,33 +157,31 @@ export const StyledTabItem = styled(Box.as('button'))<StyledType & Pick<TabsItem
       },
     },
   }),
-  ({children}) => {
+  ({children, gap = space.xxs}) => {
     if (typeof children === 'string') {
       return ellipsisStyles;
     } else {
       return {
         display: 'flex',
+        gap,
       };
     }
   }
 );
 
 export const useTabsItem = composeHooks(
-  createElemPropsHook(useTabsModel)(
-    ({state}, _?: React.Ref<HTMLButtonElement>, elemProps: {'data-id'?: string} = {}) => {
-      const name = elemProps['data-id'] || '';
+  createElemPropsHook(useTabsModel)(({state}, _, elemProps: {'data-id'?: string} = {}) => {
+    const name = elemProps['data-id'] || '';
 
-      const selected = !!elemProps['data-id'] && isSelected(name, state);
+    const selected = !!elemProps['data-id'] && isSelected(name, state);
 
-      return {
-        type: 'button',
-        role: 'tab',
-        id: `${state.id}-${name}`,
-        'aria-selected': selected,
-        'aria-controls': `tabpanel-${state.id}-${name}`,
-      };
-    }
-  ),
+    return {
+      type: 'button' as const,
+      role: 'tab' as const,
+      'aria-selected': selected,
+      'aria-controls': `tabpanel-${state.id}-${name}`,
+    };
+  }),
   useListItemSelect,
   useOverflowListItemMeasure,
   useListItemRovingFocus,

package/tabs/lib/TabsList.tsx

@@ -10,7 +10,7 @@ import {
   styled,
   StyledType,
 } from '@workday/canvas-kit-react/common';
-import {Stack} from '@workday/canvas-kit-react/layout';
+import {Flex} from '@workday/canvas-kit-react/layout';
 import {
   useOverflowListMeasure,
   useListRenderItems,
@@ -19,9 +19,7 @@ import {
 
 import {useTabsModel} from './useTabsModel';
 
-// Use `Partial` here to make `spacing` optional
-export interface TabListProps<T = any>
-  extends Omit<Partial<ExtractProps<typeof Stack, never>>, 'children'> {
+export interface TabListProps<T = any> extends Omit<ExtractProps<typeof Flex, never>, 'children'> {
   /**
    * If items are passed to a `TabsModel`, the child of `Tabs.List` should be a render prop. The
    * List will determine how and when the item will be rendered.
@@ -38,25 +36,18 @@ export interface TabListProps<T = any>
 export const useTabsList = composeHooks(
   createElemPropsHook(useTabsModel)(() => {
     const modality = useModalityType();
-    return {role: 'tablist', overflowX: modality === 'touch' ? 'auto' : undefined};
+    return {
+      role: 'tablist',
+      overflowX: modality === 'touch' ? 'auto' : undefined,
+    } as const;
   }),
   useOverflowListMeasure,
   useListResetCursorOnBlur
 );
 
-const StyledStack = styled(Stack)<StyledType>({
-  '::after': {
-    content: '""',
-    position: 'sticky',
-    height: 52,
-    minWidth: 30,
-    background: `linear-gradient(to right,rgba(255,255,255,0),white);`,
-    zIndex: 1,
-    right: 0,
-    top: 0,
-    pointerEvents: 'none',
-  },
-});
+const StyledStack = styled(Flex)<StyledType & {maskImage?: string}>(({maskImage}) => ({
+  maskImage: maskImage,
+}));
 
 export const TabsList = createSubcomponent('div')({
   displayName: 'Tabs.List',
@@ -64,13 +55,21 @@ export const TabsList = createSubcomponent('div')({
   elemPropsHook: useTabsList,
 })<TabListProps>(({children, overflowButton, ...elemProps}, Element, model) => {
   const modality = useModalityType();
+  const touchStates = useTouchDirection();
   return (
     <StyledStack
       as={Element}
       position="relative"
       borderBottom={`1px solid ${commonColors.divider}`}
       paddingX={modality === 'touch' ? 'zero' : 'm'}
-      spacing="xxxs"
+      gap="xs"
+      maskImage={
+        modality === 'touch' && touchStates.isDragging
+          ? `linear-gradient(${
+              touchStates.direction === 'left' ? 'to left' : 'to right'
+            }, white 80%, transparent)`
+          : undefined
+      }
       {...elemProps}
     >
       {useListRenderItems(model, children)}
@@ -78,3 +77,36 @@ export const TabsList = createSubcomponent('div')({
     </StyledStack>
   );
 });
+
+export const useTouchDirection = () => {
+  const [isDragging, setIsDragging] = React.useState(false);
+  const [touchDir, setTouchDirection] = React.useState('right');
+
+  React.useEffect(() => {
+    let prevXPos = window.pageXOffset;
+    const handleTouchMove = function(e: TouchEvent) {
+      const currXPos = e.touches[0].clientX;
+      setIsDragging(true);
+      if (currXPos > prevXPos) {
+        setTouchDirection('left');
+      } else if (currXPos < prevXPos) {
+        setTouchDirection('right');
+      }
+      prevXPos = currXPos;
+      e.preventDefault();
+    };
+    const handleDragEnd = function() {
+      setIsDragging(false);
+    };
+    window.addEventListener('touchmove', handleTouchMove);
+    window.addEventListener('touchstart', handleDragEnd);
+    window.addEventListener('touchend', handleDragEnd);
+    return () => {
+      window.removeEventListener('touchmove', handleTouchMove);
+      window.removeEventListener('touchstart', handleDragEnd);
+      window.removeEventListener('touchend', handleDragEnd);
+    };
+  }, []);
+
+  return {direction: touchDir, isDragging: isDragging};
+};

package/tabs/lib/TabsOverflowButton.tsx

@@ -4,7 +4,7 @@ import {chevronDownSmallIcon} from '@workday/canvas-system-icons-web';
 import {
   createElemPropsHook,
   composeHooks,
-  subModelHook,
+  createSubModelElemPropsHook,
   createSubcomponent,
 } from '@workday/canvas-kit-react/common';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
@@ -25,10 +25,10 @@ export const useTabsOverflowButton = composeHooks(
   createElemPropsHook(useTabsModel)(() => {
     return {
       'aria-haspopup': true,
-    };
+    } as const;
   }),
   useOverflowListTarget,
-  subModelHook((m: ReturnType<typeof useTabsModel>) => m.menu, useMenuTarget)
+  createSubModelElemPropsHook(useTabsModel)(m => m.menu, useMenuTarget)
 );
 
 export const TabsOverflowButton = createSubcomponent('button')({
@@ -37,7 +37,7 @@ export const TabsOverflowButton = createSubcomponent('button')({
   elemPropsHook: useTabsOverflowButton,
 })<OverflowButtonProps>(({children, ...elemProps}, Element) => {
   return (
-    <StyledTabItem type="button" spacing="xxxs" as={Element} {...elemProps}>
+    <StyledTabItem type="button" gap="xxxs" as={Element} {...elemProps}>
       <span>{children}</span>
       <SystemIcon icon={chevronDownSmallIcon} />
     </StyledTabItem>

package/tabs/lib/TabsPanel.tsx

@@ -8,6 +8,7 @@ import {
   ExtractProps,
   hideMouseFocus,
   StyledType,
+  slugify,
 } from '@workday/canvas-kit-react/common';
 import {Item} from '@workday/canvas-kit-react/collection';
 import {Box} from '@workday/canvas-kit-react/layout';
@@ -38,11 +39,7 @@ export interface TabPanelProps extends ExtractProps<typeof Box, never> {
 const StyledTabsPanel = styled(Box)<StyledType>(hideMouseFocus);
 
 export const useTabsPanel = createElemPropsHook(useTabsModel)(
-  (
-    {state, events},
-    _?: React.Ref<HTMLElement>,
-    elemProps: {'data-id'?: string; item?: Item<any>} = {}
-  ) => {
+  ({state, events}, _, elemProps: {'data-id'?: string; item?: Item<any>} = {}) => {
     const [localId, setLocalId] = React.useState(elemProps['data-id'] || elemProps.item?.id || '');
 
     useMountLayout(() => {
@@ -57,11 +54,11 @@ export const useTabsPanel = createElemPropsHook(useTabsModel)(
     });
 
     return {
-      role: 'tabpanel',
-      'aria-labelledby': `${state.id}-${localId}`,
+      role: 'tabpanel' as const,
+      'aria-labelledby': slugify(`${state.id}-${localId}`),
       hidden: !!localId && localId !== state.selectedIds[0],
-      id: `tabpanel-${state.id}-${localId}`,
-      tabIndex: 0,
+      id: slugify(`tabpanel-${state.id}-${localId}`),
+      tabIndex: 0 as const,
     };
   }
 );

package/tabs/lib/useTabsModel.tsx

@@ -8,6 +8,22 @@ import {
 
 import {useMenuModel} from '@workday/canvas-kit-react/menu';
 
+/**
+ * The TabsModel extends the [Collection
+ * System](/getting-started/for-developers/resources/collection-api/). Tabs have tab items and
+ * panels. Tabs can be overflowed if there isn't enough room to render and will overflow to a
+ * {@link MenuModel} sub-model.
+ *
+ * ```tsx
+ * const model = useTabsModel({
+ *   onSelect(data) {
+ *     console.log('Selected Tab', data)
+ *   }
+ * })
+ *
+ * <Tabs model={model}>{Tabs child components}</Tabs>
+ * ```
+ */
 export const useTabsModel = createModelHook({
   defaultConfig: {
     ...useOverflowListModel.defaultConfig,
@@ -32,6 +48,7 @@ export const useTabsModel = createModelHook({
     menuConfig: {} as typeof useMenuModel.TConfig,
   },
   requiredConfig: useOverflowListModel.requiredConfig,
+  contextOverride: useOverflowListModel.Context,
 })(config => {
   const initialSelectedRef = React.useRef(config.initialTab);
   const getId = config.getId || defaultGetId;

package/text/lib/LabelText.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import {Property} from 'csstype';
-import {createComponent, styled, StyledType} from '@workday/canvas-kit-react/common';
-import {Text, TextProps} from '@workday/canvas-kit-react/text';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {Text, TextProps} from './Text';
 import {inputColors} from '@workday/canvas-kit-react/tokens';
 
 export interface TypeLabelProps extends TextProps {
@@ -9,17 +9,37 @@ export interface TypeLabelProps extends TextProps {
   disabled?: boolean;
 }
 
-const StyledLabel = styled(Text.as('label'))<StyledType & TypeLabelProps>(
-  ({cursor, disabled, variant}) => ({
-    color: disabled && variant !== 'inverse' ? inputColors.disabled.text : undefined,
-    cursor: cursor && !disabled ? cursor : 'default',
-    opacity: disabled && variant === 'inverse' ? '.4' : '1',
-  })
-);
-
+/**
+ * This component is intended to be used for labeling input fields. It's built on top of the
+ * {@link Text} component, so it has access to all `TextProps`. By default, it renders a semantic
+ * `label` element.
+ *
+ * It also uses the `subtext.large` typeLevel by default:
+ * - font-size: 14px (0.875rem)
+ * - font-weight: regular (400)
+ *
+ * ```tsx
+ * import { LabelText } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomLabelText = () => (
+ *   <LabelText>Input Label Text</LabelText>
+ * );
+ * ```
+ */
 export const LabelText = createComponent('label')({
   displayName: 'Label',
-  Component: (elemProps: TypeLabelProps, ref, Element) => {
-    return <StyledLabel ref={ref} as={Element} typeLevel="subtext.large" {...elemProps} />;
+  Component: ({cursor, disabled, variant, ...elemProps}: TypeLabelProps, ref, Element) => {
+    return (
+      <Text
+        ref={ref}
+        as={Element}
+        typeLevel="subtext.large"
+        color={disabled && variant !== 'inverse' ? inputColors.disabled.text : undefined}
+        cursor={cursor && !disabled ? cursor : 'default'}
+        opacity={disabled && variant === 'inverse' ? '.4' : '1'}
+        variant={variant}
+        {...elemProps}
+      />
+    );
   },
 });

package/text/lib/Text.tsx

@@ -7,17 +7,26 @@ import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
 export interface TextProps extends BoxProps {
   /**
    * Type token as string with level and size separated by dot.
-   */
-   typeLevel?: `${keyof CanvasTypeHierarchy}.${'large'|'medium'|'small'}`;
+   * These values map to our [Canvas type levels](https://canvas.workday.com/tokens/type#type-styles).
+   *
+   * ```tsx
+   * <Text typeLevel="body.small">Small body text</Text>
+   * ```
+  */
+  typeLevel?: `${keyof CanvasTypeHierarchy}.${'large'|'medium'|'small'}`;
   /**
    * Type variant token names: `error`, `hint` or `inverse`.
-   */
+   *
+   * ```tsx
+   * <Text variant="error" typeLevel="subtext.large">Error text</Text>
+   * ```
+  */
   variant?: keyof CanvasTypeVariants;
 }
 
 /**
  * Function returns updated props by token and variant values
- */
+*/
 const validateProps = ({typeLevel, variant, ...props}: TextProps) => {
   let updatedProps: any = props;
   const tokenPropNames = [
@@ -31,7 +40,7 @@ const validateProps = ({typeLevel, variant, ...props}: TextProps) => {
 
   /*
   If token provided it updates undefined values of token styles:
-  `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `color` 
+  `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `color`
   by replacing them by token value
   */
   if (typeLevel) {
@@ -56,6 +65,37 @@ const validateProps = ({typeLevel, variant, ...props}: TextProps) => {
   return updatedProps;
 };
 
+/**
+ * This is a generic base component intended to render any text. It's built on top of the
+ * {@link Box} component. It also has `typeLevel` and `variant` style props that simplify navigating
+ * our type hierarchy and using [Canvas type
+ * tokens](https://canvas.workday.com/tokens/type#type-styles). By default, it renders a semantic
+ * `span` element, but you can adjust this as needed with the `as` prop.
+ *
+ * The type hierarchy is organized into four levels, which correspond to our [Canvas type
+ * levels](https://canvas.workday.com/tokens/type#type-styles).
+ *
+ * - `title`: Intended to be used for large page titles.
+ * - `heading`: Intended to be used for headings and large text.
+ * - `body`: Intended to be used for standard body text.
+ * - `subtext`: Intended to be used for small subtext content or in tight spaces.
+ *
+ * Each level has three sizes: `large`, `medium`, and `small`.
+ *
+ * You can provide any level and size to the `typeLevel` prop, and it will apply the correct styles
+ * accordingly. In the example below we're providing the `subtext` level and `small` size to the
+ * component with the value `subtext.small`.
+ *
+ * ```tsx
+ * import { Text } from '@workday/canvas-kit-react/text';
+ *
+ * const CustomErrorText = () => (
+ *   <Text typeLevel="subtext.small" variant="error">
+ *     Error Text
+ *   </Text>
+ * );
+ * ```
+*/
 export const Text = createComponent('span')({
   displayName: 'Text',
   Component: ({children, ...elemProps}: TextProps, ref, Element) => (