@axinom/mosaic-ui 0.75.0-rc.5 → 0.77.0

package/src/components/List/List.tsx

@@ -6,12 +6,14 @@ import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
 } from 'react';
 import type { ActionData } from '..';
 import { noop } from '../../helpers/utils';
 import type { Data } from '../../types/data';
+import { ActionBar, type ActionBarData } from '../ActionBar';
 import { ButtonContext } from '../Buttons/Button.model';
 import { TextButton } from '../Buttons/TextButton/TextButton';
 import {
@@ -27,7 +29,7 @@ import { ListHeader } from './ListHeader/ListHeader';
 import type { ListRowProps } from './ListRow/ListRow';
 import { ListRowLoader } from './ListRow/ListRowLoader';
 import { ListRowRenderer } from './ListRowRenderer/ListRowRenderer';
-import { getActionButtonVisibility, isTrigger, useSort } from './helpers';
+import { getActionButtonVisibility, getTriggerIndex, useSort } from './helpers';
 import { useColumnsSize } from './useColumnsSize';
 
 export interface ListProps<T extends Data> {
@@ -44,7 +46,7 @@ export interface ListProps<T extends Data> {
   isLoading?: boolean;
   /** Defines whether there was an error with the data. If true a button will be shown that will trigger `onRetry` when hit. */
   isError?: boolean;
-  /** Optional error message to display if an error occurs. (default: 'There was an error.) */
+  /** Optional error message to display if an error occurs. (default: 'There was an error.') */
   errorMsg?: string;
   /** Determines whether the component should render the error message and the 'onRetry' button. Set this to false if error handling will be done outside this component. (default: true) */
   handleRetry?: boolean;
@@ -90,13 +92,16 @@ export interface ListProps<T extends Data> {
   /**
    * When set, this function is used to generate the link that the user should be navigated to for each item.
    *
-   * This property takes precedence over `onItemClicked`, which will not be executed in case `generateItemLink` is set!
+   * This property takes precedence over `onItemClicked`, which is only executed
+   * while the link is suppressed, i.e. when the list is in a selection mode or
+   * the row is disabled.
    */
   generateItemLink?: (data: T) => LocationDescriptor<unknown>;
   /**
    * Raised when an data item is clicked.
    *
-   * This is not being used, if generateItemLink is set!
+   * If `generateItemLink` is set, this is only raised while the list is in a
+   * selection mode or the row is disabled.
    */
   onItemClicked?: (data: T) => void | Promise<void>;
   /** Raised when item selection has changed */
@@ -109,6 +114,16 @@ export interface ListProps<T extends Data> {
   onRetry?: () => void;
   /** CSS Class name for additional styles */
   className?: string;
+  /**
+   * Content of the bar that sits on top of the column header, holding the
+   * actions of whichever context is currently active.
+   *
+   * Consumers that offer several sets of actions, e.g. bulk actions and quick
+   * edit, resolve which of them is active and pass that one - only a single set
+   * can be on display at a time. The bar collapses while it has neither a label
+   * nor any actions to show.
+   */
+  actionBar?: ActionBarData;
   /** Provide inline actions which are available through '...' context menu */
   inlineMenuActions?: (data: T) => ActionData[];
   /** Function to determine if a specific row should be disabled */
@@ -117,6 +132,31 @@ export interface ListProps<T extends Data> {
   customRowRenderer?: (props: ListRowProps<T>) => ReactElement | null;
 }
 
+interface Selection {
+  /** Keys of the rows that are selected individually. */
+  keys: ReadonlySet<string>;
+  /**
+   * Set while every row counts as selected without being tracked individually:
+   * the header 'select all' checkbox is checked, or the user has checked every
+   * row while `enableSelectAllDeselect` is on. Rows that are loaded later are
+   * selected too, so this cannot be derived from `keys` and `data`.
+   */
+  isAll: boolean;
+}
+
+/** Shared empty selection, so that clearing twice does not re-render. */
+const EMPTY_SELECTION: Selection = { keys: new Set<string>(), isAll: false };
+
+/**
+ * Property used to identify a row when no `keyProperty` is given. `Data` allows
+ * any string index, so this holds for every `T` even though TypeScript cannot
+ * prove that 'id' is one of `keyof T`.
+ */
+const DEFAULT_KEY_PROPERTY = 'id';
+
+/** Prefix for the positional fallback key, to keep it out of real key values. */
+const INDEX_KEY_PREFIX = '__list_index_';
+
 const ListRenderer = <T extends Data>(
   {
     columns,
@@ -134,7 +174,7 @@ const ListRenderer = <T extends Data>(
     headerRowActionSize = '28px',
     horizontalTextAlign = 'left',
     verticalTextAlign = 'center',
-    keyProperty = 'id' as keyof T,
+    keyProperty,
     showActionButton = true,
     loadingTriggerOffset = 10,
     defaultSortOrder,
@@ -149,158 +189,212 @@ const ListRenderer = <T extends Data>(
     onRetry = noop,
     generateItemLink,
     className = '',
+    actionBar,
     inlineMenuActions,
     isRowDisabled,
     customRowRenderer,
   }: PropsWithChildren<ListProps<T>>,
   ref?: React.ForwardedRef<ListElement>,
 ): JSX.Element => {
-  const [listItems, setListItems] = useState<ListItem<T>[]>([]);
-  const isAllItemsChecked = useRef<boolean>(false);
+  const [selection, setSelection] = useState<Selection>(EMPTY_SELECTION);
+  /**
+   * Mirrors `selection` so that handlers can read-modify-write it without
+   * waiting for a re-render, which keeps several toggles within one batch from
+   * overwriting each other. Never read while rendering - `selection` is what
+   * drives the output.
+   */
+  const selectionRef = useRef<Selection>(selection);
+
+  const applySelection = useCallback((next: Selection): void => {
+    selectionRef.current = next;
+    setSelection(next);
+  }, []);
+
+  const rowKeyProperty = (keyProperty ?? DEFAULT_KEY_PROPERTY) as keyof T;
+
+  /**
+   * Resolves the stable identity of a row. Falls back to the row position if
+   * the data carries no value for `keyProperty`, in which case the selection
+   * cannot survive a re-ordering of `data` (see the warning below).
+   */
+  const getRowKey = useCallback(
+    (row: T, index: number): string => {
+      const key = row[rowKeyProperty];
+      return key == null ? `${INDEX_KEY_PREFIX}${index}` : String(key);
+    },
+    [rowKeyProperty],
+  );
+
+  const listItems = useMemo<ListItem<T>[]>(
+    () =>
+      data.map((row, index) => ({
+        selected: selection.isAll || selection.keys.has(getRowKey(row, index)),
+        data: row,
+      })),
+    [data, getRowKey, selection],
+  );
+
+  const hasWarnedAboutKeyProperty = useRef<boolean>(false);
 
   useEffect(() => {
-    setListItems((prevState: ListItem<T>[]) => {
-      const newListItems: ListItem<T>[] = data.map((i, index) => ({
-        selected: isAllItemsChecked.current || prevState[index]?.selected,
-        data: i,
-      }));
-      return newListItems;
-    });
-  }, [data]);
-
-  const { columnSizes, resetColumnSizes, setColumnSizes, hasActionColumn } =
-    useColumnsSize(
-      columns,
-      Boolean(showActionButton),
-      selectionMode,
-      Boolean(inlineMenuActions),
+    if (
+      hasWarnedAboutKeyProperty.current ||
+      selectionMode === ListSelectMode.None ||
+      data.length === 0 ||
+      data[0][rowKeyProperty] != null
+    ) {
+      return;
+    }
+
+    hasWarnedAboutKeyProperty.current = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      `List: 'selectionMode' is enabled but the data has no '${String(
+        rowKeyProperty,
+      )}' property. The selection is tracked by row position and will apply to the wrong rows once the data is sorted or an item is removed. Set 'keyProperty' to a property that identifies a row.`,
     );
+  }, [data, rowKeyProperty, selectionMode]);
 
-  const customStyles = {
-    gridRowGap: rowGap,
-    minWidth: minimumWidth,
-    width: '100%',
-  };
+  const {
+    columnSizes,
+    resetColumnSizes,
+    setColumnSizes,
+    hasActionColumn,
+    actionSlotSize,
+  } = useColumnsSize(
+    columns,
+    Boolean(showActionButton),
+    selectionMode,
+    Boolean(inlineMenuActions),
+  );
 
-  const itemSelectionHandler = useCallback(
-    (items: ListItem<T>[]) => {
-      const selectedData: T[] = items.map(({ data }) => data);
-      if (enableSelectAllDeselect) {
-        if (items.length === listItems.length) {
-          isAllItemsChecked.current = true;
-        } else {
-          isAllItemsChecked.current = false;
-        }
-      }
-      onItemSelected &&
-        onItemSelected({
-          mode: 'SINGLE_ITEMS',
-          items: selectedData,
-        });
-    },
-    [enableSelectAllDeselect, listItems.length, onItemSelected],
+  // `minimumWidth` sizes the columns, so it belongs to the container that holds
+  // them rather than to the frame around it.
+  const listStyles = useMemo(
+    () => ({ gridRowGap: rowGap, minWidth: minimumWidth }),
+    [minimumWidth, rowGap],
   );
 
+  const clearSelection = useCallback((): void => {
+    applySelection(EMPTY_SELECTION);
+
+    onItemSelected({
+      mode: 'SINGLE_ITEMS',
+      items: [],
+    });
+  }, [applySelection, onItemSelected]);
+
   const headerCheckboxHandler = useCallback(
     (checked: boolean): void => {
-      setListItems((prevState) =>
-        prevState.map((i) => ({
-          selected: checked,
-          data: i.data,
-        })),
+      applySelection({ keys: EMPTY_SELECTION.keys, isAll: checked });
+
+      onItemSelected(
+        checked ? { mode: 'SELECT_ALL' } : { mode: 'SINGLE_ITEMS', items: [] },
       );
+    },
+    [applySelection, onItemSelected],
+  );
 
-      isAllItemsChecked.current = checked;
+  const itemSelectedHandler = useCallback(
+    (selected: boolean, key: string): void => {
+      const current = selectionRef.current;
+      // Toggling a row while 'select all' is active turns the implicit
+      // selection into an explicit one, so that the other rows stay selected.
+      const nextKeys = new Set(
+        current.isAll ? data.map(getRowKey) : current.keys,
+      );
 
-      if (checked) {
-        onItemSelected({
-          mode: 'SELECT_ALL',
-        });
+      if (selected) {
+        nextKeys.add(key);
       } else {
-        onItemSelected({
-          mode: 'SINGLE_ITEMS',
-          items: [],
-        });
+        nextKeys.delete(key);
       }
-    },
-    [onItemSelected],
-  );
 
-  const itemSelectedHandler = useCallback(
-    (selected: boolean, index: number): void => {
-      const items = [...listItems];
-      items[index].selected = selected;
-      setListItems(items);
-      itemSelectionHandler(items.filter((item) => item.selected === true));
+      applySelection({
+        keys: nextKeys,
+        isAll:
+          enableSelectAllDeselect &&
+          data.length > 0 &&
+          nextKeys.size === data.length,
+      });
+
+      onItemSelected({
+        mode: 'SINGLE_ITEMS',
+        items: data.filter((row, index) => nextKeys.has(getRowKey(row, index))),
+      });
     },
-    [itemSelectionHandler, listItems],
+    [applySelection, data, enableSelectAllDeselect, getRowKey, onItemSelected],
   );
 
-  const onTriggeredHandler = (): void => {
+  const onTriggeredHandler = useCallback((): void => {
     if (!isLoading && !isError) {
       onRequestMoreData();
     }
-  };
+  }, [isError, isLoading, onRequestMoreData]);
 
-  const itemClickedHandler = async (data: T, index: number): Promise<void> => {
+  const itemClickedHandler = async (row: T, index: number): Promise<void> => {
     try {
-      await onItemClicked(data);
+      await onItemClicked(row);
 
       if (selectionMode === ListSelectMode.Single) {
-        setListItems((prevState) =>
-          prevState.map((item, i) => ({
-            selected: i === index,
-            data: item.data,
-          })),
-        );
+        applySelection({
+          keys: new Set([getRowKey(row, index)]),
+          isAll: false,
+        });
       }
-    } catch (error) {
+    } catch {
+      // The consumer rejected the click, so the selection is left untouched.
       return;
     }
   };
 
   const { sort, sortChangedHandler } = useSort(defaultSortOrder, onSortChanged);
 
+  // Intentionally without a dependency array: the handle reads `listItems` to
+  // resolve the index, so it has to be rebuilt whenever the rows change.
   useImperativeHandle(ref, () => ({
-    resetSelection: () => {
-      setListItems((prevState) =>
-        prevState.map((i) => ({
-          selected: false,
-          data: i.data,
-        })),
-      );
+    resetSelection: clearSelection,
+    selectIndex: (index: number) => {
+      const item = listItems[index];
 
-      isAllItemsChecked.current = false;
+      // Nothing at that position, or the list renders no selection at all - in
+      // which case selecting would raise `onItemSelected` for something the
+      // user can neither see nor undo.
+      if (!item || selectionMode === ListSelectMode.None) {
+        return;
+      }
 
-      onItemSelected({
-        mode: 'SINGLE_ITEMS',
-        items: [],
-      });
-    },
-    selectIndex: (index: number) => {
       if (selectionMode === ListSelectMode.Single) {
-        itemClickedHandler(listItems[index].data, index);
+        // Single selection only follows clicks, so it raises no event of its
+        // own, and raising `onItemClicked` would report a click that never
+        // happened. The row is just marked.
+        applySelection({
+          keys: new Set([getRowKey(item.data, index)]),
+          isAll: false,
+        });
       } else {
-        itemSelectedHandler(true, index);
+        itemSelectedHandler(true, getRowKey(item.data, index));
       }
     },
   }));
 
+  const previousSelectionMode = useRef<ListSelectMode>(selectionMode);
+
   useEffect(() => {
-    if (selectionMode !== ListSelectMode.Multi) {
-      setListItems((prevState) =>
-        prevState.map((i) => ({
-          selected: false,
-          data: i.data,
-        })),
-      );
+    const modeChanged = previousSelectionMode.current !== selectionMode;
+    previousSelectionMode.current = selectionMode;
+
+    // Leaving multi select drops the selection, so that the consumer is not
+    // left holding a selection that is no longer visible in the list.
+    if (modeChanged && selectionMode !== ListSelectMode.Multi) {
+      clearSelection();
     }
-  }, [selectionMode]);
+  }, [clearSelection, selectionMode]);
 
   const getRowDisabledState = useCallback(
     (item: ListItem<T>, index: number): boolean => {
       const isDisabledDueToSelectAll =
-        isAllItemsChecked.current &&
+        selection.isAll &&
         !enableSelectAllDeselect &&
         selectionMode === ListSelectMode.Multi;
 
@@ -309,95 +403,126 @@ const ListRenderer = <T extends Data>(
 
       return isDisabledDueToSelectAll || isDisabledByCustomLogic;
     },
-    [enableSelectAllDeselect, selectionMode, isRowDisabled],
+    [enableSelectAllDeselect, isRowDisabled, selection.isAll, selectionMode],
   );
 
+  const triggerIndex = getTriggerIndex(listItems.length, loadingTriggerOffset);
+
+  // Without a label and without actions there is nothing for the bar to show,
+  // so it gives its space back to the list.
+  const showActionBar =
+    actionBar !== undefined &&
+    (!!actionBar.label || actionBar.actions.length > 0);
+
   return (
     <div
       className={clsx(classes.wrapper, 'list-wrapper', className)}
-      style={customStyles}
       data-test-id="list"
     >
-      {/* Header */}
-      <ListHeader
-        columns={columns}
-        itemSelected={isAllItemsChecked.current}
-        sortData={sort}
-        columnSizes={columnSizes}
-        columnGap={columnGap}
-        rowHeight={headerRowHeight}
-        actionSize={headerRowActionSize}
-        horizontalTextAlign={horizontalTextAlign}
-        verticalTextAlign={verticalTextAlign}
-        showItemCheckbox={
-          enableSelectAll &&
-          selectionMode === ListSelectMode.Multi &&
-          listItems.length > 0
-        }
-        isCheckboxDisabled={listItems.length === 0}
-        onCheckboxToggled={headerCheckboxHandler}
-        onSortChanged={sortChangedHandler}
-        onResetColumnSizes={resetColumnSizes}
-        onColumnSizesChanged={setColumnSizes}
-        hasActionColumn={hasActionColumn}
-      />
-
-      {/* Rows */}
-      {listItems.map((item: ListItem<T>, index) => (
-        <ListRowRenderer<T>
-          key={String(item.data[keyProperty] || index)}
-          customRowRenderer={customRowRenderer}
-          isTrigger={isTrigger<T>(index, listItems, loadingTriggerOffset)}
-          onTriggered={onTriggeredHandler}
-          listRowProps={{
-            columns,
-            data: item.data,
-            itemSelected: item.selected,
-            isRowDisabled: getRowDisabledState(item, index),
-            columnSizes,
-            columnGap,
-            rowHeight: listRowHeight,
-            actionSize: listRowActionSize,
-            horizontalTextAlign,
-            verticalTextAlign,
-            textWrap,
-            selectionMode,
-            showActionButton:
-              selectionMode === ListSelectMode.None &&
-              getActionButtonVisibility(item.data, showActionButton),
-            showCheckMark: selectionMode === ListSelectMode.Single,
-            showItemCheckbox: selectionMode === ListSelectMode.Multi,
-            onItemClicked: generateItemLink
-              ? generateItemLink(item.data)
-              : (data: T) => itemClickedHandler(data, index),
-            onItemSelected: (checked: boolean) =>
-              itemSelectedHandler(checked, index),
-            inlineMenuActions,
-          }}
+      {/* Actions of the active context, on top of the column header */}
+      {showActionBar && actionBar !== undefined && (
+        <ActionBar
+          {...actionBar}
+          height={headerRowHeight}
+          className={classes.actionBar}
         />
-      ))}
+      )}
 
-      {isLoading && (
-        <ListRowLoader
+      <div className={clsx(classes.list, 'list-container')} style={listStyles}>
+        {/* Header */}
+        <ListHeader
+          columns={columns}
+          itemSelected={selection.isAll}
+          sortData={sort}
           columnSizes={columnSizes}
           columnGap={columnGap}
-          rowHeight={listRowHeight}
-          columns={columns}
+          rowHeight={headerRowHeight}
+          actionSize={headerRowActionSize}
+          actionSlotSize={actionSlotSize}
+          // The bar sticks to the top of the list first, so the header comes to
+          // rest below it. Its bottom border adds to the height of its row.
+          stickyOffset={
+            showActionBar ? `calc(${headerRowHeight} + 1px)` : undefined
+          }
+          horizontalTextAlign={horizontalTextAlign}
+          verticalTextAlign={verticalTextAlign}
+          showItemCheckbox={
+            enableSelectAll &&
+            selectionMode === ListSelectMode.Multi &&
+            listItems.length > 0
+          }
+          isCheckboxDisabled={listItems.length === 0}
+          onCheckboxToggled={headerCheckboxHandler}
+          onSortChanged={sortChangedHandler}
+          onResetColumnSizes={resetColumnSizes}
+          onColumnSizesChanged={setColumnSizes}
+          hasActionColumn={hasActionColumn}
         />
-      )}
-      {noItemsMessage(listItems.length, isLoading, isError)}
-      {isError && handleRetry && (
-        <div className={clsx(classes.error)}>
-          <p>{errorMsg}</p>
-          <TextButton
-            text={'Retry'}
-            height={listRowActionSize}
-            width={'100px'}
-            buttonContext={ButtonContext.Context}
-            onButtonClicked={() => onRetry()}
+
+        {/* Rows */}
+        {listItems.map((item: ListItem<T>, index) => {
+          const rowKey = getRowKey(item.data, index);
+
+          return (
+            <ListRowRenderer<T>
+              key={rowKey}
+              customRowRenderer={customRowRenderer}
+              isTrigger={index === triggerIndex}
+              onTriggered={onTriggeredHandler}
+              listRowProps={{
+                columns,
+                data: item.data,
+                itemSelected: item.selected,
+                isRowDisabled: getRowDisabledState(item, index),
+                columnSizes,
+                columnGap,
+                rowHeight: listRowHeight,
+                actionSize: listRowActionSize,
+                horizontalTextAlign,
+                verticalTextAlign,
+                textWrap,
+                selectionMode,
+                showActionButton:
+                  selectionMode === ListSelectMode.None &&
+                  getActionButtonVisibility(item.data, showActionButton),
+                showCheckMark: selectionMode === ListSelectMode.Single,
+                showItemCheckbox: selectionMode === ListSelectMode.Multi,
+                linkTo: generateItemLink?.(item.data),
+                onItemClicked: (row: T) => itemClickedHandler(row, index),
+                onItemSelected: (checked: boolean) =>
+                  itemSelectedHandler(checked, rowKey),
+                inlineMenuActions,
+              }}
+            />
+          );
+        })}
+
+        {isLoading && (
+          <ListRowLoader
+            columnSizes={columnSizes}
+            columnGap={columnGap}
+            rowHeight={listRowHeight}
+            columns={columns}
           />
-        </div>
-      )}
+        )}
+        {!isLoading && !isError && listItems.length === 0 && (
+          <div className={classes.noData} data-test-id="list-empty">
+            <p>No items found</p>
+          </div>
+        )}
+        {isError && handleRetry && (
+          <div className={classes.error}>
+            <p>{errorMsg}</p>
+            <TextButton
+              text={'Retry'}
+              height={listRowActionSize}
+              width={'100px'}
+              buttonContext={ButtonContext.Context}
+              onButtonClicked={() => onRetry()}
+            />
+          </div>
+        )}
+      </div>
     </div>
   );
 };
@@ -412,17 +537,3 @@ const ListRenderer = <T extends Data>(
  * />
  */
 export const List = React.forwardRef(ListRenderer);
-
-const noItemsMessage = (
-  itemsCount: number,
-  isLoading: boolean,
-  isError: boolean,
-): ReactElement | undefined => {
-  if (!isLoading && !isError && itemsCount === 0) {
-    return (
-      <div className={clsx(classes.NoData)} data-test-id="list-empty">
-        <p>No items found</p>
-      </div>
-    );
-  }
-};

package/src/components/List/ListHeader/ListHeader.module.scss

@@ -15,6 +15,20 @@
   border-bottom: solid 1px
     var(--list-header-border-color, $list-header-border-color);
 
+  // The select all checkbox lines up with the checkboxes of the rows, which
+  // occupy the last slot of the actions column - any slot before it belongs to
+  // the inline menu or the row action button.
+  .actionColumn {
+    justify-items: end;
+
+    .selectAllSlot {
+      height: 100%;
+
+      display: grid;
+      place-items: center;
+    }
+  }
+
   .columnLabel {
     box-sizing: border-box;
     width: 100%;

package/src/components/List/ListHeader/ListHeader.spec.tsx

@@ -37,6 +37,7 @@ const mockProps: ListHeaderProps<TestListHeaderData> = {
   columnGap: '5px',
   rowHeight: '44px',
   actionSize: '50px',
+  actionSlotSize: '50px',
   horizontalTextAlign: 'left',
   verticalTextAlign: 'center',
   hasActionColumn: true,