@agregio-solutions/design-system 1.91.0 → 1.92.0

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

@@ -0,0 +1,680 @@
+# Combobox
+
+## 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/Combobox/Combobox.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, screen, userEvent, within } from "storybook/test";
+
+import Combobox from "./Combobox";
+
+const meta: Meta<typeof Combobox> = {
+  component: 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 },
+    defaultInputValue: { control: false },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Combobox> = {
+  args: {
+    id: "my-select",
+    onChange: fn(),
+    label: "[Insert label]",
+    defaultItems: [
+      { text: "Option 1", id: "1" },
+      { text: "Option 2", id: "2" },
+      { text: "Option 3", id: "3" },
+      { text: "Option 4", id: "4" },
+      { text: "Option 5", id: "5" },
+      { text: "Option 6", id: "6" },
+      { text: "Option 7", id: "7" },
+      { text: "Option 8", id: "8" },
+      { text: "Option 9", id: "9" },
+      { 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 WithLongOptions: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    items: [
+      { text: "Option 1", id: "1" },
+      {
+        text: "Very long option that should be truncated",
+        id: "very-long",
+      },
+    ],
+    value: "very-long",
+  },
+};
+
+export const Disabled: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+  },
+};
+
+export const Focus: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    value: "2",
+    inputProps: {
+      ...Playground.args?.inputProps,
+      // @ts-ignore
+      "data-force-focus": true,
+    },
+  },
+};
+
+export const WithError: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    value: "2",
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    value: "2",
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const Horizontal: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    description: undefined,
+    orientation: "horizontal",
+    wrapperProps: undefined,
+    fullWidth: false,
+  },
+};
+
+export const WithTallDropdown: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    tallDropdown: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await user.type(canvas.getByLabelText("[Insert label]"), "Option");
+    const listbox = await screen.findByRole("listbox");
+    await expect(listbox).toHaveAttribute("data-tall", "true");
+  },
+};
+
+export const FullWidth: StoryObj<typeof Combobox> = {
+  parameters: {
+    ...meta.parameters,
+    layout: "padded",
+  },
+  args: {
+    ...Playground.args,
+    wrapperProps: undefined,
+    inputProps: 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.
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+
+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 { useController, useForm } from "react-hook-form";
+
+const meta: Meta<typeof Combobox> = {
+  component: Combobox,
+  ...ComboboxStories.default,
+  parameters: {
+    ...ComboboxStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ShouldSelectAValue: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "9");
+    await screen.findByText("Option 9", { selector: "span" });
+    await user.click(screen.getByText("Option 9", { selector: "span" }));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveValue(
+      "Option 9",
+    );
+    await expect((args as any).onChange).toHaveBeenCalledWith("9");
+  },
+};
+
+export const TestWithCustomAriaLabel: StoryObj<typeof Combobox> = {
+  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.type(canvas.getByLabelText("Select me"), "3");
+    await screen.findByText("Option 3", { selector: "span" });
+    await user.click(screen.getByText("Option 3", { selector: "span" }));
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+    await expect(canvas.getByLabelText("Select me")).toHaveValue("Option 3");
+    await expect((args as any).onChange).toHaveBeenCalledWith("3");
+  },
+};
+
+export const ShouldDeselectAValue: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "Option 3");
+    await screen.findByText("Option 3", { selector: "span" });
+    await user.click(screen.getByText("Option 3", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveValue(
+      "Option 3",
+    );
+    await expect((args as any).onChange).toHaveBeenCalledWith("3");
+    await user.clear(canvas.getByLabelText("[Insert label]"));
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveValue("");
+    await expect((args as any).onChange).toHaveBeenCalledWith("");
+  },
+};
+
+export const ShouldNotSelectADisabledOption: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "disabled");
+    await screen.findByText("Option disabled", { selector: "span" });
+    await user.click(screen.getByText("Option disabled", { selector: "span" }));
+    await expect(canvas.getByLabelText("[Insert label]")).not.toHaveValue(
+      "Option disabled",
+    );
+    await expect((args as any).onChange).not.toHaveBeenCalled();
+  },
+};
+
+export const TestDisabledCombobox: StoryObj<typeof Combobox> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("[Insert label]")).toBeDisabled();
+    await user.type(canvas.getByLabelText("[Insert label]"), "1");
+    await expectNotPresent(() =>
+      screen.queryByText("Option 1", { selector: "span" }),
+    );
+  },
+};
+
+export const ExampleControlledValue: StoryObj<typeof Combobox> = {
+  render: () => {
+    const Form = () => {
+      const [value, setValue] = useState<string>("");
+
+      return (
+        <>
+          <div>The selected value is : {value}</div>
+          <Combobox
+            id="my-combobox"
+            label="[Insert label]"
+            value={value}
+            onChange={setValue}
+            defaultItems={Array.from({ length: 30 }, (_, index) => ({
+              text: `Option ${index + 1}`,
+              id: `${index + 1}`,
+            }))}
+          />
+        </>
+      );
+    };
+
+    return <Form />;
+  },
+};
+
+export const TestControlleValuedMode: StoryObj<typeof Combobox> = {
+  render: ExampleControlledValue.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "2");
+    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]")).toHaveValue(
+      "Option 2",
+    );
+    await canvas.findByText("The selected value is : 2");
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Combobox> = {
+  render: (args) => {
+    const ReactHookFormExample = () => {
+      const { control } = useForm<any>();
+      const comboboxField = useController({ control, name: "combobox" });
+
+      return (
+        <>
+          <div>The selected value is : {comboboxField.field.value}</div>
+          <Combobox
+            id="my-combobox"
+            label="[Insert label]"
+            value={comboboxField.field.value}
+            onChange={comboboxField.field.onChange}
+            defaultItems={[
+              { text: "Option 1", id: "1" },
+              { text: "Option 2", id: "2" },
+              { text: "Option 3", id: "3" },
+            ]}
+          />
+        </>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+
+export const TestReactHookForm: StoryObj<typeof Combobox> = {
+  render: ExampleWithReactHookForm.render as any,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "2");
+    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]")).toHaveValue(
+      "Option 2",
+    );
+    await canvas.findByText("The selected value is : 2");
+  },
+};
+
+export const ExampleBackendManaged: StoryObj<typeof Combobox> = {
+  render: () => {
+    type Item = {
+      id: string;
+      text: string;
+    };
+
+    const ALL_ITEMS: Item[] = Array.from({ length: 100 }, (_, index) => {
+      return {
+        id: `${index + 1}`,
+        text: `Option ${index + 1}`,
+      };
+    });
+
+    const fakeApi = (search: string): Promise<Item[]> => {
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve(
+            ALL_ITEMS.filter((item) => item.text.includes(search)).slice(0, 5),
+          );
+        }, 300);
+      });
+    };
+
+    const Form = () => {
+      const [value, setValue] = useState<string>("");
+      const [inputValue, setInputValue] = useState<string>("");
+      const [options, setOptions] = useState<Item[]>([]);
+
+      useEffect(() => {
+        fakeApi(inputValue).then((options) => setOptions(options));
+      }, [inputValue]);
+
+      return (
+        <>
+          <div>The selected value is : {value}</div>
+          <Combobox
+            id="my-combobox"
+            label="[Insert label]"
+            value={value}
+            onChange={setValue}
+            inputValue={inputValue}
+            onInputChange={setInputValue}
+            items={options} // Please note we now use `items` instead of `defaultItems`. This tells Combobox to not filter the items internally.
+          />
+        </>
+      );
+    };
+
+    return <Form />;
+  },
+};
+
+export const TestExampleBackendManaged: StoryObj<typeof Combobox> = {
+  render: ExampleBackendManaged.render as any,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.type(canvas.getByLabelText("[Insert label]"), "Option 99");
+    await screen.findByText("Option 99", { selector: "span" }); // Wait for the option to show up (can be async data fetching)
+    await user.click(screen.getByText("Option 99", { selector: "span" })); // Click on the option
+    await canvas.findByText("The selected value is : 99"); // Check that the value is selected (will probably be different depending on the implementation)
+  },
+};
+
+export const ExampleWithLinks: StoryObj<typeof Combobox> = {
+  render: () => {
+    const Form = () => {
+      const [value, setValue] = useState<string>("");
+
+      return (
+        <>
+          <div>The selected value is : {value}</div>
+          <Combobox
+            id="my-combobox"
+            label="[Insert label]"
+            value={value}
+            onChange={setValue}
+            defaultItems={[
+              { text: "Option 1", id: "1" },
+              { text: "Google", id: "google", href: "https://google.com" },
+            ]}
+          />
+        </>
+      );
+    };
+
+    return <Form />;
+  },
+};
+
+export const ExampleWithCustomFiltering: StoryObj<typeof Combobox> = {
+  render: () => {
+    const options = [
+      { id: "1", text: "fake@email.com" },
+      { id: "2", text: "anotherfake@email.com" },
+      { id: "3", text: "bob@email.com" },
+      { id: "4", text: "joe@email.com" },
+      { id: "5", text: "yourEmail@email.com" },
+      { id: "6", text: "valid@email.com" },
+    ];
+
+    const Form = () => {
+      const [value, setValue] = useState<string>("");
+
+      return (
+        <>
+          <div>The selected value is : {value}</div>
+          <Combobox
+            id="my-combobox"
+            label="[Insert label]"
+            value={value}
+            onChange={setValue}
+            defaultItems={options}
+            defaultFilter={(itemText, filterValue) =>
+              // Prefer a `startsWith` filter instead of the default `includes`
+              itemText.toLowerCase().startsWith(filterValue.toLowerCase())
+            }
+          />
+        </>
+      );
+    };
+
+    return <Form />;
+  },
+};
+
+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"
+            value="" // Need to force the value as we "fake" the normal combobox behavior
+            selectionMode="multiple" // Enable the checkboxes on the select items
+            onChange={(id) => {
+              // if element is already selected, remove it
+              if (selectedPerimetersIds.includes(id)) {
+                setSelectedPerimetersIds(
+                  selectedPerimetersIds.filter(
+                    (perimeterId) => perimeterId !== id,
+                  ),
+                );
+              } else {
+                // If the element is not selected, add it to the list
+                setSelectedPerimetersIds([...selectedPerimetersIds, id]);
+              }
+            }}
+            defaultItems={data.map((perimeter) => ({
+              text: perimeter.name,
+              id: perimeter.id,
+              isSelected: selectedPerimetersIds.includes(perimeter.id),
+            }))}
+          />
+
+          <div>
+            <div>Selected perimeters:</div>
+            <ul>
+              {selectedPerimeters.map((perimeter) => (
+                <li key={perimeter.id}>{perimeter.name}</li>
+              ))}
+            </ul>
+          </div>
+        </div>
+      );
+    };
+    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,
+  Canvas,
+  Controls,
+  Source,
+  ArgTypes,
+  Stories,
+} from "@storybook/addon-docs/blocks";
+
+import * as Combobox from "./Combobox.stories";
+import * as ComboboxTests from "./tests/Combobox.stories";
+
+<Meta of={Combobox} />
+
+# Combobox
+
+A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.
+
+A combo box can be built using the `<datalist>` HTML element, but this is very limited in functionality and difficult to style.
+ComboBox helps achieve accessible combo box and autocomplete components that can be styled as needed.
+
+- **Flexible** – Support for selecting pre-defined values, controlled and uncontrolled state, custom filter functions, async loading, disabled items.
+- **Keyboard navigation** – ComboBox can be opened and navigated using the arrow keys, along with page up/down, home/end, etc. The list of options is filtered while typing into the input, and items can be selected with the enter key.
+- **Accessible** – Follows the ARIA combobox pattern. Custom localized announcements are included for option focusing, filtering, and selection using an ARIA live region to ensure announcements are clear and consistent.
+
+## Basic usage (with state), filtering managed internally
+
+Here is the most simple usage of the combobox, with a list of predefined items and a controlled state.
+
+**Please note that we are using the `defaultItems` prop to pass the items to the combobox.**
+Doing so will let the combobox manage the filtered list of items internally.
+
+<Source of={ComboboxTests.ExampleControlledValue} type="code" dark />
+
+## Custom filtering
+
+By default, ComboBox uses a "includes" function to filter the list of options.
+This can be overridden using the `defaultFilter` prop (or by using the `items` prop to control the filtered list).
+**When `items` is provided rather than `defaultItems`, ComboBox does no filtering of its own.**
+
+The following example is a slightly modified version of the previous example, with a custom filter function that uses the `defaultFilter` prop.
+
+<Source of={ComboboxTests.ExampleWithCustomFiltering} type="code" dark />
+
+## With React hook form
+
+Here is an example of how to use the combobox with React hook form.
+
+<Source of={ComboboxTests.ExampleWithReactHookForm} type="code" dark />
+
+## Async filtering on backend
+
+Here is an example of how to use the combobox with async filtering on backend (i.e. API call).
+
+Use this if you have a large list of items and you have an API endpoint that is responsible for filtering the items.
+
+**Please note that we are using the `items` prop to pass the items to the combobox (instead of `defaultItems`).**
+Doing so will disable the internal filtering of the combobox, and you will be responsible for managing the filtered list of items.
+
+<Source of={ComboboxTests.ExampleBackendManaged} type="code" dark />
+
+## Links
+
+By default, interacting with an item in a ComboBox selects it and updates the input value.
+Alternatively, items may be links to another page or website.
+This can be achieved by passing the `href` attribute to the item (`items` prop).
+Interacting with link items navigates to the provided URL and does not update the selection or input value.
+
+<Source of={ComboboxTests.ExampleWithLinks} type="code" dark />
+
+## 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.
+
+<Source of={ComboboxTests.MultipleSelectionExample} 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={ComboboxTests.TestExampleBackendManaged} type="code" dark />
+
+## Playground & Props
+
+<Canvas of={Combobox.Playground} />
+
+<Controls of={Combobox.Playground} />
+
+<Stories />
+```