@arbor-education/design-system.components 0.25.3 → 0.25.5

package/src/components/breadcrumbs/Breadcrumbs.test.tsx

@@ -0,0 +1,185 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { Breadcrumbs } from './Breadcrumbs.js';
+
+const basicItems = [
+  { label: 'Home', href: '/' },
+  { label: 'Library', href: '/library' },
+  { label: 'Current page', href: '/library/current' },
+];
+
+describe('Breadcrumbs', () => {
+  test('renders a nav element', () => {
+    render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+    expect(screen.getByRole('navigation')).toBeInTheDocument();
+  });
+
+  test('uses breadcrumbLabel as aria-label', () => {
+    render(<Breadcrumbs items={basicItems} breadcrumbLabel="Page navigation" />);
+    expect(screen.getByRole('navigation')).toHaveAttribute('aria-label', 'Page navigation');
+  });
+
+  test('renders all item labels', () => {
+    render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+    expect(screen.getByText('Home')).toBeInTheDocument();
+    expect(screen.getByText('Library')).toBeInTheDocument();
+    expect(screen.getByText('Current page')).toBeInTheDocument();
+  });
+
+  test('applies a custom className to the nav element', () => {
+    render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" className="custom-class" />);
+    expect(screen.getByRole('navigation')).toHaveClass('custom-class');
+  });
+
+  describe('active item', () => {
+    test('marks the last item as aria-current="page"', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByText('Current page').closest('a')).toHaveAttribute('aria-current', 'page');
+    });
+
+    test('does not mark non-last items as aria-current', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByText('Home').closest('a')).not.toHaveAttribute('aria-current');
+      expect(screen.getByText('Library').closest('a')).not.toHaveAttribute('aria-current');
+    });
+
+    test('does not have an href — the current page is non-navigable', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByText('Current page').closest('a')).not.toHaveAttribute('href');
+    });
+  });
+
+  describe('separators', () => {
+    test('renders a separator between each item but not after the last', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      const separators = screen.getAllByText('/', { selector: '[aria-hidden]' });
+      expect(separators).toHaveLength(basicItems.length - 1);
+    });
+  });
+
+  describe('copy button', () => {
+    beforeEach(() => {
+      Object.defineProperty(navigator, 'clipboard', {
+        value: { writeText: vi.fn().mockResolvedValue(undefined) },
+        configurable: true,
+      });
+    });
+
+    test('renders a copy button on the last item', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'Copy breadcrumb path' })).toBeInTheDocument();
+    });
+
+    test('copies item labels joined with " > " to clipboard on click', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      fireEvent.click(screen.getByRole('button', { name: 'Copy breadcrumb path' }));
+      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('Home > Library > Current page');
+    });
+
+    test('uses copyText prop when provided instead of deriving from items', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" copyText="Custom > Path > Override" />);
+      fireEvent.click(screen.getByRole('button', { name: 'Copy breadcrumb path' }));
+      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('Custom > Path > Override');
+    });
+
+    test('excludes ellipsis item labels from the copied path', () => {
+      const itemsWithEllipsis = [
+        { label: 'Home', href: '/' },
+        { label: 'Show hidden pages', isEllipsis: true as const },
+        { label: 'Year 11', href: '/students/year-11' },
+        { label: 'Attendance', href: '/students/year-11/attendance' },
+      ];
+      render(<Breadcrumbs items={itemsWithEllipsis} breadcrumbLabel="Breadcrumb" />);
+      fireEvent.click(screen.getByRole('button', { name: 'Copy breadcrumb path' }));
+      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('Home > Year 11 > Attendance');
+    });
+
+    test('shows a check icon immediately after clicking', () => {
+      render(<Breadcrumbs items={basicItems} breadcrumbLabel="Breadcrumb" />);
+      fireEvent.click(screen.getByRole('button', { name: 'Copy breadcrumb path' }));
+      expect(screen.getByRole('button', { name: 'Breadcrumb path copied' })).toBeInTheDocument();
+    });
+  });
+
+  describe('ellipsis item', () => {
+    const itemsWithEllipsis = [
+      { label: 'Home', href: '/' },
+      { label: 'More pages', isEllipsis: true as const },
+      { label: 'Current page', href: '/current' },
+    ];
+
+    const itemsWithEllipsisLast = [
+      { label: 'Home', href: '/' },
+      { label: 'More pages', isEllipsis: true as const },
+    ];
+
+    test('renders an ellipsis button with accessible label from item label', () => {
+      render(<Breadcrumbs items={itemsWithEllipsis} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'More pages' })).toBeInTheDocument();
+    });
+
+    test('does not render the ellipsis item as a link', () => {
+      render(<Breadcrumbs items={itemsWithEllipsis} breadcrumbLabel="Breadcrumb" />);
+      const links = screen.getAllByRole('link');
+      expect(links.every(link => link.textContent !== 'More pages')).toBe(true);
+    });
+
+    test('does not render a copy button when the last item is an ellipsis', () => {
+      render(<Breadcrumbs items={itemsWithEllipsisLast} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.queryByRole('button', { name: 'Copy breadcrumb path' })).not.toBeInTheDocument();
+    });
+
+    test('forwards onClick from the item to the ellipsis button', () => {
+      const handleClick = vi.fn();
+      const items = [
+        { label: 'Home', href: '/' },
+        { label: 'More pages', isEllipsis: true as const, onClick: handleClick },
+        { label: 'Current page', href: '/current' },
+      ];
+      render(<Breadcrumbs items={items} breadcrumbLabel="Breadcrumb" />);
+      fireEvent.click(screen.getByRole('button', { name: 'More pages' }));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('dropdown item', () => {
+    const itemsWithDropdown = [
+      { label: 'Home', href: '/' },
+      {
+        label: 'Students',
+        href: '/students',
+        dropdownOptions: [
+          { label: 'All students', href: '/students' },
+          { label: 'My tutor group', href: '/students/tutor-group' },
+        ],
+      },
+      { label: 'Current page', href: '/current' },
+    ];
+
+    test('renders the dropdown trigger with the item label', () => {
+      render(<Breadcrumbs items={itemsWithDropdown} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByText('Students')).toBeInTheDocument();
+    });
+
+    test('renders the dropdown trigger with role="button"', () => {
+      render(<Breadcrumbs items={itemsWithDropdown} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'Students' })).toBeInTheDocument();
+    });
+
+    test('renders the dropdown trigger with aria-haspopup="menu"', () => {
+      render(<Breadcrumbs items={itemsWithDropdown} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'Students' })).toHaveAttribute('aria-haspopup', 'menu');
+    });
+
+    test('does not have an href — the dropdown trigger is not a link', () => {
+      render(<Breadcrumbs items={itemsWithDropdown} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'Students' })).not.toHaveAttribute('href');
+    });
+
+    test('has tabIndex=0 so it remains keyboard focusable without an href', () => {
+      render(<Breadcrumbs items={itemsWithDropdown} breadcrumbLabel="Breadcrumb" />);
+      expect(screen.getByRole('button', { name: 'Students' })).toHaveAttribute('tabindex', '0');
+    });
+  });
+});

