@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,296 @@
+# Switch
+
+## 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/Switch/Switch.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Switch from "./Switch";
+import { within, expect, userEvent, fn } from "storybook/test";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Switch> = {
+  component: Switch,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Switch> = {
+  args: {
+    id: "nice-switch",
+    label: "Label",
+    onChange: fn(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+  },
+};
+
+export const Large: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    size: "large",
+  },
+};
+
+export const NoLabel: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    label: undefined,
+    "aria-label": "Label",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expectNotPresent(() => canvas.queryByText("Label"));
+    await canvas.findByLabelText("Label");
+  },
+};
+
+export const LabelLeft: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    labelPosition: "left",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+  },
+};
+
+export const DefaultSelected: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    defaultSelected: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).toBeChecked();
+  },
+};
+
+export const Disabled: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+    await userEvent.click(canvas.getByLabelText("Label"));
+    await expect(args.onChange).toHaveBeenCalledTimes(0);
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+  },
+};
+export const DisabledSelected: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+    defaultSelected: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).toBeChecked();
+    await userEvent.click(canvas.getByLabelText("Label"));
+    await expect(args.onChange).toHaveBeenCalledTimes(0);
+    await expect(canvas.getByLabelText("Label")).toBeChecked();
+  },
+};
+
+export const Focus: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-focus-visible": true,
+  },
+};
+
+export const WithFormattedText: StoryObj<typeof Switch> = {
+  args: {
+    ...Playground.args,
+    label: (
+      <div>
+        <h3 style={{ margin: 0 }}>Activate the wifi</h3>
+        <div>
+          The wi-fi will connect to your device and allow you to access the
+          internet.
+        </div>
+      </div>
+    ),
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 300 }}>
+        <Story />
+      </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 Switch from "../Switch";
+import { userEvent, within, expect } from "storybook/test";
+import { useState } from "react";
+import { useController, useForm } from "react-hook-form";
+
+const meta: Meta<typeof Switch> = {
+  component: Switch,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ExampleControlled: StoryObj<typeof Switch> = {
+  render: (args) => {
+    const ControlledExample = () => {
+      const [isSelected, setIsSelected] = useState(false);
+
+      return (
+        <div>
+          <div>Is selected: {isSelected ? "Yes" : "No"}</div>
+
+          <Switch
+            isSelected={isSelected}
+            onChange={() => setIsSelected(!isSelected)}
+            label="Wi-Fi"
+          />
+        </div>
+      );
+    };
+
+    return <ControlledExample {...args} />;
+  },
+};
+
+export const TestControlled: StoryObj<typeof Switch> = {
+  render: ExampleControlled.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Is selected: No");
+    await expect(canvas.getByLabelText("Wi-Fi")).not.toBeChecked();
+    await userEvent.click(canvas.getByText("Wi-Fi"));
+    await expect(canvas.getByLabelText("Wi-Fi")).toBeChecked();
+    await canvas.findByText("Is selected: Yes");
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Switch> = {
+  render: (args) => {
+    const ReactHookFormExample = () => {
+      const { control } = useForm({
+        defaultValues: {
+          wifi: true,
+        },
+      });
+
+      const wifiField = useController({ control, name: "wifi" });
+
+      return (
+        <form>
+          <div>Is selected: {wifiField.field.value ? "Yes" : "No"}</div>
+          <Switch
+            id="wifi-id-1"
+            label="Wi-Fi"
+            isSelected={wifiField.field.value}
+            onChange={(isSelected) => wifiField.field.onChange(isSelected)}
+          />
+        </form>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+
+export const TestWithReactHookForm: StoryObj<typeof Switch> = {
+  render: ExampleWithReactHookForm.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Is selected: Yes");
+    await expect(canvas.getByLabelText("Wi-Fi")).toBeChecked();
+    await user.click(canvas.getByText("Wi-Fi"));
+    await expect(canvas.getByLabelText("Wi-Fi")).not.toBeChecked();
+    await canvas.findByText("Is selected: No");
+  },
+};
+```
+
+## 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 Switch from "./Switch.stories";
+import * as SwitchTests from "./tests/Switch.stories";
+
+<Meta of={Switch} />
+
+# Switch
+
+A switch allows a user to turn a setting on or off.
+
+<Canvas of={Switch.Playground} />
+<Controls of={Switch.Playground} />
+
+## Features
+
+There is no native HTML element with switch styling.
+`<input type="checkbox">` is the closest semantically, but isn't styled or exposed to assistive technology as a switch.
+Switch helps achieve accessible switches that can be styled as needed.
+
+- **Styleable** – Hover, press, keyboard focus, and selection states are provided for easy styling. These states only apply when interacting with an appropriate input device, unlike CSS pseudo classes.
+- **Accessible** – Uses a visually hidden `<input>` element with role="switch" under the hood, which also enables HTML form integration and autofill. A label element is built-in to ensure the switch is usable with assistive technologies.
+- **Cross-browser** – Mouse, touch, keyboard, and focus interactions are normalized to ensure consistency across browsers and devices.
+
+In most cases, switches should have a visual label.
+If the switch does not have a visible label, an `aria-label` or `aria-labelledby` prop must be passed instead to identify the element to assistive technology.
+
+## Example usage (with state)
+
+<Source of={SwitchTests.ExampleControlled} type="code" dark />
+
+## Example usage (with react-hook-form)
+
+<Source of={SwitchTests.ExampleWithReactHookForm} type="code" dark />
+
+<Stories />
+```

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

@@ -0,0 +1,295 @@
+# Tabs
+
+## 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/Tabs/Tabs.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Tabs from "./Tabs/Tabs";
+import TabList from "./TabList/TabList";
+import Tab from "./Tab/Tab";
+import TabPanel from "./TabPanel/TabPanel";
+import { Route, Routes, useLocation } from "react-router-dom";
+import React from "react";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Tabs> = {
+  component: Tabs,
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const SimpleTabs: StoryObj<typeof Tabs> = {
+  render: () => (
+    <Tabs defaultSelectedKey="1">
+      <TabList style={{ marginBottom: 16 }}>
+        <Tab id="1">Panel 1</Tab>
+        <Tab id="2">Panel 2</Tab>
+        <Tab id="3" badgeProps={{ nature: "negative", variant: "dot" }}>
+          Panel 3
+        </Tab>
+        <Tab id="disabled" isDisabled>
+          Disabled tab
+        </Tab>
+      </TabList>
+      <TabPanel id="1">Content for the panel 1</TabPanel>
+      <TabPanel id="2">Content for the panel 2</TabPanel>
+      <TabPanel id="3">Content for the panel 3</TabPanel>
+      <TabPanel id="disabled">Content for the panel disabled</TabPanel>
+    </Tabs>
+  ),
+};
+
+export const WithoutFlexWrapper: StoryObj<typeof Tabs> = {
+  parameters: {
+    layout: "padded",
+  },
+  render: SimpleTabs.render,
+};
+
+export const ControlledMode: StoryObj<typeof Tabs> = {
+  render: () => {
+    function AppTabs() {
+      const [selectedKey, setSelectedKey] = React.useState("1");
+
+      return (
+        <Tabs selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
+          <TabList style={{ marginBottom: 16 }}>
+            <Tab id="1">Panel 1</Tab>
+            <Tab id="2">Panel 2</Tab>
+          </TabList>
+          <TabPanel id="1">Content for the panel 1</TabPanel>
+          <TabPanel id="2">Content for the panel 2</TabPanel>
+        </Tabs>
+      );
+    }
+
+    return <AppTabs />;
+  },
+};
+
+export const WithReactRouter: StoryObj<typeof Tabs> = {
+  render: () => {
+    function AppTabs() {
+      const { pathname } = useLocation();
+
+      return (
+        <Tabs selectedKey={pathname}>
+          <TabList aria-label="Tabs" style={{ marginBottom: 16 }}>
+            <Tab id="/pane-1" href="/pane-1">
+              Panel 1
+            </Tab>
+            <Tab id="/pane-2" href="/pane-2">
+              Panel 2
+            </Tab>
+            <Tab id="/pane-3" href="/pane-3">
+              Panel 3
+            </Tab>
+            <Tab id="/pane-disabled" href="/pane-disabled" isDisabled>
+              Panel disabled
+            </Tab>
+          </TabList>
+          <TabPanel 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>
+          </TabPanel>
+        </Tabs>
+      );
+    }
+
+    return <AppTabs />;
+  },
+};
+
+export const WithOverflow: StoryObj<typeof Tabs> = {
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "none",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  render: () => {
+    function AppTabs() {
+      return (
+        <Tabs>
+          <TabList>
+            <Tab id="tab-1">Tab 1</Tab>
+            <Tab id="tab-2" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 2
+            </Tab>
+            <Tab id="tab-3" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 3
+            </Tab>
+            <Tab id="tab-4" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 4
+            </Tab>
+            <Tab id="tab-5" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 5
+            </Tab>
+            <Tab id="tab-6" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 6
+            </Tab>
+            <Tab id="tab-7" badgeProps={{ nature: "negative", variant: "dot" }}>
+              Tab 7
+            </Tab>
+          </TabList>
+          <div style={{ marginTop: "var(--spacing-md" }}>
+            <TabPanel id="tab-1">Content for the panel 1</TabPanel>
+            <TabPanel id="tab-2">Content for the panel 2</TabPanel>
+            <TabPanel id="tab-3">Content for the panel 3</TabPanel>
+            <TabPanel id="tab-4">Content for the panel 4</TabPanel>
+            <TabPanel id="tab-5">Content for the panel 5</TabPanel>
+            <TabPanel id="tab-6">Content for the panel 6</TabPanel>
+            <TabPanel id="tab-7">Content for the panel 7</TabPanel>
+          </div>
+        </Tabs>
+      );
+    }
+
+    return <AppTabs />;
+  },
+};
+```
+
+## 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 Tabs from "./Tabs.stories";
+import * as TabPanel from "./TabPanel/TabPanel.stories";
+import * as TabList from "./TabList/TabList.stories";
+import Tab from "./Tab/Tab";
+
+<Meta of={Tabs} />
+
+# Tabs
+
+<Canvas of={Tabs.SimpleTabs} />
+
+## Basic usage
+
+Here is the simplest way to use the Tabs component. All the state is managed by the Tabs component.
+You can define the default selected tab on the first render with the `defaultSelectedKey` prop.
+
+<Source of={Tabs.SimpleTabs} type="code" dark />
+
+## Controlled mode
+
+If you need more control about the state of the Tabs component, you can use the `selectedKey` and `onSelectionChange` props to control the selected tab.
+
+<Source of={Tabs.ControlledMode} type="code" dark />
+
+## Using a Router to render the TabPanels
+
+It is possible to use a Router to render the TabPanels, thus making the Tabs 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 Tabs component.
+
+Without a RouterProvider, the Tabs 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={Tabs.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 Tabs component like this :
+
+```tsx
+import { useLocation } from "react-router-dom";
+
+export const NestedPage = () => {
+  const { pathname } = useLocation();
+
+  return (
+    <>
+      <Tabs selectedKey={pathname}>
+        <TabList>
+          <Tab id="/nested/pane-1" href="/nested/pane-1">
+            Panel 1
+          </Tab>
+          <Tab id="/nested/pane-2" href="/nested/pane-2">
+            Panel 2
+          </Tab>
+          <Tab id="/nested/pane-3" href="/nested/pane-3">
+            Panel 3
+          </Tab>
+        </TabList>
+        <TabPanel 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>
+        </TabPanel>
+      </Tabs>
+    </>
+  );
+};
+```
+
+## Tabs component Props
+
+`Tabs` is the root component of the whole tabs system, other "Tab\*" subcomponents must be above it in the tree.
+
+<ArgTypes of={Tabs.SimpleTabs} />
+
+## Tab component Props
+
+The `Tab` component is used to display one of the choices. It can also be a link.
+
+<ArgTypes of={Tab} />
+
+## TabList component Props
+
+The `TabList` is responsible to align correctly the different `Tab` component inside of it, and also enable a11y features like keyboard navigation and screen-reader props.
+
+<ArgTypes of={TabList.Default} />
+
+## TabPanel component Props
+
+This optional component is required if you want the `Tabs` to fully handle the state (uncontrolled) and show the corresponding active panel depending on the selected Tab ID.
+
+If you use the controlled mode, it's still good to use TabPanel but it's not required.
+
+<ArgTypes of={TabPanel.Default} />
+
+<Stories />
+````

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

@@ -0,0 +1,81 @@
+# Tag
+
+## 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/Tag/Tag.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Tag from "./Tag";
+import { within } from "storybook/test";
+import { ICON_NAMES_ARRAY } from "@components/Icon/Icon";
+
+const meta: Meta<typeof Tag> = {
+  component: Tag,
+  tags: ["autodocs"],
+  argTypes: {
+    children: { type: "string" },
+    iconLeft: {
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const Default: StoryObj<typeof Tag> = {
+  args: {
+    children: "[Insert tag]",
+    nature: "default",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(args.children as string);
+  },
+};
+
+export const WithIcon: StoryObj<typeof Tag> = {
+  args: {
+    ...Default.args,
+    iconLeft: "help_outline",
+  },
+};
+
+export const Informative: StoryObj<typeof Tag> = {
+  args: {
+    ...WithIcon.args,
+    nature: "informative",
+  },
+};
+
+export const Negative: StoryObj<typeof Tag> = {
+  args: {
+    ...WithIcon.args,
+    nature: "negative",
+  },
+};
+
+export const Positive: StoryObj<typeof Tag> = {
+  args: {
+    ...WithIcon.args,
+    nature: "positive",
+  },
+};
+
+export const Warning: StoryObj<typeof Tag> = {
+  args: {
+    ...WithIcon.args,
+    nature: "warning",
+  },
+};
+```