@agregio-solutions/design-system 2.2.0 → 2.3.0

package/dist/packages/components/DataTable/DataTable.d.ts

@@ -41,6 +41,15 @@ type Props<TFeatures extends TableFeatures, TData extends RowData> = {
      * @default "default".
      */
     size?: "small" | "default" | "large";
+    /**
+     * Whether the table is loading its data for the first time.
+     * Renders skeleton rows under the real header, as many as the page size
+     * (`pagination.pageSize`, else `table.state.pagination.pageSize`, else 10).
+     * Map it to react-query `isLoading` (first load, no data yet), not `isFetching`:
+     * on refetch, keep the current rows displayed (e.g. with `placeholderData: keepPreviousData`).
+     * @default false
+     */
+    isLoading?: boolean;
 };
-export default function DataTable<TFeatures extends TableFeatures, TData extends RowData>({ table, pagination, renderSubComponent, itemsPerPageOptions, size, ...divProps }: Props<TFeatures, TData>): React.JSX.Element;
+export default function DataTable<TFeatures extends TableFeatures, TData extends RowData>({ table, pagination, renderSubComponent, itemsPerPageOptions, size, isLoading, ...divProps }: Props<TFeatures, TData>): React.JSX.Element;
 export {};

package/dist/packages/components/DataTable/DataTableRoot/DataTableRoot.d.ts

@@ -8,6 +8,10 @@ export type Props = {
      * The inline style for the element.
      */
     style?: React.CSSProperties;
+    /**
+     * Whether the table content is loading.
+     */
+    "aria-busy"?: boolean;
     children: React.ReactNode;
 };
 export default function DataTableRoot({ children, ...otherProps }: Props): React.JSX.Element;

package/dist/packages/components/DataTable/DataTableSkeletonRows/DataTableSkeletonRows.d.ts

@@ -0,0 +1,11 @@
+export type Props = {
+    /**
+     * The number of skeleton rows to render.
+     */
+    rowCount: number;
+    /**
+     * The number of skeleton cells to render in each row.
+     */
+    columnCount: number;
+};
+export default function DataTableSkeletonRows({ rowCount, columnCount, }: Props): import('react').JSX.Element;

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

@@ -52,7 +52,7 @@ 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 { expect, within } from "storybook/test";
 import { someTime } from "@internal/test-utils-storybook/test-utils-storybook";
 import DataTableRoot from "./DataTableRoot/DataTableRoot";
 import DataTableRow from "./DataTableRow/DataTableRow";
@@ -161,9 +161,13 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
         [],
       );
 
-      const data: Array<User> = useMemo(
-        () =>
-          arrayOfLength(300).map((index) => ({
+      // Fetch the whole dataset once: filtering, sorting and pagination happen client-side
+      // `isLoading` is only true on the first load, while there is no data yet
+      const { data, isLoading } = useQuery({
+        queryKey: ["all-users"],
+        queryFn: async (): Promise<Array<User>> => {
+          await someTime(100); // Your API call goes here
+          return arrayOfLength(300).map((index) => ({
             firstname: `Firstname ${index + 1}`,
             lastname: `Lastname ${index + 1}`,
             email: `john-doe${index + 1}@example.com`,
@@ -172,9 +176,13 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
             day: DAYS[index % DAYS.length],
             organization: ORGANIZATIONS[index % ORGANIZATIONS.length],
             isActive: index % 2 === 0,
-          })),
-        [DAYS, FOODS, ORGANIZATIONS],
-      );
+          }));
+        },
+      });
+
+      // The table data needs a stable reference: an inline `data ?? []` would create a new array on every render while loading
+      // ⚠ This should be memoized!
+      const users = useMemo(() => data ?? [], [data]);
 
       // Here starts the interesting stuff: columns definitions.
       // All the features of the filters comes from those columns definitions
