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

package/button/lib/PrimaryButton.tsx

@@ -88,14 +88,11 @@ const getPrimaryButtonColors = (variant: 'inverse' | undefined, theme: EmotionCa
 export interface PrimaryButtonProps extends Themeable, GrowthBehavior, BaseButtonProps {
   /**
    * The variant of the PrimaryButton.
-   * @default undefined
    */
   variant?: 'inverse';
   /**
    * There are four button sizes: `extraSmall`, `small`, `medium`, and `large`.
    * If no size is provided, it will default to `medium`.
-   *
-   * @default 'medium'
    */
   size?: ButtonSizes;
   /**
@@ -106,17 +103,24 @@ export interface PrimaryButtonProps extends Themeable, GrowthBehavior, BaseButto
   /**
    * Button icon positions can either be `start` or `end`.
    * If no value is provided, it defaults to `start`.
-   * @default 'start'
    */
   iconPosition?: IconPositions;
   /**
    * If set to `true`, transform the icon's x-axis to mirror the graphic
-   * @default false
    */
   shouldMirrorIcon?: boolean;
   children?: React.ReactNode;
 }
 
+/**
+ * Primary Buttons are high emphasis. Use once per screen to draw attention to the highest priority
+ * action. Multiple primary buttons make it confusing for the user to understand what action they
+ * should take. Not all screens require a Primary Button.
+ *
+ * Primary Buttons have four sizes: `extraSmall`, `small`, `medium`, and `large`. Icons are
+ * supported for every size and can be positioned at the `start` or `end` with the `iconPosition`
+ * prop.
+ */
 export const PrimaryButton = createComponent('button')({
   displayName: 'PrimaryButton',
   Component: (

package/button/lib/SecondaryButton.tsx

@@ -45,6 +45,15 @@ export interface SecondaryButtonProps extends Themeable, GrowthBehavior, BaseBut
   children?: React.ReactNode;
 }
 
+/**
+ * Secondary Buttons have a medium level of emphasis. Use them for non-critical actions. Secondary
+ * Buttons can be used on most pages without restrictions and work well for multiple actions of
+ * equal weight. They can be used in conjunction with a Primary Button or independently.
+ *
+ * Secondary Buttons have four sizes: `extraSmall`, `small`, `medium`, and `large`. Icons are
+ * supported for every size and can be positioned at the `start` or `end` with the `iconPosition`
+ * prop.
+ */
 export const SecondaryButton = createComponent('button')({
   displayName: 'SecondaryButton',
   Component: (

package/button/lib/TertiaryButton.tsx

@@ -16,20 +16,16 @@ import {BaseButton, BaseButtonProps} from './BaseButton';
 export interface TertiaryButtonProps extends Themeable, BaseButtonProps {
   /**
    * The variant of the TertiaryButton.
-   * @default undefined
    */
   variant?: 'inverse' | undefined;
   /**
-   * There are three button sizes: `extraSmall`, `small`, and `medium`.
+   * There are four button sizes: `extraSmall`, `small`, `medium`, and `large`.
    * If no size is provided, it will default to `medium`.
-   *
-   * @default 'medium'
    */
   size?: ButtonSizes;
   /**
    * Button icon positions can either be `start` or `end`.
    * If no value is provided, it defaults to `start`.
-   * @default 'start'
    */
   iconPosition?: IconPositions;
   /**
@@ -41,18 +37,15 @@ export interface TertiaryButtonProps extends Themeable, BaseButtonProps {
    */
   /**
    * If set to `true`, transform the icon's x-axis to mirror the graphic
-   * @default false
    */
   shouldMirrorIcon?: boolean;
   /**
    * If set to `true`, transform text to all letters uppercase
-   * @default undefined
    */
   allCaps?: boolean;
   children?: React.ReactNode;
   /**
    * If set to `true`, make icon button available to use theme colors instead of default
-   * @default false
    */
   isThemeable?: boolean;
 }
@@ -200,6 +193,16 @@ const getMinWidthStyles = (children: React.ReactNode, size: ButtonSizes): string
   return children ? 'auto' : minWidthNum;
 };
 
+/**
+ * Tertiary Buttons have the lowest emphasis. Use for less important actions that the user may not
+ * often be looking to do. Tertiary Buttons have lower prominence as its container is not visible
+ * until it is interacted with. Use Tertiary Buttons for supplemental actions such as “View More”,
+ * “Read More” or “Select a File”. Tertiary Buttons are frequently used on Cards.
+ *
+ * Tertiary Buttons have four sizes: `extraSmall`, `small`, `medium` and `large`. Icons are
+ * supported for every size and can be positioned at the `start` or `end` with the `iconPosition`
+ * prop.
+ */
 export const TertiaryButton = createComponent('button')({
   displayName: 'TertiaryButton',
   Component: (
@@ -211,7 +214,6 @@ export const TertiaryButton = createComponent('button')({
       children,
       icon,
       shouldMirrorIcon = false,
-      allCaps,
       ...elemProps
     }: TertiaryButtonProps,
     ref,
@@ -224,7 +226,6 @@ export const TertiaryButton = createComponent('button')({
       <StyledTertiaryButtonContainer
         ref={ref}
         as={Element}
-        allCaps={allCaps}
         colors={getTertiaryButtonColors(variant, theme, hasThemeStyles)}
         size={size}
         padding={getPaddingStyles(icon, iconPosition, children, size)}

package/button/lib/parts/ButtonLabelIcon.tsx

@@ -1,22 +1,15 @@
 import React from 'react';
-import {CanvasSystemIcon} from '@workday/design-assets-types';
 import {ButtonSizes, IconPositions} from '../types';
 import {createComponent} from '@workday/canvas-kit-react/common';
-import {SystemIcon} from '@workday/canvas-kit-react/icon';
-import {BoxProps} from '@workday/canvas-kit-react/layout';
+import {SystemIcon, SystemIconProps} from '@workday/canvas-kit-react/icon';
 
-export interface ButtonLabelIconProps extends BoxProps {
+export interface ButtonLabelIconProps extends Partial<SystemIconProps> {
   /**
    * There are four button sizes: `extraSmall`, `small`, `medium`, and `large`.
    *
    * @default 'medium'
    */
   size?: ButtonSizes;
-  /**
-   * The icon of the Button.
-   * Note: not displayed at `small` size
-   */
-  icon?: CanvasSystemIcon;
   /**
    * Button icon positions can either be `left` or `right`.
    * If no value is provided, it defaults to `left`.

package/card/lib/Card.tsx

@@ -14,6 +14,18 @@ export interface CardProps extends BoxProps {
   children?: React.ReactNode;
 }
 
+/**
+ * `Card` is a container component that holds a {@link CardBody Card.Body} and an optional
+ * {@link CardHeading Card.Heading}. `Card` wraps a non-semantic `div` element. The element can be
+ * replaced using the `as` prop, or a `role` or other `aria-*` attributes can be added to give
+ * `Card` semantic meaning.
+ *
+ * **Note**: Changing the `Card` container to certain semantic elements will put accessibility at
+ * risk. For example, using the `as` prop to change the cards to buttons will flatten the content in
+ * the card. Headings, calls to action, etc. will not function as expected for users with
+ * disabilities. Semantic container elements like `<section>`, or using `<li>` grouped together in a
+ * common `<ul>` can be a useful way to elevate the accessibility of your design.
+ */
 export const Card = createComponent('div')({
   displayName: 'Card',
   Component: ({children, ...elemProps}: CardProps, ref, Element) => {
@@ -33,7 +45,31 @@ export const Card = createComponent('div')({
     );
   },
   subComponents: {
+    /**
+     * `Card.Heading` is an optional subcomponent that is meant to describe the Card. Since `Card`
+     * is a non-semantic presentational component, `Card.Heading` does not automatically have any
+     * semantic meaning. If your use case requires the Heading to label the Card, you must do so
+     * manually.
+     *
+     * For example, {@link Modal} (which uses a `Card`) adds an `aria-labelledby` and a `role` to
+     * the `Card`, as well as an `id` to the `Card.Heading`.
+     *
+     * ```tsx
+     * <Card role="dialog" aria-labelledby="card-heading">
+     *   <Card.Heading id="card-heading">Card Title</Card.Heading>
+     *   <Card.Body>Card Contents</Card.Body>
+     * </Card>
+     * ```
+     *
+     * `Card.Heading` defaults to an `<h3>` element, but it can be changed using the `as` prop.
+     */
     Heading: CardHeading,
+    /**
+     * `Card.Body` is a non-semantic subcomponent that contains the body of the card. Attributes may
+     * be added to give `Card.Body` semantic meaning. If `Card.Body` is brief (like in a short
+     * dialog), it may be helpful to add an `aria-describedby` referencing the `id` of the
+     * `Card.Body` to the `Card` container.
+     */
     Body: CardBody,
   },
 });

package/checkbox/lib/Checkbox.tsx

@@ -29,7 +29,7 @@ export interface CheckboxProps extends Themeable {
   disabled?: boolean;
   /**
    * The HTML `id` of the underlying checkbox input element. This is required if `label` is defined as a non-empty string.
-   * @default A uniquely generated id
+   * @default {useUniqueId}
    */
   id?: string;
   /**
@@ -314,9 +314,6 @@ export const Checkbox = createComponent('input')({
       theme = useTheme(),
       id,
       disabled,
-      onChange,
-      value,
-      error,
       indeterminate,
       variant,
       ...elemProps
@@ -334,10 +331,7 @@ export const Checkbox = createComponent('input')({
             disabled={disabled}
             id={inputId}
             ref={ref}
-            onChange={onChange}
             type="checkbox"
-            value={value}
-            error={error}
             variant={variant}
             aria-checked={indeterminate ? 'mixed' : checked}
             {...elemProps}
@@ -365,7 +359,7 @@ export const Checkbox = createComponent('input')({
             htmlFor={inputId}
             disabled={disabled}
             variant={variant}
-            paddingLeft={checkboxLabelDistance}
+            paddingInlineStart={checkboxLabelDistance}
           >
             {label}
           </LabelText>

package/collection/index.ts

@@ -8,9 +8,13 @@ export * from './lib/useListRenderItem';
 export * from './lib/useListResetCursorOnBlur';
 export * from './lib/useListItemRovingFocus';
 export * from './lib/useListItemSelect';
+export * from './lib/useListKeyboardHandler';
+export * from './lib/useListLoader';
 export * from './lib/useListModel';
 export * from './lib/useGridModel';
-export {ListBox} from './lib/ListBox';
+export * from './lib/useListActiveDescendant';
+export * from './lib/useListItemAllowChildStrings';
+export {ListBox, ListBoxProps} from './lib/ListBox';
 export {
   singleSelectionManager,
   multiSelectionManager,

package/collection/lib/ListBox.tsx

@@ -3,26 +3,27 @@ import {
   createContainer,
   createElemPropsHook,
   createSubcomponent,
+  ExtractProps,
 } from '@workday/canvas-kit-react/common';
-import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 
 import {useListModel} from './useListModel';
 import {useListRenderItems} from './useListRenderItem';
 import {useListItemRegister} from './useListItemRegister';
 
-export interface ListBoxProps extends Omit<BoxProps, 'children'> {
-  children?: React.ReactNode | ((item: any) => React.ReactNode);
+export interface ListBoxProps<T = any> extends Omit<ExtractProps<typeof Flex, never>, 'children'> {
+  children?: React.ReactNode | ((item: T, index: number) => React.ReactNode);
 }
 
 export const ListBoxItem = createSubcomponent('li')({
   displayName: 'Item',
   modelHook: useListModel,
   elemPropsHook: useListItemRegister,
-})<BoxProps>((elemProps, Element) => {
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
   return <Box as={Element} {...elemProps} />;
 });
 
-const useListBox = createElemPropsHook(useListModel)(model => {
+export const useListBox = createElemPropsHook(useListModel)(model => {
   return {
     style: {
       position: 'relative' as const,
@@ -32,8 +33,17 @@ const useListBox = createElemPropsHook(useListModel)(model => {
 });
 
 /**
- * Basic list box that supports virtualization. `ListBox.Item` contains a very simple list item
- * without much functionality. The `ListBox` contains two `Box` elements:
+ * The `ListBox` component that offers vertical rendering of a collection in the form of a
+ * 2-dimension list. It supports virtualization, rendering only visible items in the DOM while also
+ * providing aria attributes to allow screen readers to still navigate virtual lists. The `ListBox`
+ * contains a basic `ListBox.Item` that renders list items that render correctly with virtualization
+ * and adds `aria-setsize` and `aria-posinset` for screen readers.
+
+ * The `ListBox` is very basic and only adds enough functionality to render correctly. No additional
+ * behaviors are added to navigate or select. React Hooks are provided to add this functionality and
+ * are used by higher level components like `Menu` and `Menu.Item` which utilize `ListBox`. The
+ * `ListBox` contains two `Box` elements:
+ *
  * - Outer Box: Presentational container element responsible for overflow and height. `height` and
  *   `maxHeight` props will be applied here.
  * - Inner Box: The element responsible for the virtual container. Height is controlled by the model
@@ -45,26 +55,31 @@ export const ListBox = createContainer('ul')({
   elemPropsHook: useListBox,
   subComponents: {
     /**
-     * Extremely simple ListBox item that contains no functionality other than registering items and
-     * adding aria virtualization attributes. If you need more functionality, create your own
-     * component using list item hooks.
+     * The `ListBox.Item` is a simple placeholder for listbox items. The functionality of a
+     * collection item varies between components. For example, a `Tabs.Item` and a `Menu.Item` have
+     * shared functionality, but have different behavior. All collection-based components should
+     * implement a custom `Item` subcomponent using the collection-based behavior hooks. The [Roving
+     * Tabindex](#roving-tabindex) example uses the `elemPropsHook` to provide additional
+     * functionality. `elemPropsHook` is provided on all compound components and is useful in the
+     * example to add additional functionality without making a new component.
      */
     Item: ListBoxItem,
   },
-})<ListBoxProps>(({height, maxHeight, ...elemProps}, Element, model) => {
+})<ListBoxProps>(({height, maxHeight, marginY, ...elemProps}, Element, model) => {
+  // We're moving `marginY` to the container to not interfere with the virtualization size. We set
+  // the `marginY` on the Flex to `0` to avoid inaccurate scrollbars
+
   // TODO figure out what style props should go to which `Box`
   return (
     <Box
       ref={model.state.containerRef}
-      height={
-        height || model.state.isVirtualized ? model.state.UNSTABLE_virtual.totalSize : undefined
-      }
+      marginY={marginY}
       maxHeight={maxHeight}
       overflowY={model.state.orientation === 'vertical' ? 'auto' : undefined}
     >
-      <Box as={Element} {...elemProps}>
+      <Flex as={Element} flexDirection="column" {...elemProps} marginY={0}>
         {useListRenderItems(model, elemProps.children)}
-      </Box>
+      </Flex>
     </Box>
   );
 });

package/collection/lib/keyUtils.ts

@@ -0,0 +1,88 @@
+import React from 'react';
+import {useCursorListModel} from './useCursorListModel';
+
+export const orientationKeyMap = {
+  horizontal: {
+    ArrowLeft: 'goToPrevious',
+    Left: 'goToPrevious',
+    ArrowRight: 'goToNext',
+    Right: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+  vertical: {
+    ArrowUp: 'goToPrevious',
+    Up: 'goToPrevious',
+    ArrowDown: 'goToNext',
+    Down: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+} as const;
+
+const rightToLeftMap = {
+  ArrowLeft: 'ArrowRight',
+  Left: 'Right',
+  ArrowRight: 'ArrowLeft',
+  Right: 'Left',
+  Home: 'Home',
+  End: 'End',
+  PageDown: 'PageDown',
+  PageUp: 'PageUp',
+} as const;
+
+const gridKeyMap = {
+  ...orientationKeyMap.horizontal,
+  Home: 'goToFirstOfRow',
+  End: 'goToLastOfRow',
+  ArrowUp: 'goToPreviousRow',
+  Up: 'goToPreviousRow',
+  ArrowDown: 'goToNextRow',
+  Down: 'goToNextRow',
+} as const;
+
+const ctrlKeyMap = {
+  Home: 'goToFirst',
+  End: 'goToLast',
+} as const;
+
+const hasOwnKey = <T extends object>(obj: T, key: any): key is keyof T => obj.hasOwnProperty(key);
+
+export function keyboardEventToCursorEvents(
+  event: React.KeyboardEvent,
+  model: ReturnType<typeof useCursorListModel>,
+  isRTL: boolean
+): boolean {
+  // Test ctrl key first
+  if (event.ctrlKey) {
+    for (const key in ctrlKeyMap) {
+      if (hasOwnKey(ctrlKeyMap, key)) {
+        if (event.key === key) {
+          model.events[ctrlKeyMap[key]]?.();
+          return true;
+        }
+      }
+    }
+  }
+  // Try regular keys
+  const map = model.state.columnCount > 0 ? gridKeyMap : orientationKeyMap[model.state.orientation];
+  for (const key in map) {
+    if (hasOwnKey(map, key)) {
+      if (isRTL ? event.key === rightToLeftMap[key] : event.key === key) {
+        const eventName =
+          model.state.columnCount > 0
+            ? gridKeyMap[key]
+            : orientationKeyMap[model.state.orientation][key];
+        if (model.events[eventName]) {
+          model.events[eventName]?.();
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}

package/collection/lib/useBaseListModel.tsx

@@ -1,17 +1,16 @@
 import React from 'react';
 import {useVirtual} from './react-virtual';
 
-import {useUniqueId, assert, createModelHook, Generic} from '@workday/canvas-kit-react/common';
+import {useUniqueId, createModelHook, Generic} from '@workday/canvas-kit-react/common';
 
 export type Orientation = 'horizontal' | 'vertical';
 
 export const defaultGetId = (item: any): string => {
-  assert(item.id, 'A list item must have an `id` field or a `getId` function defined');
-  return item.id;
+  return typeof item === 'string' ? item : item.id || '';
 };
 
 export const defaultGetTextValue = (item: any): string => {
-  return item.text || '';
+  return typeof item === 'string' ? item : item.text || '';
 };
 
 export interface Item<T> {
@@ -79,15 +78,21 @@ export const useBaseListModel = createModelHook({
     /** IDREF of the list. Children ids can be derived from this id */
     id: '',
     /**
-     * Optional function to return an id of an item. If not provided, the default function will return
-     * the `id` property from the object of each item. If you did not provide `items`, do not override
-     * this function. If you don't provided `items` and instead provide static items via JSX, the list
-     * will create an internal array of items where `id` is the only property and the default `getId`
-     * will return the desired result.
+     * Optional function to return an id of an item. If not provided, the default function will
+     * return the `id` property from the object of each item. If you did not provide `items`, do not
+     * override this function. If you don't provided `items` and instead provide static items via
+     * JSX, the list will create an internal array of items where `id` is the only property and the
+     * default `getId` will return the desired result.
      */
-    getId: (item: Generic) => item.id as string,
-
-    getTextValue: (item: Generic) => (item.text || '') as string,
+    getId: (item: Generic) =>
+      typeof item === 'string' ? item : item === undefined ? '' : (item.id as string),
+    /**
+     * Optional function to return the text representation of an item. If not provided, the default
+     * function will return the `text` property of the object of each item or an empty string if
+     * there is no `text` property. If you did not provide `items`, do not override this function.
+     */
+    getTextValue: (item: Generic) =>
+      (typeof item === 'string' ? item : item === undefined ? '' : item.text || '') as string,
     /**
      * Array of all ids which are currently disabled. This is used for navigation to skip over items
      * which are not focusable.
@@ -112,8 +117,17 @@ export const useBaseListModel = createModelHook({
 })(config => {
   const id = useUniqueId(config.id);
 
+  // Optimization to not redo items when `getId` and `getTextValue` references change. They will not
+  // likely change during the lifecycle and we don't want to recalculate items when a lamba is
+  // passed instead of a stable reference.
+  const getIdRef = React.useRef(defaultGetId);
+  const getTextValueRef = React.useRef(defaultGetTextValue);
+
   const getId = config.getId || defaultGetId;
   const getTextValue = config.getTextValue || defaultGetTextValue;
+  getIdRef.current = getId;
+  getTextValueRef.current = getTextValue;
+
   const [orientation] = React.useState(config.orientation || 'vertical');
   const [UNSTABLE_defaultItemHeight, setDefaultItemHeight] = React.useState(
     config.defaultItemHeight
@@ -125,13 +139,13 @@ export const useBaseListModel = createModelHook({
     () =>
       (config.items || []).map((item, index) => {
         return {
-          id: getId(item),
+          id: getIdRef.current(item),
           index,
           value: item,
-          textValue: getTextValue(item),
+          textValue: getTextValueRef.current(item),
         };
       }),
-    [config.items, getId, getTextValue]
+    [config.items]
   );
   const [staticItems, setStaticItems] = React.useState<Item<Generic>[]>([]);
   const UNSTABLE_virtual = useVirtual({