@workday/canvas-kit-react 6.0.0-beta.0-next.13 → 6.0.0

package/tabs/lib/overflow/useOverflowModel.tsx

@@ -0,0 +1,185 @@
+import React from 'react';
+
+import {createEventMap, ToModelConfig, useEventMap} from '@workday/canvas-kit-react/common';
+import {
+  SelectionState,
+  SelectionEvents,
+  BaseSelectionModelConfig,
+  useSelectionModel,
+  SelectionModelConfig,
+  selectionEventMap,
+  SelectionModel,
+} from '../selection';
+
+export type OverflowState<T = unknown> = SelectionState<T> & {
+  containerWidth: number;
+  overflowTargetWidth: number;
+  itemWidthCache: Record<string, number>;
+  hiddenIds: string[];
+};
+
+export type OverflowEvents<T = unknown> = SelectionEvents<T> & {
+  setContainerWidth(data: {width?: number}): void;
+  setOverflowTargetWidth(data: {width: number}): void;
+  addItemWidth(data: {id: string; width: number}): void;
+  removeItemWidth(data: {id: string}): void;
+  addHiddenKey(data: {id: string}): void;
+  removeHiddenKey(data: {id: string}): void;
+};
+
+export interface OverflowModel<T = unknown> extends SelectionModel<T> {
+  state: OverflowState<T>;
+  events: OverflowEvents<T>;
+}
+
+export const overflowEventMap = createEventMap<OverflowEvents>()({
+  guards: {
+    ...selectionEventMap.guards,
+    shouldSetContainerWidth: 'setContainerWidth',
+    shouldSetOverflowTargetWidth: 'setOverflowTargetWidth',
+    shouldAddItemWidth: 'addItemWidth',
+    shouldRemoveItemWidth: 'removeItemWidth',
+    shouldAddHiddenKey: 'addHiddenKey',
+    shouldRemoveHiddenKey: 'removeHiddenKey',
+  },
+  callbacks: {
+    ...selectionEventMap.callbacks,
+    onSetContainerWidth: 'setContainerWidth',
+    onSetOverflowTargetWidth: 'setOverflowTargetWidth',
+    onAddItemWidth: 'addItemWidth',
+    onRemoveItemWidth: 'removeItemWidth',
+    onAddHiddenKey: 'addHiddenKey',
+    onRemoveHiddenKey: 'removeHiddenKey',
+  },
+});
+
+export type BaseOverflowModelConfig<T> = BaseSelectionModelConfig<T> & {
+  initialHiddenIds?: string[];
+  containerWidth?: number;
+};
+
+export type OverflowModelConfig<T> = BaseOverflowModelConfig<T> &
+  Partial<ToModelConfig<OverflowState<T>, OverflowEvents<T>, typeof selectionEventMap>>;
+
+export function getHiddenIds(
+  containerWidth: number,
+  overflowTargetWidth: number,
+  itemWidthCache: Record<string, number>,
+  selectedIds: string[] | 'all'
+): string[] {
+  /** Allows us to prioritize showing the selected item */
+  let selectedKey: undefined | string;
+  /** Tally of combined item widths. We'll add items that fit until the container is full */
+  let itemWidth = 0;
+  /** Tally ids that won't fit inside the container. These will be used by components to hide
+   * elements that won't fit in the container */
+  const hiddenIds: string[] = [];
+
+  if (selectedIds !== 'all' && selectedIds.length) {
+    selectedKey = selectedIds[0];
+  }
+
+  if (
+    Object.keys(itemWidthCache).reduce((sum, key) => sum + itemWidthCache[key], 0) <= containerWidth
+  ) {
+    // All items fit, return empty array
+    return [];
+  } else if (selectedKey) {
+    if (itemWidthCache[selectedKey] + overflowTargetWidth > containerWidth) {
+      // If the selected item doesn't fit, only show overflow (all items hidden)
+      return Object.keys(itemWidthCache);
+    } else {
+      // at least the selected item and overflow target fit. Update our itemWidth with the sum
+      itemWidth += itemWidthCache[selectedKey] + overflowTargetWidth;
+    }
+  }
+
+  for (const key in itemWidthCache) {
+    if (key !== selectedKey) {
+      itemWidth += itemWidthCache[key];
+      if (itemWidth > containerWidth) {
+        hiddenIds.push(key);
+      }
+    }
+  }
+
+  return hiddenIds;
+}
+
+export const useOverflowModel = <T extends unknown>(
+  config: OverflowModelConfig<T> = {}
+): OverflowModel<T> => {
+  const [hiddenIds, setHiddenIds] = React.useState(config.initialHiddenIds || []);
+  const [itemWidthCache, setItemWidthCache] = React.useState<Record<string, number>>({});
+  const [containerWidth, setContainerWidth] = React.useState(0);
+  const containerWidthRef = React.useRef(0);
+  const itemWidthCacheRef = React.useRef(itemWidthCache);
+  const [overflowTargetWidth, setOverflowTargetWidth] = React.useState(0);
+  const overflowTargetWidthRef = React.useRef(0);
+
+  // Cursors skip over disabled ids, but know nothing of hidden ids. We'll go ahead and disable
+  // hidden ids as well
+  const nonInteractiveIds = (config.nonInteractiveIds || []).concat(hiddenIds);
+
+  const model = useSelectionModel({...(config as SelectionModelConfig<T>), nonInteractiveIds});
+
+  const state = {
+    ...model.state,
+    hiddenIds,
+    itemWidthCache,
+    containerWidth,
+    overflowTargetWidth,
+  };
+
+  const events = useEventMap(overflowEventMap, state, config, {
+    ...model.events,
+    select(data) {
+      const {selectedIds} = model.selection.select(data.id, state as SelectionState<T>);
+      const ids = getHiddenIds(
+        containerWidthRef.current,
+        overflowTargetWidthRef.current,
+        itemWidthCacheRef.current,
+        selectedIds
+      );
+      model.events.select(data);
+
+      setHiddenIds(ids);
+    },
+    setContainerWidth({width}) {
+      containerWidthRef.current = width || 0;
+      setContainerWidth(width || 0);
+
+      const ids = getHiddenIds(
+        containerWidthRef.current,
+        overflowTargetWidthRef.current,
+        itemWidthCacheRef.current,
+        state.selectedIds
+      );
+
+      setHiddenIds(ids);
+    },
+    setOverflowTargetWidth({width}) {
+      overflowTargetWidthRef.current = width;
+      setOverflowTargetWidth(width);
+    },
+    addItemWidth({id, width}) {
+      itemWidthCacheRef.current = {...itemWidthCacheRef.current, [id]: width};
+
+      setItemWidthCache(itemWidthCacheRef.current);
+    },
+    removeItemWidth({id}) {
+      const newCache = {...itemWidthCacheRef.current};
+      delete newCache[id];
+      itemWidthCacheRef.current = newCache;
+      setItemWidthCache(itemWidthCacheRef.current);
+    },
+    addHiddenKey({id}) {
+      setHiddenIds(ids => ids.concat(id));
+    },
+    removeHiddenKey({id}) {
+      setHiddenIds(ids => ids.filter(key => key !== id));
+    },
+  } as OverflowEvents<T>);
+
+  return {state, events, selection: model.selection, getId: model.getId};
+};

