@agregio-solutions/design-system 2.1.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

@@ -45,13 +45,14 @@ import DataTableCell from "@packages/components/DataTable/DataTableCell/DataTabl
 import DataTable from "@packages/components/DataTable/DataTable";
 import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
 import Checkbox from "../Checkbox/Checkbox";
-import Radio from "../Radio/Radio";
+import RadioGroup from "../RadioGroup/RadioGroup";
+import RadioGroupItem from "../RadioGroupItem/RadioGroupItem";
 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 { 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";
@@ -160,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`,
@@ -171,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
@@ -213,18 +222,17 @@ export const WithReactTableFrontEndManaged: StoryObj<typeof DataTable> = {
               filterFn: "equals",
               meta: {
                 FilterInDrawer: ({ column }) => (
-                  <div>
-                    <b>Filter by day:</b>
-
+                  <RadioGroup
+                    label="Filter by day"
+                    value={
+                      (column.getFilterValue() as string | undefined) ?? null
+                    }
+                    onChange={(day) => column.setFilterValue(day)}
+                  >
                     {DAYS.map((day) => (
-                      <Radio
-                        label={day}
-                        key={day}
-                        checked={column.getFilterValue() === day}
-                        onChange={() => column.setFilterValue(day)}
-                      />
+                      <RadioGroupItem label={day} key={day} value={day} />
                     ))}
-                  </div>
+                  </RadioGroup>
                 ),
               } satisfies TypeTableColumnWithFilter<
                 typeof clientFeatures,
@@ -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/dist/packages/components/PageLayout/doc.md

@@ -51,7 +51,8 @@ import {
 } from "@tanstack/react-table";
 import DataTableHeader from "../DataTable/DataTableHeader/DataTableHeader";
 import DataTableCell from "../DataTable/DataTableCell/DataTableCell";
-import Radio from "../Radio/Radio";
+import RadioGroup from "../RadioGroup/RadioGroup";
+import RadioGroupItem from "../RadioGroupItem/RadioGroupItem";
 import Filter, { TypeTableColumnWithFilter } from "../Filter/Filter";
 import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
 import Checkbox from "../Checkbox/Checkbox";
@@ -307,18 +308,17 @@ export const PageLayoutWithDataTable: Story = {
               filterFn: "equals",
               meta: {
                 FilterInDrawer: ({ column }) => (
-                  <div>
-                    <b>Filter by day:</b>
-
+                  <RadioGroup
+                    label="Filter by day"
+                    value={
+                      (column.getFilterValue() as string | undefined) ?? null
+                    }
+                    onChange={(day) => column.setFilterValue(day)}
+                  >
                     {DAYS.map((day) => (
-                      <Radio
-                        label={day}
-                        key={day}
-                        checked={column.getFilterValue() === day}
-                        onChange={() => column.setFilterValue(day)}
-                      />
+                      <RadioGroupItem label={day} key={day} value={day} />
                     ))}
-                  </div>
+                  </RadioGroup>
                 ),
               } satisfies TypeTableColumnWithFilter<
                 typeof tableFeaturesSet,

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

@@ -1,4 +1,7 @@
 import { default as React } from 'react';
+/**
+ * @deprecated Use `RadioGroup` with `RadioGroupItem` instead.
+ */
 export type Props = Omit<React.HTMLProps<HTMLInputElement>, "label" | "type"> & {
     /**
      * The text to display next to the radio button.
@@ -13,5 +16,9 @@ export type Props = Omit<React.HTMLProps<HTMLInputElement>, "label" | "type"> &
      */
     wrapperProps?: React.HTMLProps<HTMLDivElement>;
 };
+/**
+ * @deprecated Use `RadioGroup` with `RadioGroupItem` instead: it names the group,
+ * handles keyboard navigation and displays helper and error texts.
+ */
 declare const Radio: React.ForwardRefExoticComponent<Omit<Props, "ref"> & React.RefAttributes<HTMLInputElement>>;
 export default Radio;

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

@@ -350,6 +350,10 @@ import * as RadioTests from "./tests/Radio.stories";
 
 # Radio
 
+> **Deprecated** — use `RadioGroup` with `RadioGroupItem` instead. It names the group for
+> assistive technologies, handles keyboard navigation (one tab stop, arrow keys) and displays
+> helper and error texts. See the "Migrating from `Radio`" section of the `RadioGroup` docs.
+
 Use this component exactly like an `<input type="radio">` but with an added `label` prop.
 
 <Canvas of={Radio.WithLabel} />

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

@@ -0,0 +1,92 @@
+import { default as React } from 'react';
+import { Props as LabelProps } from '../Label/Label';
+import { Props as FormGroupWrapperProps } from '../../internal-components/FormGroupWrapper/FormGroupWrapper';
+export type Props = {
+    /**
+     * The `RadioGroupItem`s to display in the group.
+     */
+    children: React.ReactNode;
+    /**
+     * The value of the selected radio (controlled). `null` means no radio is selected.
+     */
+    value?: string | null;
+    /**
+     * The value of the radio selected on first render (uncontrolled).
+     */
+    defaultValue?: string;
+    /**
+     * Handler that is called with the value of the newly selected radio.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The name of the radios, used when submitting an HTML form.
+     */
+    name?: string;
+    /**
+     * Whether all the radios of the group are disabled.
+     */
+    isDisabled?: boolean;
+    /**
+     * Whether the radios can be focused but not changed by the user.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Layout of the radios inside the group.
+     * @default "vertical"
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * Accessible name of the group, required when `label` is not a string.
+     */
+    "aria-label"?: string;
+    /**
+     * Props to pass to the wrapper div (for example, `style` or `className`).
+     */
+    wrapperProps?: React.HTMLProps<HTMLDivElement>;
+} & Pick<LabelProps, "label" | "labelIconRight" | "labelIconRightTooltip" | "required"> & Pick<FormGroupWrapperProps, "helperText" | "helperTextIcon" | "errorHelperText" | "errorHelperTextIcon" | "successHelperText" | "successHelperTextIcon" | "warningHelperText" | "warningHelperTextIcon" | "orientation" | "className" | "style">;
+declare const RadioGroup: React.ForwardRefExoticComponent<{
+    /**
+     * The `RadioGroupItem`s to display in the group.
+     */
+    children: React.ReactNode;
+    /**
+     * The value of the selected radio (controlled). `null` means no radio is selected.
+     */
+    value?: string | null;
+    /**
+     * The value of the radio selected on first render (uncontrolled).
+     */
+    defaultValue?: string;
+    /**
+     * Handler that is called with the value of the newly selected radio.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The name of the radios, used when submitting an HTML form.
+     */
+    name?: string;
+    /**
+     * Whether all the radios of the group are disabled.
+     */
+    isDisabled?: boolean;
+    /**
+     * Whether the radios can be focused but not changed by the user.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Layout of the radios inside the group.
+     * @default "vertical"
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * Accessible name of the group, required when `label` is not a string.
+     */
+    "aria-label"?: string;
+    /**
+     * Props to pass to the wrapper div (for example, `style` or `className`).
+     */
+    wrapperProps?: React.HTMLProps<HTMLDivElement>;
+} & Pick<LabelProps, "label" | "required" | "labelIconRight" | "labelIconRightTooltip"> & Pick<FormGroupWrapperProps, "className" | "style" | "orientation" | "helperText" | "helperTextIcon" | "errorHelperText" | "errorHelperTextIcon" | "successHelperText" | "successHelperTextIcon" | "warningHelperText" | "warningHelperTextIcon"> & React.RefAttributes<{
+    focus: (options?: FocusOptions) => void;
+}>>;
+export default RadioGroup;