@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,167 @@
+# NavigationItem
+
+## 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/NavigationItem/NavigationItem.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 NavigationItem from "./NavigationItem";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+import { NavigationProvider } from "../Navigation/context";
+
+const meta = {
+  component: NavigationItem,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "dark" },
+  },
+  argTypes: {
+    href: { control: "text" },
+    subLinks: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <NavigationProvider>
+        <Story />
+      </NavigationProvider>
+    ),
+  ],
+} satisfies Meta<typeof NavigationItem>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Link: Story = {
+  args: {
+    label: "Libellé",
+    href: "/some-url",
+    iconLeft: "home",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(args.label as string);
+    await expect(
+      canvas.getByText(args.label as string).parentElement,
+    ).toHaveAttribute("href", args.href);
+  },
+};
+
+export const ActiveLink: Story = {
+  args: {
+    ...Link.args,
+    isActive: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      canvas.getByText(args.label as string).parentElement,
+    ).toHaveAttribute("data-active", "true");
+  },
+};
+
+export const Dropdown: Story = {
+  args: {
+    ...Link.args,
+    href: undefined,
+    subLinks: [
+      {
+        label: "Sous-libellé 1",
+        href: "/some-url-1",
+      },
+      {
+        label: "Sous-libellé 2",
+        href: "/some-url-2",
+      },
+    ],
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(args.label as string);
+    await expect(
+      canvas.getByText(args.label as string).parentElement,
+    ).not.toHaveAttribute("href");
+    await expectNotPresent(() => canvas.queryByText("Sous-libellé 1"));
+    await expectNotPresent(() => canvas.queryByText("Sous-libellé 2"));
+  },
+};
+
+export const DropdownOpenByDefault: Story = {
+  args: {
+    ...Dropdown.args,
+    defaultOpen: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(args.label as string);
+    await expect(
+      canvas.getByText(args.label as string).parentElement,
+    ).not.toHaveAttribute("href");
+    await expect(
+      canvas.getByText("Sous-libellé 1").parentElement,
+    ).toHaveAttribute("href", "/some-url-1");
+    await expect(
+      canvas.getByText("Sous-libellé 2").parentElement,
+    ).toHaveAttribute("href", "/some-url-2");
+  },
+};
+
+export const LinkCollapsed: Story = {
+  decorators: [
+    (Story) => (
+      <NavigationProvider initialIsCollapsed={true}>
+        <Story />
+      </NavigationProvider>
+    ),
+  ],
+  args: {
+    ...Link.args,
+  },
+};
+
+export const LinkCollapsedActive: Story = {
+  decorators: [
+    (Story) => (
+      <NavigationProvider initialIsCollapsed={true}>
+        <Story />
+      </NavigationProvider>
+    ),
+  ],
+  args: {
+    ...Link.args,
+    isActive: true,
+  },
+};
+
+export const WithReactNodeLabel: Story = {
+  args: {
+    ...Link.args,
+    "aria-label": "Indisponibilités",
+    label: (
+      <div>
+        <div>Tableau de bord</div>
+        <div style={{ fontSize: "10px", lineHeight: "12px" }}>
+          Indisponibilités
+        </div>
+      </div>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Indisponibilités");
+    await canvas.findByText("Tableau de bord");
+  },
+};
+```

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

@@ -0,0 +1,206 @@
+# NotificationCard
+
+## 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/NotificationCard/NotificationCard.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { fn, within, expect } from "storybook/test";
+import NotificationCard from "./NotificationCard";
+import Button from "../Button/Button";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof NotificationCard> = {
+  component: NotificationCard,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: "400px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    title: "[Insert title]",
+    description: "[Insert description]",
+    dateAndTime: "[Day & Hour] • [Timer]",
+    isRead: false,
+    type: "default",
+    menuActions: [
+      { text: "Action 1", onClick: fn() },
+      { text: "Action 2", onClick: fn() },
+    ],
+    children: (
+      <>
+        <Button
+          text="[Insert name]"
+          mode="secondary"
+          size="small"
+          onClick={fn()}
+        />
+        <Button
+          text="[Insert name]"
+          mode="secondary"
+          size="small"
+          onClick={fn()}
+        />
+      </>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("[Insert title]");
+    await canvas.findByText("[Insert description]");
+    await canvas.findByText("[Day & Hour] • [Timer]");
+    await expect(await canvas.findAllByText("[Insert name]")).toHaveLength(2);
+    await canvas.findByTestId("unread-badge");
+  },
+};
+
+export const ReadNotification: Story = {
+  args: {
+    ...Playground.args,
+    isRead: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expectNotPresent(() => canvas.queryByTestId("unread-badge"));
+  },
+};
+
+export const WithAvatar: Story = {
+  args: {
+    ...Playground.args,
+    avatarUrl: "https://i.pravatar.cc/300?img=5",
+    avatarAlt: "John Doe",
+    title: "Jesse Pokman",
+    description: "You have a new message",
+    dateAndTime: "15 min ago",
+    children: (
+      <Button text="View" mode="secondary" size="small" onClick={fn()} />
+    ),
+    menuActions: [
+      { text: "Mark as read", onClick: fn() },
+      { text: "Delete", onClick: fn() },
+    ],
+  },
+};
+
+export const Minimal: Story = {
+  args: {
+    title: "Minimal example",
+    isRead: true,
+    menuActions: [],
+  },
+};
+
+export const InformativeUnread: Story = {
+  args: {
+    ...Playground.args,
+    isRead: false,
+    type: "informative",
+  },
+};
+
+export const InformativeRead: Story = {
+  args: {
+    ...Playground.args,
+    isRead: true,
+    type: "informative",
+  },
+};
+
+export const NegativeUnread: Story = {
+  args: {
+    ...Playground.args,
+    isRead: false,
+    type: "negative",
+  },
+};
+
+export const NegativeRead: Story = {
+  args: {
+    ...Playground.args,
+    isRead: true,
+    type: "negative",
+  },
+};
+
+export const WarningUnread: Story = {
+  args: {
+    ...Playground.args,
+    isRead: false,
+    type: "warning",
+  },
+};
+
+export const WarningRead: Story = {
+  args: {
+    ...Playground.args,
+    isRead: true,
+    type: "warning",
+  },
+};
+
+export const PositiveUnread: Story = {
+  args: {
+    ...Playground.args,
+    isRead: false,
+    type: "positive",
+  },
+};
+
+export const PositiveRead: Story = {
+  args: {
+    ...Playground.args,
+    isRead: true,
+    type: "positive",
+  },
+};
+
+export const WithCustomIcon: Story = {
+  args: {
+    ...Playground.args,
+    customIcon: "bolt",
+  },
+};
+
+export const WithCloseButton: Story = {
+  args: {
+    ...Playground.args,
+    menuActions: undefined,
+    isRead: true,
+    onClose: fn(),
+  },
+};
+
+export const WithLongContent: Story = {
+  args: {
+    ...Playground.args,
+    title:
+      "This is a very long title that should overflow. This is a very long title that should overflow",
+    description:
+      "This is a very long description that should overflow. This is a very long description that should overflow",
+    dateAndTime:
+      "This is a very long date and time that should overflow. This is a very long date and time that should overflow",
+  },
+};
+```

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

@@ -0,0 +1,240 @@
+# Notifications
+
+## 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/Notifications/Notifications.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { fn, userEvent, within } from "storybook/test";
+import Notifications from "./Notifications";
+import NotificationCard from "../NotificationCard/NotificationCard";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+import { I18nProvider } from "react-aria-components";
+import Toaster from "../Toaster/Toaster";
+import { toast } from "sonner";
+import { useEffect } from "react";
+
+const meta: Meta<typeof Notifications> = {
+  component: Notifications,
+  argTypes: {
+    children: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en">
+        <Toaster />
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    triggerProps: {
+      iconLeft: "notifications_none",
+      size: "small",
+      mode: "tertiary",
+    },
+    nbOfReadNotifications: 1,
+    nbOfUnreadNotifications: 2,
+    onParametersClick: fn(),
+    onMarkAllAsReadClick: fn(),
+    children: (
+      <>
+        <NotificationCard
+          title="Notification 1"
+          isRead={false}
+          description="Description 1"
+          dateAndTime="16/07/2025 • 10:00"
+        />
+        <NotificationCard
+          title="Notification 2"
+          isRead={true}
+          description="Description 2"
+          dateAndTime="18/07/2025 • 11:00"
+        />
+        <NotificationCard
+          title="Notification 3"
+          isRead={false}
+          description="Description 3"
+          dateAndTime="21/07/2025 • 13:00"
+        />
+      </>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByRole("button"));
+    await canvas.findByText("Notifications");
+    await canvas.findByText("Mark all as read");
+    await canvas.findByLabelText("Parameters");
+    await canvas.findByLabelText("Close");
+    await canvas.findByText("Notification 1");
+    await canvas.findByText("Notification 2");
+    await canvas.findByText("Notification 3");
+  },
+};
+
+export const LotsOfItems: Story = {
+  args: {
+    ...Playground.args,
+    nbOfReadNotifications: 20,
+    nbOfUnreadNotifications: 20,
+    children: (
+      <>
+        {Array.from({ length: 20 }).map((_, index) => (
+          <NotificationCard
+            key={index}
+            title={`Notification ${index + 1}`}
+            isRead={false}
+            description={`Description ${index + 1}`}
+            dateAndTime={`${index + 1}/07/2025 • ${index + 1}:00`}
+            menuActions={[{ text: "Mark as read", onClick: fn() }]}
+          />
+        ))}
+      </>
+    ),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByRole("button"));
+  },
+};
+
+export const WithoutFooter: Story = {
+  args: {
+    ...Playground.args,
+    onParametersClick: undefined,
+    onMarkAllAsReadClick: undefined,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByRole("button"));
+    await canvas.findByText("Notifications");
+    await canvas.findByText("Notification 1");
+    await canvas.findByText("Notification 2");
+    await canvas.findByText("Notification 3");
+    await canvas.findByLabelText("Close");
+    await expectNotPresent(() => canvas.queryByText("Mark all as read"));
+    await expectNotPresent(() => canvas.queryByLabelText("Parameters"));
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    ...Playground.args,
+    children: undefined,
+    isLoading: true,
+    nbOfReadNotifications: 0,
+    nbOfUnreadNotifications: 0,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByRole("button"));
+    await canvas.findByText("Notifications");
+    await canvas.findByLabelText("Close");
+    await expectNotPresent(() => canvas.queryByText("Mark all as read"));
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    ...Playground.args,
+    children: undefined,
+    nbOfReadNotifications: 0,
+    nbOfUnreadNotifications: 0,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ delay: 25 });
+    await user.click(canvas.getByRole("button"));
+  },
+};
+
+export const StandaloneNotification: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      useEffect(() => {
+        toast.custom(
+          (toastId) => (
+            <NotificationCard
+              title="Success message"
+              isRead={false}
+              description="Description"
+              dateAndTime="16/07/2025 • 10:00"
+              onClose={() => toast.dismiss(toastId)}
+              style={{ width: 400 }}
+            />
+          ),
+          {
+            unstyled: true,
+            position: "top-right",
+            closeButton: false,
+          },
+        );
+      }, []);
+      return <div />;
+    };
+    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 { Meta, Controls, Source, Canvas } from "@storybook/addon-docs/blocks";
+
+import * as Notifications from "./Notifications.stories";
+import * as NotificationsTests from "./tests/NotificationsTests.stories";
+
+<Meta of={Notifications} />
+
+# Notifications
+
+<Canvas of={Notifications.Playground} />
+<Controls of={Notifications.Playground} />
+
+## Full featured example usage
+
+Bellow you can find a full featured example usage of the Notifications component.
+
+- integration within a Header component
+- integration with useQuery and useMutation (from Tanstack Query) to handle fetching/updating the notifications
+- generated using composition, to allow you advanced customization (see performance section below)
+
+The dataset is abstracted away, please refer to the [NotificationCard component](?path=/docs/components-notificationcard--docs) to see all available props.
+
+<Source of={NotificationsTests.FullImplementationExample} type="code" dark />
+
+## Performance and customization
+
+If you intend to receive a lot of notifications, you might want to consider using advanced features like pagination, infinite scroll, virtualized list, etc.
+
+With the actual implementation, you will notice that the component is not optimized for performance.
+This is intended, Notifications and NotificationCard are only responsible for rendering the UI.
+But the composition allows you to easily add these features.
+
+For example, you can easily add a wrapper around the NotificationCards to add infinite scroll, pagination, or even virtualized list.
+
+Feel free to contact us if you need help with this.
+```