package/tabs/lib/overflow/useOverflowTarget.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+
+import {createHook, useMountLayout, useLocalRef} from '@workday/canvas-kit-react/common';
+
+import {OverflowModel} from './useOverflowModel';
+
+// use a hidden style instead of `hidden` attribute for measurement purposes. `hidden` elements have no dimensions
+const hiddenStyle = {
+  position: 'absolute',
+  left: -99999,
+};
+
+export const useOverflowTarget = createHook(
+  (model: OverflowModel, ref?: React.Ref<HTMLButtonElement>) => {
+    const {elementRef, localRef} = useLocalRef(ref);
+    // track first render to force correct size calculations
+    const firstRender = React.useRef(true);
+
+    useMountLayout(() => {
+      firstRender.current = false;
+      if (localRef.current) {
+        const styles = getComputedStyle(localRef.current);
+
+        model.events.setOverflowTargetWidth({
+          width:
+            localRef.current.offsetWidth +
+            parseFloat(styles.marginLeft) +
+            parseFloat(styles.marginRight),
+        });
+      }
+    });
+
+    const isHidden = !model.state.hiddenIds.length;
+
+    return {
+      ref: elementRef,
+      'aria-hidden': isHidden,
+      tabIndex: -1,
+      style: isHidden ? hiddenStyle : {},
+    };
+  }
+);

