@workday/canvas-kit-react 5.2.11 → 5.3.0-next.18

package/tabs/lib/TabsOverflowButton.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+
+import {chevronDownSmallIcon} from '@workday/canvas-system-icons-web';
+import {
+  createComponent,
+  useModelContext,
+  createHook,
+  composeHooks,
+  subModelHook,
+} from '@workday/canvas-kit-react/common';
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {space} from '@workday/canvas-kit-react/tokens';
+import {useOverflowTarget} from './overflow';
+import {useMenuTarget} from './menu';
+
+import {TabsModelContext} from './Tabs';
+import {TabsModel} from './useTabsModel';
+import {StyledTabItem} from './TabsItem';
+
+export interface OverflowButtonProps {
+  /**
+   * The label text of the Tab.
+   */
+  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?: TabsModel;
+}
+
+export const TabsOverflowButton = createComponent('button')({
+  displayName: 'Tabs.OverflowButton',
+  Component: ({model, children, ...elemProps}: OverflowButtonProps, ref, Element) => {
+    const localModel = useModelContext(TabsModelContext, model);
+
+    const props = useTabsOverflowButton(localModel, elemProps, ref);
+
+    return (
+      <StyledTabItem hasIcon={true} spacing={space.xxxs} type="button" as={Element} {...props}>
+        <span>{children}</span>
+        <SystemIcon icon={chevronDownSmallIcon} />
+      </StyledTabItem>
+    );
+  },
+});
+
+export const useTabsOverflowButton = composeHooks(
+  createHook(
+    (model: TabsModel, _?: React.Ref<HTMLButtonElement>, elemProps: {name?: string} = {}) => {
+      return {
+        'aria-haspopup': true,
+      };
+    }
+  ),
+  useOverflowTarget,
+  subModelHook((m: TabsModel) => m.menu, useMenuTarget)
+);

package/tabs/lib/{TabPanel.tsx → TabsPanel.tsx}

@@ -1,19 +1,21 @@
-/** @jsx jsx */
 import React from 'react';
-import {jsx, css} from '@emotion/core';
+import styled from '@emotion/styled';
 
 import {
   createComponent,
-  mouseFocusBehavior,
-  useLocalRef,
   useModelContext,
   useMountLayout,
+  createHook,
+  ExtractProps,
+  hideMouseFocus,
+  StyledType,
 } from '@workday/canvas-kit-react/common';
+import {Box} from '@workday/canvas-kit-labs-react/common';
 
 import {TabsModelContext} from './Tabs';
 import {TabsModel} from './useTabsModel';
 