@@ -347,7 +355,7 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
       // And here we define the table as usual
       const table = useTable({
         features: clientFeatures,
-        data,
+        data: users,
         columns,
         initialState: {
           globalFilter: "", // Add this to show the global filter (aka the Search bar)
@@ -400,6 +408,7 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
             table={table}
             pagination={pagination}
             itemsPerPageOptions={[12, 24, 36, 48, 60]} // Add this to customize the page size options available in the select
+            isLoading={isLoading}
           />
         </>
       );
@@ -407,6 +416,10 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
 
     return <ParentComponent />;
   },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Firstname 1");
+  },
 };
 
 type User = {
@@ -485,7 +498,8 @@ export const WithReactTableBackEndManaged: StoryObj<typeof DataTable> = {
       );
 
       // Fetch data using the table state (filters, pagination, sorting, etc.)
-      const { data } = useQuery({
+      // `isLoading` is only true on the first load: on refetch, `keepPreviousData` keeps the current rows displayed
+      const { data, isLoading } = useQuery({
         placeholderData: keepPreviousData, // from @tanstack/react-query, recommended to use it in this scenario
         queryKey: ["users", pagination, sorting, columnFilters],
         queryFn: () =>
@@ -499,6 +513,10 @@ export const WithReactTableBackEndManaged: StoryObj<typeof DataTable> = {
           }),
       });
 
+      // The table data needs a stable reference: an inline `data?.data ?? []` would create a new array on every render while loading
+      // ⚠ This should be memoized!
+      const users = useMemo(() => data?.data ?? [], [data]);
+
       // You will need to create a column helper, typed with the registered features
       // ⚠ This should be memoized!
       const columnHelper = useMemo(
@@ -595,7 +613,7 @@ export const WithReactTableBackEndManaged: StoryObj<typeof DataTable> = {
       // Instantiate the table with @tanstack/react-table
       const table = useTable({
         features: serverFeatures,
-        data: data?.data || [],
+        data: users,
         columns,
         manualPagination: true,
         manualSorting: true,
@@ -615,7 +633,11 @@ export const WithReactTableBackEndManaged: StoryObj<typeof DataTable> = {
       return (
         <>
           <Filter table={table} />
-          <DataTable table={table} pagination={pagination} />
+          <DataTable
+            table={table}
+            pagination={pagination}
+            isLoading={isLoading}
+          />
         </>
       );
     }
@@ -677,6 +699,85 @@ export const Empty: StoryObj<typeof DataTable> = {
   },
 };
 
+export const Loading: StoryObj<typeof DataTable> = {
+  render: () => {
+    const ParentComponent = () => {
+      const columnHelper = useMemo(
+        () => createColumnHelper<typeof clientFeatures, User>(),
+        [],
+      );
+
+      const data = useMemo(() => [], []);
+
+      const columns = useMemo(
+        () =>
+          columnHelper.columns([
+            columnHelper.accessor("firstname", {
+              header: ({ header }) => (
+                <DataTableHeader
+                  onSortClick={header.column.getToggleSortingHandler()}
+                  sortDirection={header.column.getIsSorted() || "none"}
+                  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 table = useTable({
+        features: clientFeatures,
+        data,
+        columns,
+        initialState: {
+          pagination: { pageIndex: 0, pageSize: 10 },
+        },
+      });
+
+      const pagination = table.state.pagination;
+
+      return <DataTable table={table} pagination={pagination} isLoading />;
+    };
+
+    return <ParentComponent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByRole("table")).toHaveAttribute(
+      "aria-busy",
+      "true",
+    );
+    await expect(canvas.getAllByRole("columnheader")).toHaveLength(3);
+    // 1 skeleton row per item of the page (pageSize: 10)
+    await expect(
+      canvasElement.querySelectorAll(
+        '[data-design-system-component="DataTableSkeletonRows"]',
+      ),
+    ).toHaveLength(10);
+    // Skeleton rows are hidden from assistive technologies: only the header row is exposed
+    await expect(canvas.getAllByRole("row")).toHaveLength(1);
+    await expect(
+      canvas.queryByText("Sorry, there is currently no data to display."),
+    ).not.toBeInTheDocument();
+  },
+};
+
 export const WithSubColumns: StoryObj<typeof DataTable> = {
   render: () => {
     const data: Array<User> = arrayOfLength(300).map((index) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agregio-solutions/design-system",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "React Component library and Storybook that is part of the Design System for Agregio Solutions",
   "type": "module",
   "module": "dist/design-system.js",