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

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

@@ -18,6 +18,13 @@ export interface ListHeaderProps<T extends Data> {
   rowHeight: string;
   /** Size of the checkbox */
   actionSize: string;
+  /** Width of a single action slot of the trailing actions column */
+  actionSlotSize: string;
+  /**
+   * Distance the header keeps from the top of the list while it is stuck, to
+   * leave room for whatever sticks above it. (default: '0')
+   */
+  stickyOffset?: string;
   /** Horizontal alignment of text */
   horizontalTextAlign: 'left' | 'right' | 'center';
   /** Vertical alignment of text */
@@ -54,6 +61,8 @@ export interface ListHeaderProps<T extends Data> {
  *  columnSizes={'1fr'}
  *  columnGap={'5px'}
  *  rowHeight={'44px'}
+ *  actionSize={'28px'}
+ *  actionSlotSize={'50px'}
  *  horizontalTextAlign={'left'}
  *  verticalTextAlign={'center'}
  * />
@@ -64,6 +73,8 @@ export const ListHeader = <T extends Data>({
   columnGap,
   rowHeight,
   actionSize,
+  actionSlotSize,
+  stickyOffset,
   horizontalTextAlign,
   verticalTextAlign,
   itemSelected = false,
@@ -83,6 +94,7 @@ export const ListHeader = <T extends Data>({
     gridColumnGap: columnGap,
     justifyItems: horizontalTextAlign,
     alignItems: verticalTextAlign,
+    top: stickyOffset,
   } as React.CSSProperties;
 
   const { cols, mouseDown, ResizeIndicator } = useResize(
@@ -131,16 +143,21 @@ export const ListHeader = <T extends Data>({
         {hasActionColumn && (
           <div
             ref={cols[cols.length - 1].ref}
-            className={clsx(classes.columnLabel)}
+            className={clsx(classes.columnLabel, classes.actionColumn)}
           >
             {showItemCheckbox && (
-              <ListCheckBox
-                height={actionSize}
-                width={actionSize}
-                isChecked={itemSelected}
-                isDisabled={isCheckboxDisabled}
-                onCheckBoxToggled={onCheckboxToggled}
-              />
+              <div
+                className={classes.selectAllSlot}
+                style={{ width: actionSlotSize }}
+              >
+                <ListCheckBox
+                  height={actionSize}
+                  width={actionSize}
+                  isChecked={itemSelected}
+                  isDisabled={isCheckboxDisabled}
+                  onCheckBoxToggled={onCheckboxToggled}
+                />
+              </div>
             )}
           </div>
         )}

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

@@ -1,7 +1,7 @@
 @import '../../../styles/common.scss';
 
 .columnsRoot {
-  padding: 1px 0px 1px 5px;
+  padding: 1px 0;
   display: grid;
   justify-items: left;
   align-items: center;

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

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 import { fireEvent, render } from '@testing-library/react';
 import React from 'react';
-import { BrowserRouter } from 'react-router-dom';
+import { BrowserRouter, MemoryRouter, useLocation } from 'react-router-dom';
 import { describe, expect, it, vi } from 'vitest';
 import { type Column, ListSelectMode } from '../List.model';
 import { ListRow, type ListRowProps, setLocale } from './ListRow';
@@ -401,50 +401,137 @@ describe('ListRow', () => {
   });
 
   describe('linking', () => {
-    it('does render a link if not in select mode and got a string as "onItemClicked"', () => {
+    /** Renders the path the router currently points at, to tell a click that
+     * navigated apart from one that was suppressed. `Link` calls
+     * `preventDefault` itself whenever it navigates, so the event is no help. */
+    const LocationProbe: React.FC = () => {
+      const { pathname } = useLocation();
+      return <span data-test-id="location">{pathname}</span>;
+    };
+
+    const renderRow = (
+      props: Partial<ListRowProps<TestExplorerData>>,
+    ): { link: HTMLAnchorElement; path: () => string | null } => {
+      const { container } = render(
+        <MemoryRouter initialEntries={['/start']}>
+          <ListRow {...mockProps} {...props} />
+          <LocationProbe />
+        </MemoryRouter>,
+      );
+
+      return {
+        link: container.querySelector('a') as HTMLAnchorElement,
+        path: () =>
+          container.querySelector('[data-test-id="location"]')?.textContent ??
+          null,
+      };
+    };
+
+    it(`does render a link if it got a 'linkTo'`, () => {
       const { container } = render(
         <BrowserRouter>
           <ListRow
             {...mockProps}
-            onItemClicked="http://this.is.a.test.url"
+            linkTo="http://this.is.a.test.url"
             selectionMode={ListSelectMode.None}
           />
         </BrowserRouter>,
       );
 
-      const link = container.querySelector('a');
-
-      expect(link).toBeInTheDocument();
+      expect(container.querySelector('a')).toBeInTheDocument();
     });
 
-    it('does not render a link if in select mode and got a string as "onItemClicked"', () => {
+    it(`does not render a link if it got no 'linkTo'`, () => {
       const { container } = render(
         <ListRow
           {...mockProps}
-          onItemClicked="http://this.is.a.test.url"
+          onItemClicked={() => {
+            // empty
+          }}
           selectionMode={ListSelectMode.Single}
         />,
       );
 
-      const link = container.querySelector('.link');
+      expect(container.querySelector('.link')).not.toBeInTheDocument();
+    });
 
-      expect(link).not.toBeInTheDocument();
+    it('navigates when there is no selection mode', () => {
+      const onItemClickedSpy = vi.fn();
+      const { link, path } = renderRow({
+        linkTo: '/somewhere',
+        selectionMode: ListSelectMode.None,
+        onItemClicked: onItemClickedSpy,
+      });
+
+      fireEvent.click(link);
+
+      expect(path()).toBe('/somewhere');
+      // The link takes precedence, so the click handler stays out of the way
+      expect(onItemClickedSpy).not.toHaveBeenCalled();
     });
 
-    it('does not render a link if it got a function as "onItemClicked"', () => {
-      const { container } = render(
-        <ListRow
-          {...mockProps}
-          onItemClicked={() => {
-            // empty
-          }}
-          selectionMode={ListSelectMode.Single}
-        />,
-      );
+    it('keeps the link in the tree in single select mode, but does not navigate', () => {
+      const onItemClickedSpy = vi.fn();
+      const { link, path } = renderRow({
+        linkTo: '/somewhere',
+        selectionMode: ListSelectMode.Single,
+        onItemClicked: onItemClickedSpy,
+      });
+
+      // The anchor stays, so that switching selection mode does not remount the cells
+      expect(link).toBeInTheDocument();
+
+      fireEvent.click(link);
+
+      expect(path()).toBe('/start');
+      expect(onItemClickedSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('selects instead of navigating in multi select mode', () => {
+      const onItemSelectedSpy = vi.fn();
+      const { link, path } = renderRow({
+        linkTo: '/somewhere',
+        selectionMode: ListSelectMode.Multi,
+        itemSelected: false,
+        onItemSelected: onItemSelectedSpy,
+      });
+
+      fireEvent.click(link);
 
-      const link = container.querySelector('.link');
+      expect(path()).toBe('/start');
+      expect(onItemSelectedSpy).toHaveBeenCalledWith(true);
+    });
+
+    it('does not navigate if the row is disabled', () => {
+      const onItemClickedSpy = vi.fn();
+      const { link, path } = renderRow({
+        linkTo: '/somewhere',
+        selectionMode: ListSelectMode.None,
+        isRowDisabled: true,
+        onItemClicked: onItemClickedSpy,
+      });
+
+      fireEvent.click(link);
+
+      expect(path()).toBe('/start');
+      expect(onItemClickedSpy).not.toHaveBeenCalled();
+    });
+
+    it('does not navigate on a middle click while the link is suppressed', () => {
+      const { link } = renderRow({
+        linkTo: '/somewhere',
+        selectionMode: ListSelectMode.Multi,
+      });
+
+      // `Link` ignores auxclick entirely, so a prevented default here is ours
+      const event = new MouseEvent('auxclick', {
+        bubbles: true,
+        cancelable: true,
+        button: 1,
+      });
+      fireEvent(link, event);
 
-      expect(link).not.toBeInTheDocument();
+      expect(event.defaultPrevented).toBe(true);
     });
   });
 

package/src/components/List/ListRow/ListRow.tsx

@@ -44,11 +44,22 @@ export interface ListRowProps<T extends Data> {
   showItemCheckbox?: boolean;
   /** Defines whether a row is disabled (default: false) */
   isRowDisabled?: boolean;
-  /** Used for when a row is clicked. This can be either a callback function that will be executed
-   * or a URL where the user should be navigated to.
-   * When the list should navigate the user to e.g. a details page of a entry it is recommended to
-   * directly pass the URL here instead of a callback function that does the routing in JavaScript. */
-  onItemClicked?: LocationDescriptor<unknown> | ((data: T) => void);
+  /**
+   * Location the user should be navigated to when the row is clicked. A row with
+   * a link renders its content as an anchor, which is preferred over routing in
+   * JavaScript when the row leads to e.g. a details page.
+   *
+   * Whether this is set decides the element the row content is wrapped in, so it
+   * must not come and go over the lifetime of a row: doing so remounts every
+   * cell and resets their state. To stop a row from navigating, put the list in
+   * a selection mode or disable the row instead of removing the link.
+   */
+  linkTo?: LocationDescriptor<unknown>;
+  /**
+   * Called when the row is clicked. A row that navigates through `linkTo` only
+   * raises this while its navigation is suppressed.
+   */
+  onItemClicked?: (data: T) => void;
   /**
    * A function that is getting called, when the selection state of the row changes.
    */
@@ -105,6 +116,7 @@ const ListRowComponent = <T extends Data>(
     showActionButton = true,
     showCheckMark = false,
     showItemCheckbox = false,
+    linkTo,
     onItemClicked = noop,
     onItemSelected = noop,
     isRowDisabled = false,
@@ -131,16 +143,41 @@ const ListRowComponent = <T extends Data>(
       if (selectionMode === ListSelectMode.Multi) {
         onItemSelected(!itemSelected);
         // Emit onItemClicked for all other modes
-      } else if (typeof onItemClicked === 'function') {
+      } else {
         onItemClicked(data);
       }
     },
     [isRowDisabled, itemSelected, onItemClicked, onItemSelected, selectionMode],
   );
 
-  const isLinkable: boolean =
-    selectionMode === ListSelectMode.None &&
-    typeof onItemClicked !== 'function';
+  // A row that is disabled, or that is part of a selection, selects instead of
+  // navigating. The anchor stays in the tree either way - swapping it for
+  // another element would remount every cell and reset their state.
+  const suppressNavigation =
+    isRowDisabled || selectionMode !== ListSelectMode.None;
+
+  const onLinkClicked = useCallback(
+    (event: React.MouseEvent): void => {
+      if (!suppressNavigation) {
+        return;
+      }
+
+      event.preventDefault();
+      onItemClickedHandler(data);
+    },
+    [data, onItemClickedHandler, suppressNavigation],
+  );
+
+  // A middle click raises `auxclick` instead of `click`, and would otherwise
+  // open the suppressed link in a new tab.
+  const onLinkAuxClicked = useCallback(
+    (event: React.MouseEvent): void => {
+      if (suppressNavigation) {
+        event.preventDefault();
+      }
+    },
+    [suppressNavigation],
+  );
 
   const generateCells = useMemo(() => {
     return columns.map((column: Column<T>) => {
@@ -174,10 +211,12 @@ const ListRowComponent = <T extends Data>(
       data-test-id="list-entry"
     >
       {/* Items */}
-      {isLinkable ? (
+      {linkTo !== undefined ? (
         <Link
-          to={onItemClicked as string}
+          to={linkTo}
           className={clsx(classes.content, classes.link)}
+          onClick={onLinkClicked}
+          onAuxClick={onLinkAuxClicked}
         >
           {generateCells}
         </Link>
@@ -206,12 +245,12 @@ const ListRowComponent = <T extends Data>(
           {showActionButton && selectionMode === ListSelectMode.None && (
             <>
               {showActionButton &&
-                (typeof onItemClicked !== 'function' ? (
+                (linkTo !== undefined ? (
                   <Button
                     icon={IconName.ChevronRight}
                     height={actionSize}
                     width={actionSize}
-                    path={onItemClicked}
+                    path={linkTo}
                     dataTestId="list-entry-action"
                   />
                 ) : (

package/src/components/List/ListRowRenderer/ListRowRenderer.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useRef } from 'react';
+import React, { useCallback, useEffect, useRef } from 'react';
 import type { Data } from '../../../types/data';
 import { ListRow, type ListRowProps } from '../ListRow/ListRow';
 
@@ -30,31 +30,37 @@ export const ListRowRenderer = <T extends Data>({
 > | null => {
   // Pagination trigger logic
   // Trigger based on: https://www.youtube.com/watch?v=NZKUirTtxcg
-  const onTriggeredHandler = useCallback(() => {
-    onTriggered && onTriggered();
+  const observer = useRef<IntersectionObserver>();
+
+  // `onTriggered` is read through a ref so that `elementRef` below can stay
+  // stable. React only re-runs a callback ref when its identity or the node
+  // changes, and every re-run observes the node again - which reports the
+  // current intersection state right away and would raise `onTriggered` anew
+  // for a row that never moved.
+  const onTriggeredRef = useRef(onTriggered);
+
+  useEffect(() => {
+    onTriggeredRef.current = onTriggered;
   }, [onTriggered]);
 
-  const observer = useRef<IntersectionObserver>();
-  const elementRef = useCallback(
-    (node: HTMLDivElement) => {
-      if (isTrigger === false) {
-        return;
-      }
-      if (observer.current) {
-        observer.current.disconnect();
-      }
-      observer.current = new IntersectionObserver(([entry]) => {
-        if (entry.isIntersecting) {
-          onTriggeredHandler();
-        }
-      });
+  const elementRef = useCallback((node: HTMLDivElement | null): void => {
+    observer.current?.disconnect();
+    observer.current = undefined;
+
+    // React passes null when the node is detached, either on unmount or
+    // because the row stopped being the trigger.
+    if (node === null) {
+      return;
+    }
 
-      if (node) {
-        observer.current.observe(node);
+    observer.current = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) {
+        onTriggeredRef.current?.();
       }
-    },
-    [isTrigger, onTriggeredHandler],
-  );
+    });
+
+    observer.current.observe(node);
+  }, []);
 
   if (customRowRenderer) {
     const customElement = customRowRenderer(listRowProps);

package/src/components/List/helpers.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { getTriggerIndex } from './helpers';
+
+describe('getTriggerIndex', () => {
+  it('sits loadingTriggerOffset rows before the end', () => {
+    // 100 rows, 10 rows left after the trigger row (indices 90-99)
+    expect(getTriggerIndex(100, 10)).toBe(89);
+    expect(getTriggerIndex(30, 10)).toBe(19);
+    expect(getTriggerIndex(11, 10)).toBe(0);
+  });
+
+  it('clamps to the first row when the page is shorter than the offset', () => {
+    // Such a page cannot fill the viewport, so no scrolling could ever bring a
+    // later row into view - the list has to ask for more data straight away.
+    expect(getTriggerIndex(10, 10)).toBe(0);
+    expect(getTriggerIndex(5, 10)).toBe(0);
+    expect(getTriggerIndex(1, 10)).toBe(0);
+  });
+
+  it('has no trigger row if there are no rows', () => {
+    expect(getTriggerIndex(0, 10)).toBe(-1);
+    expect(getTriggerIndex(0, 0)).toBe(-1);
+  });
+
+  it('triggers on the last row if the offset is zero or negative', () => {
+    expect(getTriggerIndex(30, 0)).toBe(29);
+    expect(getTriggerIndex(30, -5)).toBe(29);
+  });
+});

package/src/components/List/helpers.ts

@@ -1,14 +1,22 @@
 import { useState } from 'react';
-import type { Data } from '../../types';
-import type { ListItem, SortData } from './List.model';
+import type { SortData } from './List.model';
 
-export const isTrigger = function <T extends Data>(
-  index: number,
-  listItems: ListItem<T>[],
+/**
+ * Index of the row that requests the next page once it comes into view. It sits
+ * `loadingTriggerOffset` rows before the end, clamped to the first row: a page
+ * that is shorter than the offset does not fill the viewport, so there is no
+ * scrolling that could ever bring a later row into view.
+ * @param itemCount number of rows currently rendered
+ * @param loadingTriggerOffset number of rows left before a load is triggered
+ * @returns the index of the trigger row, or -1 if there are no rows
+ */
+export const getTriggerIndex = (
+  itemCount: number,
   loadingTriggerOffset: number,
-): boolean {
-  return listItems.length - loadingTriggerOffset === index + 1 ? true : false;
-};
+): number =>
+  itemCount === 0
+    ? -1
+    : Math.max(0, itemCount - Math.max(0, loadingTriggerOffset) - 1);
 
 export const useSort = <T>(
   defaultSortOrder: SortData<T> | undefined,
@@ -21,7 +29,7 @@ export const useSort = <T>(
 
   const sortChangedHandler = (sort: SortData<T>): void => {
     setSort(sort);
-    onSortChanged && onSortChanged(sort);
+    onSortChanged(sort);
   };
 
   return { sort, sortChangedHandler } as const;

package/src/components/List/useColumnsSize.ts

@@ -30,24 +30,31 @@ const getColumnsSizeDefinition = function <T extends Data>(
   return columnSizeDefinition.join(' ');
 };
 
+/** Width of a single action within the trailing actions column. */
+const ACTION_SLOT_SIZE_PX = 50;
+
+/**
+ * Spacing between two actions of the trailing actions column. Has to match the
+ * `grid-gap` of the actions of ListRow.
+ */
+const ACTION_SLOT_GAP_PX = 8;
+
 const getActionsColumnSizePx = (...enableActions: boolean[]): string => {
   const enabledActionsCount = enableActions.filter(
     (actionEnabled) => actionEnabled,
   ).length;
 
-  const defaultActionSizePx = 50;
-  const defaultActionsRawGapPx = 8;
   const calculateMultiActionsColumnSizePx = (actionsCount: number): number => {
     return (
-      defaultActionSizePx * actionsCount +
-      defaultActionsRawGapPx * (actionsCount - 1)
+      ACTION_SLOT_SIZE_PX * actionsCount +
+      ACTION_SLOT_GAP_PX * (actionsCount - 1)
     );
   };
 
   const sizePx =
     enabledActionsCount > 1
       ? calculateMultiActionsColumnSizePx(enabledActionsCount)
-      : defaultActionSizePx;
+      : ACTION_SLOT_SIZE_PX;
 
   return `${sizePx}px`;
 };
@@ -59,8 +66,9 @@ const getActionsColumnSizePx = (...enableActions: boolean[]): string => {
  * @param selectMode current select mode
  * @param showInlineMenu whether the inline menu is shown
  * @returns an object containing the columnSizes (CSS grid-template-columns),
- *          a reset function (to reset to the initial column sizes)
- *          and a setter function (to update the column sizes)
+ *          a reset function (to reset to the initial column sizes),
+ *          a setter function (to update the column sizes)
+ *          and the size of a single action slot of the trailing actions column
  */
 export const useColumnsSize = <T extends Data>(
   columns: Column<T>[],
@@ -72,6 +80,7 @@ export const useColumnsSize = <T extends Data>(
   resetColumnSizes: () => void;
   setColumnSizes: (newColumnSizes: string) => void;
   hasActionColumn: boolean;
+  actionSlotSize: string;
 } => {
   const [isResized, setIsResized] = useState<boolean>(false);
 
@@ -124,6 +133,7 @@ export const useColumnsSize = <T extends Data>(
       showActionButton,
       showInlineMenu,
     ),
+    actionSlotSize: `${ACTION_SLOT_SIZE_PX}px`,
   };
 };
 function hasActionColumn(

package/src/components/PageHeader/PageHeader.model.ts

@@ -1,5 +1,5 @@
+import type { IconName } from '../Icons';
 import type { PageHeaderActionProps } from './PageHeaderAction/PageHeaderAction.model';
-import type { PageHeaderActionsGroupProps } from './PageHeaderActionsGroup/PageHeaderActionsGroup';
 
 export interface PageHeaderProps {
   /** Title shown in page header */
@@ -17,6 +17,43 @@ export interface PageHeaderProps {
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface PageHeaderSpacerProps {}
 
+/**
+ * A group of actions. The group renders a single action on the page header,
+ * which opens an action bar holding the actions of the group below the page
+ * header. Only one group can be open at a time, and groups are told apart by
+ * their label.
+ */
+export interface PageHeaderActionsGroupProps {
+  /** Array of Actions to be rendered on the action bar */
+  actions: PageHeaderActionProps[];
+  /** Whether group is disabled (default: false) */
+  disabled?: boolean;
+  /** Whether actions in the group are disabled or not (default: false)*/
+  groupActionsDisabled?: boolean;
+  /** CSS Class name for additional styles of the action that opens the group */
+  className?: string;
+  /** The label of the action. */
+  label: string;
+  /** Optional built in icon. This prop also accepts an img src. */
+  icon?: IconName | string;
+  /**
+   * Optional text rendered at the start of the action bar while the group is
+   * open, e.g. 'Selected 3'. (default: undefined)
+   */
+  actionBarLabel?: string;
+  /**
+   * Whether group actions are shown by default. Only one group can be open, so
+   * if several groups set this, the first of them opens. (default: false)
+   */
+  openActionsGroupOnStart?: boolean;
+  /**
+   * Callback to emit when Group Actions is toggled
+   * The expanded state is supplied as an argument
+   * A rejected promise aborts the toggle.
+   */
+  onActionsGroupToggled?: (expanded: boolean) => Promise<void>;
+}
+
 export type PageHeaderActionItemProps =
   | (PageHeaderSpacerProps & { kind: 'spacer' })
   | (PageHeaderActionProps & { kind: 'action' })