@agregio-solutions/design-system 1.91.0 → 1.92.0

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

@@ -0,0 +1,332 @@
+# Breadcrumbs
+
+## 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/Breadcrumbs/Breadcrumbs.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 { I18nProvider } from "react-aria-components";
+
+import Component from "./Breadcrumbs";
+
+const meta: Meta<typeof Component> = {
+  component: Component,
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (story) => <I18nProvider locale="en-EN">{story()}</I18nProvider>,
+  ],
+};
+export default meta;
+
+const generateLinks = (howMany: number) =>
+  Array.from({ length: howMany }, (_, i) => ({
+    href: `/${i + 1}`,
+    text: i === 0 ? "Home" : `Page ${i + 1}`,
+  }));
+
+export const OneItem: StoryObj<typeof Component> = {
+  args: {
+    links: generateLinks(1),
+  },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement).toBeEmptyDOMElement();
+  },
+};
+
+export const TwoItems: StoryObj<typeof Component> = {
+  args: {
+    links: [
+      { href: "/", text: "Home" },
+      { href: "", text: "Page 2" }, // Simulate case when devs don't provide an href
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Home");
+    await expect(canvas.getByText("Home")).toHaveAttribute("href", "/");
+    await expect(canvas.getByText("Home")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 2")).not.toHaveAttribute("href");
+    await expect(canvas.getByText("Page 2")).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  },
+};
+
+export const ThreeItems: StoryObj<typeof Component> = {
+  args: {
+    links: generateLinks(3),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Home");
+    await expect(canvas.getByText("Home")).toHaveAttribute("href", "/1");
+    await expect(canvas.getByText("Home")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 2")).toHaveAttribute("href", "/2");
+    await expect(canvas.getByText("Page 2")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 3")).toHaveAttribute("href", "/3");
+    await expect(canvas.getByText("Page 3")).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  },
+};
+
+export const FourItems: StoryObj<typeof Component> = {
+  args: {
+    links: generateLinks(4),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Home");
+    await expect(canvas.getByText("Home")).toHaveAttribute("href", "/1");
+    await expect(canvas.getByText("Home")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 2")).toHaveAttribute("href", "/2");
+    await expect(canvas.getByText("Page 2")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 3")).toHaveAttribute("href", "/3");
+    await expect(canvas.getByText("Page 3")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 4")).toHaveAttribute("href", "/4");
+    await expect(canvas.getByText("Page 4")).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  },
+};
+
+export const FiveItems: StoryObj<typeof Component> = {
+  args: {
+    links: generateLinks(5),
+  },
+};
+```
+
+## 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 { userEvent, within, expect, screen } from "storybook/test";
+import { Route, Routes } from "react-router-dom";
+import { I18nProvider } from "react-aria";
+
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+import { FiveItems } from "../Breadcrumbs.stories";
+import Breadcrumbs from "../Breadcrumbs";
+
+const meta: Meta<typeof Breadcrumbs> = {
+  component: Breadcrumbs,
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (story) => <I18nProvider locale="en-EN">{story()}</I18nProvider>,
+  ],
+};
+export default meta;
+
+export const ShouldOpenTheItems: StoryObj<typeof Breadcrumbs> = {
+  args: {
+    ...FiveItems.args,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    const dropdownLinkIsNotPresent = async (text: string) =>
+      expectNotPresent(() => canvas.queryByText(text, { selector: "span" }));
+
+    const getDropdownLink = (text: string) =>
+      screen.getByText(text, { selector: "span" }).closest("a");
+
+    // Test closed state
+    await canvas.findByText("Home");
+    await expect(canvas.getByText("Home")).toHaveAttribute("href", "/1");
+    await expect(canvas.getByText("Home")).not.toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByText("Page 5")).toHaveAttribute("href", "/5");
+    await expect(canvas.getByText("Page 5")).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await dropdownLinkIsNotPresent("Page 2");
+    await dropdownLinkIsNotPresent("Page 3");
+    await dropdownLinkIsNotPresent("Page 4");
+
+    // Test open state
+    await user.click(canvas.getByLabelText("Show more"));
+    await canvas.findByText("Page 2");
+    await expect(getDropdownLink("Page 2")).toHaveAttribute("href", "/2");
+    await expect(getDropdownLink("Page 3")).toHaveAttribute("href", "/3");
+    await expect(getDropdownLink("Page 4")).toHaveAttribute("href", "/4");
+  },
+};
+
+export const ShouldWorkWithReactRouter: StoryObj<typeof Breadcrumbs> = {
+  render: () => {
+    const Demo = () => {
+      return (
+        <>
+          <Breadcrumbs
+            links={[
+              { href: "/page-1", text: "Home" },
+              { href: "/page-2", text: "Page 2" },
+              { href: "/page-3", text: "Page 3" },
+            ]}
+          />
+
+          <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 = () => <Demo />;
+
+    return <Pages />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Home");
+    await expect(canvas.getByText("Home")).toHaveAttribute("href", "/page-1");
+    await expect(canvas.getByText("Page 2")).toHaveAttribute("href", "/page-2");
+    await expect(canvas.getByText("Page 3")).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("Home"));
+    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"));
+  },
+};
+
+export const ShouldFallbackToHomeForTheFirstLink: StoryObj<typeof Breadcrumbs> =
+  {
+    args: {
+      ...FiveItems.args,
+      links: [
+        { href: "/page-1", text: "" },
+        { href: "/page-2", text: "Page 2" },
+        { href: "/page-3", text: "Page 3" },
+      ],
+    },
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement);
+      await canvas.findByText("Home");
+      await expect(canvas.getByText("Home")).toHaveAttribute("href", "/page-1");
+      await expect(canvas.getByText("Page 2")).toHaveAttribute(
+        "href",
+        "/page-2",
+      );
+      await expect(canvas.getByText("Page 3")).toHaveAttribute(
+        "href",
+        "/page-3",
+      );
+    },
+  };
+
+export const ExampleWithRouterOptions: StoryObj<typeof Breadcrumbs> = {
+  render: () => {
+    return (
+      <Breadcrumbs
+        links={[
+          { href: "/page-1", text: "Home", routerOptions: { replace: true } },
+          { href: "/page-2", text: "Page 2", routerOptions: { replace: true } },
+        ]}
+      />
+    );
+  },
+};
+```
+
+## 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 Breadcrumbs from "./Breadcrumbs.stories";
+import * as BreadcrumbsTests from "./tests/Breadcrumbs.stories";
+
+<Meta of={Breadcrumbs} />
+
+# Breadcrumbs
+
+<Canvas of={Breadcrumbs.FourItems} />
+
+## Breadcrumbs props
+
+<Controls of={Breadcrumbs.FourItems} />
+
+## `links` prop
+
+Its an array of objects that represents the props passed directly to the underlying Link component from React Aria.
+
+Most of the time, you'll just need to pass an `href` and a `children` for the text (like in the example above).
+
+But if you need more control over the rendered links, [here are the actual props available in the React Aria docs](https://react-spectrum.adobe.com/react-aria/Link.html#props).
+
+## Integration with framework routers
+
+It is possible to make this `Breadcrumbs` 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 in the `Breadcrumbs` component will behave like your framework-specific link.
+You can even pass router-specific props with the `routerOptions` prop, like:
+
+<Source of={BreadcrumbsTests.ExampleWithRouterOptions} type="code" dark />
+
+<Stories />
+```