package/tabs/lib/selection/index.ts

@@ -0,0 +1,3 @@
+export * from './useSelectionModel';
+export * from './useSelectionItem';
+export * from './useResetCursorOnBlur';

package/tabs/lib/selection/useResetCursorOnBlur.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+
+import {createHook} from '@workday/canvas-kit-react/common';
+import {orientationKeyMap} from '../cursor';
+
+import {SelectionModel} from './useSelectionModel';
+
+/**
+ * Reset the cursor to the selected item when the list looses focus
+ */
+export const useResetCursorOnBlur = createHook(({state, events}: SelectionModel) => {
+  const programmaticFocusRef = React.useRef(false);
+  return {
+    onKeyDown(event: React.KeyboardEvent) {
+      // Programmatic focus only on any focus change via keyboard
+      if (Object.keys(orientationKeyMap[state.orientation]).indexOf(event.key) !== -1) {
+        programmaticFocusRef.current = true;
+      }
+    },
+    onFocus() {
+      programmaticFocusRef.current = false;
+    },
+    onBlur() {
+      if (!programmaticFocusRef.current) {
+        events.goTo({id: state.selectedIds[0]});
+      }
+    },
+  };
+});

package/tabs/lib/selection/useSelectionItem.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+import {createHook} from '@workday/canvas-kit-react/common';
+
+import {SelectionModel} from './useSelectionModel';
+
+export const useSelectionItem = createHook(
+  (
+    {state, events}: SelectionModel,
+    _?: React.Ref<HTMLElement>,
+    elemProps: {name?: string} = {}
+  ) => {
+    const name = elemProps.name || '';
+    const onClick = (event: React.MouseEvent<HTMLElement>) => {
+      if (
+        state.nonInteractiveIds.includes(name) ||
+        event.currentTarget.hasAttribute('aria-disabled')
+      ) {
+        return;
+      }
+      events.select({id: name});
+    };
+
+    return {onClick};
+  }
+);

