add more JSDoc comments, enhance story, fix ininite scroll threshold

Author: Lukas742

packages/main/src/components/AnalyticalTable/AnalyticalTable.stories.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs/blocks';
+import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 import { AnalyticalTable } from '@ui5/webcomponents-react/lib/AnalyticalTable';
 import { createSelectArgTypes } from '../../../../../shared/stories/createSelectArgTypes';
 import { TableScaleWidthMode } from '@ui5/webcomponents-react/lib/TableScaleWidthMode';
@@ -15,6 +15,7 @@ import { TextAlign } from '@ui5/webcomponents-react/lib/TextAlign';
 import { DefaultLoadingComponent } from './defaults/LoadingComponent';
 import { DefaultNoDataComponent } from './defaults/NoDataComponent';
 import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
+import { useEffect, useRef, useState } from 'react';
 
 <Meta
   title="Components / AnalyticalTable"
@@ -125,42 +126,7 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
 <DocsHeader />
 
 <Canvas>
-  <Story name="Default">
-    {(args) => (
-      <div style={{ display: 'flex', flexDirection: 'column' }}>
-        <AnalyticalTable
-          {...args}
-          title={args.title}
-          data={args.data}
-          columns={args.columns}
-          loading={args.loading}
-          alternateRowColor={args.alternateRowColor}
-          sortable={args.sortable}
-          filterable={args.filterable}
-          visibleRows={args.visibleRows}
-          minRows={args.minRows}
-          groupable={args.groupable}
-          selectionMode={args.selectionMode}
-          scaleWidthMode={args.scaleWidthMode}
-          onRowSelected={args.onRowSelected}
-          onSort={args.onSort}
-          onGroup={args.onGroup}
-          onRowExpandChange={args.onRowExpandChange}
-          groupBy={args.groupBy}
-          rowHeight={args.rowHeight}
-          selectedRowIds={args.selectedRowIds}
-          onColumnsReordered={args.onColumnsReordered}
-          withRowHighlight={args.withRowHighlight}
-          highlightField={args.highlightField}
-          infiniteScroll={args.infiniteScroll}
-          infiniteScrollThreshold={args.infiniteScrollThreshold}
-          onLoadMore={args.onLoadMore}
-          selectionBehavior={args.selectionBehavior}
-          overscanCountHorizontal={args.overscanCountHorizontal}
-        />
-      </div>
-    )}
-  </Story>
+  <Story name="Default">{(args) => <AnalyticalTable {...args} />}</Story>
 </Canvas>
 
 <ArgsTable story="." />
@@ -203,6 +169,13 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
 
 ## Recipes
 
+### How to select rows containing active elements?
+
+By default, the `AnalyticalTable` will not select any rows after clicking on active elements inside a table cell like a `Button`, `Link`,
+etc. <br />
+In case you want to select the row anyways, you can "mark" the event to allow such a behaviour. <br />
+Example: `<Link onClick={(e) => {e.markerAllowTableRowSelection = true;}>My Link Text</Link>`
+
 ### How do I stop my table state from automatically resetting when my data changes?
 
 By default, the `AnalyticalTable` will reset the sorters, filters, grouping, selected rows, etc. when the table data changes.
