@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,231 @@
+# Menu
+
+## 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/Menu/Menu.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Menu from "./Menu";
+import MenuItem from "../MenuItem/MenuItem";
+
+const meta: Meta<typeof Menu> = {
+  component: Menu,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    children: { control: false },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    buttonProps: {
+      iconLeft: "menu",
+      mode: "secondary",
+    },
+    children: (
+      <>
+        <MenuItem onClick={() => alert("open")} text="Open" />
+        <MenuItem onClick={() => alert("rename")} text="Rename…" />
+        <MenuItem onClick={() => alert("duplicate")} text="Duplicate" />
+        <MenuItem onClick={() => alert("share")} text="Share…" />
+        <MenuItem
+          onClick={() => alert("disabled")}
+          text="Disabled"
+          isDisabled
+        />
+      </>
+    ),
+  },
+};
+
+export const OpenByDefault: Story = {
+  args: {
+    ...Playground.args,
+    defaultOpen: true,
+  },
+};
+```
+
+## 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, userEvent, within, screen } from "storybook/test";
+import Menu from "../Menu";
+
+import * as MenuStories from "../Menu.stories";
+import MenuItem from "@packages/components/MenuItem/MenuItem";
+import { useState } from "react";
+
+const meta: Meta<typeof Menu> = {
+  component: Menu,
+  ...MenuStories.default,
+  parameters: {
+    ...MenuStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ExampleUsage: Story = {
+  render: () => {
+    const Parent = () => {
+      const [selectedItem, setSelectedItem] = useState("");
+
+      return (
+        <div>
+          <p>The selected item is: {selectedItem}</p>
+
+          <Menu
+            buttonProps={{
+              iconLeft: "menu",
+              "aria-label": "Menu",
+              mode: "secondary",
+            }}
+          >
+            <MenuItem text="Item 1" onClick={() => setSelectedItem("Item 1")} />
+            <MenuItem text="Item 2" onClick={() => setSelectedItem("Item 2")} />
+            <MenuItem text="Item 3" onClick={() => setSelectedItem("Item 3")} />
+            <MenuItem
+              text="Disabled item"
+              onClick={() => setSelectedItem("Item disabled")}
+              isDisabled
+            />
+          </Menu>
+        </div>
+      );
+    };
+
+    return <Parent />;
+  },
+};
+export const ControlledOpenState: Story = {
+  render: () => {
+    const Parent = () => {
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <Menu
+          isOpen={isOpen}
+          onOpenChange={setIsOpen}
+          buttonProps={{
+            iconLeft: "menu",
+            "aria-label": "Menu",
+            mode: "secondary",
+          }}
+        >
+          <MenuItem text="Item 1" />
+          <MenuItem text="Item 2" />
+        </Menu>
+      );
+    };
+
+    return <Parent />;
+  },
+};
+
+export const TestShouldOpenAndClickOnItem: Story = {
+  render: ExampleUsage.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await user.click(canvas.getByLabelText("Menu"));
+    await screen.findByText("Item 1");
+    await user.click(screen.getByText("Item 1"));
+    expect(
+      canvas.getByText("The selected item is: Item 1"),
+    ).toBeInTheDocument();
+    await expect(canvas.queryByText("Item 1")).not.toBeInTheDocument();
+  },
+};
+
+export const TestShouldNotOpenAndClickOnDisabledItem: Story = {
+  render: ExampleUsage.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await user.click(canvas.getByLabelText("Menu"));
+    await screen.findByText("Disabled item");
+    await user.click(screen.getByText("Disabled item"));
+    expect(
+      canvas.queryByText("The selected item is: Disabled item"),
+    ).not.toBeInTheDocument();
+    await screen.findByText("Disabled item");
+  },
+};
+```
+
+## 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 Menu from "./Menu.stories";
+import * as MenuTests from "./tests/Menu.stories";
+
+<Meta of={Menu} />
+
+# Menu
+
+A menu displays a list of actions or options that a user can choose.
+
+## Example usage
+
+<Source of={MenuTests.ExampleUsage} type="code" dark />
+
+## Features
+
+There is no native element to implement a menu in HTML that is widely supported.
+Menu and MenuItem help achieve accessible menu components that are nicely styled and easy to use.
+
+- **Keyboard navigation** – Menu items can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and disabled items are supported as well.
+- **Trigger interactions** – Menus can be triggered by pressing with a mouse or touch, or optionally, with a long press interaction. The arrow keys also open the menu with a keyboard, automatically focusing the first or last item accordingly.
+- **Accessible** – Follows the ARIA menu pattern, with keyboard shortcut elements within each item for improved screen reader announcement.
+
+## Controlled open state
+
+The open state of the menu can be controlled via the `defaultOpen` and `isOpen` props.
+
+<Source of={MenuTests.ControlledOpenState} type="code" dark />
+
+Alternatively, you can use the `defaultOpen` if you just want the menu to be
+open by default (without having to manage the open state yourself).
+
+## How to test this component?
+
+It is really simple to test a menu. Here is an example:
+
+<Source of={MenuTests.TestShouldOpenAndClickOnItem} type="code" dark />
+
+## Playground & Props
+
+<Canvas of={Menu.Playground} />
+
+<Controls of={Menu.Playground} />
+```

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

@@ -0,0 +1,166 @@
+# Message
+
+## 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/Message/Message.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import Message from "./Message";
+import { I18nProvider } from "react-aria-components";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Message> = {
+  component: Message,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    children: { control: { type: "text" } },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    nature: "negative",
+    onClose: fn(),
+    actions: [
+      { text: "Primary Action", mode: "primary" },
+      { text: "Secondary Action", mode: "secondary" },
+    ],
+    title: "The Title",
+    children: "Some error message",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await canvas.findByText(args.title as string);
+    await canvas.findByText(args.children as string);
+    await canvas.findByText("Primary Action");
+    await canvas.findByText("Secondary Action");
+    await user.click(await canvas.findByLabelText("Close alert"));
+    await expect(args.onClose).toHaveBeenCalledTimes(1);
+    await user.click(await canvas.findByText(args.children as string)); // Just to avoid the close button being focused in Chromatic snapshot
+  },
+};
+
+export const Positive: Story = {
+  args: {
+    ...Playground.args,
+    nature: "positive",
+  },
+};
+
+export const Warning: Story = {
+  args: {
+    ...Playground.args,
+    nature: "warning",
+  },
+};
+
+export const Informative: Story = {
+  args: {
+    ...Playground.args,
+    nature: "informative",
+  },
+};
+
+export const Negative: Story = {
+  args: {
+    ...Playground.args,
+    nature: "negative",
+  },
+};
+
+export const Minimal: Story = {
+  args: {
+    children: "Some error message",
+  },
+};
+
+export const PixelPerfect: Story = {
+  args: {
+    onClose: fn(),
+    title: "[Insert title]",
+    actions: [
+      { text: "[Insert name]", mode: "primary" },
+      { text: "[Insert name]", mode: "secondary" },
+      { text: "[Insert name]", mode: "secondary" },
+    ],
+    children: "[Insert description]",
+  },
+};
+
+export const StressTestOverflow: Story = {
+  decorators: [
+    (Story) => (
+      <div style={{ width: "800px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    ...PixelPerfect.args,
+    children:
+      "qsdhqjshdjhqskjdhjkqsdhqkshdjkqhsdhqjksdhjkqhsdkjhqjksdhkjqsjkhdkjqhsdkjhqkdsjdsqqsdhqjshdjhqskjdhjkqsdhqkshdjkqhsdhqjksdhjkqhsdkjhqjksdhkjqsjkhdkjqhsdkjhqkdsjdsq",
+  },
+};
+
+export const Mobile: Story = {
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "padded",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  args: {
+    ...PixelPerfect.args,
+  },
+};
+
+export const FullWidth: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  args: {
+    ...PixelPerfect.args,
+  },
+};
+
+export const AutoHide: Story = {
+  args: {
+    ...Playground.args,
+    autoHide: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await canvas.findByText(args.children as string);
+    await user.click(await canvas.findByLabelText("Close alert"));
+    await expect(
+      canvas.queryByText(args.children as string),
+    ).not.toBeInTheDocument();
+  },
+};
+```

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

