@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,370 @@
+# Radio
+
+## 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/Radio/Radio.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Radio from "./Radio";
+import { userEvent, within, expect, fn } from "storybook/test";
+import Icon from "@components/Icon/Icon";
+
+const meta: Meta<typeof Radio> = {
+  component: Radio,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+export const WithLabel: StoryObj<typeof Radio> = {
+  args: {
+    id: "radio-id",
+    label: "Label",
+    onChange: fn(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+  },
+};
+
+export const WithLabelSelected: StoryObj<typeof Radio> = {
+  args: {
+    ...WithLabel.args,
+    checked: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Label");
+    await expect(canvas.getByLabelText("Label")).toBeChecked();
+  },
+};
+
+export const WithLabelDisabled: StoryObj<typeof Radio> = {
+  args: {
+    ...WithLabel.args,
+    disabled: 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 WithLabelFocus: StoryObj<typeof Radio> = {
+  args: {
+    ...WithLabel.args,
+    labelProps: {
+      // @ts-ignore
+      "data-force-focus": true,
+    },
+  },
+};
+
+export const WithoutLabel: StoryObj<typeof Radio> = {
+  args: {
+    label: undefined,
+    "aria-label": "Label",
+    title: "Title",
+    onChange: fn(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText("Label");
+    await canvas.findByTitle("Title");
+    await expect(canvas.getByLabelText("Label")).not.toBeChecked();
+  },
+};
+
+export const WithoutLabelSelected: StoryObj<typeof Radio> = {
+  args: {
+    ...WithoutLabel.args,
+    checked: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText("Label");
+    await expect(canvas.getByLabelText("Label")).toBeChecked();
+  },
+};
+
+export const WithoutLabelDisabled: StoryObj<typeof Radio> = {
+  args: {
+    ...WithoutLabel.args,
+    disabled: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText("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 WithoutLabelFocus: StoryObj<typeof Radio> = {
+  args: {
+    ...WithoutLabel.args,
+    labelProps: {
+      // @ts-ignore
+      "data-force-focus": true,
+    },
+  },
+};
+
+export const WithLongText: StoryObj<typeof Radio> = {
+  args: {
+    ...WithLabel.args,
+    label: "This is a very long text that should be truncated",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 200 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const WithComponent: StoryObj<typeof Radio> = {
+  args: {
+    ...WithLabel.args,
+    label: <Icon name="star" style={{ fontSize: 60 }} />,
+  },
+};
+```
+
+## 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 Radio from "../Radio";
+import { fireEvent, within, expect } from "storybook/test";
+import { useState } from "react";
+import { useForm, useWatch } from "react-hook-form";
+import { someTime } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Radio> = {
+  component: Radio,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+// Be warned ! There is a known issue with the userEvent.click on radio inputs in Firefox
+// This is why we use a mix of userEvent and fireEvent, waiting for a fix in userEvent
+// See: https://github.com/testing-library/user-event/issues/1149
+
+export const ExampleControlled: StoryObj<typeof Radio> = {
+  render: (args) => {
+    type ControlledExampleProps = {
+      initialSelected?: string;
+    };
+
+    const ControlledExample = ({ initialSelected }: ControlledExampleProps) => {
+      const [selected, setSelected] = useState<string>(initialSelected || "");
+      return (
+        <div>
+          <div>Debug selected: {selected}</div>
+
+          <div>
+            <Radio
+              id="radio-id-1"
+              label="Option 1"
+              checked={selected === "radio-id-1"}
+              onChange={() => setSelected("radio-id-1")}
+            />
+          </div>
+          <div>
+            <Radio
+              id="radio-id-2"
+              label="Option 2"
+              checked={selected === "radio-id-2"}
+              onChange={() => setSelected("radio-id-2")}
+            />
+          </div>
+        </div>
+      );
+    };
+
+    return <ControlledExample {...args} />;
+  },
+};
+
+export const TestControlled: StoryObj<typeof Radio> = {
+  render: ExampleControlled.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Debug selected:");
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await fireEvent.click(canvas.getByLabelText("Option 1"));
+    await expect(canvas.getByLabelText("Option 1")).toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-1");
+    await fireEvent.click(canvas.getByLabelText("Option 2"));
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-2");
+  },
+};
+
+export const TestControlledWithInitialValue: StoryObj<typeof Radio> = {
+  // @ts-ignore
+  render: () => ExampleControlled.render({ initialSelected: "radio-id-1" }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByLabelText("Option 1")).toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-1");
+    await fireEvent.click(canvas.getByLabelText("Option 2"));
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-2");
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Radio> = {
+  render: (args) => {
+    type ReactHookFormExampleProps = {
+      initialSelected?: string;
+    };
+
+    const ReactHookFormExample = ({
+      initialSelected,
+    }: ReactHookFormExampleProps) => {
+      const { register, control } = useForm({
+        defaultValues: {
+          radio: initialSelected || "",
+        },
+      });
+      const radio = useWatch({ control, name: "radio" });
+
+      return (
+        <form>
+          <div>Debug selected: {radio}</div>
+          <div>
+            <Radio
+              {...register("radio")}
+              id="radio-id-1"
+              label="Option 1"
+              value="radio-id-1"
+            />
+          </div>
+          <div>
+            <Radio
+              {...register("radio")}
+              id="radio-id-2"
+              label="Option 2"
+              value="radio-id-2"
+            />
+          </div>
+        </form>
+      );
+    };
+
+    return <ReactHookFormExample {...args} />;
+  },
+};
+
+export const TestWithReactHookForm: StoryObj<typeof Radio> = {
+  render: ExampleWithReactHookForm.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await someTime(500);
+    await canvas.findByText("Debug selected:");
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await fireEvent.click(canvas.getByLabelText("Option 1"));
+    await expect(canvas.getByLabelText("Option 1")).toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-1");
+    await fireEvent.click(canvas.getByLabelText("Option 2"));
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-2");
+  },
+};
+
+export const TestWithReactHookFormAndInitialValue: StoryObj<typeof Radio> = {
+  render: () =>
+    // @ts-ignore
+    ExampleWithReactHookForm.render({ initialSelected: "radio-id-1" }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await someTime(500);
+    await await expect(canvas.getByLabelText("Option 1")).toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).not.toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-1");
+    await fireEvent.click(canvas.getByLabelText("Option 2"));
+    await expect(canvas.getByLabelText("Option 1")).not.toBeChecked();
+    await expect(canvas.getByLabelText("Option 2")).toBeChecked();
+    await canvas.findByText("Debug selected: radio-id-2");
+  },
+};
+```
+
+## 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 Radio from "./Radio.stories";
+import * as RadioTests from "./tests/Radio.stories";
+
+<Meta of={Radio} />
+
+# Radio
+
+Use this component exactly like an `<input type="radio">` but with an added `label` prop.
+
+<Canvas of={Radio.WithLabel} />
+
+## Uncontrolled example (with react-hook-form)
+
+<Source of={RadioTests.ExampleWithReactHookForm} type="code" dark />
+
+## Controlled example
+
+<Source of={RadioTests.ExampleControlled} type="code" dark />
+
+### Radio props
+
+<Controls of={Radio.WithLabel} />
+
+<Stories />
+```

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

@@ -0,0 +1,64 @@
+# RouterProvider
+
+## 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/RouterProvider/RouterProvider.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import RouterProvider from "./RouterProvider";
+
+const meta: Meta<typeof RouterProvider> = {
+  component: RouterProvider,
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const Default: StoryObj<typeof RouterProvider> = {
+  args: {
+    children: "demo",
+  },
+};
+```
+
+## 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 } from "@storybook/addon-docs/blocks";
+
+import * as RouterProvider from "./RouterProvider.stories";
+
+<Meta of={RouterProvider} />
+
+# RouterProvider
+
+This component should be used if :
+
+- you use components from the Design System that handle links (like `Link`, `Tabs` or `Breadcrumbs`)
+- you want to use the client side routing from your router (like `react-router-dom`)
+
+The setup is simple, but differs from framework to framework.
+
+Because the `RouterProvider` of the Design System is just a re-export of the React Aria once, we prefer to redirect you to the official doc for an up-to-date instructions with clean sections (instead of copy-pasting everything here).
+
+**The only difference is that you will import `RouterProvider` from "@agregio-solutions/design-system" and not from "react-aria-components".**
+
+```tsx
+import { RouterProvider } from "@agregio-solutions/design-system";
+```
+
+Read and apply the setup depending on your framework in the React Aria docs : https://react-spectrum.adobe.com/react-aria/routing.html
+````