package/src/components/breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,92 @@
+import { BreadcrumbLink } from './BreadcrumbLink.js';
+import { BreadcrumbEllipsis } from './BreadcrumbEllipsis.js';
+import { BreadcrumbItemSeparator } from './BreadcrumbItemSeparator.js';
+import { BreadcrumbDropdown } from './BreadcrumbDropdown.js';
+import type {
+  BreadcrumbsProps,
+  BreadcrumbLinkProps,
+  BreadcrumbEllipsisProps,
+  BreadcrumbDropdownProps,
+  BreadcrumbCopyButtonProps,
+  BreadcrumbItem,
+} from './types.js';
+import classNames from 'classnames';
+import { BreadcrumbCopyButton } from './BreadcrumbCopyButton.js';
+import { useEffect, useRef, useState } from 'react';
+
+const COPY_FEEDBACK_DURATION_MS = 2000;
+
+const renderLink = (item: BreadcrumbItem, isLast: boolean) => {
+  const hasDropdownOptions = Boolean(item.dropdownOptions?.length);
+  if (item.isEllipsis) {
+    return <BreadcrumbEllipsis screenReaderText={item.label} onClick={item.onClick} />;
+  }
+  if (hasDropdownOptions) {
+    return <BreadcrumbDropdown item={item} />;
+  }
+  return <BreadcrumbLink item={item} isActive={isLast} />;
+};
+
+export const Breadcrumbs = (props: BreadcrumbsProps) => {
+  const { items, breadcrumbLabel = 'Breadcrumbs', className, copyText, ...rest } = props;
+  const [copyButtonClicked, setCopyButtonClicked] = useState(false);
+  const copyTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  useEffect(() => () => clearTimeout(copyTimerRef.current), []);
+
+  const handleCopyButtonClick = () => {
+    if (!navigator.clipboard) {
+      return;
+    }
+    setCopyButtonClicked(true);
+    navigator.clipboard
+      .writeText(copyText ?? items.filter(item => !item.isEllipsis).map(item => item.label).join(' > '))
+      .catch(() => {})
+      .finally(() => {
+        copyTimerRef.current = setTimeout(() => {
+          setCopyButtonClicked(false);
+        }, COPY_FEEDBACK_DURATION_MS);
+      });
+  };
+
+  return (
+    <nav
+      {...rest}
+      aria-label={breadcrumbLabel}
+      className={classNames('ds-breadcrumbs__container', className)}
+    >
+      <ol className="ds-breadcrumbs__list">
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1;
+
+          return (
+            <li key={`${item.label}-${index}`} className="ds-breadcrumbs__item">
+              {renderLink(item, isLast)}
+              {isLast
+                ? (
+                    !item.isEllipsis && <BreadcrumbCopyButton isClicked={copyButtonClicked} onClick={handleCopyButtonClick} />
+                  )
+                : (
+                    <BreadcrumbItemSeparator />
+                  )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+};
+
+Breadcrumbs.Link = BreadcrumbLink;
+Breadcrumbs.Ellipsis = BreadcrumbEllipsis;
+Breadcrumbs.ItemSeparator = BreadcrumbItemSeparator;
+Breadcrumbs.Dropdown = BreadcrumbDropdown;
+Breadcrumbs.CopyButton = BreadcrumbCopyButton;
+
+export namespace Breadcrumbs {
+  export type Props = BreadcrumbsProps;
+  export type LinkProps = BreadcrumbLinkProps;
+  export type EllipsisProps = BreadcrumbEllipsisProps;
+  export type DropdownProps = BreadcrumbDropdownProps;
+  export type CopyButtonProps = BreadcrumbCopyButtonProps;
+}

package/src/components/breadcrumbs/breadcrumbs.scss

@@ -0,0 +1,158 @@
+.ds-breadcrumbs__container {
+  display: flex;
+  align-items: center;
+}
+
+.ds-breadcrumbs__list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--breadcrumbs-spacing-gap-horizontal);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.ds-breadcrumbs__item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--breadcrumbs-breadcrumb-link-spacing-gap-horizontal);
+}
+
+.ds-breadcrumbs__label {
+  font-family: var(--type-body-p-family);
+  font-size: var(--type-body-p-size);
+  font-weight: var(--type-body-p-weight);
+  color: var(--breadcrumbs-breadcrumb-link-default-color-text);
+  line-height: var(--type-body-line-height);
+}
+
+.ds-breadcrumbs__link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--breadcrumbs-breadcrumb-link-spacing-gap-horizontal);
+  text-decoration: none;
+  cursor: pointer;
+  border-radius: var(--spacing-small);
+
+  &:hover {
+    .ds-breadcrumbs__label {
+      color: var(--breadcrumbs-breadcrumb-link-hover-color-text);
+    }
+  }
+
+  &:focus-visible {
+    border: none;
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-brand-300);
+    text-decoration: none;
+  }
+
+
+  &[aria-current="page"] {
+    .ds-breadcrumbs__label {
+      font-family: var(--type-body-bold-family);
+      font-weight: var(--type-body-bold-weight);
+      font-size: var(--type-body-bold-size);
+      color: var(--breadcrumbs-breadcrumb-link-active-color-text);
+
+      &:hover {
+        color: var(--breadcrumbs-breadcrumb-link-hover-color-text);
+      }
+    }
+  }
+}
+
+.ds-breadcrumbs__separator {
+  display: inline-flex;
+  align-items: center;
+  margin: 0 var(--breadcrumbs-breadcrumb-link-default-spacing-gap-horizontal);
+  color: var(--breadcrumbs-divider-default-color);
+  user-select: none;
+}
+
+.ds-button--icon-only.ds-button--S.ds-breadcrumbs__ellipsis-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  background-color: transparent;
+  border: none;
+  border-radius: var(--breadcrumbs-elipsis-radius);
+  cursor: pointer;
+  width: calc(16px + 2 * var(--spacing-xsmall));
+  height: calc(16px + 2 * var(--spacing-xsmall));
+
+  svg {
+    color: var(--breadcrumbs-elipsis-default-color);
+    width: var(--icon-size-small);
+    height: var(--icon-size-small);
+  }
+
+  &:active {
+    color: var(--breadcrumbs-elipsis-hover-color);
+    background-color: var(--breadcrumbs-elipsis-hover-colour-background);
+  }
+
+  &:hover {
+    color: var(--breadcrumbs-elipsis-hover-color);
+    background-color: var(--breadcrumbs-elipsis-hover-colour-background);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 var(--focus-border) var(--color-brand-300);
+    background-color: transparent;
+  }
+
+  &:focus:not(:focus-visible) {
+    outline: none;
+    box-shadow: none;
+  }
+}
+
+.ds-button--icon-only.ds-button--S.ds-breadcrumbs__copy-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  background-color: transparent;
+  border: none;
+  border-radius: var(--breadcrumbs-copy-icon-radius);
+  cursor: pointer;
+  width: calc(16px + 2 * var(--spacing-xsmall));
+  height: calc(16px + 2 * var(--spacing-xsmall));
+
+  svg {
+    color: var(--breadcrumbs-copy-icon-default-color);
+    width: var(--icon-size-xsmall);
+    height: var(--icon-size-xsmall);
+  }
+
+  &:active {
+    color: var(--breadcrumbs-copy-icon-hover-color);
+    background-color: var(--breadcrumbs-copy-icon-hover-color-background);
+  }
+
+  &:hover {
+    color: var(--breadcrumbs-copy-icon-hover-color);
+    background-color: var(--breadcrumbs-copy-icon-hover-color-background);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 var(--focus-border) var(--color-brand-300);
+    background-color: transparent;
+  }
+
+  &:focus:not(:focus-visible) {
+    outline: none;
+    box-shadow: none;
+  }
+
+  &--clicked {
+    svg {
+      color: var(--breadcrumbs-breadcrumb-link-hover-color-icon);
+    }
+  }
+}

