@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,398 @@
+# SegmentedControl
+
+## 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/SegmentedControl/SegmentedControl.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import SegmentedControl from "./SegmentedControl";
+import SegmentedControlList from "./SegmentedControlList/SegmentedControlList";
+import SegmentedControlButton from "./SegmentedControlButton/SegmentedControlButton";
+import SegmentedControlPanel from "./SegmentedControlPanel/SegmentedControlPanel";
+import { Route, Routes, useLocation } from "react-router-dom";
+import React from "react";
+
+const meta: Meta<typeof SegmentedControl> = {
+  component: SegmentedControl,
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const SimpleSegmentedControl: StoryObj<typeof SegmentedControl> = {
+  render: () => (
+    <SegmentedControl defaultSelectedKey="1">
+      <SegmentedControlList style={{ marginBottom: 16 }}>
+        <SegmentedControlButton id="1" text="Panel 1" icon="help_outline" />
+        <SegmentedControlButton id="2" text="Panel 2" />
+        <SegmentedControlButton id="3" text="Panel 3" />
+        <SegmentedControlButton id="disabled" isDisabled text="Disabled" />
+      </SegmentedControlList>
+      <SegmentedControlPanel id="1">
+        Content for the panel 1
+      </SegmentedControlPanel>
+      <SegmentedControlPanel id="2">
+        Content for the panel 2
+      </SegmentedControlPanel>
+      <SegmentedControlPanel id="3">
+        Content for the panel 3
+      </SegmentedControlPanel>
+      <SegmentedControlPanel id="disabled">
+        Content for the panel disabled
+      </SegmentedControlPanel>
+    </SegmentedControl>
+  ),
+};
+
+export const WithoutFlexWrapper: StoryObj<typeof SegmentedControl> = {
+  parameters: {
+    layout: "padded",
+  },
+  render: SimpleSegmentedControl.render,
+};
+
+export const ControlledMode: StoryObj<typeof SegmentedControl> = {
+  render: () => {
+    function Parent() {
+      const [selectedKey, setSelectedKey] = React.useState("1");
+
+      return (
+        <SegmentedControl
+          selectedKey={selectedKey}
+          onSelectionChange={setSelectedKey}
+        >
+          <SegmentedControlList style={{ marginBottom: 16 }}>
+            <SegmentedControlButton id="1" text="Panel 1" />
+            <SegmentedControlButton id="2" text="Panel 2" />
+          </SegmentedControlList>
+          <SegmentedControlPanel id="1">
+            Content for the panel 1
+          </SegmentedControlPanel>
+          <SegmentedControlPanel id="2">
+            Content for the panel 2
+          </SegmentedControlPanel>
+        </SegmentedControl>
+      );
+    }
+
+    return <Parent />;
+  },
+};
+
+export const WithReactRouter: StoryObj<typeof SegmentedControl> = {
+  render: () => {
+    function Parent() {
+      const { pathname } = useLocation();
+
+      return (
+        <SegmentedControl selectedKey={pathname}>
+          <SegmentedControlList
+            aria-label="SegmentedControl"
+            style={{ marginBottom: 16 }}
+          >
+            <SegmentedControlButton
+              id="/pane-1"
+              href="/pane-1"
+              text="Panel 1"
+            />
+            <SegmentedControlButton
+              id="/pane-2"
+              href="/pane-2"
+              text="Panel 2"
+            />
+            <SegmentedControlButton
+              id="/pane-3"
+              href="/pane-3"
+              text="Panel 3"
+            />
+            <SegmentedControlButton
+              id="/pane-disabled"
+              href="/pane-disabled"
+              isDisabled
+              text="Panel disabled"
+            />
+          </SegmentedControlList>
+          <SegmentedControlPanel id={pathname}>
+            <Routes>
+              <Route path="/pane-1" element="Content for the panel 1" />
+              <Route path="/pane-2" element="Content for the panel 2" />
+              <Route path="/pane-3" element="Content for the panel 3" />
+              <Route
+                path="/pane-disabled"
+                element="Content for the panel disabled"
+              />
+            </Routes>
+          </SegmentedControlPanel>
+        </SegmentedControl>
+      );
+    }
+
+    return <Parent />;
+  },
+};
+```
+
+## 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 SegmentedControl from "../SegmentedControl.tsx";
+import {
+  SimpleSegmentedControl,
+  WithReactRouter,
+} from "../SegmentedControl.stories.tsx";
+import { userEvent, waitFor, within, expect } from "storybook/test";
+import {
+  expectNotPresent,
+  someTime,
+} from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof SegmentedControl> = {
+  component: SegmentedControl,
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ShouldWorkWithSimpleSegmentedControl: StoryObj<
+  typeof SegmentedControl
+> = {
+  render: SimpleSegmentedControl.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await canvas.findByText("Panel 1");
+    await waitFor(() =>
+      expect(canvas.getByText("Panel 1").parentElement).toHaveAttribute(
+        "aria-selected",
+        "true",
+      ),
+    );
+    await canvas.findByText("Content for the panel 1");
+    await user.click(canvas.getByText("Panel 2"));
+    await expect(canvas.getByText("Panel 2").parentElement).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await canvas.findByText("Content for the panel 2");
+    await user.click(canvas.getByText("Panel 3"));
+    await expect(canvas.getByText("Panel 3").parentElement).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await canvas.findByText("Content for the panel 3");
+    await user.click(canvas.getByText("Disabled"));
+    await expect(canvas.getByText("Disabled").parentElement).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+    await expectNotPresent(() =>
+      canvas.queryByText("Content for the panel disabled"),
+    );
+    await canvas.findByText("Content for the panel 3");
+  },
+};
+
+export const ShouldWorkWithReactRouter: StoryObj<typeof SegmentedControl> = {
+  render: WithReactRouter.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await someTime(100); // Avoid flaky tests
+
+    const checkPanelPresent = async (panelId: string) => {
+      await canvas.findByText(`Content for the panel ${panelId}`);
+      await expect(
+        canvas.getByText(`Panel ${panelId}`).parentElement,
+      ).toHaveAttribute("aria-selected", "true");
+    };
+
+    const checkPanelNotPresent = async (panelId: string) => {
+      await expectNotPresent(() =>
+        canvas.queryByText(`Content for the panel ${panelId}`),
+      );
+      await expect(
+        canvas.getByText(`Panel ${panelId}`).parentElement,
+      ).toHaveAttribute("aria-selected", "false");
+    };
+
+    await checkPanelNotPresent("1");
+    await checkPanelNotPresent("2");
+    await checkPanelNotPresent("3");
+    await checkPanelNotPresent("disabled");
+
+    // Click on the first panel
+    await user.click(canvas.getByText("Panel 1"));
+    await checkPanelPresent("1");
+    await checkPanelNotPresent("2");
+    await checkPanelNotPresent("3");
+    await checkPanelNotPresent("disabled");
+
+    // Click on the second panel
+    await user.click(canvas.getByText("Panel 2"));
+    await checkPanelNotPresent("1");
+    await checkPanelPresent("2");
+    await checkPanelNotPresent("3");
+    await checkPanelNotPresent("disabled");
+
+    // Click on the third panel
+    await user.click(canvas.getByText("Panel 3"));
+    await checkPanelNotPresent("1");
+    await checkPanelNotPresent("2");
+    await checkPanelPresent("3");
+    await checkPanelNotPresent("disabled");
+
+    // Click on the disabled panel
+    await user.click(canvas.getByText("Panel disabled"));
+    await checkPanelNotPresent("1");
+    await checkPanelNotPresent("2");
+    await checkPanelPresent("3"); // still present
+    await checkPanelNotPresent("disabled");
+  },
+};
+```
+
+## 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 {
+  Canvas,
+  Meta,
+  Stories,
+  ArgTypes,
+  Source,
+} from "@storybook/addon-docs/blocks";
+
+import * as SegmentedControl from "./SegmentedControl.stories";
+import * as SegmentedControlPanel from "./SegmentedControlPanel/SegmentedControlPanel.stories";
+import * as SegmentedControlList from "./SegmentedControlList/SegmentedControlList.stories";
+import SegmentedControlButton from "./SegmentedControlButton/SegmentedControlButton";
+
+<Meta of={SegmentedControl} />
+
+# SegmentedControl
+
+<Canvas of={SegmentedControl.SimpleSegmentedControl} />
+
+## Basic usage
+
+Here is the simplest way to use the SegmentedControl component. All the state is managed by the SegmentedControl component.
+You can define the default selected SegmentedControlButton on the first render with the `defaultSelectedKey` prop.
+
+<Source of={SegmentedControl.SimpleSegmentedControl} type="code" dark />
+
+## Controlled mode
+
+If you need more control about the state of the SegmentedControl component, you can use the `selectedKey` and `onSelectionChange` props to control the selected SegmentedControlButton.
+
+<Source of={SegmentedControl.ControlledMode} type="code" dark />
+
+## Using a Router to render the SegmentedControlPanels
+
+It is possible to use a Router to render the SegmentedControlPanels, thus making the SegmentedControl simple links that will update the URL using your framework-specific Router.
+
+Doing so may be a little bit more complex than using simple state management, but comes with some benefits like SEO / preserving the browser history / keep the selected panel on page reloads / etc.
+
+**It will also requires you to setup the [RouterProvider](?path=/docs/components-routerprovider--docs)** to make the Router available to the SegmentedControl component.
+
+Without a RouterProvider, the SegmentedControl will render as simple links that will make a full page reload (instead of a `router.push` or `router.replace` call).
+
+Here is a basic example using React Router v6.
+
+<Source of={SegmentedControl.WithReactRouter} type="code" dark />
+
+If you use `<Outlet />` in your app to render your main routes, you may have to use nested route indications instead of giving a full URL.
+
+First, in your main pages routes definitions, you should have a route that will render the same component for the nested paths:
+
+```jsx
+<Route path="/nested/*" element={<NestedPage />} />
+```
+
+Then, inside the NestedPage component, you can use the SegmentedControl component like this :
+
+```tsx
+import { useLocation } from "react-router-dom";
+
+export const NestedPage = () => {
+  const { pathname } = useLocation();
+
+  return (
+    <>
+      <SegmentedControl selectedKey={pathname}>
+        <SegmentedControlList>
+          <SegmentedControlButton
+            id="/nested/pane-1"
+            href="/nested/pane-1"
+            text="Panel 1"
+          />
+          <SegmentedControlButton
+            id="/nested/pane-2"
+            href="/nested/pane-2"
+            text="Panel 2"
+          />
+          <SegmentedControlButton
+            id="/nested/pane-3"
+            href="/nested/pane-3"
+            text="Panel 3"
+          />
+        </SegmentedControlList>
+        <SegmentedControlPanel id={pathname}>
+          <Routes>
+            {/*       👇 paths are relative to the parent route, no need to give the absolute URL */}
+            <Route path="pane-1" element="Content for the panel 1" />
+            <Route path="pane-2" element="Content for the panel 2" />
+            <Route path="pane-3" element="Content for the panel 3" />
+          </Routes>
+        </SegmentedControlPanel>
+      </SegmentedControl>
+    </>
+  );
+};
+```
+
+## SegmentedControl component Props
+
+`SegmentedControl` is the root component of the whole SegmentedControl system, other "SegmentedControlButton\*" subcomponents must be above it in the tree.
+
+<ArgTypes of={SegmentedControl.SimpleSegmentedControl} />
+
+## SegmentedControlButton component Props
+
+The `SegmentedControlButton` component is used to display one of the choices. It can also be a link.
+
+<ArgTypes of={SegmentedControlButton} />
+
+## SegmentedControlList component Props
+
+The `SegmentedControlList` is responsible to align correctly the different `SegmentedControlButton` component inside of it, and also enable a11y features like keyboard navigation and screen-reader props.
+
+<ArgTypes of={SegmentedControlList.Default} />
+
+## SegmentedControlPanel component Props
+
+This optional component is required if you want the `SegmentedControl` to fully handle the state (uncontrolled) and show the corresponding active panel depending on the selected SegmentedControlButton ID.
+
+If you use the controlled mode, it's still good to use SegmentedControlPanel but it's not required.
+
+<ArgTypes of={SegmentedControlPanel.Default} />
+
+<Stories />
+````

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

@@ -60,6 +60,10 @@ interface GenericProps extends Pick<LabelProps, "label" | "labelIconRight" | "la
      * If you give a ReactNode as label, you should then provide an aria-label as string to ensure there is no accessibility issue
      */
     "aria-label"?: string;
+    /**
+     * When true, increases the dropdown max-height from 200px to 400px.
+     */
+    tallDropdown?: boolean;
 }
 interface SelectSingleProps extends GenericProps {
     /**