@agregio-solutions/design-system 2.0.0 → 2.2.0

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

@@ -350,6 +350,10 @@ import * as RadioTests from "./tests/Radio.stories";
 
 # Radio
 
+> **Deprecated** — use `RadioGroup` with `RadioGroupItem` instead. It names the group for
+> assistive technologies, handles keyboard navigation (one tab stop, arrow keys) and displays
+> helper and error texts. See the "Migrating from `Radio`" section of the `RadioGroup` docs.
+
 Use this component exactly like an `<input type="radio">` but with an added `label` prop.
 
 <Canvas of={Radio.WithLabel} />

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

@@ -0,0 +1,92 @@
+import { default as React } from 'react';
+import { Props as LabelProps } from '../Label/Label';
+import { Props as FormGroupWrapperProps } from '../../internal-components/FormGroupWrapper/FormGroupWrapper';
+export type Props = {
+    /**
+     * The `RadioGroupItem`s to display in the group.
+     */
+    children: React.ReactNode;
+    /**
+     * The value of the selected radio (controlled). `null` means no radio is selected.
+     */
+    value?: string | null;
+    /**
+     * The value of the radio selected on first render (uncontrolled).
+     */
+    defaultValue?: string;
+    /**
+     * Handler that is called with the value of the newly selected radio.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The name of the radios, used when submitting an HTML form.
+     */
+    name?: string;
+    /**
+     * Whether all the radios of the group are disabled.
+     */
+    isDisabled?: boolean;
+    /**
+     * Whether the radios can be focused but not changed by the user.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Layout of the radios inside the group.
+     * @default "vertical"
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * Accessible name of the group, required when `label` is not a string.
+     */
+    "aria-label"?: string;
+    /**
+     * Props to pass to the wrapper div (for example, `style` or `className`).
+     */
+    wrapperProps?: React.HTMLProps<HTMLDivElement>;
+} & Pick<LabelProps, "label" | "labelIconRight" | "labelIconRightTooltip" | "required"> & Pick<FormGroupWrapperProps, "helperText" | "helperTextIcon" | "errorHelperText" | "errorHelperTextIcon" | "successHelperText" | "successHelperTextIcon" | "warningHelperText" | "warningHelperTextIcon" | "orientation" | "className" | "style">;
+declare const RadioGroup: React.ForwardRefExoticComponent<{
+    /**
+     * The `RadioGroupItem`s to display in the group.
+     */
+    children: React.ReactNode;
+    /**
+     * The value of the selected radio (controlled). `null` means no radio is selected.
+     */
+    value?: string | null;
+    /**
+     * The value of the radio selected on first render (uncontrolled).
+     */
+    defaultValue?: string;
+    /**
+     * Handler that is called with the value of the newly selected radio.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The name of the radios, used when submitting an HTML form.
+     */
+    name?: string;
+    /**
+     * Whether all the radios of the group are disabled.
+     */
+    isDisabled?: boolean;
+    /**
+     * Whether the radios can be focused but not changed by the user.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Layout of the radios inside the group.
+     * @default "vertical"
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * Accessible name of the group, required when `label` is not a string.
+     */
+    "aria-label"?: string;
+    /**
+     * Props to pass to the wrapper div (for example, `style` or `className`).
+     */
+    wrapperProps?: React.HTMLProps<HTMLDivElement>;
+} & Pick<LabelProps, "label" | "required" | "labelIconRight" | "labelIconRightTooltip"> & Pick<FormGroupWrapperProps, "className" | "style" | "orientation" | "helperText" | "helperTextIcon" | "errorHelperText" | "errorHelperTextIcon" | "successHelperText" | "successHelperTextIcon" | "warningHelperText" | "warningHelperTextIcon"> & React.RefAttributes<{
+    focus: (options?: FocusOptions) => void;
+}>>;
+export default RadioGroup;

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