package/src/components/breadcrumbs/types.ts

@@ -0,0 +1,31 @@
+export type BreadcrumbItem = {
+  label: string;
+  href?: string;
+  dropdownOptions?: BreadcrumbItem[];
+  isEllipsis?: boolean;
+  onClick?: () => void;
+};
+
+export type BreadcrumbsProps = {
+  items: BreadcrumbItem[];
+  breadcrumbLabel?: string;
+  copyText?: string;
+} & React.HTMLAttributes<HTMLElement>;
+
+export type BreadcrumbLinkProps = {
+  item: BreadcrumbItem;
+  isDropdown?: boolean;
+  isActive?: boolean;
+} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+export type BreadcrumbEllipsisProps = {
+  screenReaderText: string;
+} & React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+export type BreadcrumbDropdownProps = {
+  item: BreadcrumbItem;
+};
+
+export type BreadcrumbCopyButtonProps = {
+  isClicked?: boolean;
+} & React.ButtonHTMLAttributes<HTMLButtonElement>;

package/src/components/button/button.scss

@@ -206,6 +206,8 @@
 
   // Text Link Button
   &--text-link {
+    display: inline;
+    padding: 0;
     background-color: var(--button-medium-text-link-default-color-background);
     color: var(--button-medium-text-link-default-color-text);
     border: var(--border-weight) solid var(--button-medium-text-link-default-color-border);

package/src/components/dropdown/dropdown.scss

@@ -21,6 +21,7 @@
     color: var(--form-dropdown-form-drop-item-default-color-text);
     gap: var(--form-dropdown-form-drop-item-spacing-gap-horizontal);
     cursor: pointer;
+    text-decoration: none;
 
     &:hover {
         background: var(--form-dropdown-form-drop-item-hover-color-background);