@@ -272,32 +245,115 @@ export const ResponsiveTable = () => {
 With the help of that effect, the table will now show either 2 columns on a mobile phone, 3 columns on a tablet device and all columns on Desktop devices.
 This even works if you resize the browser window!
 
+<br />
+
 # Stories
 
+<br />
+
 ## Tree Table
 
 <Canvas>
-  <Story name="Tree Table" args={{ data: generateData(20, true) }}>
-    {(args) => (
-      <AnalyticalTable
-        {...args}
-        title={args.title}
-        data={args.data}
-        columns={args.columns}
-        loading={args.loading}
-        sortable={args.sortable}
-        filterable={args.filterable}
-        visibleRows={args.visibleRows}
-        minRows={args.minRows}
-        selectionMode={args.selectionMode}
-        onRowSelected={args.onRowSelected}
-        onSort={args.onSort}
-        onRowExpandChange={args.onRowExpandChange}
-        subRowsKey={args.subRowsKey}
-        selectedRowIds={args.selectedRowIds}
-        selectionBehavior={args.selectionBehavior}
-        isTreeTable
-      />
-    )}
+  <Story name="Tree Table" args={{ data: generateData(20, true), isTreeTable: true }}>
+    {(args) => <AnalyticalTable {...args} />}
+  </Story>
+</Canvas>
+
+The `data` structure of the tree table is as follows:
+
+```js
+const data = {
+    name: "Greg Miller",
+    age: 35,
+    friend: {
+        name: "Rose Franco",
+        age: 32,
+    },
+    status: "None",
+    subRows: [
+        {
+            name: "Rick DeAngelo",
+            age: 25,
+            friend: {
+                name: "Susanne Franco",
+                age: 37,
+            },
+            status: "None",
+            subRows: [...],
+        },
+    ],
+    ...
+};
+```
+
+In this example the default key for sub row detection is used (`subRows`), you can use any key you like by setting the `subRowsKey` prop.
+
+<br />
+
+## Infinite Scrolling
+
+The table initially contains 50 rows, when the last 10 rows are reached the table will load more data.
+
+<Canvas>
+  <Story name="Infinite Scrolling">
+    {(args) => {
+      const [data, setData] = useState(args.data.slice(0, 50));
+      const [loading, setLoading] = useState(false);
+      const offset = useRef(50);
+      const onLoadMore = () => {
+        setLoading(true);
+      };
+      useEffect(() => {
+        if (loading) {
+          setTimeout(() => {
+            setData((prev) => [...prev, ...args.data.slice(offset.current, offset.current + 50)]);
+            setLoading(false);
+            offset.current += 50;
+          }, 2000);
+        }
+      }, [loading, args.data, offset.current]);
+      return (
+        <AnalyticalTable
+          data={data}
+          columns={args.columns}
+          infiniteScroll={true}
+          infiniteScrollThreshold={10}
+          title="Scroll to load more data"
+          onLoadMore={onLoadMore}
+          loading={loading}
+        />
+      );
+    }}
   </Story>
 </Canvas>
+
+```jsx
+const InfiniteScrollTable = (props) => {
+  const [data, setData] = useState(props.data.slice(0, 50));
+  const [loading, setLoading] = useState(false);
+  const offset = useRef(50);
+  const onLoadMore = () => {
+    setLoading(true);
+  };
+  useEffect(() => {
+    if (loading) {
+      setTimeout(() => {
+        setData((prev) => [...prev, ...props.data.slice(offset.current, offset.current + 50)]);
+        setLoading(false);
+        offset.current += 50;
+      }, 2000);
+    }
+  }, [loading, props.data, offset.current]);
+  return (
+    <AnalyticalTable
+      data={data}
+      columns={props.columns}
+      infiniteScroll={true}
+      infiniteScrollThreshold={10}
+      title="Scroll to load more data"
+      onLoadMore={onLoadMore}
+      loading={loading}
+    />
+  );
+};
+```

packages/main/src/components/AnalyticalTable/TableBody/VirtualTableBodyContainer.tsx

@@ -13,7 +13,8 @@ export const VirtualTableBodyContainer = (props) => {
     onLoadMore,
     rows,
     internalRowHeight,
-    handleExternalScroll
+    handleExternalScroll,
+    visibleRows
   } = props;
   const [isMounted, setIsMounted] = useState(false);
 
@@ -35,8 +36,8 @@ export const VirtualTableBodyContainer = (props) => {
       const isScrollingDown = lastScrollTop.current < scrollOffset;
       if (isScrollingDown && infiniteScroll) {
         lastScrollTop.current = scrollOffset;
-        const currentTopRow = Math.floor(scrollOffset / internalRowHeight);
-        if (rows.length - currentTopRow < infiniteScrollThreshold) {
+        const currentLastRow = Math.floor(scrollOffset / internalRowHeight) + visibleRows;
+        if (rows.length - currentLastRow < infiniteScrollThreshold) {
           if (!firedInfiniteLoadEvents.current.has(rows.length)) {
             onLoadMore({
               detail: {

packages/main/src/components/AnalyticalTable/index.tsx

@@ -75,7 +75,7 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
    */
   data: Record<any, any>[];
   /**
-   * Component or text rendered in the title section of the `AnalyticalTable`.
+   * Component or text rendered in the title section of the `AnalyticalTable`.<br />
    * __Note:__ If not set, it will be hidden.
    */
   title?: ReactText | ReactNode;
@@ -90,12 +90,12 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
    */
   minRows?: number;
   /**
-   * The number of rows visible without going into overflow.
+   * The number of rows visible without going into overflow.<br />
    * __Note:__ If the data contains more entries than the `visibleRow` count, a vertical scrollbar is rendered and the table goes into overflow.
    */
   visibleRows?: number;
   /**
-   * Indicates whether a loading indicator should be shown.
+   * Indicates whether a loading indicator should be shown.<br />
    * __Note:__ If the data array is not empty and loading is set to `true` a `Loader` will be displayed underneath the header, otherwise a loading placeholder will be shown.
    * You can use your own placeholder by passing it to the `LoadingComponent` prop.
    */
@@ -144,17 +144,17 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
    */
   groupBy?: string[];
   /**
-   * Defines the selection behavior of the table. <br />
-   *   __"Row":__ A selection column is rendered along with the normal columns. The whole row is selectable.
-   *   __"RowOnly":__ No selection column is rendered along with the normal columns. The whole row is selectable.
-   *   __"RowSelector":__ The row is only selectable by clicking on the corresponding field in the selection column.
+   * Defines the selection behavior of the table.<br />
+   * - __"Row":__ A selection column is rendered along with the normal columns. The whole row is selectable.
+   * - __"RowOnly":__ No selection column is rendered along with the normal columns. The whole row is selectable.
+   * - __"RowSelector":__ The row is only selectable by clicking on the corresponding field in the selection column.
    */
   selectionBehavior?: TableSelectionBehavior;
   /**
    * Defines the `SelectionMode` of the table.<br />
-   *   __"None":__ The rows are not selectable.
-   *   __"SingleSelect":__ You can select only one row at once. Clicking on another row will unselect the previously selected row.
-   *   __"MultiSelect":__ You can select multiple rows.
+   * - __"None":__ The rows are not selectable.
+   * - __"SingleSelect":__ You can select only one row at once. Clicking on another row will unselect the previously selected row.
+   * - __"MultiSelect":__ You can select multiple rows.
    */
   selectionMode?: TableSelectionMode;
   /**
@@ -175,7 +175,8 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
    */
   infiniteScroll?: boolean;
   /**
-   * Defines the infinite scroll threshold. When the threshold is reached, the `onLoadMore` event is fired.
+   * The `infiniteScrollThreshold` defines at how many remaining rows the `onLoadMore` event should be fired.<br />
+   * Example: Your initial dataset consists of 50 entries and you want to load more data when the user scrolled to the 40th row. Then you should set the `infiniteScrollThreshold` to 10.
    */
   infiniteScrollThreshold?: number;
 
@@ -246,13 +247,9 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
 }
 
 const useStyles = createComponentStyles(styles, { name: 'AnalyticalTable' });
-
 /**
- * ### Usage Notes
- * By default, the `AnalyticalTable` will not select any rows after clicking on active elements like a `Button`, `Link`,
- * etc. <br />
- * In case you want to select the row anyways, you can "mark" the event to allow such a behaviour. <br />
- * Example: `<Link onClick={(e) => {e.markerAllowTableRowSelection = true;}>My Link Text</Link>`
+ * The `AnalyticalTable` provides a set of convenient functions for responsive table design, including virtualization of rows and columns, infinite scrolling and customizable columns that will, unless otherwise defined, distribute the available space equally among themselves.
+ * It also provides several possibilities for working with the data, including sorting, filtering, grouping and aggregation.
  */
 const AnalyticalTable: FC<TableProps> = forwardRef((props: TableProps, ref: Ref<HTMLDivElement>) => {
   const {
@@ -587,6 +584,7 @@ const AnalyticalTable: FC<TableProps> = forwardRef((props: TableProps, ref: Ref<
               internalRowHeight={internalRowHeight}
               rows={rows}
               handleExternalScroll={handleBodyScroll}
+              visibleRows={visibleRows}
             >
               <VirtualTableBody
                 classes={classes}