-export interface TabPanelProps {
+export interface TabPanelProps<T = unknown> extends ExtractProps<typeof Box, never> {
   /**
    * The contents of the TabPanel.
    */
@@ -35,28 +37,20 @@ export interface TabPanelProps {
    * 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?: TabsModel;
+  model?: TabsModel<T>;
 }
 
-const styles = css(
-  mouseFocusBehavior({
-    '&:focus': {
-      outline: 'none',
-    },
-  })
-);
+const StyledTabsPanel = styled(Box)<StyledType>(hideMouseFocus);
 
-export const TabPanel = createComponent('div')({
-  displayName: 'Tabs.Panel',
-  Component: ({children, name = '', model, ...elemProps}: TabPanelProps, ref, Element) => {
-    const {state, events} = useModelContext(TabsModelContext, model);
-    const [tabName, setTabName] = React.useState(name);
-    const {localRef, elementRef} = useLocalRef(ref);
+export const useTabsPanel = createHook(
+  ({state, events}: TabsModel, _?: React.Ref<HTMLElement>, elemProps: {name?: string} = {}) => {
+    const name = elemProps.name;
+    const [tabName, setTabName] = React.useState(elemProps.name || '');
 
     useMountLayout(() => {
       const index = state.panelIndexRef.current;
       const tabName = name || String(index);
-      events.registerPanel({item: {id: tabName, ref: localRef}});
+      events.registerPanel({item: {id: tabName}});
       setTabName(tabName);
 
       return () => {
@@ -64,19 +58,27 @@ export const TabPanel = createComponent('div')({
       };
     });
 
+    return {
+      role: 'tabpanel',
+      'aria-labelledby': `${state.id}-${tabName}`,
+      hidden: !!tabName && tabName !== state.selectedIds[0],
+      id: `tabpanel-${state.id}-${tabName}`,
+      tabIndex: 0,
+    };
+  }
+);
+
+export const TabsPanel = createComponent('div')({
+  displayName: 'Tabs.Panel',
+  Component: ({children, model, ...elemProps}: TabPanelProps, ref, Element) => {
+    const localModel = useModelContext(TabsModelContext, model);
+
+    const props = useTabsPanel(localModel, elemProps, ref);
+
     return (
-      <Element
-        ref={elementRef}
-        role="tabpanel"
-        css={styles}
-        aria-labelledby={`tab-${state.id}-${tabName}`}
-        hidden={!!tabName && tabName !== state.activeTab}
-        id={`tabpanel-${state.id}-${tabName}`}
-        tabIndex={0}
-        {...elemProps}
-      >
+      <StyledTabsPanel as={Element} {...props}>
         {children}
-      </Element>
+      </StyledTabsPanel>
     );
   },
 });

package/tabs/lib/TabsPanels.tsx

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+import {createComponent, useModelContext} from '@workday/canvas-kit-react/common';
+
+import {TabsModelContext} from './Tabs';
+import {TabsModel} from './useTabsModel';
+import {useRenderItems} from './list';
+
+export interface TabsPanelsProps<T = unknown> {
+  /**
+   *
+   */
+  children: ((item: T) => React.ReactNode) | 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?: TabsModel<T>;
+}
+
+export const TabsPanels = createComponent()({
+  displayName: 'Tabs.Panels',
+  Component: ({children, model}: TabsPanelsProps) => {
+    const localModel = useModelContext(TabsModelContext, model);
+
+    return <>{useRenderItems(localModel, children)}</>;
+  },
+});

package/tabs/lib/cursor/index.ts

@@ -1,2 +1,2 @@
-export * from './hooks';
+export * from './useRovingFocus';
 export * from './useCursorModel';

package/tabs/lib/cursor/useCursorModel.tsx

@@ -1,11 +1,5 @@
 import React from 'react';
-import {
-  createEventMap,
-  Model,
-  ToModelConfig,
-  useEventMap,
-  assert,
-} from '@workday/canvas-kit-react/common';
+import {createEventMap, ToModelConfig, useEventMap, assert} from '@workday/canvas-kit-react/common';
 
 import {
   ListState,
@@ -13,13 +7,13 @@ import {
   BaseListModelConfig,
   listEventMap,
   useListModel,
-  Item,
   ListModelConfig,
+  ListModel,
 } from '../list/useListModel';
 
 export type Orientation = 'horizontal' | 'vertical';
 
-export type CursorState = ListState & {
+export type CursorState<T = unknown> = ListState<T> & {
   /** Orientation of the list. This property determines what "next" and "previous" mean. This should
    * be set to match the layout of UI components */
   orientation: Orientation;
@@ -27,7 +21,7 @@ export type CursorState = ListState & {
   cursorId: string;
 };
 
-export type CursorEvents = ListEvents & {
+export type CursorEvents<T = unknown> = ListEvents<T> & {
   /** Directly sets the cursor to the list item by its identifier.  */
   goTo(data: {id: string}): void;
   /** Set the cursor to the "next" item in the list. If the end of the list is detected, it will
@@ -42,7 +36,10 @@ export type CursorEvents = ListEvents & {
   last(): void;
 };
 
-export type CursorModel = Model<CursorState, CursorEvents>;
+export interface CursorModel<T = unknown> extends ListModel<T> {
+  state: CursorState<T>;
+  events: CursorEvents<T>;
+}
 
 export const cursorEventMap = createEventMap<CursorEvents>()({
   guards: {
@@ -61,98 +58,114 @@ export const cursorEventMap = createEventMap<CursorEvents>()({
   },
 });
 
-export type BaseCursorModelConfig = BaseListModelConfig & {
+export type BaseCursorModelConfig<T> = BaseListModelConfig<T> & {
   /**
    * The orientation of a list of items. Values are either `vertical` or `horizontal`. This value will
-   * effect which keys activate progression through a list. For example, `horizontal` will activate with
+   * effect which ids activate progression through a list. For example, `horizontal` will activate with
    * left and right arrows while `vertical` will activate with up and down arrows.
    * @default 'vertical'
    */
   orientation?: Orientation;
+  /**
+   * Initial cursor position. If not provided, the cursor will point to the first item in the list
+   */
+  initialCursorId?: string;
 };
 
-export type CursorModelConfig = BaseCursorModelConfig &
-  Partial<ToModelConfig<CursorState, CursorEvents, typeof cursorEventMap>>;
+export type CursorModelConfig<T> = BaseCursorModelConfig<T> &
+  Partial<ToModelConfig<CursorState<T>, CursorEvents<T>, typeof cursorEventMap>>;
+
+export const useCursorNavigation = <T extends unknown>(
+  state: CursorState<T>,
+  getId: ListModel<T>['getId']
+) => {
+  // refs for performance so that new functions aren't created every render
+  const getIdRef = React.useRef(getId);
+  const itemsRef = React.useRef(state.items);
+  const nonInteractiveIdsRef = React.useRef(state.nonInteractiveIds);
+
+  itemsRef.current = state.items;
+  nonInteractiveIdsRef.current = state.nonInteractiveIds;
+
+  // return a memoized function to prevent recreation of functions every render
+  return React.useMemo(() => {
+    const getFirst = () => itemsRef.current[0];
+    const getLast = () => itemsRef.current[itemsRef.current.length - 1];
+
+    const getItem = (id: string): T => {
+      const item = id ? itemsRef.current.find(item => getIdRef.current(item) === id) : getFirst(); // no id, return first item
+      assert(item, `Item not found: ${id}`);
+      return item;
+    };
+
+    const getOffsetItem = (offset: number) => (id: string, tries = itemsRef.current.length): T => {
+      const items = itemsRef.current;
+      const item = getItem(id);
+
+      const getId = getIdRef.current;
+      const currentIndex = items.findIndex(i => getId(item) === getId(i));
+      let nextIndex = currentIndex + offset;
+      if (nextIndex < 0) {
+        nextIndex = items.length - 1;
+      } else if (nextIndex >= items.length) {
+        nextIndex = 0;
+      }
 
-const getFirst = (items: Item[]): Item => {
-  return items[0];
-};
+      if (nonInteractiveIdsRef.current.includes(getId(items[nextIndex])) && tries > 0) {
+        // The next item is disabled, try again, but only if we haven't already tried everything.
+        // Avoid an infinite loop with `tries`
+        return getOffsetItem(offset)(getId(items[nextIndex]), tries - 1);
+      }
 
-const getLast = (items: Item[]): Item => {
-  return items[items.length - 1];
-};
+      return items[nextIndex];
+    };
 
-export const getItem = (id: string, items: Item[]): Item => {
-  const item = id ? items.find(item => item.id === id) : getFirst(items); // no id, return first item
-  assert(item, `Item not found: ${id}`);
-  return item;
-};
+    const getNext = getOffsetItem(1);
+    const getPrevious = getOffsetItem(-1);
 
-const getOffsetItem = (offset: number) => (id: string, items: Item[]): Item => {
-  const item = getItem(id, items);
-  const currentIndex = items.findIndex(({id}) => item.id === id);
-  let nextIndex = currentIndex + offset;
-  if (nextIndex < 0) {
-    nextIndex = items.length - 1;
-  } else if (nextIndex >= items.length) {
-    nextIndex = 0;
-  }
-
-  const disabledAttribute = items[nextIndex].ref.current?.getAttribute('disabled');
-  if (disabledAttribute !== null || disabledAttribute === 'false') {
-    // The next item is disabled, try again
-    return getOffsetItem(offset)(items[nextIndex].id, items);
-  }
-
-  return items[nextIndex];
+    return {getFirst, getLast, getItem, getNext, getPrevious};
+  }, []);
 };
 
-export const hasItems = (items: Item[]) => items.some(item => item.ref.current);
-
-export const getNext = getOffsetItem(1);
-export const getPrevious = getOffsetItem(-1);
-
-export const useCursorModel = (config: CursorModelConfig = {}): CursorModel => {
+export const useCursorModel = <T extends unknown>(
+  config: CursorModelConfig<T> = {}
+): CursorModel<T> => {
   const [orientation] = React.useState(config.orientation || 'vertical');
   const [cursorId, setCursorId] = React.useState('');
-  const initialCurrentRef = React.useRef('');
-  const list = useListModel(config as ListModelConfig);
+  const list = useListModel(config as ListModelConfig<T>);
+  const initialCurrentRef = React.useRef(
+    config.initialCursorId || config.items?.length ? list.getId(config.items![0]) : ''
+  );
 
   const state = {...list.state, orientation, cursorId};
+  const navigation = useCursorNavigation(state, list.getId);
 
   const events = useEventMap(cursorEventMap, state, config, {
     ...list.events,
     registerItem(data) {
       // point the cursor at the first item
       if (!initialCurrentRef.current) {
-        initialCurrentRef.current = data.item.id;
+        initialCurrentRef.current = list.getId(data.item);
         setCursorId(initialCurrentRef.current);
       }
       list.events.registerItem(data);
     },
-    unregisterItem(data) {
-      // move the cursor forward if the the cursor is pointing to an item that is being removed
-      if (state.cursorId === data.id && state.items.some(i => i.ref.current !== null)) {
-        events.next();
-      }
-      list.events.unregisterItem(data);
-    },
     goTo({id}) {
       setCursorId(id);
     },
     next() {
-      setCursorId(getNext(state.cursorId, state.items).id);
+      setCursorId(list.getId(navigation.getNext(state.cursorId)));
     },
     previous() {
-      setCursorId(getPrevious(state.cursorId, state.items).id);
+      setCursorId(list.getId(navigation.getPrevious(state.cursorId)));
     },
     first() {
-      setCursorId(getFirst(state.items).id);
+      setCursorId(list.getId(navigation.getFirst()));
     },
     last() {
-      setCursorId(getLast(state.items).id);
+      setCursorId(list.getId(navigation.getLast()));
     },
-  });
+  } as CursorEvents<T>);
 
-  return {state, events};
+  return {state, events, getId: list.getId};
 };

package/tabs/lib/cursor/useRovingFocus.tsx

@@ -0,0 +1,94 @@
+import React from 'react';
+import {useIsRTL, createHook} from '@workday/canvas-kit-react/common';
+
+import {CursorModel, useCursorNavigation} from './useCursorModel';
+
+export const orientationKeyMap = {
+  horizontal: {
+    ArrowLeft: 'previous',
+    Left: 'previous',
+    ArrowRight: 'next',
+    Right: 'next',
+    Home: 'first',
+    End: 'last',
+  },
+  vertical: {
+    ArrowUp: 'previous',
+    Up: 'previous',
+    ArrowDown: 'next',
+    Down: 'next',
+    Home: 'first',
+    End: 'last',
+  },
+} as const;
+
+const rightToLeftMap = {
+  ArrowLeft: 'ArrowRight',
+  Left: 'Right',
+  ArrowRight: 'ArrowLeft',
+  Right: 'Left',
+  Home: 'End',
+  End: 'Home',
+} as const;
+
+/**
+ * Handles the roving focus behavior of a Cursor model. It should be added to the element
+ * representing a list item.
+ *
+ * @see https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex
+ */
+export const useRovingFocus = createHook(
+  ({state, events, getId}: CursorModel, ref, elemProps: {name?: string} = {}) => {
+    // Tracks when this element has focus. If this item is removed while still focused, we have to
+    // inform the model to move the cursor to the next item.
+    const focusRef = React.useRef(false);
+    const getIdRef = React.useRef(getId);
+
+    // Create a ref out of state. We don't want to watch state on unmount, so we use a ref to get the
+    // current value at the time of unmounting. Otherwise, `state.items` would be a cached value of an
+    // empty array
+    const stateRef = React.useRef(state);
+    stateRef.current = state;
+
+    const keyDownRef = React.useRef(false);
+    const isRTL = useIsRTL();
+
+    const navigation = useCursorNavigation(state, getId);
+
+    React.useEffect(() => {
+      if (keyDownRef.current) {
+        const item = navigation.getItem(state.cursorId);
+        document.querySelector<HTMLElement>(`#${state.id}-${getIdRef.current(item)}`)?.focus();
+
+        keyDownRef.current = false;
+      }
+    }, [state.cursorId, state.id, navigation]);
+
+    return {
+      onKeyDown(event: React.KeyboardEvent) {
+        (Object.keys(
+          orientationKeyMap[state.orientation]
+        ) as (keyof typeof orientationKeyMap[typeof state.orientation])[]).forEach(key => {
+          if (isRTL ? event.key === rightToLeftMap[key] : event.key === key) {
+            const event = orientationKeyMap[state.orientation][key];
+            keyDownRef.current = true;
+            events[event]?.();
+          }
+        });
+      },
+      onFocus() {
+        focusRef.current = true;
+      },
+      onBlur() {
+        focusRef.current = false;
+      },
+      id: `${state.id}-${elemProps.name}`,
+      tabIndex: !state.cursorId
+        ? 0 // cursor isn't known yet, be safe and mark this as focusable
+        : !!elemProps.name && state.cursorId === elemProps.name
+        ? 0 // A name is known and cursor is here
+        : -1, // A name is known an cursor is somewhere else
+      ref,
+    };
+  }
+);

package/tabs/lib/list/index.ts

@@ -1,2 +1,3 @@
-export * from './hooks';
+export * from './useListRegisterItem';
 export * from './useListModel';
+export * from './renderItem';

package/tabs/lib/list/renderItem.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+
+import {ListModel} from './useListModel';
+
+export function useRenderItems<T>(
+  model: ListModel<T>,
+  children: ((item: T) => React.ReactNode) | React.ReactNode
+) {
+  const items = React.useMemo(() => {
+    return typeof children === 'function'
+      ? model.state.items.map(item => React.cloneElement(children(item), {key: model.getId(item)}))
+      : null;
+    // If we added `children` as a dependency, this memo would be useless. If the user wants the
+    // item to rerender, the item and items array needs to be updated.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [model.state.items]);
+
+  return items || children;
+}

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};
 };