docs(AnalyticalTable): add feature examples subfolder (#8499)

Author: Lukas742

.storybook/components/VersionSwitch.tsx

@@ -63,6 +63,7 @@ addons.register(ADDON_ID, () => {
             onClick={() => {
               setOpen(true);
             }}
+            ariaLabel={false}
           >
             Version: {activeVersion}
           </IconButton>

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

@@ -99,6 +99,8 @@ const TableComp = () => {
 
 ## Tree Table
 
+Set `isTreeTable` to `true` and provide nested data via the `subRows` key (configurable with `subRowsKey`). Each row with `subRows` becomes expandable.
+
 <Canvas of={ComponentStories.TreeTable} sourceState={'none'} />
 
 The `data` structure of the tree table is as follows:
@@ -136,7 +138,7 @@ In this example the default key for sub row detection is used (`subRows`), you c
 
 The table initially contains 50 rows, when the last 10 rows are reached the table will load more data.
 
-**Note:** To prevent the table state from resetting when the data is updated, please see [this recipe](?path=/docs/data-display-analyticaltable-recipes--docs#how-to-stop-the-table-state-from-automatically-resetting-when-the-data-changes).
+**Note:** To prevent the table state from resetting when the data is updated, please see [this faq entry](?path=/docs/data-display-analyticaltable-faq--docs#how-to-stop-the-table-state-from-automatically-resetting-when-the-data-changes).
 
 <Canvas sourceState="none" of={ComponentStories.InfiniteScrolling} />
 
@@ -172,109 +174,31 @@ const InfiniteScrollTable = (props) => {
       header="Scroll to load more data"
       onLoadMore={onLoadMore}
       loading={loading}
-      reactTableOptions: {{ autoResetSelectedRows: false }}
+      reactTableOptions={{ autoResetSelectedRows: false }}
     />
   );
 };
 ```
 
 </details>
 
-## AnalyticalTable with subcomponents
-
-Adding custom subcomponents below table rows can be achieved by setting the `renderRowSubComponent` prop.
-The prop expects a function with an optional parameter containing the `row` instance, there you can control which row should display subcomponents. If you want to display the subcomponent at the bottom of the row without an expandable container, you can set `subComponentsBehavior` prop to `"Visible"` or to `"IncludeHeight"`. "Visible" simply adds the subcomponent to the row without including its height in the initial calculation of the table body, whereas "IncludeHeight" does.
-
-### Notes
-
-- When `renderRowSubComponent` is set, `grouping` is disabled.
-- When rendering active elements inside the subcomponent, make sure to add the `data-subcomponent-active-element' attribute, otherwise focus behavior won't be consistent.
-- When `AnalyticalTableSubComponentsBehavior.IncludeHeight` or `AnalyticalTableSubComponentsBehavior.IncludeHeightExpandable` is used, `AnalyticalTableVisibleRowCountMode.Interactive` is not supported.
-
-<ControlsWithNote of={ComponentStories.Subcomponents} include={['renderRowSubComponent', 'subComponentsBehavior']} />
-
-<Canvas sourceState="none" of={ComponentStories.Subcomponents} />
-
-### Code
-
-<details>
-
-<summary>Show Code</summary>
-
-```jsx
-const TableWithSubcomponents = (props) => {
-  const renderRowSubComponent = (row) => {
-    if (row.id === '0') {
-      return (
-        <FlexBox
-          style={{ backgroundColor: 'lightblue', height: '300px' }}
-          justifyContent={FlexBoxJustifyContent.Center}
-          alignItems={FlexBoxAlignItems.Center}
-          direction={FlexBoxDirection.Column}
-        >
-          <Tag>height: 300px</Tag>
-          <Text>This subcomponent will only be displayed below the first row.</Text>
-          <hr />
-          <Text>
-            The button below is rendered with `data-subcomponent-active-element` attribute to ensure consistent focus
-            behavior
-          </Text>
-          <Button data-subcomponent-active-element>Click</Button>
-        </FlexBox>
-      );
-    }
-    if (row.id === '1') {
-      return (
-        <FlexBox
-          style={{ backgroundColor: 'lightyellow', height: '100px' }}
-          justifyContent={FlexBoxJustifyContent.Center}
-          alignItems={FlexBoxAlignItems.Center}
-          direction={FlexBoxDirection.Column}
-        >
-          <Tag>height: 100px</Tag>
-          <Text>This subcomponent will only be displayed below the second row.</Text>
-        </FlexBox>
-      );
-    }
-    if (row.id === '2') {
-      return null;
-    }
-    return (
-      <FlexBox
-        style={{ backgroundColor: 'lightgrey', height: '50px' }}
-        justifyContent={FlexBoxJustifyContent.Center}
-        alignItems={FlexBoxAlignItems.Center}
-        direction={FlexBoxDirection.Column}
-      >
-        <Tag>height: 50px</Tag>
-        <Text>This subcomponent will be displayed below all rows except the first, second and third.</Text>
-      </FlexBox>
-    );
-  };
-  return (
-    <AnalyticalTable
-      data={props.data}
-      columns={props.columns}
-      renderRowSubComponent={renderRowSubComponent}
-      subComponentsBehavior={AnalyticalTableSubComponentsBehavior.Expandable} //default value
-    />
-  );
-};
-```
+## Auto Row Count
 
-</details>
+Set `visibleRowCountMode` to `AnalyticalTableVisibleRowCountMode.Auto` or `AutoWithEmptyRows` to let the table automatically fill its container with rows.
 
-## Adjust the number of rows to the container height
+**Prerequisites:**
 
-By adding the `visibleRowCountMode` prop and setting it to `AnalyticalTableVisibleRowCountMode.Auto` the table automatically fills the surrounding container with rows and when setting it to `AnalyticalTableVisibleRowCountMode.AutoWithEmptyRows`, empty rows fill the container as well, if not enough visible rows are available.
+- The table **must** be placed inside a container with a **defined height** (e.g. `height: 500px`, `flex: 1`, or a CSS Grid row). Without a constrained parent, the table cannot determine how many rows to render.
+- `AutoWithEmptyRows` fills remaining space with empty rows when there aren't enough data rows to fill the container.
+- `Auto` may lead to inconsistent table heights depending on the container — prefer `AutoWithEmptyRows` for a stable layout.
 
 <ControlsWithNote
-  of={ComponentStories.DynamicRowCount}
+  of={ComponentStories.AutoRowCount}
   include={['containerHeight', 'visibleRowCountMode']}
   hideHTMLPropsNote
 />
 
-<Canvas sourceState="none" of={ComponentStories.DynamicRowCount} />
+<Canvas sourceState="none" of={ComponentStories.AutoRowCount} />
 
 ### Code
 
@@ -294,10 +218,10 @@ const TableComponent = (props) => {
 };
 ```
 
-## Responsively display columns on small devices (Pop-In)
+## Responsive Columns (Pop-In)
 
 <ControlsWithNote
-  of={ComponentStories.ResponsiveColumns}
+  of={ComponentStories.ResponsiveColumnsPopIn}
   hideHTMLPropsNote
   include={['adjustTableHeightOnPopIn', 'containerWidth']}
 />
@@ -315,7 +239,7 @@ In the example below you can have a look at this behavior:
 - `600`: The content of the "Age" column is moved to the first column (`responsiveMinWidth: 601`) and receives a custom header.
 - `400`: The content of the "Friend Name" column is moved to the first column and the "Friend Age" column is hidden (`responsiveMinWidth: 401`). The "Friend Name" column also receives a custom header.
 
-<Canvas sourceState="none" of={ComponentStories.ResponsiveColumns} />
+<Canvas sourceState="none" of={ComponentStories.ResponsiveColumnsPopIn} />
 
 ### Columns Config
 
@@ -366,9 +290,9 @@ const COLUMNS = [
     Header: 'PopinDisplay Modes',
     responsivePopIn: true,
     responsiveMinWidth: 801,
-    popinDisplay: popinDisplay, // possible values: "Block", "Inline", "WithoutHeader"
+    popinDisplay: AnalyticalTablePopinDisplay.Block, // possible values: "Block", "Inline", "WithoutHeader"
     Cell: () => {
-      return <Text maxLines={1}>Using popinDisplay: {popinDisplay}</Text>;
+      return <Text maxLines={1}>Using popinDisplay: Block</Text>;
     }
   }
 ];
@@ -410,118 +334,11 @@ const COLUMNS = [
 ];
 ```
 
-## Display indicator for navigated rows
-
-To display show the navigation column you need to set `withNavigationHighlight` to `true` and to mark a row as "navigated" the `markNavigatedRow` prop is required.
-With the `markNavigatedRow` callback it is possible to define when and how many navigation indicators should be shown.
-
-Click on any of the rows in the example below to display the "navigated" indicator in the navigation-column.
-
-<Canvas sourceState="none" of={ComponentStories.NavigationIndicator} />
-
-### Code
-
-```jsx
-export const TableWithNavigationIndicators = () => {
-  const [selectedRow, setSelectedRow] = useState();
-  const onRowSelect = (e) => {
-    setSelectedRow(e.detail.row);
-  };
-  const markNavigatedRow = useCallback(
-    (row) => {
-      return selectedRow?.id === row.id;
-    },
-    [selectedRow]
-  );
-  return (
-    <AnalyticalTable
-      data={data}
-      columns={columns}
-      withNavigationHighlight
-      selectionMode={selectionMode}
-      markNavigatedRow={markNavigatedRow}
-      onRowSelect={onRowSelect}
-    />
-  );
-};
-```
-
-## Custom column filtering
-
-It is possible to define your own filter function and filter component on each column. For this you need to customize the column option `filter` or add a custom filter type to the `reactTableOptions.filterTypes` object (for a custom filter function) and the column option `Filter` (for a custom filter component).
-
-Here you can find an example using a `MultiComboBox` with multiple values as filter.
-
-<Canvas sourceState="none" of={ComponentStories.CustomFilter} />
-
-### Code
-
-<details>
-
-<summary>Show static code</summary>
-
-```jsx
-const filterFn = (rows, accessor, filterValue) => {
-  if (filterValue.length > 0) {
-    return rows.filter((row) => {
-      const rowVal = row.values[accessor];
-      if (filterValue.some((item) => rowVal.includes(item))) {
-        return true;
-      }
-      return false;
-    });
-  }
-  return rows;
-};
-const COLUMNS = [
-  {
-    Header: 'Name',
-    accessor: 'name',
-    // either define your filter function here or set is as `reactTableOption` and pass the key as string here (see below)
-    filter: filterFn,
-    Filter: ({ column }) => {
-      const firstNames = ['Carl', 'Dan', 'Rose', 'Susanne'];
-      return (
-        <MultiComboBox
-          onSelectionChange={(e) => {
-            column.setFilter(e.detail.items.map((item) => item.getAttribute('text')));
-          }}
-        >
-          {firstNames.map((item) => {
-            const isSelected = column?.filterValue?.some((filterVal) => filterVal.includes(item));
-            return <MultiComboBoxItem text={item} key={item} selected={isSelected} />;
-          })}
-        </MultiComboBox>
-      );
-    }
-  },
-  {
-    Header: 'Age',
-    accessor: 'age'
-  }
-];
-const TableComponent = () => {
-  return (
-    <ThemeProvider>
-      <AnalyticalTable
-        columns={COLUMNS}
-        data={DATA}
-        filterable
-        // you can also define your function here, then you can just pass the key as string to the `filter` column option
-        // reactTableOptions={{
-        //   filterTypes: {
-        //     multiValueFilter: filterFn
-        //   }
-        // }}
-      />
-    </ThemeProvider>
-  );
-};
-```
+## Table Without Data
 
-</details>
+Use the `NoDataComponent` prop to customize the empty state. By default, a simple text message is shown. You can pass a custom component (e.g. an `IllustratedMessage`) to display a richer empty state for different scenarios like "no data" vs. "no filter results". The component receives an `accessibleRole` prop that should be forwarded for accessibility.
 
-## Table Without Data
+**Note:** When using an `IllustratedMessage` as `NoDataComponent`, the table must have sufficient height for the illustration to render properly. With `visibleRowCountMode` set to `Auto` or `AutoWithEmptyRows`, the table container needs a minimum height of approximately `300px`. With the default `Fixed` mode, ensure `visibleRows` provides enough vertical space (typically 5+ rows).
 
 <Canvas of={ComponentStories.NoData} />
 
@@ -588,6 +405,8 @@ function NoDataTable(props) {
 
 ## Kitchen Sink
 
+A comprehensive example combining many AnalyticalTable features: sorting, filtering, grouping, custom cells, row and navigation highlighting, infinite scrolling, column reordering, vertical alignment, `scaleWidthModeOptions` for custom renderers, `retainColumnWidth`, `sortDescFirst`, and more.
+
 <Canvas of={ComponentStories.KitchenSink} />
 
 ### Code
@@ -634,12 +453,14 @@ const columns = [
     disableFilters: false,
     disableGroupBy: true,
     disableSortBy: false,
-    hAlign: 'End'
+    hAlign: 'End',
+    sortDescFirst: true
   },
   {
     Header: 'Friend Name',
     accessor: 'friend.name',
-    autoResizable: true
+    autoResizable: true,
+    vAlign: VerticalAlign.Middle
   },
   {
     Filter: () => {},
@@ -648,17 +469,26 @@ const columns = [
     autoResizable: true,
     filter: () => {},
     hAlign: 'End',
-    headerLabel: 'Friend Age'
+    headerLabel: 'Friend Age',
+    scaleWidthModeOptions: { headerString: 'Friend Age' }
+  },
+  {
+    Header: 'Status',
+    id: 'os',
+    Cell: () => {},
+    scaleWidthModeOptions: { cellString: 'Negative' }
   },
   {
     Cell: () => {},
     Header: 'Actions',
     accessor: '.',
     cellLabel: () => {},
     disableFilters: true,
+    disableGlobalFilter: true,
     disableGroupBy: true,
     disableResizing: true,
     disableSortBy: true,
+    disableDragAndDrop: true,
     id: 'actions',
     minWidth: 100,
     width: 100
@@ -688,6 +518,7 @@ const TestComp2 = () => {
       minRows={5}
       noDataText="Custom 'noDataText' message"
       overscanCountHorizontal={5}
+      retainColumnWidth
       scaleWidthMode="Smart"
       selectedRowIds={{
         3: true
@@ -698,6 +529,7 @@ const TestComp2 = () => {
       subRowsKey="subRows"
       visibleRowCountMode="Interactive"
       visibleRows={5}
+      withNavigationHighlight
       withRowHighlight
       onAutoResize={() => {}}
       onColumnsReorder={() => {}}