@@ -0,0 +1,289 @@
+# Modal
+
+## 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/Modal/Modal.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Modal, { ModalActions, ModalContent, Props } from "./Modal";
+import { screen } from "storybook/test";
+import { useState } from "react";
+import Button from "@components/Button/Button";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Modal> = {
+  component: Modal,
+  argTypes: {
+    children: { control: false },
+  },
+  parameters: {
+    layout: "none",
+  },
+  render: (args) => {
+    function ParentComponent(props: Props) {
+      const [isOpen, setIsOpen] = useState(props.isOpen);
+
+      return (
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            height: "100vh",
+          }}
+        >
+          <Modal {...props} isOpen={isOpen} onOpenChange={setIsOpen}>
+            <ModalContent>{props.children}</ModalContent>
+
+            <ModalActions>
+              <Button
+                onClick={() => setIsOpen(false)}
+                text="Close"
+                mode="secondary"
+              />
+              <Button onClick={() => setIsOpen(false)} text="Apply" />
+            </ModalActions>
+          </Modal>
+
+          <div style={{ textAlign: "center" }}>
+            <Button onClick={() => setIsOpen(true)} text="Open Modal" />
+            <div style={{ marginTop: 16 }}>
+              The Modal is {isOpen ? "open" : "closed"}
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return <ParentComponent {...args}>{args.children}</ParentComponent>;
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Modal> = {
+  args: {
+    title: "[Insert Modal title]",
+    children: <div>The content</div>,
+    isOpen: true,
+  },
+  play: async ({ args }) => {
+    await screen.findByText(args.title);
+    await screen.findByText("The content");
+    await screen.findByText("Close");
+    await screen.findByLabelText("Close");
+    await expectNotPresent(() => screen.queryByText("Submit"));
+  },
+};
+
+export const OverflowingContent: StoryObj<typeof Modal> = {
+  args: {
+    ...Playground.args,
+    children: "The content. ".repeat(400),
+  },
+};
+
+export const CustomWidth: StoryObj<typeof Modal> = {
+  args: {
+    ...Playground.args,
+    width: "auto",
+  },
+};
+```
+
+## 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 Modal, { ModalActions, ModalContent } from "../Modal";
+import { userEvent, within, screen } from "storybook/test";
+import { useState } from "react";
+import Button from "@components/Button/Button";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+import { Playground } from "../Modal.stories";
+import baseMeta from "../Modal.stories";
+import { useForm } from "react-hook-form";
+import TextInput from "@components/TextInput/TextInput";
+import { ModalForm } from "../Modal.styled";
+
+const meta: Meta<typeof Modal> = {
+  component: Modal,
+  parameters: {
+    layout: "none",
+    chromatic: { disableSnapshot: true },
+  },
+  render: baseMeta.render,
+};
+export default meta;
+
+export const TestCloseButtonNextTitleShouldCloseModal: StoryObj<typeof Modal> =
+  {
+    args: {
+      ...Playground.args,
+    },
+    play: async ({ canvasElement, args }) => {
+      const canvas = within(canvasElement);
+      const user = userEvent.setup({ delay: 50 });
+      await canvas.findByText("The Modal is open");
+      await screen.findByText(args.title);
+      await user.click(screen.getByLabelText("Close"));
+      await canvas.findByText("The Modal is closed");
+      await expectNotPresent(() => screen.queryByText(args.title));
+    },
+  };
+
+export const TestFooterCloseButtonShouldCloseModal: StoryObj<typeof Modal> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("The Modal is open");
+    await screen.findByText(args.title);
+    await user.click(screen.getByText("Close"));
+    await canvas.findByText("The Modal is closed");
+    await expectNotPresent(() => screen.queryByText(args.title));
+  },
+};
+
+export const ExampleUsage: StoryObj<typeof Modal> = {
+  render: () => {
+    function ParentComponent() {
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <div>
+          <div>
+            <Button onClick={() => setIsOpen(true)} text="Open modal" />
+          </div>
+          <Modal isOpen={isOpen} onOpenChange={setIsOpen} title="Modal title">
+            <ModalContent>Modal content</ModalContent>
+            <ModalActions>
+              <Button
+                onClick={() => setIsOpen(false)}
+                text="Close"
+                mode="secondary"
+              />
+              <Button onClick={() => setIsOpen(false)} text="Apply" />
+            </ModalActions>
+          </Modal>
+        </div>
+      );
+    }
+
+    return <ParentComponent />;
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof Modal> = {
+  render: () => {
+    type Form = {
+      name: string;
+      email: string;
+    };
+
+    type FormProps = {
+      onClose: () => void;
+      onSubmit: (values: Form) => void;
+    };
+
+    function Form({ onClose, onSubmit }: FormProps) {
+      const form = useForm<Form>();
+
+      return (
+        <ModalForm
+          onSubmit={form.handleSubmit((data: Form) => {
+            onSubmit(data);
+          })}
+        >
+          <ModalContent>
+            <TextInput
+              {...form.register("name", { required: "Name is required" })}
+              id="name"
+              label="Name"
+              errorHelperText={form.formState.errors.name?.message}
+            />
+          </ModalContent>
+          <ModalActions>
+            <Button onClick={onClose} text="Close" mode="secondary" />
+            <Button type="submit" text="Create user" />
+          </ModalActions>
+        </ModalForm>
+      );
+    }
+
+    function ParentComponent() {
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <div>
+          <Button onClick={() => setIsOpen(true)} text="Open form" />
+
+          <Modal
+            isOpen={isOpen}
+            onOpenChange={setIsOpen}
+            title="Creating a new user"
+          >
+            <Form
+              onClose={() => setIsOpen(false)}
+              onSubmit={(values) => {
+                // API call for example
+                console.log(values); // eslint-disable-line no-console
+                setIsOpen(false);
+              }}
+            />
+          </Modal>
+        </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 } from "@storybook/addon-docs/blocks";
+
+import * as Modal from "./Modal.stories";
+import * as ModalTests from "./tests/Modal.stories";
+
+<Meta of={Modal} />
+
+# Modal
+
+The HTML `<dialog>` element can be used to build modals.
+However, it is not yet widely supported across browsers, and building fully accessible custom dialogs from scratch is very difficult and error prone.
+Modal helps achieve accessible modals.
+
+- **Accessible** – Content outside the model is hidden from assistive technologies while it is open. The modal closes when interacting outside, or pressing the Escape key.
+- **Focus management** – Focus is moved into the modal on mount, and restored to the trigger element on unmount. While open, focus is contained within the modal, preventing the user from tabbing outside.
+- **Scroll locking** – Scrolling the page behind the modal is prevented while it is open, including in mobile browsers.
+
+## Example usage
+
+<Source of={ModalTests.ExampleUsage} type="code" dark />
+
+## Example with a form
+
+<Source of={ModalTests.ExampleWithReactHookForm} type="code" dark />
+
+## Props
+
+<Controls of={Modal.Playground} />
+```