@agregio-solutions/design-system 1.90.1 → 1.92.0

package/dist/packages/components/DataTable/doc.md

@@ -0,0 +1,1124 @@
+# DataTable
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/DataTable/DataTable.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Filter, { TypeTableColumnWithFilter } from "../Filter/Filter";
+import arrayOfLength from "@internal/arrayOfLength/arrayOfLength";
+import {
+  ColumnFiltersState,
+  ColumnSort,
+  SortingState,
+  createColumnHelper,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import DataTableHeader from "@packages/components/DataTable/DataTableHeader/DataTableHeader";
+import { useMemo, useState } from "react";
+import { useQuery, keepPreviousData } from "@tanstack/react-query";
+import DataTableCell from "@packages/components/DataTable/DataTableCell/DataTableCell";
+import DataTable from "@packages/components/DataTable/DataTable";
+import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
+import Checkbox from "../Checkbox/Checkbox";
+import Radio from "../Radio/Radio";
+import { I18nProvider } from "react-aria-components";
+import Select from "../Select/Select";
+import SelectItem from "../SelectItem/SelectItem";
+import Button from "../Button/Button";
+import Switch from "../Switch/Switch";
+import { within } from "storybook/test";
+import { someTime } from "@internal/test-utils-storybook/test-utils-storybook";
+import DataTableRoot from "./DataTableRoot/DataTableRoot";
+import DataTableRow from "./DataTableRow/DataTableRow";
+
+const meta: Meta<typeof DataTable> = {
+  component: DataTable,
+  parameters: {
+    layout: "padded",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale={"en-EN"}>
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
+  render: () => {
+    const ParentComponent = () => {
+      // Below are just type definition of the data and its generation
+      // Typically you would get this from your API and will not have to create them here
+      // We let it so you can fully understand how the filter works based on the data provided
+
+      type User = {
+        firstname: string;
+        lastname: string;
+        email: string;
+        isValidated?: boolean;
+        day?: string;
+        foods?: Array<string>;
+        organization?: { id: string; name: string };
+        isActive?: boolean;
+      };
+
+      const ALL_FOODS = useMemo(
+        () => ["Pizza", "Hamburger", "Ramen", "Sushi", "Fries"],
+        [],
+      );
+
+      const FOODS = useMemo(
+        () => [
+          [ALL_FOODS[0], ALL_FOODS[1]],
+          [ALL_FOODS[1], ALL_FOODS[2]],
+          [ALL_FOODS[2], ALL_FOODS[3]],
+          [ALL_FOODS[3], ALL_FOODS[4]],
+          [ALL_FOODS[4], ALL_FOODS[0]],
+        ],
+        [ALL_FOODS],
+      );
+
+      const ORGANIZATIONS = useMemo(
+        () => [
+          { id: "1", name: "EDF Store and Forecast" },
+          { id: "2", name: "Agregio Solutions" },
+          { id: "3", name: "Dalkia" },
+        ],
+        [],
+      );
+
+      const DAYS = useMemo(
+        () => ["Monday", "Tuesday", "Wednesday", "Thursday"],
+        [],
+      );
+
+      const data: Array<User> = useMemo(
+        () =>
+          arrayOfLength(300).map((index) => ({
+            firstname: `Firstname ${index + 1}`,
+            lastname: `Lastname ${index + 1}`,
+            email: `john-doe${index + 1}@example.com`,
+            isValidated: index % 2 === 0,
+            foods: FOODS[index % FOODS.length],
+            day: DAYS[index % DAYS.length],
+            organization: ORGANIZATIONS[index % ORGANIZATIONS.length],
+            isActive: index % 2 === 0,
+          })),
+        [DAYS, FOODS, ORGANIZATIONS],
+      );
+
+      // Here starts the interesting stuff: columns definitions.
+      // All the features of the filters comes from those columns definitions
+      // Please read carefully each column, they all serve as a different example of how to use the filters
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            // Here, because there is no "FilterInDrawer" component, there will be nothing in the filter drawer related to the firstname
+            // But the firstname can still be filtered by the global filter (search input)
+            header: ({ header }) => (
+              <DataTableHeader
+                onSortClick={header.column.getToggleSortingHandler()}
+                sortDirection={header.column.getIsSorted() || "none"}
+                text="Firstname"
+              />
+            ),
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          // Here is an example using a "FilterInDrawer" component that render a radio group to filter the day
+          // Please note the "filterFn" is "arrIncludes" for this king of value (Array<string>)
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // Finally, you will note that the Chips are auto-generated, if you do not want to use them you can set the `skipFilterChips` to true
+          columnHelper.accessor("day", {
+            id: "Day",
+            header: () => <DataTableHeader text="Day" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+            filterFn: "equals",
+            meta: {
+              FilterInDrawer: ({ column }) => (
+                <div>
+                  <b>Filter by day:</b>
+
+                  {DAYS.map((day) => (
+                    <Radio
+                      label={day}
+                      key={day}
+                      checked={column.getFilterValue() === day}
+                      onChange={() => column.setFilterValue(day)}
+                    />
+                  ))}
+                </div>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is another example using a "FilterInDrawer" component that render a checkbox group to filter the food
+          // Please note the "filterFn" is "arrIncludesSome" -> we want to include all entries that match at least one food
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // Finally, you will note that the Chips are auto-generated, if you do not want to use them you can set the `skipFilterChips` to true
+          columnHelper.accessor("foods", {
+            id: "Foods",
+            header: () => <DataTableHeader text="Foods" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue()?.join(", ")}</DataTableCell>
+            ),
+            filterFn: "arrIncludesSome",
+            meta: {
+              FilterInDrawer: ({ column }) => (
+                <div style={{ marginTop: 8 }}>
+                  <b>Filter by food (at least one):</b>
+                  <CheckboxGroup
+                    value={(column.getFilterValue() as any) || []}
+                    onChange={column.setFilterValue}
+                    aria-label="Filter by food (at least one)"
+                  >
+                    {ALL_FOODS.map((food) => (
+                      <div key={food}>
+                        <Checkbox label={food} value={food} />
+                      </div>
+                    ))}
+                  </CheckboxGroup>
+                </div>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is another example using a "FilterInDrawer" component that render a select to filter the organization
+          // Please note the "filterFn" is a custom function that will filter the data based on the organization id
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // And most important here, we have a custom meta property `filterChips` that will generate a chip to display the selected organization
+          // The Filter can not handle automatic chips when the data is a complex object, so you have to handle that manually
+          columnHelper.accessor("organization", {
+            id: "Organization",
+            header: () => <DataTableHeader text="Organization" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue()?.name}</DataTableCell>
+            ),
+            filterFn: (row, _, filterValue) => {
+              if (!filterValue) return true;
+              return row.original.organization?.id === filterValue;
+            },
+            meta: {
+              filterChips: ({ column }) => {
+                const value = column.getFilterValue();
+                const organization = ORGANIZATIONS.find(
+                  (org) => org.id === value,
+                );
+                if (!organization) return [];
+                return [
+                  {
+                    value: `Organization: ${organization.name}`,
+                    onClose: () => column.setFilterValue(null),
+                  },
+                ];
+              },
+              FilterInDrawer: ({ column }) => (
+                <Select
+                  id="organization-select"
+                  label="Filter by organization:"
+                  mode="single"
+                  value={(column.getFilterValue() as any) || null}
+                  onChange={column.setFilterValue}
+                  fullWidth
+                  wrapperProps={{ style: { marginBottom: 8 } }}
+                >
+                  {ORGANIZATIONS.map((organization) => (
+                    <SelectItem
+                      text={organization.name}
+                      id={organization.id}
+                      key={organization.id}
+                    />
+                  ))}
+                </Select>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is an example that uses a filter outside of the drawer.
+          // See the "extraLeftContent" prop to see how to connect it to react-table filtering features
+          columnHelper.accessor("isActive", {
+            header: () => <DataTableHeader text="Active" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue() ? "✅" : "❌"}</DataTableCell>
+            ),
+            filterFn: (row, _, filterValue) => {
+              if (!filterValue) return true;
+              return !!row.original.isActive;
+            },
+          }),
+          // Here is an example of an empty column, for example to display an actions bar
+          // You can note that the header is empty, the text is optional
+          columnHelper.display({
+            id: "actions",
+            header: () => <DataTableHeader />,
+            cell: () => (
+              <DataTableCell>
+                <Button mode="secondary" iconLeft="edit" />
+              </DataTableCell>
+            ),
+          }),
+        ],
+        [ALL_FOODS, DAYS, ORGANIZATIONS, columnHelper],
+      );
+
+      // And here we define the table as usual
+      const table = useReactTable({
+        data,
+        columns,
+        initialState: {
+          globalFilter: "", // Add this to show the global filter (aka the Search bar)
+          pagination: {
+            pageSize: 12, // Add this to customize the page size
+          },
+        },
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getPaginationRowModel: getPaginationRowModel(),
+      });
+
+      // Get the pagination state
+      const pagination = table.getState().pagination;
+
+      // Render the table using the base DataTable component
+      return (
+        <>
+          <Filter<User>
+            onDownloadClick={() => alert("Download")}
+            onSettingsClick={() => alert("Settings")}
+            table={table}
+            extraLeftContent={
+              <>
+                <Switch
+                  label="Only active"
+                  isSelected={!!table.getColumn("isActive")?.getFilterValue()}
+                  onChange={() =>
+                    table
+                      .getColumn("isActive")
+                      ?.setFilterValue((prevValue: boolean) => !prevValue)
+                  }
+                />
+              </>
+            }
+            extraRightContent={
+              <>
+                <Button
+                  mode="secondary"
+                  onClick={() => alert("Secondary")}
+                  text="Secondary"
+                />
+                <Button
+                  mode="primary"
+                  onClick={() => alert("Primary")}
+                  text="Primary"
+                />
+              </>
+            }
+          />
+          <DataTable
+            table={table}
+            pagination={pagination}
+            itemsPerPageOptions={[12, 24, 36, 48, 60]} // Add this to customize the page size options available in the select
+          />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+type User = {
+  firstname: string;
+  lastname: string;
+  email: string;
+  isValidated?: boolean;
+  day?: string;
+  foods?: Array<string>;
+  organization?: { id: string; name: string };
+  isActive?: boolean;
+};
+
+// Just a fake API to simulate a backend
+async function api(params: {
+  page: number;
+  pageSize: number;
+  sorting: ColumnSort;
+  emails?: Array<string>;
+}) {
+  await someTime(100);
+  const { page, pageSize, sorting, emails } = params;
+
+  let data: Array<User> = arrayOfLength(300).map((index) => ({
+    firstname: `Firstname ${index + 1}`,
+    lastname: `Lastname ${index + 1}`,
+    email: `john-doe${index + 1}@example.com`,
+  }));
+
+  if (emails && emails.length > 0) {
+    data = data.filter((user) => emails.includes(user.email));
+  }
+
+  if (sorting) {
+    const key = sorting.id;
+
+    data.sort((a: any, b: any) => {
+      if (sorting.desc) {
+        return b[key].localeCompare(a[key], undefined, { numeric: true });
+      } else {
+        a[key].localeCompare(b[key], undefined, { numeric: true });
+      }
+    });
+  }
+
+  return {
+    data: data.slice(page * pageSize, (page + 1) * pageSize),
+    total: data.length,
+  };
+}
+
+export const WithReactTableBackEndManaged: StoryObj<typeof DataTable> = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+    layout: "padded",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  render: () => {
+    function UsersTable() {
+      // Create state for the pagination
+      const [pagination, setPagination] = useState({
+        pageIndex: 0, //initial page index
+        pageSize: 10, //default page size
+      });
+
+      // Create state for the sorting (with an initial state)
+      const [sorting, setSorting] = useState<SortingState>([
+        { id: "email", desc: false },
+      ]);
+
+      // Create state for the filters
+      const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>(
+        [],
+      );
+
+      // Fetch data using the table state (filters, pagination, sorting, etc.)
+      const { data } = useQuery({
+        placeholderData: keepPreviousData, // from @tanstack/react-query, recommended to use it in this scenario
+        queryKey: ["users", pagination, sorting, columnFilters],
+        queryFn: () =>
+          // You API call goes here, you have access to the table state to build your query params
+          api({
+            page: pagination.pageIndex,
+            pageSize: pagination.pageSize,
+            sorting: sorting[0], // handle only one sorting for this example
+            emails: columnFilters.find((filter) => filter.id === "email")
+              ?.value as Array<string>,
+          }),
+      });
+
+      // You will need to create a column helper
+      // ⚠ This should be memoized!
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      // Then, you can define the columns
+      // ⚠ This should be memoized!
+      const columns = useMemo(
+        () => [
+          // Example of a custom column for initials (no data model, so no filters, etc)
+          columnHelper.display({
+            id: "initials",
+            header: () => <DataTableHeader text="Initials" />,
+            cell: (props) => (
+              <DataTableCell>
+                {/*Here is an example of how you can access the data model values directly (if needed) */}
+                {props.row.original.firstname[0]}
+                {props.row.original.lastname[0]}
+              </DataTableCell>
+            ),
+          }),
+          // Example of a column with sorting (accessor means it has data model)
+          columnHelper.accessor("firstname", {
+            header: ({ header }) => (
+              <DataTableHeader
+                onSortClick={header.column.getToggleSortingHandler()}
+                sortDirection={header.column.getIsSorted() || "none"}
+                text="Firstname"
+              />
+            ),
+            cell: (props) => (
+              <DataTableCell iconLeft="star_outline">
+                {/* because the accessor key ("firstname") is a data model object key, we can access it directly with getValue() */}
+                {props.getValue()}
+              </DataTableCell>
+            ),
+          }),
+          columnHelper.accessor("lastname", {
+            header: ({ header }) => (
+              <DataTableHeader
+                onSortClick={header.column.getToggleSortingHandler()}
+                sortDirection={header.column.getIsSorted() || "none"}
+                text="Lastname"
+              />
+            ),
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.accessor("email", {
+            header: ({ header }) => (
+              <DataTableHeader
+                onSortClick={header.column.getToggleSortingHandler()}
+                sortDirection={header.column.getIsSorted() || "none"}
+                text="Email"
+                iconLeft="send"
+              />
+            ),
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+            meta: {
+              FilterInDrawer: ({ column }) => (
+                <Select
+                  id="email-select"
+                  label="Filter by email:"
+                  mode="multiple"
+                  selectedKeys={(column.getFilterValue() as any) || []}
+                  onSelectionChange={column.setFilterValue}
+                  fullWidth
+                  wrapperProps={{ style: { marginBottom: 8 } }}
+                >
+                  {arrayOfLength(10).map((index) => (
+                    <SelectItem
+                      text={`john-doe${index + 1}@example.com`}
+                      id={`john-doe${index + 1}@example.com`}
+                      key={`john-doe${index + 1}@example.com`}
+                    />
+                  ))}
+                </Select>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+        ],
+        [columnHelper],
+      );
+
+      // Instantiate the table with @tanstack/react-table
+      const table = useReactTable({
+        data: data?.data || [],
+        columns,
+        getCoreRowModel: getCoreRowModel(), // from @tanstack/react-table
+        manualPagination: true,
+        manualSorting: true,
+        manualFiltering: true,
+        onPaginationChange: setPagination, //update the pagination state when internal APIs mutate the pagination state
+        onSortingChange: setSorting, //update the sorting state when internal APIs mutate the sorting state
+        onColumnFiltersChange: setColumnFilters, //update the column filters state when internal APIs mutate the column filters state
+        rowCount: data?.total, //total number of rows
+        state: {
+          pagination,
+          sorting,
+          columnFilters,
+        },
+      });
+
+      // Render the table using the base DataTable component
+      return (
+        <>
+          <Filter<User> table={table} />
+          <DataTable table={table} pagination={pagination} />
+        </>
+      );
+    }
+
+    return <UsersTable />;
+  },
+};
+
+export const Empty: StoryObj<typeof DataTable> = {
+  render: () => {
+    const ParentComponent = () => {
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      const data = useMemo(() => [], []);
+
+      const columns = useMemo(
+        () => [
+          columnHelper.display({
+            id: "example",
+            header: () => <DataTableHeader text="Example" />,
+            cell: () => <DataTableCell>Example</DataTableCell>,
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const table = useReactTable({
+        data,
+        columns,
+        initialState: {
+          globalFilter: "",
+        },
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getPaginationRowModel: getPaginationRowModel(),
+      });
+
+      const pagination = table.getState().pagination;
+
+      return (
+        <>
+          <Filter<User>
+            onDownloadClick={() => alert("Download")}
+            onSettingsClick={() => alert("Settings")}
+            table={table}
+          />
+          <DataTable table={table} pagination={pagination} />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Sorry, there is currently no data to display.");
+  },
+};
+
+export const WithSubColumns: StoryObj<typeof DataTable> = {
+  render: () => {
+    const data: Array<User> = arrayOfLength(300).map((index) => ({
+      firstname: `Firstname ${index + 1}`,
+      lastname: `Lastname ${index + 1}`,
+      email: `john-doe${index + 1}@example.com`,
+    }));
+
+    const ParentComponent = () => {
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      const columns = useMemo(
+        () => [
+          columnHelper.group({
+            id: "name",
+            header: (group) => (
+              <DataTableHeader
+                text="Name group"
+                colSpan={group.header.colSpan}
+              />
+            ),
+            columns: [
+              columnHelper.accessor("firstname", {
+                id: "Firstname",
+                header: () => <DataTableHeader text="Firstname" />,
+                cell: (props) => (
+                  <DataTableCell>{props.getValue()}</DataTableCell>
+                ),
+              }),
+              columnHelper.accessor("lastname", {
+                id: "Lastname",
+                header: () => <DataTableHeader text="Lastname" />,
+                cell: (props) => (
+                  <DataTableCell>{props.getValue()}</DataTableCell>
+                ),
+              }),
+            ],
+          }),
+          columnHelper.group({
+            id: "other",
+            header: (group) => (
+              <DataTableHeader
+                text="Other group"
+                colSpan={group.header.colSpan}
+                border="left"
+              />
+            ),
+            columns: [
+              columnHelper.accessor("email", {
+                id: "Email",
+                header: () => <DataTableHeader border="left" text="Email" />,
+                cell: (props) => (
+                  <DataTableCell border="left">
+                    {props.getValue()}
+                  </DataTableCell>
+                ),
+              }),
+            ],
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const table = useReactTable({
+        data,
+        columns,
+        initialState: {
+          globalFilter: "",
+        },
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getPaginationRowModel: getPaginationRowModel(),
+      });
+
+      const pagination = table.getState().pagination;
+
+      return (
+        <>
+          <Filter<User> table={table} />
+          <DataTable table={table} pagination={pagination} />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const WithContentOverflow: StoryObj<typeof DataTable> = {
+  render: () => {
+    const data: Array<any> = arrayOfLength(300).map((index) => ({
+      firstname: `Firstnameverylongthatwilloverflowonthescreensqhjdhqskdhkqshdkhqkdshhqsdhkqhshqhdskqjshdjhqsjkhdkqhskjdhqjkshdqkshdkhqsdkjqhdsjkhqsdk ${index + 1}`,
+    }));
+
+    const ParentComponent = () => {
+      const columnHelper = useMemo(() => createColumnHelper<any>(), []);
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            id: "Firstname",
+            header: () => <DataTableHeader text="Firstname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const table = useReactTable({
+        data,
+        columns,
+        initialState: {
+          globalFilter: "",
+        },
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getPaginationRowModel: getPaginationRowModel(),
+      });
+
+      const pagination = table.getState().pagination;
+
+      return (
+        <>
+          <Filter<User> table={table} />
+          <DataTable table={table} pagination={pagination} />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+  decorators: [
+    (Story) => (
+      <div
+        style={{ width: "100%", maxWidth: "700px", border: "1px solid red" }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const CustomExpandUi: StoryObj<typeof DataTable> = {
+  render: () => {
+    const ParentComponent = () => {
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      // Fake data, should come from an API typically
+      const data = useMemo(
+        () => [
+          { firstname: "John", lastname: "Doe", email: "john-doe@example.com" },
+          { firstname: "Jane", lastname: "Doe", email: "jane-doe@example.com" },
+        ],
+        [],
+      );
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            header: () => <DataTableHeader text="Firstname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.display({
+            id: "expander",
+            header: () => <DataTableHeader text="" />,
+            cell: ({ row }) => (
+              <DataTableCell style={{ width: 72 }}>
+                <Button
+                  mode="tertiary"
+                  iconLeft={row.getIsExpanded() ? "expand_less" : "expand_more"} // Show a different icon when the row is expanded
+                  onClick={row.getToggleExpandedHandler()} // Here you plug your button with react-table expanded handler
+                />
+              </DataTableCell>
+            ),
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const table = useReactTable({
+        data,
+        columns,
+        getRowCanExpand: () => true, // tell the table that all rows can be expanded
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getExpandedRowModel: getExpandedRowModel(), // from @tanstack/react-table
+      });
+
+      return (
+        <>
+          <DataTable
+            table={table}
+            // Here you can tell the table how to render an expanded row
+            renderSubComponent={({ row }) => (
+              <pre>
+                <code>{JSON.stringify(row.original, null, 2)}</code>
+              </pre>
+            )}
+          />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const ExpandingSubRows: StoryObj<typeof DataTable> = {
+  render: () => {
+    type UserWithAffiliates = User & { affiliates?: Array<UserWithAffiliates> };
+
+    const ParentComponent = () => {
+      const columnHelper = useMemo(
+        () => createColumnHelper<UserWithAffiliates>(),
+        [],
+      );
+
+      // Fake data, should come from an API typically
+      const data = useMemo(
+        () => [
+          {
+            firstname: "John",
+            lastname: "Doe",
+            email: "john-doe@example.com",
+            affiliates: [
+              {
+                firstname: "Marcel",
+                lastname: "Potter",
+                email: "marcel@example.com",
+              },
+              {
+                firstname: "Willy",
+                lastname: "Potter",
+                email: "willy@example.com",
+              },
+              {
+                firstname: "Michele",
+                lastname: "Potter",
+                email: "michele@example.com",
+              },
+            ],
+          },
+          {
+            firstname: "Jane",
+            lastname: "Doe",
+            email: "jane-doe@example.com",
+            affiliates: [
+              {
+                firstname: "Marcel",
+                lastname: "Potter",
+                email: "marcel@example.com",
+              },
+            ],
+          },
+        ],
+        [],
+      );
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            header: () => <DataTableHeader text="Firstname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.accessor("lastname", {
+            id: "Lastname",
+            header: () => <DataTableHeader text="Lastname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.display({
+            id: "expander",
+            header: () => <DataTableHeader text="" />,
+            cell: ({ row }) => (
+              <DataTableCell style={{ width: 72 }}>
+                {row.getCanExpand() && (
+                  <Button
+                    mode="tertiary"
+                    iconLeft={
+                      // Show a different icon when the row is expanded
+                      row.getIsExpanded() ? "expand_less" : "expand_more"
+                    }
+                    onClick={row.getToggleExpandedHandler()} // Here you plug your button with react-table expanded handler
+                  />
+                )}
+              </DataTableCell>
+            ),
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const table = useReactTable({
+        data,
+        columns,
+        getSubRows: (row) => row.affiliates,
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getExpandedRowModel: getExpandedRowModel(), // from @tanstack/react-table
+      });
+
+      return <DataTable table={table} />;
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const WithoutReactTable: StoryObj<typeof DataTable> = {
+  render: () => {
+    const data = [
+      { firstname: "John", lastname: "Doe", email: "john-doe@example.com" },
+      { firstname: "Jane", lastname: "Doe", email: "jane-doe@example.com" },
+      { firstname: "Jim", lastname: "Beam", email: "jim-beam@example.com" },
+    ];
+
+    return (
+      <DataTableRoot>
+        <thead>
+          <tr>
+            <DataTableHeader text="Firstname" />
+            <DataTableHeader text="Lastname" />
+            <DataTableHeader text="Email" />
+          </tr>
+        </thead>
+        <tbody>
+          {data.map((item) => (
+            <DataTableRow key={item.email}>
+              <DataTableCell>{item.firstname}</DataTableCell>
+              <DataTableCell>{item.lastname}</DataTableCell>
+              <DataTableCell>{item.email}</DataTableCell>
+            </DataTableRow>
+          ))}
+        </tbody>
+      </DataTableRoot>
+    );
+  },
+};
+
+export const Sizes: StoryObj<typeof DataTable> = {
+  render: () => {
+    const ParentComponent = () => {
+      const data: Array<User> = useMemo(
+        () =>
+          arrayOfLength(5).map((index) => ({
+            firstname: `Firstname ${index + 1}`,
+            lastname: `Lastname ${index + 1}`,
+            email: `john-doe${index + 1}@example.com`,
+          })),
+        [],
+      );
+
+      const columnHelper = useMemo(() => createColumnHelper<User>(), []);
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            header: () => <DataTableHeader text="Firstname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.accessor("lastname", {
+            header: () => <DataTableHeader text="Lastname" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          columnHelper.accessor("email", {
+            header: () => <DataTableHeader text="Email" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+        ],
+        [columnHelper],
+      );
+
+      const TableWithSize = ({
+        size,
+      }: {
+        size: "small" | "default" | "large";
+      }) => {
+        const table = useReactTable({
+          data,
+          columns,
+          getCoreRowModel: getCoreRowModel(),
+        });
+
+        return (
+          <div style={{ marginBottom: 32 }}>
+            <h3 style={{ marginBottom: 8 }}>Size: {size}</h3>
+            <DataTable table={table} size={size} />
+          </div>
+        );
+      };
+
+      return (
+        <>
+          <TableWithSize size="small" />
+          <TableWithSize size="default" />
+          <TableWithSize size="large" />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+```mdx
+import { Meta, DocsStory } from "@storybook/addon-docs/blocks";
+
+import * as DataTable from "./DataTable.stories";
+import * as DataTableRoot from "./DataTableRoot/DataTableRoot.stories";
+
+<Meta of={DataTable} />
+
+# DataTable
+
+## Philosophy and usage
+
+Creating a table consists mainly of two parts:
+
+- Creating the UI to display the data
+- Handling the data manipulation (sorting, filtering, paginating, etc.)
+
+The Design System will only provide the UI part, and **you will have to handle the data manipulation yourself**.
+
+But because this is not trivial at all, we encourage you to use a third-party library.
+Our recommendation is to use the excellent headless library [react-table](https://tanstack.com/table/latest).
+And because we know your time is precious, **we provide you with a good starting point to create your custom abstraction using `react-table` that you can copy-paste in your project**.
+
+Feel free to make some adaptations when needed, and to create your own abstraction above this UI component that fits your project's specific constraints and patterns.
+All those examples are here to help you get started, they are not meant to be a one-size-fits-all solution.
+
+## Creating the UI
+
+You will need quite a few components to create a table:
+
+- [DataTableRoot](?path=/docs/components-datatable-datatableroot--docs): very basic root to give base styles to your table
+- [DataTableHeader](?path=/docs/components-datatable-datatableheader--docs): to display the header of your table
+- [DataTableRow](?path=/docs/components-datatable-datatablerow--docs): to display a row of data
+- [DataTableCell](?path=/docs/components-datatable-datatablecell--docs): to display a cell of data
+- [Pagination](?path=/docs/components-pagination--docs): to handle the pagination
+- [Filter](?path=/docs/components-filter--docs): to handle the filtering
+
+If you do not have specific needs, **you can use the `DataTable` component**, which is a composition of the above components.
+This way, you can start creating your table quickly.
+
+But if one day you need to add a specific feature, you can easily replace the `DataTable` component with your own composition (feel free to copy paste the code of the `DataTable` as a starting point).
+
+## Example Integration with react-table
+
+When manipulating data, there is basically two ways to handle it:
+
+- Front-end managed: the data is fetched once and all the data manipulation is done on the front-end
+- Back-end managed: the data is fetched on demand, and the data manipulation is done on the back-end
+
+Most of the time, just go with front-end managed data, it's easier to implement, and it's faster for the user in most cases.
+
+The decision to switch to back-end managed data should be made when there are performance issues.
+Should it be from a too intensive load for the database, a payload so big that the network request becomes very slow, or any other reason.
+
+Below are two examples of how to integrate the `DataTable` component with `react-table` in both cases.
+
+### Front-end managed
+
+When the data is small, it is better to handle the data manipulation on the front-end.
+
+Here is a good starting point for creating a front-end managed table, using `react-table`, ready to copy-paste ! (click on "Show code").
+
+<DocsStory of={DataTable.WithReactTableFrontEndManaged} />
+
+### Back-end managed
+
+Letting the back-end handle the data manipulation requires a bit more work, you will need to handle some parts of the table state manually to properly send the proper parameters to your back-end (like the current page, the sorting, the filtering, etc.).
+
+Here is a good starting point for creating a back-end managed table, using `react-table`, ready to copy-paste ! (click on "Show code").
+
+<DocsStory of={DataTable.WithReactTableBackEndManaged} />
+
+## With sub columns
+
+Here is an example of how to create a table with sub columns, **click on "Show code"**.
+
+Find more explanations on this in the [TanStack Table documentation](https://tanstack.com/table/latest/docs/guide/column-defs) (in the "Grouping" section).
+
+<DocsStory of={DataTable.WithSubColumns} />
+
+## With custom UI to expand in a row
+
+Here is an example of how to create a table with a custom UI to expand in a row, **click on "Show code"**.
+
+Find more explanations on this in the [TanStack Table documentation and examples](https://tanstack.com/table/latest/docs/framework/react/examples/sub-components) ("Sub Components" example, and also the "Expanding guide").
+
+<DocsStory of={DataTable.CustomExpandUi} />
+
+## With sub rows
+
+Here is an example of how to create a table with sub rows, **click on "Show code"**.
+
+You can have any number of sub row depth, and the table will handle the UI for you (the data schema should be recursive).
+
+Find more explanations on this in the [TanStack Table documentation and examples](https://tanstack.com/table/v8/docs/framework/react/examples/expanding) ("Expanding" example, and also the "Expanding guide" docs).
+
+<DocsStory of={DataTable.ExpandingSubRows} />
+
+## Available components in Cells
+
+Our approach to this question is to be flexible.
+
+We do not want to limit you to a set of predefined components to use in your cells, nor do we expose you with tons of props to handle every possible combination of components.
+
+The only recommandation we have is **to only use one component per cell**, ideally (though it's not forbidden).
+
+Here are some examples of components you can use in your cells, click on "Show code" to see how it's done.
+
+<DocsStory of={DataTableRoot.WithSpecificComponents} />
+```