Add breadcrumb component

src/components/Breadcrumb/Breadcrumb.module.css

@@ -0,0 +1,65 @@
+/*
+Copyright 2024 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  block-size: 40px;
+  gap: var(--cpd-space-3x);
+  padding-block-end: var(--cpd-space-3x);
+  border-block-end: 1px solid var(--cpd-color-alpha-gray-400);
+  box-sizing: border-box;
+
+  .pages {
+    display: flex;
+    gap: var(--cpd-space-1x);
+
+    /* override list styles */
+    list-style: none;
+    margin: 0;
+    padding: 0;
+
+    a {
+      cursor: pointer;
+    }
+
+    .last-page {
+      font: var(--cpd-font-body-sm-regular);
+      color: var(--cpd-color-text-secondary);
+    }
+
+    /*
+     * Breadcrumb separator
+     * We want this separator to be only visual and to not be in the accessibility tree.
+     * The nav html element already provides an accessible way to separate the links.
+     */
+    li + li::before {
+      display: inline-block;
+      margin: 0 0.3em 0 0.25em;
+      transform: rotate(15deg);
+      border-inline-end: 1px solid var(--cpd-color-text-secondary);
+      block-size: var(--cpd-space-3x);
+      content: "";
+    }
+
+    /* Last page */
+    :last-child {
+      span {
+        padding-inline-start: var(--cpd-space-1x);
+      }
+    }
+  }
+}

