@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,263 @@
+# Toaster
+
+## 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/Toaster/Toaster.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { screen } from "storybook/test";
+import Toaster from "./Toaster";
+import { toast } from "sonner";
+import { useEffect } from "react";
+import Button from "../Button/Button";
+
+const meta: Meta<typeof Toaster> = {
+  component: Toaster,
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <>
+        <Toaster />
+        <Story />
+      </>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast("Default message");
+        toast("With action", {
+          action: <Button nature="informative" text="Click me" />,
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+  play: async () => {
+    await screen.findByText("Default message");
+  },
+};
+
+export const Success: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast.success("Success message");
+        toast.success("With action", {
+          action: <Button nature="positive" text="Click me" />,
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const Error: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast.error("Error message");
+        toast.error("With action", {
+          action: <Button nature="negative" text="Click me" />,
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const Warning: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast.warning("Warning message");
+        toast.warning("With action", {
+          action: <Button nature="warning" text="Click me" />,
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const WithPromise: Story = {
+  render: () => {
+    const fakePromise = new Promise((resolve) => {
+      setTimeout(() => resolve({ name: "Promise" }), 2000);
+    });
+
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast.promise(fakePromise, {
+          loading: "Loading...",
+          success: (data: any) => {
+            return `${data.name} toast has been added`;
+          },
+          error: "Error text",
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const Custom: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast(<div>A custom toast with default styling</div>, {
+          duration: 5000,
+          unstyled: true,
+          closeButton: false,
+        });
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const VeryLongText: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast(
+          "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+        );
+      }, []);
+      return <div />;
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const OverflowingText: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast("text-that-will-overflow-if-not-cutted-off-by-the-css");
+      }, []);
+      return <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 {
+  Canvas,
+  Meta,
+  Stories,
+  Controls,
+  Source,
+} from "@storybook/addon-docs/blocks";
+
+import * as Toaster from "./Toaster.stories";
+
+<Meta of={Toaster} />
+
+# Toaster
+
+## Installation
+
+The Toaster component will allow you to add toasts to your application.
+
+**First, you need to provide the Toaster component in your application.**
+
+Only import it in a single place in your app, typically in your root component or main layout component (same as any other Provider component).
+
+```tsx
+import { Toaster } from "@agregio-solutions/design-system";
+
+function App() {
+  return (
+    <ProviderXYZ>
+      {/* 👇 place the Toaster component in the same location as the global providers */}
+      <Toaster />
+      <YourApp />
+    </ProviderXYZ>
+  );
+}
+```
+
+## Usage
+
+Then, any time you want to display a toast, you can use the `toast` function.
+
+```tsx
+import { toast, Button } from "@agregio-solutions/design-system";
+
+function Page() {
+  return (
+    <div>
+      <Button onClick={() => toast("Hello world")} text="Toast me" />
+    </div>
+  );
+}
+```
+
+## Examples
+
+### Default and with action button
+
+<Source of={Toaster.Default} type="code" dark />
+
+### Success
+
+<Source of={Toaster.Success} type="code" dark />
+
+### Error
+
+<Source of={Toaster.Error} type="code" dark />
+
+### Warning
+
+<Source of={Toaster.Warning} type="code" dark />
+
+### With promise
+
+<Source of={Toaster.WithPromise} type="code" dark />
+
+### Custom toast component
+
+<Source of={Toaster.Custom} type="code" dark />
+
+## Toaster Props
+
+The Design System provides strong defaults for the Toaster component, but you can still customize it with the following props:
+
+<Controls of={Toaster.Default} />
+
+## Going further with the toast function
+
+This documentation should cover most of your needs.
+
+But if you need to go deeper with the toast function, you can refer to the [sonner documentation](https://sonner.emilkowal.ski/toast), which is the library that is used internally.
+````

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

@@ -0,0 +1,108 @@
+# ToggleButton
+
+## 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/ToggleButton/ToggleButton.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import ToggleButton from "./ToggleButton";
+import { expect, userEvent, within, fn } from "storybook/test";
+
+const meta: Meta<typeof ToggleButton> = {
+  component: ToggleButton,
+  tags: ["autodocs"],
+  globals: {
+    backgrounds: { value: "dark" },
+  },
+  argTypes: {
+    children: {
+      control: "text",
+    },
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+
+export const Playground: StoryObj<typeof ToggleButton> = {
+  args: {
+    id: "December",
+    children: "D",
+    onChange: fn(),
+    tooltip: "December",
+  },
+};
+
+export const DefaultSelected: StoryObj<typeof ToggleButton> = {
+  args: {
+    ...Playground.args,
+    defaultSelected: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button");
+    await expect(button).toHaveAttribute("aria-pressed", "true");
+  },
+};
+
+export const Disabled: StoryObj<typeof ToggleButton> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button");
+    await expect(button).toBeDisabled();
+    await userEvent.click(button);
+    await expect(button).toHaveAttribute("aria-pressed", "false");
+  },
+};
+
+export const WarningMode: StoryObj<typeof ToggleButton> = {
+  args: {
+    ...Playground.args,
+    mode: "warning",
+    defaultSelected: true,
+  },
+};
+
+export const WithIcon: StoryObj<typeof ToggleButton> = {
+  args: {
+    ...Playground.args,
+    iconName: "phone_1_full",
+    tooltip: "By phone",
+  },
+};
+
+export const Interaction: StoryObj<typeof ToggleButton> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button");
+
+    await expect(button).toHaveAttribute("aria-pressed", "false");
+
+    await userEvent.click(button);
+    await expect(button).toHaveAttribute("aria-pressed", "true");
+    expect(args.onChange).toHaveBeenCalledWith(true);
+
+    await userEvent.click(button);
+    await expect(button).toHaveAttribute("aria-pressed", "false");
+    expect(args.onChange).toHaveBeenCalledWith(false);
+  },
+};
+```

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

@@ -0,0 +1,307 @@
+# ToggleButtonGroup
+
+## 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/ToggleButtonGroup/ToggleButtonGroup.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import ToggleButtonGroup from "./ToggleButtonGroup";
+import ToggleButton from "../ToggleButton/ToggleButton";
+import { expect, userEvent, within, fn } from "storybook/test";
+import { ICON_NAMES_ARRAY } from "../Icon/Icon";
+
+const meta: Meta<typeof ToggleButtonGroup> = {
+  component: ToggleButtonGroup,
+  tags: ["autodocs"],
+  argTypes: {
+    orientation: {
+      control: "select",
+      options: ["vertical", "horizontal"],
+    },
+    labelIconRight: {
+      control: "select",
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    helperTextIcon: {
+      control: "select",
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    errorHelperTextIcon: {
+      control: "select",
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    successHelperTextIcon: {
+      control: "select",
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    warningHelperTextIcon: {
+      control: "select",
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    children: { control: false },
+    selectedKeys: { control: false },
+    defaultSelectedKeys: { control: false },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ToggleButtonGroup>;
+
+const isChecked = async (button: HTMLElement) => {
+  await expect(button).toHaveAttribute("data-selected", "true");
+};
+
+export const Playground: Story = {
+  args: {
+    orientation: "vertical",
+    label: "[Insert label]",
+    required: true,
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    helperText: "[Insert description]",
+    helperTextIcon: "help_outline",
+    onSelectionChange: fn(),
+    errorHelperText: "",
+    errorHelperTextIcon: "error_outline",
+    successHelperText: "",
+    successHelperTextIcon: "check_circle_outline",
+    warningHelperText: "",
+    warningHelperTextIcon: "warning_amber",
+    defaultSelectedKeys: [],
+    isDisabled: false,
+    selectionMode: "multiple",
+    style: {},
+    className: "",
+  },
+  render: (args) => (
+    <ToggleButtonGroup {...args}>
+      <ToggleButton id="Monday" tooltip="Lundi">
+        L
+      </ToggleButton>
+      <ToggleButton id="Tuesday" tooltip="Mardi">
+        M
+      </ToggleButton>
+      <ToggleButton id="Wednesday" tooltip="Mercredi">
+        M
+      </ToggleButton>
+      <ToggleButton id="Thursday" tooltip="Jeudi">
+        J
+      </ToggleButton>
+      <ToggleButton id="Friday" tooltip="Vendredi">
+        V
+      </ToggleButton>
+      <ToggleButton id="Saturday" mode="warning" tooltip="Samedi">
+        S
+      </ToggleButton>
+      <ToggleButton id="Sunday" isDisabled tooltip="Dimanche">
+        D
+      </ToggleButton>
+    </ToggleButtonGroup>
+  ),
+};
+
+export const SingleSelection: Story = {
+  args: {
+    ...Playground.args,
+    selectionMode: "single",
+  },
+  render: Playground.render,
+};
+
+export const WithDefaultSelectedKey: Story = {
+  args: {
+    ...Playground.args,
+    defaultSelectedKeys: ["Monday", "Thursday"],
+    warningHelperText: "[Insert warning text]",
+  },
+  render: Playground.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const mondayButton = canvas.getByText("L", { selector: "button" });
+    const thursdayButton = canvas.getByText("J", { selector: "button" });
+
+    await isChecked(mondayButton);
+    await isChecked(thursdayButton);
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+    onSelectionChange: fn(),
+  },
+  render: (args) => (
+    <ToggleButtonGroup {...args}>
+      <ToggleButton id="left" tooltip="Left">
+        A
+      </ToggleButton>
+      <ToggleButton id="center" tooltip="Center">
+        B
+      </ToggleButton>
+      <ToggleButton id="right" tooltip="Right">
+        C
+      </ToggleButton>
+    </ToggleButtonGroup>
+  ),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByText("A", { selector: "button" })).toBeDisabled();
+    await expect(canvas.getByText("B", { selector: "button" })).toBeDisabled();
+    await expect(canvas.getByText("C", { selector: "button" })).toBeDisabled();
+    await userEvent.click(canvas.getByText("A", { selector: "button" }));
+    await expect(args.onSelectionChange).not.toHaveBeenCalled();
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    ...Playground.args,
+    selectionMode: "multiple",
+    onSelectionChange: fn(),
+  },
+  render: (args) => (
+    <ToggleButtonGroup {...args}>
+      <ToggleButton id="phone" iconName="phone_2_full" tooltip="By phone" />
+      <ToggleButton id="email" iconName="mail_full" tooltip="By email" />
+      <ToggleButton id="sms" iconName="phone_1_full" tooltip="By SMS" />
+      <ToggleButton
+        id="notifications"
+        iconName="notifications_none"
+        tooltip="By notifications"
+      />
+    </ToggleButtonGroup>
+  ),
+};
+
+export const HorizontalOrientation: Story = {
+  args: {
+    ...Playground.args,
+    orientation: "horizontal",
+  },
+  render: Playground.render,
+};
+
+export const ControlledSelection: Story = {
+  render: function ControlledExample() {
+    const [selected, setSelected] = useState<string[]>(["center"]);
+
+    const handleSelectionChange = (keys: string[]) => {
+      setSelected(keys);
+    };
+
+    return (
+      <div>
+        <ToggleButtonGroup
+          {...Playground.args}
+          selectedKeys={selected}
+          onSelectionChange={handleSelectionChange}
+        >
+          <ToggleButton id="A" tooltip="A">
+            A
+          </ToggleButton>
+          <ToggleButton id="B" tooltip="B">
+            B
+          </ToggleButton>
+          <ToggleButton id="C" tooltip="C">
+            C
+          </ToggleButton>
+        </ToggleButtonGroup>
+
+        <p>Selected: {selected.join(", ") || "none"}</p>
+      </div>
+    );
+  },
+};
+```
+
+## 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 ToggleButtonGroup from "../ToggleButtonGroup";
+import { expect, userEvent, within } from "storybook/test";
+import * as ToggleButtonGroupStories from "../ToggleButtonGroup.stories";
+
+const meta: Meta<typeof ToggleButtonGroup> = {
+  ...ToggleButtonGroupStories.default,
+  component: ToggleButtonGroup,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ToggleButtonGroup>;
+
+const isChecked = async (button: HTMLElement) => {
+  await expect(button).toHaveAttribute("data-selected", "true");
+};
+
+const isNotChecked = async (button: HTMLElement) => {
+  await expect(button).not.toHaveAttribute("data-selected", "true");
+};
+
+export const MultipleSelectionTests: Story = {
+  ...ToggleButtonGroupStories.Playground,
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const mondayButton = canvas.getByText("L", { selector: "button" });
+    const thursdayButton = canvas.getByText("J", { selector: "button" });
+
+    await isNotChecked(mondayButton);
+    await isNotChecked(thursdayButton);
+
+    await userEvent.click(mondayButton);
+    await isChecked(mondayButton);
+    await expect(args.onSelectionChange).toHaveBeenCalledWith(["Monday"]);
+    await isNotChecked(thursdayButton);
+
+    await userEvent.click(thursdayButton);
+    await isChecked(mondayButton);
+    await isChecked(thursdayButton);
+    await expect(args.onSelectionChange).toHaveBeenCalledWith([
+      "Monday",
+      "Thursday",
+    ]);
+  },
+};
+
+export const SingleSelectionTests: Story = {
+  ...ToggleButtonGroupStories.SingleSelection,
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const mondayButton = canvas.getByText("L", { selector: "button" });
+    const thursdayButton = canvas.getByText("J", { selector: "button" });
+
+    await isNotChecked(mondayButton);
+    await isNotChecked(thursdayButton);
+
+    await userEvent.click(mondayButton);
+    await isChecked(mondayButton);
+    await expect(args.onSelectionChange).toHaveBeenCalledWith(["Monday"]);
+    await isNotChecked(thursdayButton);
+
+    await userEvent.click(thursdayButton);
+    await isChecked(thursdayButton);
+    await expect(args.onSelectionChange).toHaveBeenCalledWith(["Thursday"]);
+    await isNotChecked(mondayButton);
+  },
+};
+
+export const WithDefaultSelectedKeyTests: Story = {
+  ...ToggleButtonGroupStories.WithDefaultSelectedKey,
+};
+```