@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,148 @@
+# LinearProgressBar
+
+## 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/LinearProgressBar/LinearProgressBar.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { within, expect } from "storybook/test";
+import ProgressBar from "./LinearProgressBar";
+import { useEffect } from "react";
+import { useState } from "react";
+
+const meta: Meta<typeof ProgressBar> = {
+  component: ProgressBar,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  argTypes: {
+    title: { control: "text" },
+    description: { control: "text" },
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 220 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    title: "Progress title",
+    percentage: 25,
+    description: "Description",
+    hidePercentValue: false,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+
+    await canvas.findByText("Progress title");
+    await canvas.findByText("Description");
+    await canvas.findByText("25%");
+    const container = await canvas.findByTestId("progress-bar-Progress title");
+    const filler = container.firstElementChild as HTMLElement;
+
+    await expect(
+      Math.round((filler.clientWidth / container.clientWidth) * 100),
+    ).toEqual(args.percentage);
+  },
+};
+
+export const Small: Story = {
+  args: {
+    ...Playground.args,
+    size: "small",
+  },
+};
+
+export const ZeroPercent: Story = {
+  args: {
+    ...Playground.args,
+    percentage: 0,
+  },
+};
+
+export const HundredPercent: Story = {
+  args: {
+    ...Playground.args,
+    percentage: 100,
+  },
+};
+
+export const Error: Story = {
+  args: {
+    ...Playground.args,
+    nature: "negative",
+    percentage: 100,
+    hidePercentValue: true,
+  },
+};
+
+export const Success: Story = {
+  args: {
+    ...Playground.args,
+    nature: "positive",
+    percentage: 100,
+    hidePercentValue: true,
+  },
+};
+
+export const OverflowingText: Story = {
+  args: {
+    ...Playground.args,
+    nature: "positive",
+    title: "This is a very long title that overflows and should be handled",
+    description:
+      "This is a very long description that overflows and should be handled",
+  },
+};
+
+export const AnimationProgress: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: () => {
+    const ParentComponent = () => {
+      const [progress, setProgress] = useState(0);
+
+      useEffect(() => {
+        const timer = setInterval(() => {
+          setProgress((oldProgress) => {
+            if (oldProgress === 100) {
+              return 0;
+            }
+            const diff = Math.random() * 10;
+            return Math.min(oldProgress + diff, 100);
+          });
+        }, 500);
+
+        return () => {
+          clearInterval(timer);
+        };
+      }, []);
+
+      return <ProgressBar title="Progress title" percentage={progress} />;
+    };
+
+    return <ParentComponent />;
+  },
+};
+```

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

@@ -0,0 +1,206 @@
+# Link
+
+## 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/Link/Link.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Link from "./Link";
+import { within, expect } from "storybook/test";
+
+const meta: Meta<typeof Link> = {
+  component: Link,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    children: { control: "text" },
+    href: { control: "text" },
+    download: { control: "text" },
+    className: { control: "text" },
+    target: { control: false },
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Link> = {
+  args: {
+    children: "Label link",
+    href: "https://example.com",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      canvas.getByText(args.children as string).parentElement,
+    ).toHaveAttribute("href", args.href);
+  },
+};
+
+export const WithIcon: StoryObj<typeof Link> = {
+  args: {
+    ...Playground.args,
+    showLinkIcon: true,
+  },
+};
+
+export const Informative: StoryObj<typeof Link> = {
+  args: {
+    ...WithIcon.args,
+    nature: "informative",
+  },
+};
+
+export const Positive: StoryObj<typeof Link> = {
+  args: {
+    ...WithIcon.args,
+    nature: "positive",
+  },
+};
+
+export const Negative: StoryObj<typeof Link> = {
+  args: {
+    ...WithIcon.args,
+    nature: "negative",
+  },
+};
+
+export const Warning: StoryObj<typeof Link> = {
+  args: {
+    ...WithIcon.args,
+    nature: "warning",
+  },
+};
+```
+
+## 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 Link from "../Link";
+import { within, expect, userEvent } from "storybook/test";
+import { Route, Routes } from "react-router-dom";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Link> = {
+  component: Link,
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ShouldWorkWithReactRouter: StoryObj<typeof Link> = {
+  render: () => {
+    const Demo = () => {
+      return (
+        <>
+          <Link href="/page-1">Page 1</Link>
+          <Link href="/page-2">Page 2</Link>
+          <Link href="/page-3">Page 3</Link>
+
+          <Routes>
+            <Route path="/page-1" element={<div>Content page 1</div>} />
+            <Route path="/page-2" element={<div>Content page 2</div>} />
+            <Route path="/page-3" element={<div>Content page 3</div>} />
+          </Routes>
+        </>
+      );
+    };
+
+    const Pages = () => (
+      <Routes>
+        <Route path="/*" element={<Demo />} />
+      </Routes>
+    );
+
+    return <Pages />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Page 1");
+    await expect(canvas.getByText("Page 1").parentElement).toHaveAttribute(
+      "href",
+      "/page-1",
+    );
+    await expect(canvas.getByText("Page 2").parentElement).toHaveAttribute(
+      "href",
+      "/page-2",
+    );
+    await expect(canvas.getByText("Page 3").parentElement).toHaveAttribute(
+      "href",
+      "/page-3",
+    );
+    await expectNotPresent(() => canvas.queryByText("Content page 1"));
+    await expectNotPresent(() => canvas.queryByText("Content page 2"));
+    await expectNotPresent(() => canvas.queryByText("Content page 3"));
+
+    await user.click(canvas.getByText("Page 1"));
+    await expect(canvas.getByText("Content page 1")).toBeInTheDocument();
+    await expectNotPresent(() => canvas.queryByText("Content page 2"));
+    await expectNotPresent(() => canvas.queryByText("Content page 3"));
+
+    await user.click(canvas.getByText("Page 2"));
+    await expect(canvas.getByText("Content page 2")).toBeInTheDocument();
+    await expectNotPresent(() => canvas.queryByText("Content page 1"));
+    await expectNotPresent(() => canvas.queryByText("Content page 3"));
+
+    await user.click(canvas.getByText("Page 3"));
+    await expect(canvas.getByText("Content page 3")).toBeInTheDocument();
+    await expectNotPresent(() => canvas.queryByText("Content page 1"));
+    await expectNotPresent(() => canvas.queryByText("Content page 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 } from "@storybook/addon-docs/blocks";
+
+import * as Link from "./Link.stories";
+
+<Meta of={Link} />
+
+# Link
+
+<Canvas of={Link.Playground} />
+
+## Link props
+
+<Controls of={Link.Playground} />
+
+## Integration with framework routers
+
+It is possible to make this `Link` component work seamlessly with your router (like `react-router-dom`) and thus benefit from client-side routing.
+
+The first requirement is to have the [RouterProvider](?path=/docs/components-routerprovider--docs) configured in your project.
+
+And that's it! With this provider, any `Link` component will behave like your framework-specific link.
+You can even pass router-specific props with the `routerOptions` prop, like:
+
+```tsx
+import { Link } from "@agregio-solutions/design-system";
+
+<Link href="/some-url" routerOptions={{ replace: true }}>
+  {/* ☝️ replace option in the react-router-dom NavLink ! */}
+  Go!
+</Link>;
+```
+
+<Stories />
+````