package/tabs/lib/selection/useSelectionModel.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import {createEventMap, ToModelConfig, useEventMap} from '@workday/canvas-kit-react/common';
+import {
+  CursorState,
+  CursorEvents,
+  BaseCursorModelConfig,
+  useCursorModel,
+  CursorModelConfig,
+  cursorEventMap,
+  CursorModel,
+} from '../cursor/useCursorModel';
+
+export type Orientation = 'horizontal' | 'vertical';
+
+export type SelectionState<T = unknown> = CursorState<T> & {
+  selectedIds: 'all' | string[];
+  unselectedIds: string[];
+};
+
+export type SelectionEvents<T = unknown> = CursorEvents<T> & {
+  /** Select a specific item by its identifier. */
+  select(data: {id: string}): void;
+  /** Select all items. This will set `selectedIds` to `'all'` and remove all `unselectedIds`.
+   * This is especially useful for virtual lists where not all items are loaded in memory.
+   */
+  selectAll(): void;
+  unselectAll(): void;
+};
+
+export interface SelectionModel<T = unknown> extends CursorModel<T> {
+  state: SelectionState<T>;
+  events: SelectionEvents<T>;
+  selection: SelectionManager;
+}
+
+export const selectionEventMap = createEventMap<SelectionEvents>()({
+  guards: {
+    ...cursorEventMap.guards,
+    /** Should a cursor position be set? Use only in advance use-cases */
+    shouldSelect: 'select',
+  },
+  callbacks: {
+    ...cursorEventMap.callbacks,
+    /**
+     * Called when a cursor position has been changed. Useful to set state or perform side effects.
+     * This is called during state change batching, so calling state setters will not invoke extra
+     * renders.
+     */
+    onSelect: 'select',
+  },
+});
+
+/**
+ * A SelectionManager is used
+ */
+export interface SelectionManager {
+  select(
+    id: string,
+    prevState: Pick<SelectionState, 'selectedIds' | 'unselectedIds'>
+  ): Pick<SelectionState, 'selectedIds' | 'unselectedIds'>;
+}
+
+export const isSelected = (
+  id: string,
+  {selectedIds, unselectedIds}: Pick<SelectionState, 'selectedIds' | 'unselectedIds'>
+) => {
+  if (selectedIds === 'all') {
+    return !unselectedIds.includes(id);
+  }
+  return selectedIds.includes(id);
+};
+
+export const singleSelectionManager: SelectionManager = {
+  select(id: string) {
+    return {selectedIds: [id], unselectedIds: []};
+  },
+};
+
+export const multiSelectionManager: SelectionManager = {
+  select(id: string, {selectedIds, unselectedIds}) {
+    if (selectedIds === 'all') {
+      // If we have all selected, start adding/removing from `unselectedIds`
+      const existingKey = unselectedIds.includes(id);
+      return {
+        selectedIds: 'all',
+        unselectedIds: existingKey
+          ? unselectedIds.filter(key => key !== id)
+          : unselectedIds.concat(id),
+      };
+    } else {
+      const existingKey = selectedIds.includes(id);
+      return {
+        selectedIds: existingKey ? selectedIds.filter(key => key !== id) : selectedIds.concat(id),
+        unselectedIds: [],
+      };
+    }
+  },
+};
+
+export type BaseSelectionModelConfig<T> = BaseCursorModelConfig<T> & {
+  initialSelectedIds?: string[];
+  initialUnselectedIds?: string[];
+  selection?: SelectionManager;
+};
+
+export type SelectionModelConfig<T> = BaseSelectionModelConfig<T> &
+  Partial<ToModelConfig<SelectionState<T>, SelectionEvents<T>, typeof selectionEventMap>>;
+
+export const useSelectionModel = <T extends unknown>(
+  config: SelectionModelConfig<T> = {}
+): SelectionModel<T> => {
+  const cursor = useCursorModel(config as CursorModelConfig<T>);
+  const [selectedIds, setSelectedIds] = React.useState<'all' | string[]>(
+    config.initialSelectedIds || []
+  );
+  const [unselectedIds, setUnselectedIds] = React.useState(config.initialUnselectedIds || []);
+
+  const selection = config.selection || singleSelectionManager;
+
+  const state = {...cursor.state, selectedIds, unselectedIds};
+
+  const events = useEventMap(selectionEventMap, state, config, {
+    ...cursor.events,
+    select(data) {
+      const {selectedIds, unselectedIds} = selection.select(data.id, state);
+      setSelectedIds(selectedIds);
+      setUnselectedIds(unselectedIds);
+      events.goTo({id: data.id});
+    },
+  } as SelectionEvents<T>);
+
+  return {state, events, selection, getId: cursor.getId};
+};

package/tabs/lib/useTabsModel.tsx

@@ -1,79 +1,67 @@
 import React from 'react';
-import {createEventMap, Model, ToModelConfig, useEventMap} from '@workday/canvas-kit-react/common';
 import {
-  CursorState,
-  CursorEvents,
-  cursorEventMap,
-  useCursorModel,
-  BaseCursorModelConfig,
-  Orientation,
-  CursorModelConfig,
-  getNext,
-} from './cursor/useCursorModel';
-import {Item, ListEvents, ListState, useListModel} from './list/useListModel';
+  createEventMap,
+  ToModelConfig,
+  useEventMap,
+  useUniqueId,
+} from '@workday/canvas-kit-react/common';
+import {Orientation} from './cursor';
+import {defaultGetId, ListEvents, ListState, useListModel} from './list';
+import {MenuModel, MenuModelConfig, useMenuModel} from './menu';
+import {
+  overflowEventMap,
+  OverflowEvents,
+  OverflowState,
+  OverflowModelConfig,
+  BaseOverflowModelConfig,
+  useOverflowModel,
+  OverflowModel,
+} from './overflow';
 
