@agregio-solutions/design-system 1.102.6 → 2.1.0

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

@@ -23,7 +23,6 @@ const meta: Meta<typeof Combobox> = {
   argTypes: {
     helperText: { control: { type: "text" } },
     label: { control: { type: "text" } },
-    description: { control: { type: "text" } },
     errorHelperText: { control: { type: "text" } },
     successHelperText: { control: { type: "text" } },
     items: { control: false },
@@ -60,7 +59,6 @@ export const Playground: StoryObj<typeof Combobox> = {
     labelIconRight: "help_outline",
     labelIconRightTooltip: "Additional information",
     required: true,
-    description: "[Insert description]",
     helperText: "[Insert helper]",
     helperTextIcon: "help_outline",
     fullWidth: true,
@@ -72,7 +70,6 @@ export const Playground: StoryObj<typeof Combobox> = {
     const canvas = within(canvasElement);
     await canvas.findByTitle("Required");
     await canvas.findByText("[Insert label]");
-    await canvas.findByText("[Insert description]");
     await canvas.findByText("[Insert helper]");
   },
 };
@@ -142,7 +139,6 @@ export const WithWarning: StoryObj<typeof Combobox> = {
 export const Horizontal: StoryObj<typeof Combobox> = {
   args: {
     ...Playground.args,
-    description: undefined,
     orientation: "horizontal",
     wrapperProps: undefined,
     fullWidth: false,
@@ -185,12 +181,13 @@ Here are some more advanced stories with more testing coverage and examples that
 import { Meta, StoryObj } from "@storybook/react-vite";
 
 import Badge from "@packages/components/Badge/Badge";
+import ErrorBoundary from "@packages/internal-components/ErrorBoundary/ErrorBoundary";
 import Combobox from "../Combobox";
 import { Playground } from "../Combobox.stories";
 import { userEvent, within, screen, expect } from "storybook/test";
 import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
 import * as ComboboxStories from "../Combobox.stories";
-import { useEffect, useState } from "react";
+import { ComponentProps, useEffect, useState } from "react";
 import { useController, useForm } from "react-hook-form";
 
 const meta: Meta<typeof Combobox> = {
@@ -543,6 +540,298 @@ export const ExampleWithCustomFiltering: StoryObj<typeof Combobox> = {
 };
 
 export const MultipleSelectionExample: StoryObj<typeof Combobox> = {
+  parameters: {
+    ...meta.parameters,
+    layout: "padded",
+  },
+  render: () => {
+    const data = new Array(10).fill(0).map((_, index) => ({
+      id: `${index + 1}`,
+      name: `Perimeter ${index + 1}`,
+    }));
+
+    const ParentComponent = () => {
+      // List of the selected perimeters ids
+      const [selectedPerimetersIds, setSelectedPerimetersIds] = useState<
+        Array<string>
+      >([]);
+
+      // List of the selected perimeters (derived state)
+      const selectedPerimeters = data.filter((perimeter) =>
+        selectedPerimetersIds.includes(perimeter.id),
+      );
+
+      return (
+        <div style={{ display: "flex", gap: "var(--spacing-xs)" }}>
+          <Combobox
+            id="perimeters-combobox"
+            label="Select perimeters"
+            selectionMode="multiple"
+            selectedKeys={selectedPerimetersIds}
+            onSelectionChange={setSelectedPerimetersIds}
+            defaultItems={data.map((perimeter) => ({
+              text: perimeter.name,
+              id: perimeter.id,
+            }))}
+            // Display the number of selected items inside the field
+            triggerContentRight={
+              <Badge
+                value={selectedPerimetersIds.length}
+                nature="informative"
+              />
+            }
+          />
+
+          <div>
+            <div>Selected perimeters:</div>
+            <ul>
+              {selectedPerimeters.map((perimeter) => (
+                <li key={perimeter.id}>{perimeter.name}</li>
+              ))}
+            </ul>
+          </div>
+        </div>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+const MULTIPLE_LABEL = "Select perimeters";
+
+const MULTIPLE_ITEMS = Array.from({ length: 10 }, (_, index) => ({
+  id: `${index + 1}`,
+  text: `Perimeter ${index + 1}`,
+}));
+
+const MultipleCombobox = (
+  props: Pick<ComponentProps<typeof Combobox>, "disabledIds" | "required">,
+) => {
+  const [selectedKeys, setSelectedKeys] = useState<Array<string>>([]);
+
+  return (
+    <>
+      <Combobox
+        {...props}
+        id="perimeters-combobox"
+        label={MULTIPLE_LABEL}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        defaultItems={MULTIPLE_ITEMS}
+        triggerContentRight={
+          <Badge value={selectedKeys.length} nature="informative" />
+        }
+      />
+      <button type="button" onClick={() => setSelectedKeys([])}>
+        Clear selection
+      </button>
+    </>
+  );
+};
+
+const getMultipleField = (canvasElement: HTMLElement) => {
+  const input = within(canvasElement).getByLabelText(MULTIPLE_LABEL);
+  return { input, field: within(input.parentElement!) };
+};
+
+// The badge is the only text of the field besides the trigger icon
+const expectSelectedCount = async (canvasElement: HTMLElement, count: number) =>
+  expect(
+    getMultipleField(canvasElement).field.getByText(String(count)),
+  ).toBeInTheDocument();
+
+const findOption = async (text: string) =>
+  (await screen.findByText(text, { selector: "span" })).closest(
+    '[role="option"]',
+  );
+
+export const ShouldSelectMultipleValues: StoryObj<typeof Combobox> = {
+  ...MultipleSelectionExample,
+  play: async ({ canvasElement }) => {
+    const user = userEvent.setup({ delay: 50 });
+    const { input, field } = getMultipleField(canvasElement);
+    const clickOption = async (text: string) =>
+      user.click(await screen.findByText(text, { selector: "span" }));
+    const selectedList = within(within(canvasElement).getByRole("list"));
+
+    // The badge renders nothing while no item is selected
+    await expectNotPresent(() => field.queryByText("0"));
+
+    // The dropdown stays open across selections
+    await user.click(field.getByRole("button"));
+
+    await clickOption("Perimeter 1");
+    await expectSelectedCount(canvasElement, 1);
+
+    await clickOption("Perimeter 2");
+    await expectSelectedCount(canvasElement, 2);
+    await expect(await findOption("Perimeter 1")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await expect(await findOption("Perimeter 2")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+
+    // Unselecting brings the count back down
+    await clickOption("Perimeter 1");
+    await expectSelectedCount(canvasElement, 1);
+    await expect(
+      selectedList.queryByText("Perimeter 1"),
+    ).not.toBeInTheDocument();
+    await expect(selectedList.getByText("Perimeter 2")).toBeInTheDocument();
+
+    // Typing filters the options, and the input is cleared after a selection
+    await user.type(input, "10");
+    await clickOption("Perimeter 10");
+    await expect(input).toHaveValue("");
+    await expectSelectedCount(canvasElement, 2);
+    await expect(selectedList.getByText("Perimeter 10")).toBeInTheDocument();
+  },
+};
+
+export const ShouldSelectMultipleValuesWithTheKeyboard: StoryObj<
+  typeof Combobox
+> = {
+  render: () => <MultipleCombobox />,
+  play: async ({ canvasElement }) => {
+    const user = userEvent.setup({ delay: 50 });
+    const { input } = getMultipleField(canvasElement);
+
+    await user.click(input);
+    await user.keyboard("{ArrowDown}");
+    await screen.findByRole("listbox");
+    await user.keyboard("{Enter}");
+    await expectSelectedCount(canvasElement, 1);
+
+    // The dropdown stays open, so the next option can be selected right away
+    await user.keyboard("{ArrowDown}{Enter}");
+    await expectSelectedCount(canvasElement, 2);
+    await expect(await findOption("Perimeter 1")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await expect(await findOption("Perimeter 2")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+
+    await user.keyboard("{Escape}");
+    await expectNotPresent(() => screen.queryByRole("listbox"));
+  },
+};
+
+export const ShouldResetTheMultipleSelectionFromTheParent: StoryObj<
+  typeof Combobox
+> = {
+  render: () => <MultipleCombobox />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const { field } = getMultipleField(canvasElement);
+
+    await user.click(field.getByRole("button"));
+    await user.click(
+      await screen.findByText("Perimeter 1", { selector: "span" }),
+    );
+    await expectSelectedCount(canvasElement, 1);
+
+    // The open dropdown hides the rest of the page from assistive technologies
+    await user.keyboard("{Escape}");
+    await user.click(canvas.getByRole("button", { name: "Clear selection" }));
+    await expectNotPresent(() => field.queryByText("1"));
+
+    await user.click(field.getByRole("button"));
+    await expect(await findOption("Perimeter 1")).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  },
+};
+
+export const ShouldNotSelectADisabledOptionInMultipleMode: StoryObj<
+  typeof Combobox
+> = {
+  render: () => <MultipleCombobox disabledIds={["2"]} />,
+  play: async ({ canvasElement }) => {
+    const user = userEvent.setup({ delay: 50 });
+    const { field } = getMultipleField(canvasElement);
+
+    await user.click(field.getByRole("button"));
+    await user.click(
+      await screen.findByText("Perimeter 2", { selector: "span" }),
+    );
+    await expect(await findOption("Perimeter 2")).toHaveAttribute(
+      "aria-disabled",
+      "true",
+    );
+    await expectNotPresent(() => field.queryByText("1"));
+  },
+};
+
+export const ShouldBeRequiredInMultipleMode: StoryObj<typeof Combobox> = {
+  render: () => <MultipleCombobox required />,
+  play: async ({ canvasElement }) => {
+    await expect(getMultipleField(canvasElement).input).toBeRequired();
+  },
+};
+
+export const ShouldThrowWhenSelectedKeysIsNotAnArray: StoryObj<
+  typeof Combobox
+> = {
+  decorators: [(Story) => <ErrorBoundary>{Story()}</ErrorBoundary>],
+  render: () => (
+    <Combobox
+      id="perimeters-combobox"
+      label={MULTIPLE_LABEL}
+      selectionMode="multiple"
+      // Simulates a loosely typed form value that is not initialized yet
+      selectedKeys={undefined as unknown as Array<string>}
+      onSelectionChange={() => {}}
+      defaultItems={MULTIPLE_ITEMS}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    await within(canvasElement).findByText(
+      'Error: Combobox "perimeters-combobox": `selectedKeys` must be an array, use `[]` when nothing is selected',
+    );
+  },
+};
+
+export const ShouldThrowWhenSelectedKeysIsUsedWithoutMultipleMode: StoryObj<
+  typeof Combobox
+> = {
+  decorators: [(Story) => <ErrorBoundary>{Story()}</ErrorBoundary>],
+  render: () => {
+    // Bypasses the types, as a loosely typed consumer would
+    const looseProps = {
+      selectedKeys: [],
+      onSelectionChange: () => {},
+    } as unknown as ComponentProps<typeof Combobox>;
+    return (
+      <Combobox
+        {...looseProps}
+        id="perimeters-combobox"
+        label={MULTIPLE_LABEL}
+        defaultItems={MULTIPLE_ITEMS}
+      />
+    );
+  },
+  play: async ({ canvasElement }) => {
+    await within(canvasElement).findByText(
+      'Error: Combobox "perimeters-combobox": `selectedKeys` requires `selectionMode="multiple"`',
+    );
+  },
+};
+
+/**
+ * @deprecated Multiple selection faked on top of a single selection.
+ * Use `selectedKeys` and `onSelectionChange` instead (see `MultipleSelectionExample`).
+ * Kept to guarantee the legacy usage keeps working.
+ */
+export const LegacyMultipleSelectionExample: StoryObj<typeof Combobox> = {
   parameters: {
     ...meta.parameters,
     layout: "padded",
@@ -709,7 +998,7 @@ export const ShouldCloseTheDropdownWhenNoOptionMatches: StoryObj<
 
 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
+````mdx
 import {
   Meta,
   Canvas,
@@ -782,16 +1071,78 @@ Interacting with link items navigates to the provided URL and does not update th
 
 ## Multiple selection
 
-Here is an example of how to use the combobox with multiple selection.
-Please note that this is a temporary solution, the React Aria combobox does not support multiple selection yet.
-The implementation details may change in the future.
+Set `selectionMode="multiple"` and control the selection with `selectedKeys` (the selected ids) and `onSelectionChange` (called with all the selected ids).
 
-Because the selection is owned by the consumer, the combobox cannot count the selected items itself.
+- The dropdown stays open after each selection, so the user can pick several items in a row.
+- The input is cleared after each selection, ready for the next search.
+- The selected items are checked in the dropdown: no need to pass `isSelected` on the items.
+
+`selectedKeys` must always be an array: pass `[]` when nothing is selected (for example while a form value is not initialized yet).
+The combobox throws an error otherwise, or when `selectedKeys` is used without `selectionMode="multiple"`.
+
+The combobox does not display the selection itself.
 Use the `triggerContentRight` prop to display a `Badge` with the count inside the field, on the left of the dropdown trigger.
 The element lays out in the flow, so the input shrinks to make room for it whatever its width, and it takes no room at all when the badge renders nothing.
 
 <Source of={ComboboxTests.MultipleSelectionExample} type="code" dark />
 
+### Typing a wrapper component
+
+The props of the multiple selection are exported as `ComboboxMultipleProps`:
+
+```tsx
+import {
+  Combobox,
+  ComboboxMultipleProps,
+} from "@agregio-solutions/design-system";
+
+type PerimetersComboboxProps = Omit<ComboboxMultipleProps, "label">;
+
+const PerimetersCombobox = (props: PerimetersComboboxProps) => (
+  <Combobox {...props} label="Perimeters" />
+);
+```
+
+`ComponentProps<typeof Combobox>` still returns the props of the single selection (with `value` and `onChange`), so the existing wrappers keep compiling unchanged.
+
+### Migrating from the deprecated multiple selection
+
+Before React Aria supported multiple selection, it was faked on top of a single selection: `value=""` was forced, `onChange` received the clicked id and the consumer toggled it in its own list, then marked the items with `isSelected`.
+
+This workaround is **deprecated**. It still works and compiles, but your editor strikes `<Combobox>` through when it is used this way.
+It will be removed in a future major version. To migrate:
+
+- Replace `value=""` with `selectedKeys={selectedIds}`.
+- Replace the `onChange` toggling logic with `onSelectionChange={setSelectedIds}`.
+- Remove `isSelected` from the items.
+
+```tsx
+// Before (deprecated)
+<Combobox
+  selectionMode="multiple"
+  value=""
+  onChange={(id) =>
+    setSelectedIds(
+      selectedIds.includes(id)
+        ? selectedIds.filter((selectedId) => selectedId !== id)
+        : [...selectedIds, id],
+    )
+  }
+  defaultItems={items.map((item) => ({
+    ...item,
+    isSelected: selectedIds.includes(item.id),
+  }))}
+/>
+
+// After
+<Combobox
+  selectionMode="multiple"
+  selectedKeys={selectedIds}
+  onSelectionChange={setSelectedIds}
+  defaultItems={items}
+/>
+```
+
 ## How to test this component?
 
 Here is a code snippet that you can use as an example to know how to test this component with react testing library:
@@ -805,4 +1156,4 @@ Here is a code snippet that you can use as an example to know how to test this c
 <Controls of={Combobox.Playground} />
 
 <Stories />
-```
+````

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

@@ -1,6 +1,8 @@
 import { default as React } from 'react';
-import { PaginationState, Row, Table } from '@tanstack/react-table';
-type Props<TData> = {
+import { PaginationState, ReactTable, Row, RowData, Table_RowPagination, TableFeatures, TableState_All } from '@tanstack/react-table';
+/** Requires `rowPaginationFeature`. */
+type OptionalPaginationApi<TFeatures extends TableFeatures, TData extends RowData> = Partial<Pick<Table_RowPagination<TFeatures, TData>, "getRowCount" | "setPageIndex" | "setPageSize">>;
+type Props<TFeatures extends TableFeatures, TData extends RowData> = {
     /**
      * The CSS className for the element.
      */
@@ -10,18 +12,25 @@ type Props<TData> = {
      */
     style?: React.CSSProperties;
     /**
-     * The table instance given by `react-table`.
+     * The table instance given by `react-table` `useTable`.
+     * The pagination and filtering APIs are read when the table registers their
+     * feature, and ignored otherwise.
+     * Call `useTable` without a state selector: `table.state` only holds the
+     * slices the selector keeps, and this component reads the filtering ones.
      */
-    table: Table<TData>;
+    table: ReactTable<TFeatures, TData> & OptionalPaginationApi<TFeatures, TData> & {
+        state: TableState_All;
+    };
     /**
      * The pagination state given by `react-table`.
+     * Requires the table to register `rowPaginationFeature`.
      */
     pagination?: PaginationState;
     /**
      * The function to render the sub component custom UI.
      */
     renderSubComponent?: (props: {
-        row: Row<TData>;
+        row: Row<TFeatures, TData>;
     }) => React.ReactNode;
     /**
      * The list of available page sizes.
@@ -33,5 +42,5 @@ type Props<TData> = {
      */
     size?: "small" | "default" | "large";
 };
-export default function DataTable<TData>({ table, pagination, renderSubComponent, itemsPerPageOptions, size, ...divProps }: Props<TData>): React.JSX.Element;
+export default function DataTable<TFeatures extends TableFeatures, TData extends RowData>({ table, pagination, renderSubComponent, itemsPerPageOptions, size, ...divProps }: Props<TFeatures, TData>): React.JSX.Element;
 export {};

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

@@ -1,10 +1,5 @@
 import { default as React } from 'react';
 export type Props = {
-    /**
-     * The level of the row, mainly to change its background color. Defaults to "root".
-     * @deprecated sub rows styling are now handled internally
-     */
-    depth?: number;
     /**
      * The CSS className for the element.
      */
@@ -15,4 +10,4 @@ export type Props = {
     style?: React.CSSProperties;
     children?: React.ReactNode;
 };
-export default function DataTableRow({ children, depth, ...otherProps }: Props): React.JSX.Element;
+export default function DataTableRow({ children, ...otherProps }: Props): React.JSX.Element;