@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,425 @@
+# Button
+
+## 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/Button/Button.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Fragment } from "react";
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { userEvent, within, waitFor, expect, fn } from "storybook/test";
+
+import Button, { Props } from "./Button";
+import ErrorBoundary from "@packages/internal-components/ErrorBoundary/ErrorBoundary";
+import { ICON_NAMES_ARRAY } from "@components/Icon/Icon";
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  argTypes: {
+    text: { type: "string" },
+    iconLeft: {
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    iconRight: {
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [(story) => <ErrorBoundary>{story()}</ErrorBoundary>],
+};
+export default meta;
+
+export const Playground: StoryObj<typeof Button> = {
+  args: {
+    text: "[Insert name]",
+    size: "medium",
+    mode: "primary",
+    nature: "action",
+    onClick: fn(),
+  },
+};
+
+export const Clicked: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByText("[Insert name]"));
+    await waitFor(() => expect(args.onClick).toHaveBeenCalledTimes(1));
+  },
+};
+
+export const Primary: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+  },
+};
+
+export const Hover: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-hovered": true,
+  },
+};
+
+export const Focus: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-focus-visible": true,
+  },
+};
+
+export const Active: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-pressed": true,
+  },
+};
+
+export const Disabled: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    disabled: true,
+    mode: "primary",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByText("[Insert name]"));
+    await waitFor(() => expect(args.onClick).toHaveBeenCalledTimes(0));
+  },
+};
+
+export const Loading: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    isLoading: true,
+    mode: "primary",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByText("[Insert name]"));
+    await waitFor(() => expect(args.onClick).toHaveBeenCalledTimes(0));
+  },
+};
+
+export const Informative: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    nature: "informative",
+  },
+};
+
+export const Negative: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    nature: "negative",
+  },
+};
+
+export const Positive: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    nature: "positive",
+  },
+};
+
+export const Warning: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    nature: "warning",
+  },
+};
+
+export const FullWidth: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    fullWidth: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: "400px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const WithIconLeft: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    iconLeft: "access_time",
+  },
+};
+
+export const WithIconRight: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    iconRight: "access_time",
+  },
+};
+
+export const WithOnlyIcon: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    text: undefined,
+    iconRight: "access_time",
+  },
+};
+
+export const WithTooltip: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    tooltip: "Tooltip",
+    tooltipProps: {
+      defaultOpen: true,
+    },
+  },
+};
+
+export const WithBadge: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    text: undefined,
+    iconLeft: "notifications_none",
+    mode: "tertiary",
+    badgeProps: {
+      nature: "negative",
+      variant: "dot",
+    },
+  },
+};
+
+export const All: StoryObj<typeof Button> = {
+  parameters: {
+    a11y: { disable: true },
+  },
+  decorators: [
+    () => (
+      <ShowcaseAllVariationsGrid
+        renderContent={(props) => (
+          <>
+            <Button {...props} />
+            <Button {...props} data-force-hovered />
+            <Button {...props} data-force-focus-visible />
+            <Button {...props} data-force-pressed />
+            <Button {...props} disabled />
+            <Button {...props} isLoading />
+          </>
+        )}
+      />
+    ),
+  ],
+};
+
+export const AllAsLink: StoryObj<typeof Button> = {
+  parameters: {
+    a11y: { disable: true },
+  },
+  decorators: [
+    () => (
+      <ShowcaseAllVariationsGrid
+        renderContent={(props) => (
+          <>
+            <Button {...props} href="/link" />
+            <Button {...props} href="/link" target="_blank" />
+            <Button {...props} href="/link" data-force-hovered />
+            <Button {...props} href="/link" data-force-focus-visible />
+            <Button {...props} href="/link" data-force-pressed />
+            <Button {...props} href="/link" disabled />
+            <Button {...props} href="/link" isLoading />
+          </>
+        )}
+      />
+    ),
+  ],
+};
+
+const ShowcaseAllVariationsGrid = ({
+  renderContent,
+}: {
+  renderContent: (props: Props) => React.ReactNode;
+}) => {
+  return (
+    <div>
+      {["action", "informative", "negative", "positive", "warning"].map(
+        (nature) => (
+          <div key={nature} style={{ marginTop: 16 }}>
+            <h1>{nature}</h1>
+            {["primary", "secondary", "tertiary"].map((mode) => (
+              <Fragment key={mode}>
+                <h2>{mode}</h2>
+                <div key={mode}>
+                  {["text", "iconLeft", "iconRight", "icon"].map(
+                    (textOrIcon) => {
+                      return (
+                        <div
+                          key={textOrIcon}
+                          style={{
+                            display: "grid",
+                            gridTemplateColumns: "repeat(3, minmax(0, 1fr))",
+                            columnGap: 8,
+                            marginTop: 16,
+                          }}
+                        >
+                          {["small", "medium", "large"].map((size) => {
+                            const props: Props = {
+                              mode: mode as Props["mode"],
+                              size: size as Props["size"],
+                              nature: nature as Props["nature"],
+                              text:
+                                textOrIcon !== "icon"
+                                  ? "[Insert name]"
+                                  : undefined,
+                              iconLeft:
+                                textOrIcon === "iconLeft"
+                                  ? "access_time"
+                                  : undefined,
+                              iconRight:
+                                textOrIcon === "iconRight" ||
+                                textOrIcon === "icon"
+                                  ? "access_time"
+                                  : undefined,
+                            };
+                            return (
+                              <div
+                                key={size}
+                                style={{
+                                  display: "flex",
+                                  flexDirection: "column",
+                                  alignItems: "center",
+                                  gap: 12,
+                                }}
+                              >
+                                {renderContent(props)}
+                              </div>
+                            );
+                          })}
+                        </div>
+                      );
+                    },
+                  )}
+                </div>
+              </Fragment>
+            ))}
+          </div>
+        ),
+      )}
+    </div>
+  );
+};
+```
+
+## 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, expect } from "storybook/test";
+
+import Button from "../Button";
+import ErrorBoundary from "@packages/internal-components/ErrorBoundary/ErrorBoundary";
+import { ICON_NAMES_ARRAY } from "@components/Icon/Icon";
+import { Playground } from "../Button.stories";
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  argTypes: {
+    text: { type: "string" },
+    iconLeft: {
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+    iconRight: {
+      options: ["", ...ICON_NAMES_ARRAY],
+    },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [(story) => <ErrorBoundary>{story()}</ErrorBoundary>],
+};
+export default meta;
+
+export const NoTextNorIcon: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    text: undefined,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Error: You must provide a text or an icon");
+  },
+};
+
+export const NoDoubleIcons: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    iconLeft: "access_time",
+    iconRight: "access_time",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText(
+      "Error: You can't provide both an iconLeft and an iconRight",
+    );
+  },
+};
+
+export const LinkWithTarget: StoryObj<typeof Button> = {
+  args: {
+    ...Playground.args,
+    href: "/link",
+    target: "_blank",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const linkElement = (await canvas.findByText("[Insert name]")).closest("a");
+    await expect(linkElement).toHaveAttribute("href", "/link");
+    await expect(linkElement).toHaveAttribute("target", "_blank");
+  },
+};
+```
+
+## 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,
+  Controls,
+  Meta,
+  Source,
+  Stories,
+} from "@storybook/addon-docs/blocks";
+
+import * as Button from "./Button.stories";
+
+<Meta of={Button} />
+
+# Button
+
+<Canvas of={Button.Playground} />
+
+## Button props
+
+<Controls of={Button.Playground} />
+```