src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,81 @@
+/*
+Copyright 2024 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { Breadcrumb as BreadcrumbComponent } from "./Breadcrumb";
+import { Meta, StoryFn } from "@storybook/react";
+import React, { ComponentProps, useState } from "react";
+import { Button } from "../Button";
+import { fn } from "@storybook/test";
+
+export default {
+  title: "Breadcrumb",
+  component: BreadcrumbComponent,
+  tags: ["autodocs"],
+  argTypes: {},
+  args: {
+    pages: ["1st level page", "2nd level page", "Current page"],
+    onPageClick: fn(),
+    onBackClick: fn(),
+    backLabel: "Back",
+  },
+} as Meta<typeof BreadcrumbComponent>;
+
+const Template: StoryFn<typeof BreadcrumbComponent> = (
+  args: ComponentProps<typeof BreadcrumbComponent>,
+) => {
+  return <BreadcrumbComponent {...args} />;
+};
+
+export const Default = Template.bind({});
+Default.args = {};
+
+function ControlledBreadcrumb(
+  args: ComponentProps<typeof BreadcrumbComponent>,
+) {
+  const pagesContent = ["Page 1", "Page 2", "Page 3"];
+  const [currentIndex, setCurrentIndex] = useState(2);
+  const currentPage = pagesContent[currentIndex];
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        alignItems: "flex-start",
+      }}
+    >
+      <BreadcrumbComponent
+        backLabel="Back"
+        pages={args.pages.slice(0, currentIndex + 1)}
+        onPageClick={(_page, index) => setCurrentIndex(index)}
+        onBackClick={() =>
+          setCurrentIndex((_currentIndex) =>
+            _currentIndex === 0 ? 0 : _currentIndex - 1,
+          )
+        }
+      />
+      {currentPage}
+      <Button onClick={() => setCurrentIndex(2)}>Reset</Button>
+    </div>
+  );
+}
+
+export const Controlled: StoryFn<typeof BreadcrumbComponent> = (
+  args: ComponentProps<typeof BreadcrumbComponent>,
+) => {
+  return <ControlledBreadcrumb {...args} />;
+};

src/components/Breadcrumb/Breadcrumb.test.tsx

@@ -0,0 +1,63 @@
+/*
+Copyright 2024 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { describe, expect, it, vi } from "vitest";
+import { composeStories } from "@storybook/react";
+import * as stories from "./Breadcrumb.stories.tsx";
+import { render, screen } from "@testing-library/react";
+import React from "react";
+import userEvent from "@testing-library/user-event";
+import { Breadcrumb } from "./Breadcrumb.tsx";
+
+const { Default } = composeStories(stories);
+
+describe("Breadcrumb", () => {
+  it("should render", () => {
+    render(<Default />);
+    expect(screen.getByRole("navigation")).toMatchSnapshot();
+  });
+
+  it("should call onPageClick when a page is clicked", async () => {
+    const user = userEvent.setup();
+    const onPageClick = vi.fn();
+    const onBackClick = vi.fn();
+
+    render(
+      <Breadcrumb
+        pages={["1st level page", "2nd level page", "Current page"]}
+        onPageClick={onPageClick}
+        onBackClick={onBackClick}
+        backLabel="Back"
+      />,
+    );
+
+    // Click listener
+    await user.click(screen.getByRole("button", { name: "1st level page" }));
+    expect(onPageClick).toHaveBeenCalledWith("1st level page", 0);
+
+    onPageClick.mockReset();
+    // Keyboard listener
+    await user.type(
+      screen.getByRole("button", { name: "1st level page" }),
+      " ",
+    );
+    expect(onPageClick).toHaveBeenCalledWith("1st level page", 0);
+
+    // Back button
+    await user.click(screen.getByRole("button", { name: "Back" }));
+    expect(onBackClick).toHaveBeenCalled();
+  });
+});

src/components/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,126 @@
+/*
+Copyright 2024 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import React, { HTMLProps, JSX, MouseEventHandler, KeyboardEvent } from "react";
+import { IconButton } from "../Button";
+import Chevron from "@vector-im/compound-design-tokens/assets/web/icons/chevron-left";
+import styles from "./Breadcrumb.module.css";
+import { Link } from "../Link/Link.tsx";
+import classNames from "classnames";
+
+interface BreadcrumbProps extends HTMLProps<HTMLElement> {
+  /**
+   * The label for the back button.
+   */
+  backLabel: string;
+  /**
+   * The click handler for the back button.
+   */
+  onBackClick: MouseEventHandler<HTMLButtonElement>;
+  /**
+   * The pages to display in the breadcrumb.
+   * All the pages except the last one are displayed as links.
+   */
+  pages: string[];
+  /**
+   * The click handler for a page.
+   * @param page - The page that was clicked.
+   * @param index - The index of the page that was clicked.
+   */
+  onPageClick: (page: string, index: number) => void;
+}
+
+/**
+ * A breadcrumb component.
+ */
+export function Breadcrumb({
+  backLabel,
+  onBackClick,
+  pages,
+  onPageClick,
+  className,
+  ...props
+}: BreadcrumbProps): JSX.Element {
+  return (
+    <nav className={classNames(styles.breadcrumb, className)} {...props}>
+      <IconButton
+        subtleBackground={true}
+        size="28px"
+        aria-label={backLabel}
+        onClick={onBackClick}
+      >
+        <Chevron />
+      </IconButton>
+      <ol className={styles.pages}>
+        {pages.map((page, index) => (
+          <Page
+            key={index}
+            page={page}
+            isLastPage={index === pages.length - 1}
+            onClick={() => onPageClick(page, index)}
+          />
+        ))}
+      </ol>
+    </nav>
+  );
+}
+
+interface PageProps {
+  /**
+   * The page to display.
+   */
+  page: string;
+  /**
+   * Whether this is the last page in the breadcrumb.
+   */
+  isLastPage: boolean;
+  /**
+   * The click handler for the page, ignore for last page.
+   */
+  onClick: () => void;
+}
+
+/**
+ * A breadcrumb page.
+ * If not the last page, the page is displayed in a link.
+ */
+function Page({ page, isLastPage, onClick }: PageProps): JSX.Element {
+  const onKeyDown = (event: KeyboardEvent<HTMLAnchorElement>) => {
+    if (event.key === " ") {
+      onClick();
+    }
+  };
+
+  return (
+    <li>
+      {isLastPage ? (
+        <span className={styles["last-page"]} aria-current="page">
+          {page}
+        </span>
+      ) : (
+        <Link
+          size="small"
+          role="button"
+          onClick={onClick}
+          onKeyDown={onKeyDown}
+          tabIndex={0}
+        >
+          {page}
+        </Link>
+      )}
+    </li>
+  );
+}