@@ -0,0 +1,569 @@
+# RadioGroup
+
+## 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/RadioGroup/RadioGroup.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, within } from "storybook/test";
+import RadioGroup from "./RadioGroup";
+import RadioGroupItem from "../RadioGroupItem/RadioGroupItem";
+import { ICON_NAMES_ARRAY } from "../Icon/Icon";
+
+const meta: Meta<typeof RadioGroup> = {
+  component: RadioGroup,
+  argTypes: {
+    direction: {
+      control: "select",
+      options: ["vertical", "horizontal"],
+    },
+    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],
+    },
+    children: { control: false },
+    value: { control: false },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroupItem value="solar" label="Solar" />
+      <RadioGroupItem value="wind" label="Wind" />
+      <RadioGroupItem value="hydro" label="Hydro" />
+    </RadioGroup>
+  ),
+};
+export default meta;
+
+type Story = StoryObj<typeof RadioGroup>;
+
+export const Playground: Story = {
+  args: {
+    label: "Energy source",
+    onChange: fn(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const group = canvas.getByRole("radiogroup", { name: "Energy source" });
+    await expect(within(group).getAllByRole("radio")).toHaveLength(3);
+    await expect(
+      canvas.getByRole("radio", { name: "Solar" }),
+    ).not.toBeChecked();
+  },
+};
+
+export const ShouldPreselectDefaultValue: Story = {
+  args: {
+    ...Playground.args,
+    defaultValue: "wind",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("radio", { name: "Wind" })).toBeChecked();
+    await expect(
+      canvas.getByRole("radio", { name: "Solar" }),
+    ).not.toBeChecked();
+  },
+};
+
+export const ShouldDisableAllRadios: Story = {
+  args: {
+    ...Playground.args,
+    defaultValue: "wind",
+    isDisabled: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    for (const radio of canvas.getAllByRole("radio")) {
+      await expect(radio).toBeDisabled();
+    }
+  },
+};
+
+export const ShouldDisableOneRadio: Story = {
+  args: Playground.args,
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroupItem value="solar" label="Solar" />
+      <RadioGroupItem value="wind" label="Wind" isDisabled />
+      <RadioGroupItem value="hydro" label="Hydro" />
+    </RadioGroup>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("radio", { name: "Wind" })).toBeDisabled();
+    await expect(canvas.getByRole("radio", { name: "Solar" })).toBeEnabled();
+  },
+};
+
+export const ShouldDisplayReadOnly: Story = {
+  args: {
+    ...Playground.args,
+    defaultValue: "wind",
+    isReadOnly: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("radio", { name: "Wind" })).toBeChecked();
+    await expect(canvas.getByText("Wind").closest("label")).toHaveAttribute(
+      "data-readonly",
+      "true",
+    );
+  },
+};
+
+export const ShouldDisplayHorizontally: Story = {
+  args: {
+    ...Playground.args,
+    direction: "horizontal",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("radiogroup")).toHaveAttribute(
+      "data-orientation",
+      "horizontal",
+    );
+  },
+};
+
+export const ShouldDisplayLabelDecorations: Story = {
+  args: {
+    ...Playground.args,
+    required: true,
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    helperText: "Main source of the site",
+    helperTextIcon: "help_outline",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Main source of the site");
+    await canvas.findByTitle("Required");
+    for (const radio of canvas.getAllByRole("radio")) {
+      await expect(radio).toBeRequired();
+    }
+  },
+};
+
+export const ShouldDisplayError: Story = {
+  args: {
+    ...Playground.args,
+    errorHelperText: "Select an energy source",
+    errorHelperTextIcon: "error_outline",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("alert")).toHaveTextContent(
+      "Select an energy source",
+    );
+    await expect(canvas.getByRole("radiogroup")).toHaveAttribute(
+      "data-invalid",
+      "true",
+    );
+  },
+};
+
+export const ShouldDescribeARadio: Story = {
+  args: Playground.args,
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroupItem
+        value="solar"
+        label="Solar"
+        description="Production during daytime only"
+      />
+      <RadioGroupItem value="wind" label="Wind" />
+    </RadioGroup>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      canvas.getByRole("radio", { name: "Solar" }),
+    ).toHaveAccessibleDescription("Production during daytime only");
+  },
+};
+
+export const ShouldWrapLongText: Story = {
+  args: Playground.args,
+  render: (args) => (
+    <div style={{ width: 200 }}>
+      <RadioGroup {...args}>
+        <RadioGroupItem
+          value="long"
+          label="This is a very long text that should wrap on several lines"
+        />
+        <RadioGroupItem value="short" label="Short" />
+      </RadioGroup>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(
+      "This is a very long text that should wrap on several lines",
+    );
+  },
+};
+```
+
+## 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 { expect, fn, userEvent, within } from "storybook/test";
+import { useState } from "react";
+import { Controller, useForm, useWatch } from "react-hook-form";
+import RadioGroup from "../RadioGroup";
+import RadioGroupItem from "../../RadioGroupItem/RadioGroupItem";
+import * as RadioGroupStories from "../RadioGroup.stories";
+
+const meta: Meta<typeof RadioGroup> = {
+  ...RadioGroupStories.default,
+  component: RadioGroup,
+  parameters: {
+    ...RadioGroupStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof RadioGroup>;
+
+const ENERGY_SOURCES = [
+  { value: "solar", label: "Solar" },
+  { value: "wind", label: "Wind" },
+  { value: "hydro", label: "Hydro" },
+];
+
+const EnergyItems = () =>
+  ENERGY_SOURCES.map((source) => (
+    <RadioGroupItem key={source.value} {...source} />
+  ));
+
+const ControlledExample = ({
+  onChange,
+}: {
+  onChange?: (value: string) => void;
+}) => {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <div>
+      <div>Debug selected: {selected}</div>
+      <RadioGroup
+        label="Energy source"
+        value={selected}
+        onChange={(value) => {
+          setSelected(value);
+          onChange?.(value);
+        }}
+      >
+        <EnergyItems />
+      </RadioGroup>
+    </div>
+  );
+};
+
+export const ExampleControlled: Story = {
+  args: { onChange: fn() },
+  render: (args) => <ControlledExample onChange={args.onChange} />,
+};
+
+export const ShouldUpdateControlledValue: Story = {
+  ...ExampleControlled,
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await user.click(canvas.getByText("Wind"));
+    await expect(canvas.getByRole("radio", { name: "Wind" })).toBeChecked();
+    await canvas.findByText("Debug selected: wind");
+    await expect(args.onChange).toHaveBeenCalledWith("wind");
+
+    await user.click(canvas.getByText("Hydro"));
+    await expect(canvas.getByRole("radio", { name: "Wind" })).not.toBeChecked();
+    await canvas.findByText("Debug selected: hydro");
+  },
+};
+
+export const ShouldSelectWhenUncontrolled: Story = {
+  args: { label: "Energy source", defaultValue: "solar", onChange: fn() },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await expect(canvas.getByRole("radio", { name: "Solar" })).toBeChecked();
+    await user.click(canvas.getByText("Hydro"));
+    await expect(canvas.getByRole("radio", { name: "Hydro" })).toBeChecked();
+    await expect(
+      canvas.getByRole("radio", { name: "Solar" }),
+    ).not.toBeChecked();
+    await expect(args.onChange).toHaveBeenCalledWith("hydro");
+  },
+};
+
+export const ShouldNavigateWithKeyboard: Story = {
+  args: { label: "Energy source", defaultValue: "solar" },
+  render: (args) => (
+    <div>
+      <RadioGroup {...args}>
+        <RadioGroupItem value="solar" label="Solar" />
+        <RadioGroupItem value="wind" label="Wind" isDisabled />
+        <RadioGroupItem value="hydro" label="Hydro" />
+      </RadioGroup>
+      <button type="button">After</button>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    const solar = canvas.getByRole("radio", { name: "Solar" });
+    const hydro = canvas.getByRole("radio", { name: "Hydro" });
+
+    await user.tab();
+    await expect(solar).toHaveFocus();
+    await expect(canvas.getByText("Solar").closest("label")).toHaveAttribute(
+      "data-focus-visible",
+      "true",
+    );
+
+    await user.keyboard("{ArrowDown}");
+    await expect(hydro).toHaveFocus();
+    await expect(hydro).toBeChecked();
+
+    await user.tab();
+    await expect(canvas.getByRole("button", { name: "After" })).toHaveFocus();
+  },
+};
+
+export const ShouldNameARadioWithoutVisibleLabel: Story = {
+  args: RadioGroupStories.Playground.args,
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroupItem value="solar" aria-label="Solar" />
+      <RadioGroupItem value="wind" aria-label="Wind" />
+    </RadioGroup>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("radio", { name: "Solar" })).toBeVisible();
+    await expect(canvas.queryByText("Solar")).not.toBeInTheDocument();
+  },
+};
+
+export const ShouldNotChangeWhenReadOnly: Story = {
+  args: {
+    label: "Energy source",
+    defaultValue: "solar",
+    isReadOnly: true,
+    onChange: fn(),
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await user.click(canvas.getByText("Wind"));
+    await expect(canvas.getByRole("radio", { name: "Solar" })).toBeChecked();
+    await expect(canvas.getByRole("radio", { name: "Wind" })).not.toBeChecked();
+    await expect(args.onChange).not.toHaveBeenCalled();
+  },
+};
+
+const ReactHookFormExample = () => {
+  const { control } = useForm({ defaultValues: { energy: "wind" } });
+  const energy = useWatch({ control, name: "energy" });
+
+  return (
+    <form>
+      <div>Debug selected: {energy}</div>
+      <Controller
+        control={control}
+        name="energy"
+        render={({ field }) => (
+          <RadioGroup
+            ref={field.ref}
+            label="Energy source"
+            name={field.name}
+            value={field.value}
+            onChange={field.onChange}
+          >
+            <EnergyItems />
+          </RadioGroup>
+        )}
+      />
+    </form>
+  );
+};
+
+export const ExampleWithReactHookForm: Story = {
+  render: () => <ReactHookFormExample />,
+};
+
+export const ShouldWorkWithReactHookForm: Story = {
+  ...ExampleWithReactHookForm,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await canvas.findByText("Debug selected: wind");
+    await expect(canvas.getByRole("radio", { name: "Wind" })).toBeChecked();
+    await user.click(canvas.getByText("Solar"));
+    await canvas.findByText("Debug selected: solar");
+    await expect(canvas.getByRole("radio", { name: "Wind" })).not.toBeChecked();
+  },
+};
+
+const ReactHookFormRequiredExample = () => {
+  const { control, handleSubmit } = useForm<{ energy: string | null }>({
+    defaultValues: { energy: null },
+  });
+
+  return (
+    <form onSubmit={handleSubmit(() => {})}>
+      <Controller
+        control={control}
+        name="energy"
+        rules={{ required: "Select an energy source" }}
+        render={({ field, fieldState }) => (
+          <RadioGroup
+            ref={field.ref}
+            label="Energy source"
+            name={field.name}
+            value={field.value}
+            onChange={field.onChange}
+            errorHelperText={fieldState.error?.message}
+          >
+            <EnergyItems />
+          </RadioGroup>
+        )}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  );
+};
+
+export const ShouldFocusFirstRadioOnReactHookFormError: Story = {
+  render: () => <ReactHookFormRequiredExample />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await user.click(canvas.getByRole("button", { name: "Submit" }));
+    await canvas.findByText("Select an energy source");
+    await expect(canvas.getByRole("radio", { name: "Solar" })).toHaveFocus();
+  },
+};
+
+const onNativeSubmit = fn();
+
+export const ShouldSubmitValueInNativeForm: Story = {
+  beforeEach: () => {
+    onNativeSubmit.mockClear();
+  },
+  render: () => (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        onNativeSubmit(new FormData(event.currentTarget).get("energy"));
+      }}
+    >
+      <RadioGroup label="Energy source" name="energy">
+        <EnergyItems />
+      </RadioGroup>
+      <button type="submit">Submit</button>
+    </form>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await user.click(canvas.getByText("Hydro"));
+    await user.click(canvas.getByRole("button", { name: "Submit" }));
+    await expect(onNativeSubmit).toHaveBeenCalledWith("hydro");
+  },
+};
+```
+
+## 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 RadioGroup from "./RadioGroup.stories";
+import * as RadioGroupTests from "./tests/RadioGroup.stories";
+
+<Meta of={RadioGroup} />
+
+# RadioGroup
+
+Lets the user pick one option among several. Each option is a `RadioGroupItem` with a unique `value`.
+The group carries the state (`value` / `defaultValue` / `onChange`), the label, and the helper and error texts.
+
+It is built on React Aria: the group is announced as a `radiogroup` with its label, it is a single tab stop,
+and arrow keys move the selection.
+
+<Canvas of={RadioGroup.Playground} />
+
+## Controlled example
+
+<Source of={RadioGroupTests.ExampleControlled} type="code" dark />
+
+## With react-hook-form
+
+Use a `Controller` (or `useController`): `register()` only works with a native input.
+Pass `field.ref` to the group's `ref`: on validation error, react-hook-form then focuses the radio holding the tab stop
+(the selected one, otherwise the first enabled one).
+
+<Source of={RadioGroupTests.ExampleWithReactHookForm} type="code" dark />
+
+## Migrating from `Radio`
+
+`Radio` is deprecated. To migrate a group of `Radio`s:
+
+- Wrap all the radios in one `RadioGroup` and move the group title into its `label` (or `aria-label`).
+- Replace each `Radio` by a `RadioGroupItem` with a `value`: it is now mandatory, even when you used to rely on `checked`.
+- Replace `checked={selected === x}` + `onChange` on each radio by `value={selected}` + `onChange={setSelected}` on the group.
+  `onChange` receives the value, not an event.
+- Replace `{...register("field")}` by a `Controller`.
+- Replace `disabled` by `isDisabled`. A radio without visible text takes an `aria-label`.
+
+Keep `Radio` for now when the radios can't sit in one block (spread across table cells) or when clicking
+the selected radio must deselect it: a radio group can't be emptied by the user.
+
+### RadioGroup props
+
+<Controls of={RadioGroup.Playground} />
+
+<Stories />
+```

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

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+export type Props = {
+    /**
+     * The value of the radio, returned by the `onChange` of the parent `RadioGroup`.
+     * Also used as the native `value` attribute when submitting an HTML form.
+     */
+    value: string;
+    /**
+     * The text to display next to the radio.
+     * If you give a ReactNode or no label at all, also provide an `aria-label`.
+     */
+    label?: string | React.ReactNode;
+    /**
+     * Accessible name of the radio, required when there is no string `label`.
+     */
+    "aria-label"?: string;
+    /**
+     * Additional text displayed below the label, linked to the radio with `aria-describedby`.
+     */
+    description?: React.ReactNode;
+    /**
+     * Whether the radio is disabled.
+     */
+    isDisabled?: boolean;
+};
+declare const RadioGroupItem: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
+export default RadioGroupItem;

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

@@ -9,5 +9,5 @@ export type Props = {
     useHref?: ComponentProps<typeof AriaRouterProvider>["useHref"];
     children: ReactNode;
 };
-declare const RouterProvider: ({ children, ...props }: Props) => import("react").JSX.Element;
+declare const RouterProvider: ({ children, ...props }: Props) => import('react').JSX.Element;
 export default RouterProvider;