@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,129 @@
+# Skeleton
+
+## 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/Skeleton/Skeleton.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Skeleton from "./Skeleton";
+
+const meta: Meta<typeof Skeleton> = {
+  component: Skeleton,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  args: {
+    variant: "text",
+    color: "neutral",
+    width: "100px",
+  },
+};
+
+export const MultilineText: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: () => {
+    return (
+      <div style={{ width: "100px" }}>
+        <Skeleton variant="text" />
+        <Skeleton variant="text" />
+        <Skeleton variant="text" />
+      </div>
+    );
+  },
+};
+
+export const Circular: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  args: {
+    ...Playground.args,
+    variant: "circular",
+    width: 100,
+    height: 100,
+  },
+};
+
+export const Rounded: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  args: {
+    ...Playground.args,
+    variant: "rounded",
+    width: "100px",
+    height: "100px",
+  },
+};
+
+export const Rectangular: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  args: {
+    ...Playground.args,
+    variant: "rectangular",
+    width: "100px",
+    height: "100px",
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => {
+    return (
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--spacing-sm)",
+        }}
+      >
+        <div>
+          <h2 style={{ fontSize: "var(--text-font-size-xl)", margin: 0 }}>
+            <Skeleton variant="text" width={"100%"} />
+          </h2>
+        </div>
+        <div>
+          <Skeleton variant="text" width={"100%"} />
+          <Skeleton variant="text" width={"80%"} />
+          <Skeleton variant="text" width={"90%"} />
+        </div>
+        <Skeleton variant="rectangular" width={200} height={50} />
+        <Skeleton variant="circular" width={150} height={150} />
+        <Skeleton variant="rounded" width={200} height={50} />
+      </div>
+    );
+  },
+};
+
+export const White: Story = {
+  args: {
+    ...Circular.args,
+    color: "white",
+  },
+  globals: {
+    backgrounds: { value: "dark" },
+  },
+};
+```

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

@@ -0,0 +1,362 @@
+# Slider
+
+## 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/Slider/Slider.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Slider from "./Slider";
+import { I18nProvider } from "react-aria-components";
+import { expect, within } from "storybook/test";
+import { useState } from "react";
+
+const meta: Meta<typeof Slider> = {
+  component: Slider,
+  argTypes: {
+    label: { control: "text" },
+    value: { control: "text" },
+    description: { control: "text" },
+    helperText: { control: "text" },
+    errorHelperText: { control: "text" },
+    successHelperText: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story, context) => (
+      <I18nProvider locale={context.parameters.locale || "en-EN"}>
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+  render: (args) => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<Array<number>>([30]);
+
+      return (
+        <>
+          <Slider {...args} onChange={setValue} value={value} />
+          <p>Debug state value: {JSON.stringify(value)}</p>
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    label: "Participants",
+    thumbLabels: ["Number of participants"],
+    minValue: 0,
+    maxValue: 100,
+    step: 1,
+    isDisabled: false,
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    description: "Select the number of participants",
+    helperText: "This is a helper text",
+    helperTextIcon: "help_outline",
+    errorHelperTextIcon: "error_outline",
+    style: {
+      minWidth: 441,
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Participants");
+    await canvas.findByLabelText("Number of participants");
+    await canvas.findByText("This is a helper text");
+    await canvas.findByText("Select the number of participants");
+    await expect(
+      canvas.getByLabelText("Value for Number of participants"),
+    ).toHaveValue("30");
+    await canvas.findByText("Debug state value: [30]");
+  },
+};
+
+export const Disabled: StoryObj<typeof Slider> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+};
+
+export const WithInvalid: StoryObj<typeof Slider> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+  },
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<Array<number>>([30]);
+      const isInvalid = (value: Array<number>) => value[0] < 50;
+
+      return (
+        <>
+          <Slider
+            label="Participants"
+            thumbLabels={["Number of participants"]}
+            onChange={setValue}
+            value={value}
+            isInvalid={isInvalid}
+            errorHelperText={
+              isInvalid(value)
+                ? "Less than 50 participants may cause the event to be cancelled"
+                : undefined
+            }
+            errorHelperTextIcon="error_outline"
+            style={{ minWidth: 441 }}
+          />
+          <p>Debug state value: {JSON.stringify(value)}</p>
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const WithTrackDots: StoryObj<typeof Slider> = {
+  args: {
+    ...Playground.args,
+    withTrackDots: true,
+    step: 10,
+  },
+};
+```
+
+## 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 Slider from "../Slider";
+import { expect, userEvent, within } from "storybook/test";
+import { useState } from "react";
+import * as SliderStories from "../Slider.stories";
+
+const meta: Meta<typeof Slider> = {
+  ...SliderStories.default,
+  component: Slider,
+  render: undefined,
+  parameters: {
+    layout: "padded",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ControlledExample: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState([30]);
+
+      return (
+        <>
+          <Slider
+            label="Participants"
+            onChange={setValue}
+            value={value}
+            thumbLabels={["Number of participants"]}
+          />
+          <p>Debug state value: {JSON.stringify(value)}</p>
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const ControlledExampleTests: Story = {
+  render: ControlledExample.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    const input = await canvas.findByLabelText(
+      "Value for Number of participants",
+    );
+    await expect(input).toHaveValue("30");
+    await canvas.findByText("Debug state value: [30]");
+    await user.clear(input);
+    await user.type(input, "40");
+    await expect(input).toHaveValue("40");
+    await canvas.findByText("Debug state value: [40]");
+  },
+};
+
+export const ControlledRangeExample: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState([9, 17]);
+
+      return (
+        <>
+          <Slider
+            label="Opening hours"
+            onChange={setValue}
+            value={value}
+            thumbLabels={["From", "To"]}
+            minValue={0}
+            maxValue={24}
+            step={1}
+          />
+          <p>Debug state value: {JSON.stringify(value)}</p>
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const ExampleWithTrackDots: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState([9, 17]);
+
+      return (
+        <>
+          <Slider
+            label="Opening hours"
+            value={value}
+            onChange={setValue}
+            thumbLabels={["From", "To"]}
+            minValue={0}
+            maxValue={24}
+            step={1}
+            withTrackDots
+          />
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const ExampleWithUpdateStepOnChangeEnd: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState([9, 17]);
+
+      return (
+        <>
+          <Slider
+            label="Opening hours"
+            value={value}
+            onChangeEnd={setValue} // Update the step only when the user stops dragging the slider
+            thumbLabels={["From", "To"]}
+            minValue={0}
+            maxValue={24}
+            step={1}
+          />
+          <p>Debug state value: {JSON.stringify(value)}</p>
+        </>
+      );
+    };
+    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 Slider from "./Slider.stories";
+import * as SliderTests from "./tests/Slider.stories";
+
+<Meta of={Slider} />
+
+# Slider
+
+<Canvas of={Slider.Playground} />
+
+<Controls of={Slider.Playground} />
+
+The `<input type="range">` HTML element can be used to build a slider, however it is very difficult to style cross browser.
+
+Slider helps achieve accessible sliders that can be styled as needed.
+
+- **Customizable** – Support for one or multiple thumbs. The whole slider, or individual thumbs can be disabled. Custom minimum, maximum, and step values are supported as well.
+- **High quality interactions** – Mouse, touch, and keyboard input is supported. Pressing the track moves the nearest thumb to that position. Text selection and touch scrolling are prevented while dragging.
+- **Touch friendly** – Multiple thumbs or sliders can be dragged at once on multi-touch screens.
+- **Accessible** – Slider thumbs use visually hidden `<input>` elements for mobile screen reader support, and HTML form integration. `<label>` and `<output>` elements are automatically associated to provide context for assistive technologies.
+
+## Usage
+
+The Slider component must be used as a controlled component. So you need to handle the `onChange` event and update the `value` prop accordingly.
+
+The value is an array of numbers. If you need a single thumb slider, you can pass a single number in the array.
+Pass two numbers in the array to get a range slider.
+
+Here is an example of a **single-thumb slider** :
+
+<Canvas of={SliderTests.ControlledExample} sourceState="shown" />
+
+And here is an example of a **range slider** :
+
+<Canvas of={SliderTests.ControlledRangeExample} sourceState="shown" />
+
+## Invalid feedback
+
+In case where you have some values that are selectionable via the Slider but may cause issues,
+you can give a feedback to the user by making the slider red.
+
+Here is an example of a range slider with invalid feedback :
+
+<Canvas of={Slider.WithInvalid} sourceState="shown" />
+
+## With track dots
+
+You can display dots on the track to help the user know the steps of the slider.
+It is recommended to use it only if you don't have a lot of possible steps.
+
+<Canvas of={SliderTests.ExampleWithTrackDots} sourceState="shown" />
+
+## Update state only when the user stops dragging
+
+You can update the state only when the user stops dragging the slider by using the `onChangeEnd` prop.
+
+This is usefull if you want to avoid the many re-renderings of the parent component while the user is dragging the Slider.
+Or even more important if the slider value is used for an API call for example (to avoid sending too many requests).
+
+<Canvas of={SliderTests.ExampleWithUpdateStepOnChangeEnd} sourceState="shown" />
+
+## How to test the slider
+
+The best way to test the slider is to use the input(s) directly.
+
+They can be targeted by their label text (passed by the thumbLabels prop).
+
+For example, take the ControlledExample story :
+
+<Source of={SliderTests.ControlledExample} type="code" dark />
+
+You can target the input with the label "Number of participants" and change its value like this :
+
+<Source of={SliderTests.ControlledExampleTests} type="code" dark />
+```

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

@@ -0,0 +1,104 @@
+# Stepper
+
+## 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/Stepper/Stepper.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { within } from "storybook/test";
+import Stepper from "./Stepper";
+import Step from "./Step/Step";
+import { StorybookSwapComponent } from "./Step/Step.styled";
+
+const meta: Meta<typeof Stepper> = {
+  component: Stepper,
+  argTypes: {
+    children: { control: false },
+  },
+  tags: ["autodocs"],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    orientation: "horizontal",
+    children: (
+      <>
+        <Step title="Step 1" isCompleted href="/step-1" />
+        <Step
+          title="Step 2"
+          description="Step 2 description"
+          isActive
+          href="/step-2"
+          nature="warning"
+        />
+        <Step
+          title="Step 3"
+          description="Step 3 description"
+          href="/step-3"
+          nature="negative"
+        >
+          <StorybookSwapComponent>Step 3 content</StorybookSwapComponent>
+        </Step>
+        <Step
+          title="Step 4"
+          description="Disabled step"
+          isDisabled
+          href="/step-4"
+        />
+      </>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Step 1");
+    await canvas.findByText("Step 2");
+    await canvas.findByText("Step 2 description");
+    await canvas.findByText("Step 3");
+    await canvas.findByText("Step 3 description");
+    await canvas.findByText("Step 3 content");
+  },
+};
+
+export const Vertical: Story = {
+  args: {
+    ...Playground.args,
+    orientation: "vertical",
+  },
+};
+
+export const Numbered: Story = {
+  args: {
+    ...Playground.args,
+    children: (
+      <>
+        <Step title="Step 1" isCompleted indicator={1} />
+        <Step
+          title="Step 2"
+          description="Step 2 description"
+          isActive
+          indicator={2}
+        />
+        <Step title="Step 3" description="Step 3 description" indicator={3} />
+        <Step
+          title="Step 4"
+          description="Disabled step"
+          isDisabled
+          indicator={4}
+        />
+      </>
+    ),
+  },
+};
+```