@workday/canvas-kit-react 5.3.0-next.10 → 5.3.0-next.24

package/tabs/lib/list/useListModel.tsx

@@ -5,34 +5,42 @@ import {
   ToModelConfig,
   useEventMap,
   useUniqueId,
+  assert,
 } from '@workday/canvas-kit-react/common';
 
-export type Item = {
-  /** IDREF of the list. Children ids can be derived from this id */
-  id: string;
-  ref: React.RefObject<HTMLElement>;
-};
-
-export type ListState = {
+export type ListState<T = unknown> = {
   /** IDREF of the list. Children ids can be derived from this id */
   id: string;
   /** Used as an auto-incrementing ID for accessibility */
   indexRef: React.RefObject<number>;
-  items: Item[];
+  items: T[];
+  /**
+   * An array of ids of non-interactive elements. Non-interactive elements usually have `disabled`
+   * applied to them and thus are not focusable by the browser. Lists need to know about these so
+   * that keyboard navigation properly skips over these items. Interactive elements that are
+   * disabled should use `[aria-disabled]` instead and should still receive focus.
+   * @see https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_disabled_controls
+   */
+  nonInteractiveIds: string[];
 };
 
-export type ListEvents = {
+export type ListEvents<T = unknown> = {
   /** Register an item to the list. Takes in an identifier, a React.Ref and an optional index. This should be called on
    * component mount */
-  registerItem(data: {item: Item; index?: number}): void;
+  registerItem(data: {item: T; index?: number}): void;
   /** Unregister an item by its identifier. This should be called when the component is unmounted */
   unregisterItem(data: {id: string}): void;
   /** Updates the position of a tab within the list. This should be called when a tab's index is updated */
   updateItemPosition(data: {id: string; index: number}): void;
 };
 
-export type ListModel = Model<ListState, ListEvents>;
+export interface ListModel<T = unknown> extends Model<ListState<T>, ListEvents<T>> {
+  getId: (item: T) => string;
+}
 
+// We don't have a way of knowing what the generic could be, so we leave it as `unknown`. It will
+// probably need to be cast to the generic in use inside extending models. This will not effect the
+// use of the model in an application, only in models composing this model.
 export const listEventMap = createEventMap<ListEvents>()({
   guards: {
     /**
@@ -76,20 +84,37 @@ export const listEventMap = createEventMap<ListEvents>()({
   },
 });
 
-export type BaseListModelConfig = {
+export type BaseListModelConfig<T = unknown> = {
   /** IDREF of the list. Children ids can be derived from this id */
   id?: string;
+  items?: T[];
+  getId?: (item: T) => string;
+  /**
+   * Array of all ids which are currently disabled
+   */
+  nonInteractiveIds?: string[];
 };
 
-export type ListModelConfig = BaseListModelConfig &
-  Partial<ToModelConfig<ListState, ListEvents, typeof listEventMap>>;
+export type ListModelConfig<T> = BaseListModelConfig<T> &
+  Partial<ToModelConfig<ListState<T>, ListEvents<T>, typeof listEventMap>>;
+
+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;
+};
 
-export const useListModel = (config: ListModelConfig = {}): ListModel => {
+export const useListModel = <T extends unknown>(config: ListModelConfig<T> = {}): ListModel<T> => {
   const id = useUniqueId(config.id);
   const indexRef = React.useRef(0);
-  const [items, setItems] = React.useState([] as Item[]);
+  const [items, setItems] = React.useState(config.items || []);
+  const getId = config.getId || defaultGetId;
 
-  const state = {id, items, indexRef};
+  const state = {
+    id,
+    items: config.items || items,
+    indexRef,
+    nonInteractiveIds: config.nonInteractiveIds || [],
+  };
 
   const events = useEventMap(listEventMap, state, config, {
     registerItem({item, index}) {
@@ -105,8 +130,8 @@ export const useListModel = (config: ListModelConfig = {}): ListModel => {
     },
     unregisterItem({id}) {
       setItems(items => {
-        if (items.find(item => item.id === id)) {
-          return items.filter(item => item.id !== id);
+        if (items.find(item => getId(item) === id)) {
+          return items.filter(item => getId(item) !== id);
         } else {
           return items;
         }
@@ -114,12 +139,12 @@ export const useListModel = (config: ListModelConfig = {}): ListModel => {
     },
     updateItemPosition({id, index}) {
       setItems(items => {
-        const copy = items.filter(item => item.id !== id);
-        copy.splice(index, 0, items.find(item => item.id === id)!);
+        const copy = items.filter(item => getId(item) !== id);
+        copy.splice(index, 0, items.find(item => getId(item) === id)!);
         return copy;
       });
     },
-  });
+  } as ListEvents<T>);
 
-  return {state, events};
+  return {state, events, getId};
 };

package/tabs/lib/list/useListRegisterItem.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+
+import {useMountLayout, createHook} from '@workday/canvas-kit-react/common';
+
+import {ListModel} from './useListModel';
+
+/**
+ * Registers an item with a list. It will return elemProps with a `name` which can be used by other
+ * hooks to identify the item in the list.
+ */
+export const useListRegisterItem = createHook(
+  (
+    {state, events, getId}: ListModel,
+    _?: React.Ref<HTMLElement>,
+    elemProps: {name?: string; index?: number; disabled?: boolean} = {}
+  ) => {
+    const [localId, setLocalId] = React.useState(elemProps.name || '');
+    const firstRender = React.useRef(true);
+
+    React.useLayoutEffect(() => {
+      if (elemProps.index !== undefined && !firstRender.current) {
+        events.updateItemPosition({id: localId, index: elemProps.index});
+      }
+      // we only care about the index changing
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [elemProps.index]);
+
+    useMountLayout(() => {
+      const defaultId = state.indexRef.current;
+      const itemId = elemProps.name || String(defaultId);
+      // bail early if item already exists. This happens if items were already provided.
+      if (state.items.find(item => getId(item) === elemProps.name)) {
+        return;
+      }
+      events.registerItem({
+        item: {id: itemId},
+        index: elemProps.index,
+      });
+      setLocalId(itemId);
+      firstRender.current = false;
+
+      return () => {
+        events.unregisterItem({id: itemId});
+      };
+    });
+
+    return {
+      'data-name': localId,
+      name: localId,
+      disabled: elemProps.disabled || state.nonInteractiveIds.includes(localId) ? true : undefined,
+    };
+  }
+);

package/tabs/lib/menu/Menu.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+
+import {createComponent, useDefaultModel} from '@workday/canvas-kit-react/common';
+
+import {MenuModel, MenuModelConfig, useMenuModel} from './useMenuModel';
+import {MenuPopper} from './MenuPopper';
+import {MenuTarget} from './MenuTarget';
+import {MenuItem} from './MenuItem';
+import {MenuCard} from './MenuCard';
+import {MenuList} from './MenuList';
+
+export const MenuModelContext = React.createContext<MenuModel>({} as any);
+
+export interface MenuProps<T> extends MenuModelConfig<T> {
+  /**
+   * The contents of the Menu. Can be `Menu` children or any valid elements.
+   */
+  children: React.ReactNode;
+  /**
+   * Optionally pass a model directly to this component. Default is to create a model out of model
+   * config passed to this component.
+   * @default useMenuModel(config)
+   */
+  model?: MenuModel<T>;
+}
+
+/**
+ * An accessible dropdown menu component. A dropdown menu usually contains a target element that
+ * opens to a menu.
+ * @example
+ * <Menu>
+ *   <Menu.Target>Open</Menu.Target>
+ *   <Menu.Popper>
+ *     <Menu.Card>
+ *       <Menu.List>
+ *         <Menu.Item name="first">First Item</Menu.Item>
+ *         <Menu.Item name="second">Second Item</Menu.Item>
+ *       </Menu.List>
+ *     </Menu.Card>
+ *   </Menu.Popper>
+ * </Menu>
+ */
+export const Menu = createComponent()({
+  displayName: 'Menu',
+  Component: ({children, model, ...config}: MenuProps<any>) => {
+    const value = useDefaultModel(model, config, useMenuModel);
+
+    return <MenuModelContext.Provider value={value}>{children}</MenuModelContext.Provider>;
+  },
+  subComponents: {
+    /**
+     * The menu card is a non-semantic element used to give the dropdown menu its distinct visual
+     * cue that the dropdown menu is floating above other content. A menu card usually contains a
+     * menu list, but can also contain other elements like a header or footer.
+     */
+    Card: MenuCard,
+    /**
+     * The menu list follows the Collections API. A list can either contain static items
+     * or a render prop and `items` to the model.
+     *
+     * @example
+     * const MyComponent = () => {
+     *   const model = useMenuModel({
+     *     items: [
+     *       { id: 'first',  text: 'First Item' },
+     *       { id: 'second', text: 'Second Item' },
+     *     ]
+     *   })
+     *
+     *   return (
+     *     <Menu model={model}>
+     *       <Menu.List>
+     *         {(item) => <Menu.Item name={item.id}>{item.text}</Menu.Item>}
+     *       </Menu.List>
+     *     </Menu>
+     *   )
+     * }
+     */
+    List: MenuList,
+    /**
+     * A menu item has an optional `name` prop that identifies the item in the menu list and will be
+     * passed to the optional `onSelect` callback of the menu model. A menu item can contain any
+     * HTML. If more complex HTML is provided, consider
+     */
+    Item: MenuItem,
+    Target: MenuTarget,
+    /**
+     * The "Popper" of a menu. The popper will appear around the `Menu.Target`. It renders a `div`
+     * element that is portalled to the `document.body` which is controlled by the `PopupStack. The
+     * `PopupStack` is not part of React. This means no extra props given to this component will be
+     * forwarded to the `div` element, but the `ref` will be forwarded.
+     */
+    Popper: MenuPopper,
+  },
+});

package/tabs/lib/menu/MenuCard.tsx

@@ -0,0 +1,96 @@
+import * as React from 'react';
+import {keyframes} from '@emotion/core';
+
+import {Card} from '@workday/canvas-kit-react/card';
+import {space, type} from '@workday/canvas-kit-react/tokens';
+import {
+  styled,
+  TransformOrigin,
+  getTranslateFromOrigin,
+  createComponent,
+  StyledType,
+  useModelContext,
+  ExtractProps,
+  createHook,
+} from '@workday/canvas-kit-react/common';
+import {getTransformFromPlacement} from '@workday/canvas-kit-react/popup';
+
+import {MenuModel} from './useMenuModel';
+import {MenuModelContext} from './Menu';
+
+export interface MenuCardProps<T = unknown> extends ExtractProps<typeof Card, never> {
+  /**
+   * Optionally pass a model directly to this component. Default is to implicitly use the same
+   * model as the container component which uses React context. Only use this for advanced use-cases
+   */
+  model?: MenuModel<T>;
+  children?: React.ReactNode;
+}
+
+const popupAnimation = (transformOrigin: TransformOrigin) => {
+  const translate = getTranslateFromOrigin(transformOrigin, space.xxs);
+
+  return keyframes`
+    0% {
+      opacity: 0;
+      transform: translate(${translate.x}px, ${translate.y}px);
+    }
+    100% {
+      opacity: 1;
+      transform: translate(0);
+    }
+  `;
+};
+
+const StyledCard = styled(Card)<
+  StyledType & {width?: number | string; transformOrigin?: TransformOrigin}
+>(
+  type.levels.subtext.large,
+  {
+    position: 'relative',
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  ({transformOrigin}) => {
+    if (transformOrigin == null) {
+      return {};
+    }
+    return {
+      animation: popupAnimation(transformOrigin),
+      animationDuration: '150ms',
+      animationTimingFunction: 'ease-out',
+      transformOrigin: `${transformOrigin.vertical} ${transformOrigin.horizontal}`,
+      // Allow overriding of animation in special cases
+      '.wd-no-animation &': {
+        animation: 'none',
+      },
+    };
+  }
+);
+
+export const MenuCard = createComponent('div')({
+  displayName: 'Menu.Card',
+  Component: ({children, model, padding = 'zero', ...elemProps}: MenuCardProps, ref, Element) => {
+    const localModel = useModelContext(MenuModelContext, model);
+    const props = useMenuCard(localModel, elemProps, ref);
+    const transformOrigin = React.useMemo(() => {
+      return getTransformFromPlacement(localModel.state.placement || 'bottom');
+    }, [localModel.state.placement]);
+
+    return (
+      <StyledCard
+        maxWidth={`calc(100vw - ${space.l})`}
+        as={Element}
+        transformOrigin={transformOrigin}
+        padding={padding}
+        {...props}
+      >
+        {children}
+      </StyledCard>
+    );
+  },
+});
+
+export const useMenuCard = createHook((_: MenuModel) => {
+  return {};
+});

package/tabs/lib/menu/MenuItem.tsx

@@ -0,0 +1,195 @@
+import * as React from 'react';
+
+import {colors, iconColors, typeColors, space, type} from '@workday/canvas-kit-react/tokens';
+import {
+  createComponent,
+  styled,
+  StyledType,
+  useModelContext,
+  composeHooks,
+  createHook,
+  useLocalRef,
+  useMount,
+} from '@workday/canvas-kit-react/common';
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {OverflowTooltip} from '@workday/canvas-kit-react/tooltip';
+import {Box} from '@workday/canvas-kit-labs-react/common';
+
+import {useListRegisterItem} from '../list';
+import {useRovingFocus} from '../cursor';
+import {MenuModel} from './useMenuModel';
+import {MenuModelContext} from './Menu';
+import {useSelectionItem} from '../selection';
+
+export interface MenuItemProps<T = unknown> {
+  /**
+   * Optionally pass index to menu item. This should be done if `Menu.Item` components were created
+   * via a `Array::map` function. This index will ensure keyboard navigation works even if items are
+   * inserted out of order.
+   */
+  index?: number;
+  /**
+   * The label text of the MenuItem.
+   */
+  children: React.ReactNode;
+  /**
+   * The name of the menu item. This name will be used in the `onSelect` callback in the model. If
+   * this property is not provided, it will default to a string representation of the the zero-based
+   * index of the Tab when it was initialized.
+   */
+  name?: string;
+  /**
+   * Optionally pass a model directly to this component. Default is to implicitly use the same
+   * model as the container component which uses React context. Only use this for advanced use-cases
+   */
+  model?: MenuModel<T>;
+  'aria-disabled'?: boolean;
+  /**
+   * Use `hasIcon={true}` when the Tab item contains an icon. This instructs the tab item to render
+   * children as a flex container to accommodate icons. You will have to use `Tabs.Item.Text` as a
+   * child element if this is set to true.
+   *
+   * @example
+   * <Menu.Item hasIcon>
+   *   <Menu.Item.Icon icon={someIcon} />
+   *   <Menu.Item.Text>Tab Text</Menu.Item.Text>
+   * </Menu.Item>
+   */
+  hasIcon?: boolean;
+}
+
+const StyledItem = styled(Box.as('li'))<StyledType & {hasIcon?: boolean}>(
+  ({theme}) => {
+    return {
+      ...type.levels.subtext.large,
+      '& > *:not(style) ~ *:not(style)': {
+        marginLeft: space.xxs,
+      },
+      padding: `${space.xxs} ${space.s}`,
+      boxSizing: 'border-box',
+      cursor: 'pointer',
+      color: colors.blackPepper300,
+      borderWidth: 0,
+      textAlign: 'left',
+      transition: 'background-color 80ms, color 80ms',
+      '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+        fill: iconColors.active,
+      },
+      '&:hover, &[aria-selected=true]': {
+        backgroundColor: theme.canvas.palette.primary.lightest,
+        color: colors.blackPepper300,
+        '.wd-icon-fill, .wd-icon-accent, .wd-icon-accent2': {
+          fill: iconColors.hover,
+        },
+        '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+          fill: iconColors.active,
+        },
+      },
+      '&:focus': {
+        outline: 'none',
+        backgroundColor: theme.canvas.palette.primary.main,
+        color: typeColors.inverse,
+        '.wd-icon-fill, .wd-icon-accent, .wd-icon-accent2': {
+          fill: iconColors.inverse,
+        },
+        '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+          fill: iconColors.inverse,
+        },
+      },
+      // We want the focus styles no matter what
+      [`[data-whatinput]`]: {
+        backgroundColor: 'inherit',
+        color: colors.blackPepper300,
+        '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+          fill: iconColors.active,
+        },
+        '&:hover, &[aria-selected=true]': {
+          backgroundColor: theme.canvas.palette.primary.lightest,
+          '.wd-icon-fill, .wd-icon-accent, .wd-icon-accent2': {
+            fill: iconColors.hover,
+          },
+        },
+        '&:focus': {
+          '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+            fill: iconColors.active,
+          },
+        },
+      },
+      backgroundColor: 'inherit',
+      '&:disabled, &[aria-disabled]': {
+        color: colors.licorice100,
+        cursor: 'default',
+        '.wd-icon-fill, .wd-icon-accent, .wd-icon-accent2': {
+          fill: iconColors.disabled,
+        },
+        '&:focus': {
+          backgroundColor: colors.blueberry200,
+          '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+            fill: iconColors.disabled,
+          },
+          '&:hover, &[aria-selected=true]': {
+            '.wd-icon-background ~ .wd-icon-accent, .wd-icon-background ~ .wd-icon-accent2': {
+              fill: iconColors.disabled,
+            },
+          },
+        },
+      },
+    };
+  },
+  ({hasIcon}) => {
+    if (hasIcon) {
+      return {
+        display: 'flex',
+      };
+    } else {
+      return {};
+    }
+  }
+);
+
+export const MenuItem = createComponent('button')({
+  displayName: 'Menu.Item',
+  Component: ({model, children, ...elemProps}: MenuItemProps, ref, Element) => {
+    const localModel = useModelContext(MenuModelContext, model);
+
+    const props = useMenuItem(localModel, elemProps, ref);
+
+    if ('production' !== process.env.NODE_ENV) {
+      // ensure `hasIcon` is used when a child has an icon
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const {elementRef, localRef} = useLocalRef(props.ref);
+      props.ref = elementRef;
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      useMount(() => {
+        if (localRef.current.querySelector('svg') && !props.hasIcon) {
+          console.warn(
+            `A Menu.Item with an icon should have the 'hasIcon' prop set to true. This ensures correct rendering`
+          );
+        }
+      });
+    }
+
+    return (
+      <OverflowTooltip placement="left">
+        <StyledItem minHeight={space.xl} as={Element} {...props}>
+          {children}
+        </StyledItem>
+      </OverflowTooltip>
+    );
+  },
+  subComponents: {
+    Icon: SystemIcon,
+    Text: styled('span')({}),
+  },
+});
+
+export const useMenuItem = composeHooks(
+  createHook((model: MenuModel, _?: React.Ref<any>, elemProps: {name?: string} = {}) => {
+    return {
+      role: 'menuitem',
+    };
+  }),
+  useSelectionItem,
+  useRovingFocus,
+  useListRegisterItem
+);

package/tabs/lib/menu/MenuList.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+
+import {commonColors} from '@workday/canvas-kit-react/tokens';
+import {
+  createComponent,
+  useModelContext,
+  createHook,
+  ExtractProps,
+} from '@workday/canvas-kit-react/common';
+import {Stack} from '@workday/canvas-kit-labs-react/layout';
+
+import {MenuModel} from './useMenuModel';
+import {MenuModelContext} from './Menu';
+import {useRenderItems} from '../list';
+
+export interface MenuListProps<T = unknown> extends Partial<ExtractProps<typeof Stack, never>> {
+  /**
+   * The label text of the MenuList.
+   */
+  children: React.ReactNode;
+  /**
+   * Optionally pass a model directly to this component. Default is to implicitly use the same
+   * model as the container component which uses React context. Only use this for advanced use-cases
+   */
+  model?: MenuModel<T>;
+}
+
+export const MenuList = createComponent('div')({
+  displayName: 'Menu.List',
+  Component: ({model, children, ...elemProps}: MenuListProps, ref, Element) => {
+    const localModel = useModelContext(MenuModelContext, model);
+
+    const props = useMenuList(localModel, elemProps, ref);
+
+    return (
+      <Stack
+        as={Element}
+        background={commonColors.background}
+        borderRadius="m"
+        padding="zero"
+        marginY="zero"
+        marginX="xxs"
+        spacing="zero"
+        overflowY="auto"
+        flexDirection={localModel.state.orientation === 'vertical' ? 'column' : 'row'}
+        {...props}
+      >
+        {useRenderItems(localModel, children)}
+      </Stack>
+    );
+  },
+});
+
+export const useMenuList = createHook((model: MenuModel) => {
+  return {
+    role: 'menu',
+    'aria-labelledby': model.state.id,
+  };
+});

package/tabs/lib/menu/MenuPopper.tsx

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+import {createComponent, ExtractProps, useModelContext} from '@workday/canvas-kit-react/common';
+import {usePopupPopper, Popper} from '@workday/canvas-kit-react/popup';
+
+import {MenuModel} from './useMenuModel';
+import {MenuModelContext} from './Menu';
+
+export interface MenuPopperProps<T = unknown> extends ExtractProps<typeof Popper> {
+  /**
+   * Optionally pass a model directly to this component. Default is to implicitly use the same
+   * model as the container component which uses React context. Only use this for advanced use-cases
+   */
+  model?: MenuModel<T>;
+}
+
+export const MenuPopper = createComponent('div')({
+  displayName: 'Menu.Popper',
+  Component: ({children, model, ...elemProps}: MenuPopperProps, ref) => {
+    const localModel = useModelContext(MenuModelContext, model);
+
+    const props = useMenuPopper(localModel, elemProps, ref);
+    return (
+      <Popper placement="bottom-start" {...props}>
+        {children}
+      </Popper>
+    );
+  },
+});
+
+export const useMenuPopper = usePopupPopper;