@agregio-solutions/design-system 1.91.0 → 1.92.0

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

@@ -0,0 +1,481 @@
+# List
+
+## 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/List/List.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import List from "./List";
+import EmptyState from "../EmptyState/EmptyState";
+import Button from "../Button/Button";
+
+const meta: Meta<typeof List> = {
+  component: List,
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 523 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    "aria-label": "Batchs and tasks",
+    sections: [
+      {
+        id: "batchs",
+        title: "Batchs",
+        items: [
+          {
+            title: "Batch 12345",
+            id: "batch-12345",
+            icon: "arrow_forward",
+            subtitle: "Lorem Ipsum dolor sit amet",
+            href: "https://www.google.com?q=batch-12345",
+            tagProps: {
+              children: "[Insert tag]",
+              iconLeft: "help_outline",
+            },
+          },
+          {
+            title: "Batch 4567",
+            id: "batch-4567",
+            icon: "arrow_forward",
+            subtitle: "Lorem Ipsum dolor sit amet",
+            href: "https://www.google.com?q=batch-4567",
+            tagProps: {
+              children: "[Insert tag]",
+              iconLeft: "help_outline",
+            },
+          },
+        ],
+      },
+      {
+        id: "tâches",
+        title: "Tâches",
+        items: [
+          {
+            title: "Tâche 1234",
+            id: "tâche-1234",
+            icon: "arrow_forward",
+            subtitle: "Lorem Ipsum dolor sit amet",
+            href: "https://www.google.com?q=tâche-1234",
+            tagProps: {
+              children: "[Insert tag]",
+              iconLeft: "help_outline",
+            },
+          },
+          {
+            title: "Tâche 4567",
+            id: "tâche-4567",
+            icon: "arrow_forward",
+            subtitle: "Lorem Ipsum dolor sit amet",
+            href: "https://www.google.com?q=tâche-4567",
+            tagProps: {
+              children: "[Insert tag]",
+              iconLeft: "help_outline",
+            },
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Batchs");
+    await canvas.findByText("Batch 12345");
+    await canvas.findByText("Batch 4567");
+    await canvas.findByText("Tâches");
+    await canvas.findByText("Tâche 1234");
+    await canvas.findByText("Tâche 4567");
+  },
+};
+
+export const PixelPerfect: Story = {
+  args: {
+    "aria-label": "10 items",
+    sections: [
+      {
+        id: "tâches",
+        title: "[Insert title here]",
+        items: new Array(10).fill(0).map((_, index) => ({
+          title: `[Insert title ${index}]`,
+          id: `id-${index}`,
+          icon: "settings",
+          subtitle: "[insert subtitle]",
+          tagProps: {
+            children: "[Insert tag]",
+            iconLeft: "help_outline",
+          },
+        })),
+      },
+    ],
+  },
+};
+
+export const WithThreeLists: Story = {
+  args: {
+    "aria-label": "Recent projects, members, and resources",
+    sections: [
+      {
+        id: "projets",
+        title: "Recent Projects",
+        items: [
+          {
+            title: "E-commerce Platform",
+            id: "e-commerce-platform",
+            icon: "arrow_forward",
+            subtitle: "Online store with payment integration",
+            tagProps: {
+              children: "Active",
+              iconLeft: "help_outline",
+            },
+          },
+          {
+            title: "Mobile App",
+            id: "mobile-app",
+            icon: "add_box",
+            subtitle: "Cross-platform React Native app",
+            tagProps: {
+              children: "In Progress",
+              iconLeft: "bolt",
+            },
+          },
+        ],
+      },
+      {
+        id: "membres",
+        items: [
+          {
+            title: "Alice Johnson",
+            id: "alice-johnson",
+            icon: "calendar_today",
+            subtitle: "Senior Frontend Developer",
+            tagProps: {
+              children: "Lead",
+              iconLeft: "star",
+            },
+          },
+          {
+            title: "Bob Smith",
+            id: "bob-smith",
+            icon: "business",
+            subtitle: "Backend Developer",
+            tagProps: {
+              children: "Member",
+              iconLeft: "fiber_new",
+            },
+          },
+          {
+            title: "Carol Davis",
+            id: "carol-davis",
+            icon: "swap_horiz",
+            subtitle: "UI/UX Designer",
+            tagProps: {
+              children: "Contractor",
+              iconLeft: "undo",
+            },
+          },
+        ],
+      },
+      {
+        id: "ressources",
+        title: "Resources",
+        items: [
+          {
+            title: "Design System Documentation",
+            id: "design-system-documentation",
+            subtitle: "Complete guide to our design tokens and components",
+            tagProps: {
+              children: "Updated",
+            },
+          },
+          {
+            title: "API Documentation",
+            id: "api-documentation",
+            subtitle: "REST API endpoints and authentication",
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Recent Projects");
+    await canvas.findByText("E-commerce Platform");
+    await canvas.findByText("Mobile App");
+    await canvas.findByText("Alice Johnson");
+    await canvas.findByText("Bob Smith");
+    await canvas.findByText("Carol Davis");
+    await canvas.findByText("Resources");
+    await canvas.findByText("Design System Documentation");
+    await canvas.findByText("API Documentation");
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    "aria-label": "Empty list",
+    sections: [],
+  },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.firstElementChild).toBeEmptyDOMElement();
+  },
+};
+
+export const EmptyWithEmptyState: Story = {
+  args: {
+    ...Empty.args,
+    renderEmptyState: () => (
+      <EmptyState
+        icon="help_outline"
+        title="No items"
+        description="Sorry! We couldn't find any items."
+      >
+        <Button mode="primary" text="Action 1" />
+        <Button mode="secondary" text="Action 2" />
+      </EmptyState>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("No items");
+    await canvas.findByText("Sorry! We couldn't find any items.");
+    await canvas.findByText("Action 1");
+    await canvas.findByText("Action 2");
+  },
+};
+```
+
+## 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 { within } from "storybook/test";
+import List from "../List";
+import * as ListStories from "../List.stories";
+
+const meta: Meta<typeof List> = {
+  ...ListStories.default,
+  parameters: {
+    ...ListStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+  component: List,
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ExampleUsage: Story = {
+  render: () => {
+    return (
+      <List
+        aria-label="Liste de batchs et de tâches"
+        sections={[
+          {
+            id: "batchs",
+            title: "Batchs",
+            items: [
+              {
+                title: "Batch 12345",
+                id: "batch-12345",
+                icon: "arrow_forward",
+                subtitle: "Lorem Ipsum dolor sit amet",
+                href: "https://www.google.com?q=batch-12345",
+                tagProps: {
+                  children: "[Insert tag]",
+                  iconLeft: "help_outline",
+                },
+              },
+              {
+                title: "Batch 4567",
+                id: "batch-4567",
+                icon: "arrow_forward",
+                subtitle: "Lorem Ipsum dolor sit amet",
+                href: "https://www.google.com?q=batch-4567",
+                tagProps: {
+                  children: "[Insert tag]",
+                  iconLeft: "help_outline",
+                },
+              },
+            ],
+          },
+          {
+            id: "tâches",
+            title: "Tâches",
+            items: [
+              {
+                title: "Tâche 1234",
+                id: "tâche-1234",
+                icon: "arrow_forward",
+                subtitle: "Lorem Ipsum dolor sit amet",
+                href: "https://www.google.com?q=tâche-1234",
+                tagProps: {
+                  children: "[Insert tag]",
+                  iconLeft: "help_outline",
+                },
+              },
+              {
+                title: "Tâche 4567",
+                id: "tâche-4567",
+                icon: "arrow_forward",
+                subtitle: "Lorem Ipsum dolor sit amet",
+                href: "https://www.google.com?q=tâche-4567",
+                tagProps: {
+                  children: "[Insert tag]",
+                  iconLeft: "help_outline",
+                },
+              },
+            ],
+          },
+        ]}
+      />
+    );
+  },
+};
+
+export const WithVariations: Story = {
+  args: {
+    "aria-label": "Mixed content",
+    sections: [
+      {
+        id: "mixed-content",
+        title: "Mixed Content Examples",
+        items: [
+          {
+            title: "Item with all properties",
+            id: "item-with-all-properties",
+            icon: "star",
+            subtitle: "This item has an icon, subtitle, and tag",
+            tagProps: {
+              children: "Complete",
+              iconLeft: "check",
+            },
+          },
+          {
+            title:
+              "Item without icon but with long subtitle text that might wrap to multiple lines to test the layout behavior",
+            id: "item-without-icon-but-with-long-subtitle",
+            subtitle:
+              "This item has no icon but includes a very long subtitle that demonstrates how the component handles text overflow and wrapping in different scenarios",
+            tagProps: {
+              children: "No Icon",
+              iconLeft: "help_outline",
+            },
+          },
+          {
+            title: "Item without tag",
+            id: "item-without-tag",
+            icon: "settings",
+            subtitle: "This item has an icon and subtitle but no tag",
+          },
+          {
+            title: "Minimal item with only title",
+            id: "minimal-item-with-only-title",
+          },
+          {
+            title:
+              "Item with very long title that might need to be truncated or wrapped depending on the container width",
+            id: "item-with-very-long-title",
+            subtitle: "Short subtitle",
+          },
+          {
+            title: "Item with special characters",
+            id: "item-with-special-characters",
+            icon: "language",
+            subtitle: "Test with émojis 🎉 and special chars: & < > \" '",
+          },
+        ],
+      },
+      {
+        id: "long-title",
+        title:
+          "Long section title that might need to be truncated or wrapped depending on the container width",
+        items: [
+          {
+            title:
+              "Long title that might need to be truncated or wrapped depending on the container width",
+            id: "long-title-item",
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Mixed Content Examples");
+    await canvas.findByText("Item with all properties");
+    await canvas.findByText("Minimal item with only title");
+  },
+};
+```
+
+## 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, Controls, Source, Canvas } from "@storybook/addon-docs/blocks";
+import * as ListStories from "./List.stories";
+import * as ListItem from "./components/ListItem/ListItem.stories";
+import * as ListStoriesTests from "./tests/List.stories";
+
+<Meta of={ListStories} />
+
+# List
+
+- **Item selection** – Single or multiple selection, disabled rows, and both toggle and replace selection behaviors.
+- **Keyboard navigation** – List items can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
+- **Touch friendly** – Selection behavior adapts depending on the device. For example, selection occurs on mouse down but on touch up, which is consistent with native conventions.
+- **Accessible** – Follows the ARIA listbox pattern, with support for items and sections, and slots for label and description elements within each item for improved screen reader announcement.
+
+<Canvas of={ListStories.Playground} />
+<Controls of={ListStories.Playground} />
+
+## ListItemProps
+
+<Controls of={ListItem.Playground} />
+
+## Example usage
+
+The usage is pretty simple, click on **"show code"** in the example above to see the code.
+
+## Actions on items / links
+
+You can add an action on an item by passing a function to the `onAction` prop.
+
+If your item is a link, you can pass a `href` prop to the item (in combination with `target`, `download` and `routerOptions` props).
+
+## About icons and descriptions
+
+For visual harmony, it is recommended, for all the items in a section, to :
+
+- either all items have no icon, or all items have an icon.
+- either all items have no description, or all items have a description.
+
+Mixing items with and without icons or descriptions is not recommended (because it looks weird).
+```

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

@@ -0,0 +1,53 @@
+# Loader
+
+## 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/Loader/Loader.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Loader from "./Loader";
+
+const meta = {
+  component: Loader,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof Loader>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    size: "medium",
+  },
+};
+
+export const Small: Story = {
+  args: {
+    size: "small",
+  },
+};
+
+export const Medium: Story = {
+  args: {
+    size: "medium",
+  },
+};
+
+export const Large: Story = {
+  args: {
+    size: "large",
+  },
+};
+```