@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,1133 @@
+# Select
+
+## 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/Select/Select.d.ts
+
+## Example usage
+
+Here are the Storybook Stories. The Select component exposes two distinct modes, each with its own stories file.
+
+### Single mode
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, within } from "storybook/test";
+
+import Select from "../Select";
+import SelectItem from "../../SelectItem/SelectItem";
+import Badge from "@packages/components/Badge/Badge";
+
+const meta: Meta<typeof Select> = {
+  component: Select,
+  argTypes: {
+    open: { control: false },
+    helperText: { control: { type: "text" } },
+    label: { control: { type: "text" } },
+    description: { control: { type: "text" } },
+    children: { control: false },
+    mode: { control: false },
+    errorHelperText: { control: { type: "text" } },
+    successHelperText: { control: { type: "text" } },
+    selectedKeys: { control: false },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Select> = {
+  args: {
+    id: "my-select",
+    onChange: fn(),
+    onOpenChange: fn(),
+    label: "[Insert label]",
+    mode: "single",
+    children: (
+      <>
+        <SelectItem text="Option 1" id="1" />
+        <SelectItem text="Option 2" id="2" />
+        <SelectItem text="Option 3" id="3" />
+        <SelectItem text="Option disabled" id="disabled" />
+      </>
+    ),
+    disabledIds: ["disabled"],
+    placeholder: "Please select an option",
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    required: true,
+    description: "[Insert description]",
+    name: "my-select",
+    helperText: "[Insert helper]",
+    helperTextIcon: "help_outline",
+    fullWidth: true,
+    wrapperProps: {
+      style: { width: 220 },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByTitle("Required");
+    await canvas.findByText("[Insert label]");
+    await canvas.findByText("[Insert description]");
+    await canvas.findByText("[Insert helper]");
+  },
+};
+
+export const WithLongOptions: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    children: (
+      <>
+        <SelectItem text="Option 1" id="1" />
+        <SelectItem
+          text={"Very long option that should be truncated"}
+          id="very-long"
+        />
+      </>
+    ),
+    mode: "single",
+    value: "very-long",
+  },
+};
+
+export const Disabled: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+  },
+};
+
+export const Focus: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    value: "2",
+    buttonProps: {
+      ...Playground.args?.buttonProps,
+      // @ts-ignore
+      "data-force-focus": true,
+    },
+  },
+};
+
+export const WithError: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    mode: "single",
+    value: "2",
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    mode: "single",
+    value: "2",
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    mode: "single",
+    value: "2",
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const WithHorizontalOrientation: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    fullWidth: false,
+    orientation: "horizontal",
+    description: undefined,
+    wrapperProps: undefined,
+  },
+};
+
+export const Open: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    mode: "single",
+    value: "2",
+    open: true,
+  },
+};
+
+export const WithTallDropdown: StoryObj<typeof Select> = {
+  args: {
+    ...Open.args,
+    tallDropdown: true,
+    children: (
+      <>
+        {Array.from({ length: 20 }, (_, i) => (
+          <SelectItem key={i + 1} text={`Option ${i + 1}`} id={`${i + 1}`} />
+        ))}
+      </>
+    ),
+  },
+  play: async () => {
+    const listbox = document.querySelector(
+      '[role="listbox"][data-tall="true"]',
+    );
+    await expect(listbox).not.toBeNull();
+  },
+};
+
+export const WithTriggerContentRight: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    wrapperProps: {
+      style: { width: 300 },
+    },
+    triggerContentRight: <Badge value="+3" />,
+  },
+};
+
+export const FullWidth: StoryObj<typeof Select> = {
+  parameters: {
+    ...meta.parameters,
+    layout: "padded",
+  },
+  args: {
+    ...Playground.args,
+    wrapperProps: undefined,
+    buttonProps: undefined,
+    fullWidth: true,
+  },
+};
+```
+
+### Multiple mode
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, within } from "storybook/test";
+import Select from "../Select";
+import SelectItem from "@components/SelectItem/SelectItem";
+import { useState } from "react";
+import { I18nProvider } from "react-aria";
+import Badge from "@packages/components/Badge/Badge";
+
+const meta: Meta<typeof Select> = {
+  component: Select,
+  argTypes: {
+    open: { control: false },
+    helperText: { control: { type: "text" } },
+    label: { control: { type: "text" } },
+    description: { control: { type: "text" } },
+    children: { control: false },
+    mode: { control: false },
+    errorHelperText: { control: { type: "text" } },
+    successHelperText: { control: { type: "text" } },
+    selectedKeys: { control: false },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  render: (args) => {
+    const Form = () => {
+      const [selectedKeys, setSelectedKeys] = useState<Array<string>>(() => {
+        if (args.mode === "multiple" && args.selectedKeys) {
+          return args.selectedKeys;
+        }
+        return [];
+      });
+
+      return (
+        <I18nProvider locale="en-EN">
+          <div style={{ marginBottom: 16 }}>
+            Debug selected values : {[...selectedKeys].join(", ")}
+          </div>
+          <Select
+            {...args}
+            mode="multiple"
+            selectedKeys={selectedKeys}
+            onSelectionChange={setSelectedKeys}
+          >
+            {args.children}
+          </Select>
+        </I18nProvider>
+      );
+    };
+
+    return <Form />;
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Select> = {
+  args: {
+    id: "my-select",
+    onOpenChange: fn(),
+    onSelectionChange: fn(),
+    label: "[Insert label]",
+    mode: "multiple",
+    children: (
+      <>
+        <SelectItem text="Option 1" id="1" />
+        <SelectItem text="Option 2" id="2" />
+        <SelectItem text="Option 3" id="3" />
+        <SelectItem text="Option disabled" id="disabled" />
+      </>
+    ),
+    disabledIds: ["disabled"],
+    placeholder: "Please select an option",
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    required: true,
+    description: "[Insert description]",
+    helperText: "[Insert helper]",
+    helperTextIcon: "help_outline",
+    fullWidth: true,
+    wrapperProps: {
+      style: { width: 220 },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByTitle("Required");
+    await canvas.findByText("[Insert label]");
+    await canvas.findByText("[Insert description]");
+    await canvas.findByText("[Insert helper]");
+  },
+};
+
+export const Disabled: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+  },
+};
+
+export const Focus: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    buttonProps: {
+      ...Playground.args?.buttonProps,
+      // @ts-ignore
+      "data-force-focus": true,
+    },
+  },
+};
+
+export const WithError: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const WithHorizontalOrientation: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    fullWidth: false,
+    orientation: "horizontal",
+    description: undefined,
+    wrapperProps: undefined,
+  },
+};
+
+export const Open: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    open: true,
+  },
+};
+
+export const WithTallDropdown: StoryObj<typeof Select> = {
+  args: {
+    ...Open.args,
+    tallDropdown: true,
+    children: (
+      <>
+        {Array.from({ length: 20 }, (_, i) => (
+          <SelectItem key={i + 1} text={`Option ${i + 1}`} id={`${i + 1}`} />
+        ))}
+      </>
+    ),
+  },
+  play: async () => {
+    const listbox = document.querySelector(
+      '[role="listbox"][data-tall="true"]',
+    );
+    await expect(listbox).not.toBeNull();
+  },
+};
+
+export const WithTriggerContentRight: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    wrapperProps: {
+      style: { width: 300 },
+    },
+    triggerContentRight: <Badge value="+3" />,
+  },
+};
+
+export const FullWidth: StoryObj<typeof Select> = {
+  parameters: {
+    ...meta.parameters,
+    layout: "padded",
+  },
+  args: {
+    ...Playground.args,
+    wrapperProps: undefined,
+    buttonProps: undefined,
+    fullWidth: true,
+  },
+};
+```
+
+## How to test this component
+
+Here are some more advanced stories with more testing coverage and examples that you can read to understand how to test this component.
+
+### Single mode
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { userEvent, within, screen, expect } from "storybook/test";
+
+import Select from "../../Select";
+import SelectItem from "../../../SelectItem/SelectItem";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+import { useState } from "react";
+import { useController, useForm } from "react-hook-form";
+import { Playground } from "../SingleMode.stories";
+
+const meta: Meta<typeof Select> = {
+  component: Select,
+  argTypes: {
+    open: { control: { type: "boolean" } },
+    helperText: { control: { type: "text" } },
+    label: { control: { type: "text" } },
+    description: { control: { type: "text" } },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+};
+export default meta;
+
+export const TestShouldSelectAValue: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Option 2",
+    );
+    await expect((args as any).onChange).toHaveBeenCalledWith("2");
+  },
+};
+
+export const TestWithCustomAriaLabel: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    label: (
+      <div>
+        Something <i>not</i> serializable
+      </div>
+    ),
+    "aria-label": "Select me",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    await user.click(canvas.getByLabelText("Select me"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expect(canvas.getByLabelText("Select me")).toHaveTextContent(
+      "Option 2",
+    );
+    await expect((args as any).onChange).toHaveBeenCalledWith("2");
+  },
+};
+
+export const TestShouldNotSelectADisabledOption: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option disabled", { selector: "span" });
+    await user.click(screen.getByText("Option disabled", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).not.toHaveTextContent(
+      "Option disabled",
+    );
+    await expect((args as any).onChange).not.toHaveBeenCalled();
+  },
+};
+
+export const TestDefaultOpened: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    defaultOpen: true,
+  },
+  play: async () => {
+    await screen.findByText("Option 1", { selector: "span" });
+    await screen.findByText("Option 2", { selector: "span" });
+    await screen.findByText("Option 3", { selector: "span" });
+    await screen.findByText("Option disabled", { selector: "span" });
+  },
+};
+
+export const TestDisabledSelect: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+    value: "2",
+    mode: "single",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Option 2",
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toBeDisabled();
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expectNotPresent(() =>
+      screen.queryByText("Option disabled", { selector: "span" }),
+    );
+  },
+};
+
+export const ExampleControlled: StoryObj<typeof Select> = {
+  render: () => {
+    const Form = () => {
+      const [value, setValue] = useState<string>("");
+
+      return (
+        <>
+          <div>The selected value is : {value}</div>
+          <Select
+            id="my-select"
+            label="[Insert label]"
+            value={value}
+            onChange={setValue}
+            mode="single"
+          >
+            <SelectItem text="Option 1" id="1" />
+            <SelectItem text="Option 2" id="2" />
+            <SelectItem text="Option 3" id="3" />
+          </Select>
+        </>
+      );
+    };
+
+    return <Form />;
+  },
+};
+
+export const TestControlledMode: StoryObj<typeof Select> = {
+  render: ExampleControlled.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]")); // Open the dropdown
+    await screen.findByText("Option 2", { selector: "span" }); // Wait for the option to show up
+    await user.click(screen.getByText("Option 2", { selector: "span" })); // Click on the option
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Option 2",
+    );
+    await canvas.findByText("The selected value is : 2"); // Check that the value is selected (will probably be different depending on the implementation)
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Select> = {
+  render: (args) => {
+    const ReactHookFormExample = () => {
+      const { control } = useForm<any>();
+      const selectField = useController({ control, name: "select" });
+
+      return (
+        <>
+          <div>The selected value is : {selectField.field.value}</div>
+          <Select
+            id="my-select"
+            label="[Insert label]"
+            value={selectField.field.value}
+            onChange={selectField.field.onChange}
+            mode="single"
+          >
+            <SelectItem text="Option 1" id="1" />
+            <SelectItem text="Option 2" id="2" />
+            <SelectItem text="Option 3" id="3" />
+          </Select>
+        </>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+
+export const TestReactHookForm: StoryObj<typeof Select> = {
+  render: ExampleWithReactHookForm.render as any,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Option 2",
+    );
+    await canvas.findByText("The selected value is : 2");
+  },
+};
+```
+
+### Multiple mode
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { userEvent, within, screen, expect } from "storybook/test";
+import Select from "../../Select";
+import SelectItem from "@components/SelectItem/SelectItem";
+import {
+  expectNotPresent,
+  expectPresent,
+} from "@internal/test-utils-storybook/test-utils-storybook";
+import { useController, useForm } from "react-hook-form";
+import baseMeta, { Playground } from "../MultipleMode.stories";
+
+const meta: Meta<typeof Select> = {
+  component: Select,
+  argTypes: {
+    ...baseMeta.argTypes,
+  },
+  parameters: {
+    ...baseMeta.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+  render: baseMeta.render,
+};
+export default meta;
+
+export const TestShouldSelectAValue: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "item selected",
+    );
+    await canvas.findByText("Debug selected values : 2");
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      canvas.queryByText("Option 2", { selector: "span" }),
+    );
+  },
+};
+
+export const TestWithCustomAriaLabel: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    label: (
+      <div>
+        Something <i>not</i> serializable
+      </div>
+    ),
+    "aria-label": "Select me",
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Select me"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expect(canvas.getByLabelText("Select me")).toHaveTextContent("1");
+    await expect(canvas.getByLabelText("Select me")).toHaveTextContent(
+      "item selected",
+    );
+    await canvas.findByText("Debug selected values : 2");
+    await user.click(canvas.getByLabelText("Select me"));
+    await expectNotPresent(() =>
+      canvas.queryByText("Option 2", { selector: "span" }),
+    );
+  },
+};
+
+export const TestShouldDeselectAValue: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    mode: "multiple",
+    selectedKeys: ["2"],
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Please select an option",
+    );
+    await canvas.findByText("Debug selected values :");
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      canvas.queryByText("Option 2", { selector: "span" }),
+    );
+  },
+};
+
+export const TestShouldSelectMultipleValues: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 1", { selector: "span" }));
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await user.click(screen.getByText("Option 3", { selector: "span" }));
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "2",
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "items selected",
+    );
+    await canvas.findByText("Debug selected values : 1, 3");
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      canvas.queryByText("Option 1", { selector: "span" }),
+    );
+  },
+};
+
+export const TestShouldNotSelectADisabledOption: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option disabled", { selector: "span" });
+    await user.click(screen.getByText("Option disabled", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Please select an option",
+    );
+  },
+};
+
+export const TestDefaultOpened: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    defaultOpen: true,
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async () => {
+    await screen.findByText("Option 1", { selector: "span" });
+    await screen.findByText("Option 2", { selector: "span" });
+    await screen.findByText("Option 3", { selector: "span" });
+    await screen.findByText("Option disabled", { selector: "span" });
+  },
+};
+
+export const TestDisabledSelect: StoryObj<typeof Select> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+  },
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "Please select an option",
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toBeDisabled();
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expectNotPresent(() =>
+      screen.queryByText("Option disabled", { selector: "span" }),
+    );
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Select> = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: (args) => {
+    const ReactHookFormExample = () => {
+      const { control } = useForm<any>({
+        defaultValues: {
+          select: [],
+        },
+      });
+      const selectField = useController({ control, name: "select" });
+
+      return (
+        <>
+          <div style={{ marginBottom: 16 }}>
+            Selected values : {selectField.field.value.join(", ")}
+          </div>
+
+          <Select
+            id="my-select"
+            label="[Insert label]"
+            selectedKeys={selectField.field.value}
+            onSelectionChange={selectField.field.onChange}
+            mode="multiple"
+            placeholder="Please select an option"
+          >
+            <SelectItem text="Option 1" id="1" />
+            <SelectItem text="Option 2" id="2" />
+            <SelectItem text="Option 3" id="3" />
+          </Select>
+        </>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+
+export const TestReactHookForm: StoryObj<typeof Select> = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: ExampleWithReactHookForm.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await screen.findByText("Option 2", { selector: "span" });
+    await user.click(screen.getByText("Option 1", { selector: "span" }));
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await user.click(screen.getByText("Option 3", { selector: "span" }));
+    await user.click(screen.getByText("Option 2", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "2",
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveTextContent(
+      "items selected",
+    );
+    await expectPresent(() => canvas.getByText("Selected values : 1, 3"));
+    await user.click(canvas.getByLabelText("[Insert label]"));
+    await expectNotPresent(() =>
+      canvas.queryByText("Option 1", { selector: "span" }),
+    );
+  },
+};
+
+export const ExampleWithSelectAllOption: StoryObj<typeof Select> = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: (args) => {
+    const ReactHookFormExample = () => {
+      const { control } = useForm<any>({
+        defaultValues: {
+          select: [],
+        },
+      });
+      const selectField = useController({ control, name: "select" });
+
+      const options = [
+        { text: "Option 1", id: "1" },
+        { text: "Option 2", id: "2" },
+        { text: "Option 3", id: "3" },
+      ];
+
+      const areAllSelected = selectField.field.value.length === options.length;
+
+      return (
+        <form>
+          <div style={{ marginBottom: 16 }}>
+            Selected values : {JSON.stringify(selectField.field.value)}
+          </div>
+
+          <Select
+            id="my-select"
+            label="Example with a 'Select All' option"
+            selectedKeys={selectField.field.value}
+            onSelectionChange={(selection) => {
+              if (selection.includes("all")) {
+                if (areAllSelected) selectField.field.onChange([]);
+                else selectField.field.onChange(options.map((o) => o.id));
+              } else {
+                selectField.field.onChange(selection);
+              }
+            }}
+            mode="multiple"
+            fullWidth
+          >
+            <SelectItem
+              text="Select All"
+              id="all"
+              isSelected={areAllSelected}
+            />
+            {options.map((option) => (
+              <SelectItem key={option.id} {...option} />
+            ))}
+          </Select>
+        </form>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+```
+
+## 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.
+
+### Single mode
+
+```mdx
+import {
+  Meta,
+  Canvas,
+  Controls,
+  Source,
+  ArgTypes,
+} from "@storybook/addon-docs/blocks";
+
+import * as Select from "./SingleMode.stories";
+import * as SelectTests from "./tests/SingleMode.stories";
+import SelectItem from "../../SelectItem/SelectItem";
+
+<Meta of={Select} />
+
+# Select (single mode)
+
+<Canvas of={Select.Playground} />
+
+## Select props
+
+<Controls
+  of={Select.Playground}
+  exclude={["onSelectionChange", "selectedKeys"]}
+/>
+
+## SelectItem props
+
+This component **should be used as a child of the Select component** and corresponds to its options.
+
+It's just a simple wrapper around DropdownListItem to make it work with the Select.
+
+<ArgTypes of={SelectItem} />
+
+## Basic usage
+
+This is how you generally want to use the `Select` component.
+You can control the value of the dropdown by passing the `value` and `onChange` props.
+
+<Source of={SelectTests.ExampleControlled} type="code" dark />
+
+## Example with react-hook-form
+
+Here is another example of how to use the `Select` component with `react-hook-form`.
+Since the Select component manages its state internally, you have to use `useController` (or the Controller component) from React Hook Form to integrate with it in a controlled mode.
+
+More information about this technical limitation on the [react-hook-form docs](https://www.react-hook-form.com/get-started/#IntegratingwithUIlibraries) and also in [React Aria docs](https://react-spectrum.adobe.com/react-aria/forms.html#react-hook-form)
+
+<Source of={SelectTests.ExampleWithReactHookForm} type="code" dark />
+
+## 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:
+
+<Source of={SelectTests.TestControlledMode} type="code" dark />
+
+## Stories
+
+### With long option
+
+<Canvas of={Select.WithLongOptions} />
+
+### Disabled
+
+<Canvas of={Select.Disabled} />
+
+### Focus
+
+<Canvas of={Select.Focus} />
+
+### With error
+
+<Canvas of={Select.WithError} />
+
+### With success
+
+<Canvas of={Select.WithSuccess} />
+
+### Full width
+
+<Canvas of={Select.FullWidth} />
+```
+
+### Multiple mode
+
+```mdx
+import {
+  Meta,
+  Canvas,
+  Controls,
+  Source,
+  ArgTypes,
+} from "@storybook/addon-docs/blocks";
+
+import * as Select from "./MultipleMode.stories";
+import * as SelectTests from "./tests/MultipleMode.stories";
+import SelectItem from "../../SelectItem/SelectItem";
+
+<Meta of={Select} />
+
+# Select (multiple mode)
+
+<Canvas of={Select.Playground} />
+
+## Select props
+
+<Controls of={Select.Playground} exclude={["value", "onChange", "name"]} />
+
+## SelectItem props
+
+This component **should be used as a child of the Select component** and corresponds to its options.
+
+It's just a simple wrapper around DropdownListItem to make it work with the Select.
+
+<ArgTypes of={SelectItem} />
+
+## Code examples
+
+### Example with react-hook-form
+
+Here is an example of how to use the `Select` component with `react-hook-form`.
+Since the Select component manages its state internally, you have to use `useController` (or the Controller component) from React Hook Form to integrate with it in a controlled mode.
+
+More information about this technical limitation on the [react-hook-form docs](https://www.react-hook-form.com/get-started/#IntegratingwithUIlibraries) and also in [React Aria docs](https://react-spectrum.adobe.com/react-aria/forms.html#react-hook-form)
+
+<Source of={SelectTests.ExampleWithReactHookForm} type="code" dark />
+
+### Example with a "Select all" option
+
+Here is an example of how to use the `Select` component with a "Select all" option.
+
+<Source of={SelectTests.ExampleWithSelectAllOption} type="code" dark />
+
+## Stories
+
+### Disabled
+
+<Canvas of={Select.Disabled} />
+
+### Focus
+
+<Canvas of={Select.Focus} />
+
+### With error
+
+<Canvas of={Select.WithError} />
+
+### With success
+
+<Canvas of={Select.WithSuccess} />
+
+### Full width
+
+<Canvas of={Select.FullWidth} />
+```