-export type TabsState = CursorState & {
-  /**
-   * The name of the active tab provided to the `Tabs.Item` component. If no name is provided, it
-   * will be a string of the index position.
-   */
-  activeTab: string;
+export type TabsState<T> = OverflowState<T> & {
+  /** IDREF of the list. Children ids can be derived from this id */
+  id: string;
   /**
    * A list of panels. Uses `ListModel`
    */
-  panels: Item[];
+  panels: T[];
   /**
    * A React.Ref of the current item index. A ref is used to allow for updating outside the normal
    * React state cycle to ensure accurate index tracking as items are registered within the same
    * state setting phase.
    */
-  panelIndexRef: ListState['indexRef'];
+  panelIndexRef: ListState<T>['indexRef'];
+  orientation: Orientation;
+  getId: (item: T) => string;
 };
 
-export type TabsEvents = CursorEvents & {
-  /**
-   * This event will set the `activeTab` in the state. Called when a user activates a tab
-   */
-  activate(data: {
-    /**
-     * The name of the tab provided to the `Tabs.Item` component. If no name is provided, it will
-     * be a string of the index position
-     */
-    tab: string;
-  }): void;
+export type TabsEvents<T = unknown> = OverflowEvents<T> & {
   /**
    * This event registers panels with state.panels. Called when a panel is mounted.
    */
-  registerPanel: ListEvents['registerItem'];
+  registerPanel: ListEvents<T>['registerItem'];
   /**
    * This event unregisters panels with state.panels. Called when a panel is unmounted.
    */
-  unregisterPanel: ListEvents['unregisterItem'];
+  unregisterPanel: ListEvents<T>['unregisterItem'];
 };
 
-export type TabsModel = Model<TabsState, TabsEvents>;
+export interface TabsModel<T = unknown> extends OverflowModel<T> {
+  state: TabsState<T>;
+  events: TabsEvents<T>;
+  menu: MenuModel<T>;
+}
 
 export const tabEventMap = createEventMap<TabsEvents>()({
   guards: {
-    ...cursorEventMap.guards,
-    /**
-     * Should the tab activate? Can prevent the tab from activating. Use this only for advanced
-     * use-cases.
-     */
-    shouldActivate: 'activate',
+    ...overflowEventMap.guards,
   },
   callbacks: {
-    ...cursorEventMap.callbacks,
-    /**
-     * This callback will fire whenever a tab is activated. The data will contain the tab's named
-     * passed to the `Tabs.Item` component. If no name was passed, it will be the index of the tab
-     * as a string.
-     */
-    onActivate: 'activate',
+    ...overflowEventMap.callbacks,
   },
 });
 
-export type BaseTabsModelConfig = Omit<BaseCursorModelConfig, 'orientation'> & {
+export type BaseTabsModelConfig<T> = Omit<BaseOverflowModelConfig<T>, 'orientation'> & {
   /**
    * Optional id for the whole `Tabs` group. The `aria-controls` of the `Tab.Item` and `id` of the
    * `Tab.Panel` will automatically derived from this id. If not provided, a unique id will be
@@ -92,55 +80,82 @@ export type BaseTabsModelConfig = Omit<BaseCursorModelConfig, 'orientation'> & {
    * @default 'horizontal'
    */
   orientation?: Orientation;
+  menuConfig?: MenuModelConfig<T>;
 };
 
-export type TabsModelConfig = BaseTabsModelConfig &
-  Partial<ToModelConfig<TabsState, TabsEvents, typeof tabEventMap>>;
+export type TabsModelConfig<T> = BaseTabsModelConfig<T> &
+  Partial<ToModelConfig<TabsState<T>, TabsEvents<T>, typeof tabEventMap>>;
 
-export const useTabsModel = (config: TabsModelConfig = {}): TabsModel => {
-  const initialTabRef = React.useRef(config.initialTab);
-  const [activeTab, setActiveTab] = React.useState(initialTabRef.current || '');
+export const useTabsModel = <T extends unknown>(config: TabsModelConfig<T> = {}): TabsModel<T> => {
+  const id = useUniqueId(config.id);
+  const initialSelectedRef = React.useRef(config.initialTab);
+  const getId = config.getId || defaultGetId;
 
-  const cursor = useCursorModel({
+  const items = config.items; // || (emptyItems as T[]);
+
+  const model = useOverflowModel<T>({
+    ...(config as OverflowModelConfig<T>),
+    id: `${id}-tabs`,
     orientation: config.orientation || 'horizontal',
-    ...(config as CursorModelConfig),
+    items,
+    onRegisterItem({data, prevState}) {
+      config?.onRegisterItem?.({data, prevState: prevState as TabsState<T>});
+      if (!initialSelectedRef.current) {
+        initialSelectedRef.current = getId(data.item);
+        events.select({id: initialSelectedRef.current});
+      }
+    },
+    initialSelectedIds: config.initialTab
+      ? [config.initialTab]
+      : config.items?.length
+      ? [getId(config.items![0])]
+      : [],
   });
-  const panels = useListModel();
 
-  const state = {
-    ...cursor.state,
-    activeTab,
+  const panels = useListModel<T>();
+
+  const state: TabsState<T> = {
+    ...model.state,
+    id,
+    getId,
+    orientation: config.orientation || 'horizontal',
     panels: panels.state.items,
     panelIndexRef: panels.state.indexRef,
   };
 
+  const overflowItems = React.useMemo(
+    () => (items ? items.filter(item => state.hiddenIds.includes(getId(item))) : undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [state.hiddenIds, items]
+  );
+
   const events = useEventMap(tabEventMap, state, config, {
-    ...cursor.events,
-    activate(data) {
-      setActiveTab(data.tab);
-      events.goTo({id: data.tab});
-    },
-    registerItem(data) {
-      if (!initialTabRef.current) {
-        initialTabRef.current = data.item.id;
-        setActiveTab(initialTabRef.current);
-      }
-      cursor.events.registerItem(data);
-    },
-    unregisterItem(data) {
-      // Activate the next tab if the current one is removed
-      if (state.activeTab === data.id && state.items.some(i => i.ref.current !== null)) {
-        const item = getNext(state.activeTab, state.items);
-        events.activate({tab: item.id});
-      }
-      cursor.events.unregisterItem(data);
-    },
+    ...model.events,
     registerPanel: panels.events.registerItem,
     unregisterPanel: panels.events.unregisterItem,
+  } as TabsEvents<T>);
+
+  const menu = useMenuModel({
+    id: `${id}-menu`,
+    items: overflowItems,
+    nonInteractiveIds: state.nonInteractiveIds.filter(key => !state.hiddenIds.includes(key)),
+    onSelect({data, prevState}) {
+      menu.events.hide();
+      events.select(data);
+      config.menuConfig?.onSelect?.({data, prevState});
+    },
+    onShow({data, prevState}) {
+      // Always select the first item when the menu is opened
+      menu.events.first();
+      config.menuConfig?.onShow?.({data, prevState});
+    },
   });
 
   return {
     state,
     events,
+    menu,
+    getId: model.getId,
+    selection: model.selection,
   };
 };

package/tokens/README.md

@@ -174,23 +174,16 @@ const buttonSyles = {
 
 ## Depth
 
-Five levels of depth are available. They are directly exported from `@workday/canvas-depth-web`.
-
-| Level            | Usage Recommendations             |
-| ---------------- | --------------------------------- |
-| Depth -1 (inset) | Inset card depth                  |
-| Depth 1          | Standard card depth               |
-| Depth 2          | Increased card depth on hover     |
-| Depth 3          | Active cards, popups              |
-| Depth 4          | Cards on white backgrounds, menus |
+Depth is the relative distance between surfaces in the z-axis. It provides delineation, focus, and priority with shadows and layering. There are five depth levels, `inset`, `1`, `2`, `3`, and `4`. Most levels only apply box-shadow styles, but `depth[4]` also applies border styles.
 
 ### Usage
 
 ```tsx
-import {depth} from '@workday/canvas-kit-react/tokens';
+import { depth } from '@workday/canvas-kit-react/tokens';
 
-depth.inset;
-depth['2'];
+const CustomCard = () => {
+  return <div css={depth[2]}>A standard-depth card</div>;
+}
 ```
 
 ## Type