@arbor-education/design-system.components 0.22.0 → 0.23.1

package/src/components/filterBar/FilterBar.test.tsx

@@ -0,0 +1,248 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useRef, useState } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import { FilterBar } from './FilterBar.js';
+
+type FilterBarNamespaceCheck = [
+  FilterBar.Props,
+  FilterBar.ToolbarProps,
+  FilterBar.ButtonProps,
+  FilterBar.ActiveListProps,
+  FilterBar.TagProps,
+  FilterBar.TagItem,
+];
+const filterBarNamespaceCheck: FilterBarNamespaceCheck | undefined = undefined;
+void filterBarNamespaceCheck;
+
+describe('FilterBar', () => {
+  test('renders toolbar buttons and empty state', () => {
+    const { container } = render(
+      <FilterBar aria-label="Attendance controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" />
+          <FilterBar.Button type="sort" />
+          <FilterBar.Button type="group" />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList emptyState="No filters applied" />
+      </FilterBar>,
+    );
+
+    expect(screen.getByRole('toolbar', { name: 'Filter, sort, and group controls' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Open filter' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Open sort' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Open group' })).toBeInTheDocument();
+    expect(screen.getByText('No filters applied')).toBeInTheDocument();
+    expect(container.querySelector('.ds-filter-bar')).toBeInTheDocument();
+  });
+
+  test('renders capped counts and preserves the full accessible label', async () => {
+    const onClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" count={142} onClick={onClick} />
+        </FilterBar.Toolbar>
+      </FilterBar>,
+    );
+
+    const button = screen.getByRole('button', { name: 'Open filter. 142 filter items applied' });
+    await userEvent.click(button);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    expect(screen.getByText('99+')).toBeInTheDocument();
+    expect(screen.getByLabelText('142 applied filter items')).toBeInTheDocument();
+  });
+
+  test('forwards active item clicks and renders label plus value', async () => {
+    const user = userEvent.setup();
+    const onItemClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList
+          items={[
+            {
+              id: 'event-type',
+              type: 'filter',
+              fieldId: 'filter-event-type',
+              label: 'Event Type',
+              value: 'Interventions',
+              onClick: onItemClick,
+            },
+          ]}
+        />
+      </FilterBar>,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Open filter Event Type: Interventions' }));
+
+    expect(screen.getAllByText('Event Type:')[0]).toBeInTheDocument();
+    expect(screen.getAllByText('Interventions')[0]).toBeInTheDocument();
+    expect(onItemClick).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'event-type',
+        type: 'filter',
+        fieldId: 'filter-event-type',
+        label: 'Event Type',
+        value: 'Interventions',
+      }),
+      expect.any(Object),
+    );
+  });
+
+  test('forwards aria-controls and aria-expanded from active items to the tag button', () => {
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList
+          items={[
+            {
+              id: 'event-type',
+              type: 'filter',
+              label: 'Event Type',
+              value: 'Interventions',
+              onClick: vi.fn(),
+              ariaControls: 'filter-modal',
+              ariaExpanded: true,
+            },
+          ]}
+        />
+      </FilterBar>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Open filter Event Type: Interventions' })).toHaveAttribute('aria-controls', 'filter-modal');
+    expect(screen.getByRole('button', { name: 'Open filter Event Type: Interventions' })).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  test('uses the active list overflow action for the focusable +N more summary', async () => {
+    const user = userEvent.setup();
+    const onOverflowClick = vi.fn();
+    const rectSpy = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function mockRect(this: HTMLElement) {
+      let width = 0;
+
+      if (this.classList.contains('ds-tag-list__viewport')) width = 220;
+      else if (this.classList.contains('ds-tag-list__item')) width = 84;
+      else if (this.classList.contains('ds-tag-list__overflow')) width = 76;
+
+      return {
+        width,
+        height: 0,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: 0,
+        x: 0,
+        y: 0,
+        toJSON() {
+          return {};
+        },
+      } as DOMRect;
+    });
+
+    try {
+      render(
+        <FilterBar>
+          <FilterBar.ActiveList
+            onOverflowClick={onOverflowClick}
+            overflowActionLabel="Show more applied items"
+            items={[
+              { id: 'date', type: 'filter', label: 'Date', value: 'Wed 26 Apr 2026' },
+              { id: 'event', type: 'filter', label: 'Event Type', value: 'Interventions' },
+              { id: 'course', type: 'filter', label: 'Course', value: 'English' },
+              { id: 'student', type: 'sort', label: 'Student', value: 'A to Z' },
+            ]}
+          />
+        </FilterBar>,
+      );
+
+      await user.click(screen.getByRole('button', { name: 'Show more applied items' }));
+      expect(onOverflowClick).toHaveBeenCalledOnce();
+    }
+    finally {
+      rectSpy.mockRestore();
+    }
+  });
+
+  test('returns focus to the first toolbar button after sequentially removing all tags from their remove buttons', async () => {
+    const user = userEvent.setup();
+
+    const Example = () => {
+      const [itemIds, setItemIds] = useState(['year-group', 'attendance-band', 'date-range']);
+      const firstToolbarButtonRef = useRef<HTMLButtonElement>(null);
+
+      const items: FilterBar.TagItem[] = itemIds.map((itemId) => {
+        const baseItem = {
+          type: 'filter' as const,
+          onClick: vi.fn(),
+          onRemove: () => setItemIds(current => current.filter(id => id !== itemId)),
+        };
+
+        switch (itemId) {
+          case 'year-group':
+            return {
+              ...baseItem,
+              id: itemId,
+              label: 'Year group',
+              value: 'Year 10',
+              removeLabel: 'Remove year group filter',
+            };
+          case 'attendance-band':
+            return {
+              ...baseItem,
+              id: itemId,
+              label: 'Attendance band',
+              value: 'Below 90%',
+              removeLabel: 'Remove attendance band filter',
+            };
+          default:
+            return {
+              ...baseItem,
+              id: itemId,
+              label: 'Date range',
+              value: 'Spring term',
+              removeLabel: 'Remove date range filter',
+            };
+        }
+      });
+
+      return (
+        <FilterBar>
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button ref={firstToolbarButtonRef} type="filter" />
+            <FilterBar.Button type="sort" />
+            <FilterBar.Button type="group" />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            items={items}
+            returnFocusRef={firstToolbarButtonRef}
+            ariaLabel="Applied attendance filters"
+          />
+        </FilterBar>
+      );
+    };
+
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Open filter' })).toHaveFocus();
+
+    await user.tab();
+    await user.tab();
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Open filter Year group: Year 10' })).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Remove year group filter' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove year group filter' }));
+    expect(screen.getByRole('button', { name: 'Remove attendance band filter' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove attendance band filter' }));
+    expect(screen.getByRole('button', { name: 'Remove date range filter' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove date range filter' }));
+    expect(screen.getByRole('button', { name: 'Open filter' })).toHaveFocus();
+  });
+});

package/src/components/filterBar/FilterBar.tsx

@@ -0,0 +1,298 @@
+import { Badge } from 'Components/badge/Badge';
+import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
+import type { IconName } from 'Components/icon/allowedIcons';
+import { Tag } from 'Components/tag/Tag';
+import { TagList } from 'Components/tagList/TagList';
+import classNames from 'classnames';
+import { Children, forwardRef, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type RefObject } from 'react';
+
+export type FilterBarType = 'filter' | 'sort' | 'group';
+
+export type FilterBarTagItem = {
+  id: string;
+  type: FilterBarType;
+  label: string;
+  value: React.ReactNode;
+  fieldId?: string;
+  icon?: IconName;
+  ariaControls?: string;
+  ariaExpanded?: boolean;
+  actionLabel?: string;
+  removeLabel?: string;
+  disabled?: boolean;
+  onClick?: (item: FilterBarTagItem, event: React.MouseEvent<HTMLButtonElement>) => void;
+  onRemove?: (item: FilterBarTagItem) => void;
+};
+
+export type FilterBarProps = HTMLAttributes<HTMLDivElement>;
+
+export type FilterBarToolbarProps = HTMLAttributes<HTMLDivElement>;
+
+export type FilterBarButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> & {
+  type: FilterBarType;
+  label?: string;
+  count?: number | null;
+  icon?: IconName;
+  htmlType?: ButtonHTMLAttributes<HTMLButtonElement>['type'];
+};
+
+export type FilterBarActiveListProps = {
+  items?: readonly FilterBarTagItem[];
+  children?: React.ReactNode;
+  className?: string;
+  ariaLabel?: string;
+  emptyState?: React.ReactNode;
+  returnFocusRef?: RefObject<HTMLElement | null>;
+  wrap?: boolean;
+  collapseOverflow?: boolean;
+  overflowActionLabel?: string;
+  onOverflowClick?: MouseEventHandler<HTMLButtonElement>;
+  overflowAriaControls?: string;
+  overflowAriaExpanded?: boolean;
+};
+
+export type FilterBarTagProps = Omit<FilterBarTagItem, 'id' | 'onClick' | 'onRemove'> & {
+  id?: string;
+  className?: string;
+  children?: React.ReactNode;
+  onClick?: (item: FilterBarTagItem, event: React.MouseEvent<HTMLButtonElement>) => void;
+  onRemove?: (item: FilterBarTagItem) => void;
+};
+
+const FILTER_BAR_TYPE_LABELS: Record<FilterBarType, string> = {
+  filter: 'Filter',
+  sort: 'Sort',
+  group: 'Group',
+};
+
+const FILTER_BAR_TYPE_ICONS: Record<FilterBarType, IconName> = {
+  filter: 'sliders-horizontal',
+  sort: 'sorting',
+  group: 'list-tree',
+};
+
+const getVisibleCount = (count?: number | null): string | null => {
+  if (typeof count !== 'number' || count <= 0) return null;
+  return count > 99 ? '99+' : `${count}`;
+};
+
+const getButtonA11yLabel = (type: FilterBarType, label: string, count?: number | null): string => {
+  if (typeof count !== 'number' || count <= 0) {
+    return `Open ${label.toLowerCase()}`;
+  }
+
+  return `Open ${label.toLowerCase()}. ${count} ${type} item${count === 1 ? '' : 's'} applied`;
+};
+
+const getTagActionLabel = (item: FilterBarTagItem): string => `Open ${item.type} ${item.label}: ${item.value}`;
+
+const FilterBarTagContent = ({ label, value }: Pick<FilterBarTagProps, 'label' | 'value'>) => (
+  <span className="ds-filter-bar__tag-content">
+    <span className="ds-filter-bar__tag-label">
+      {label}
+      :
+    </span>
+    <span className="ds-filter-bar__tag-value">{value}</span>
+  </span>
+);
+
+export const FilterBar = ({
+  children,
+  className,
+  ...rest
+}: FilterBarProps): React.JSX.Element => (
+  <div className={classNames('ds-filter-bar', className)} {...rest}>
+    {children}
+  </div>
+);
+
+const FilterBarToolbar = ({
+  children,
+  className,
+  ...rest
+}: FilterBarToolbarProps): React.JSX.Element => (
+  <div
+    className={classNames('ds-filter-bar__toolbar', className)}
+    role="toolbar"
+    {...rest}
+  >
+    {children}
+  </div>
+);
+
+const FilterBarButton = forwardRef<HTMLButtonElement, FilterBarButtonProps>(({
+  type,
+  label,
+  count,
+  icon,
+  htmlType = 'button',
+  className,
+  'aria-label': ariaLabel,
+  'aria-expanded': ariaExpanded,
+  ...rest
+}, ref): React.JSX.Element => {
+  const resolvedLabel = label ?? FILTER_BAR_TYPE_LABELS[type];
+  const resolvedIcon = icon ?? FILTER_BAR_TYPE_ICONS[type];
+  const visibleCount = getVisibleCount(count);
+  const hasAppliedItems = Boolean(visibleCount);
+  const isExpanded = ariaExpanded === true || ariaExpanded === 'true';
+
+  return (
+    <Button
+      ref={ref}
+      type={htmlType}
+      variant="tertiary"
+      size="M"
+      className={classNames('ds-filter-bar__button', {
+        'ds-filter-bar__button--has-applied': hasAppliedItems,
+        'ds-filter-bar__button--expanded': isExpanded,
+      }, className)}
+      aria-label={ariaLabel ?? getButtonA11yLabel(type, resolvedLabel, count)}
+      aria-expanded={ariaExpanded}
+      {...rest}
+    >
+      <span className="ds-filter-bar__button-content">
+        <span className="ds-filter-bar__button-icon" aria-hidden="true">
+          <Icon name={resolvedIcon} size={16} />
+        </span>
+        <span className="ds-filter-bar__button-label">{resolvedLabel}</span>
+        {visibleCount && (
+          <Badge
+            colour="green"
+            className="ds-filter-bar__button-badge"
+            a11yLabel={`${count} applied ${resolvedLabel.toLowerCase()} item${count === 1 ? '' : 's'}`}
+          >
+            {visibleCount}
+          </Badge>
+        )}
+      </span>
+    </Button>
+  );
+});
+
+FilterBarButton.displayName = 'FilterBar.Button';
+
+const FilterBarTag = ({
+  id,
+  type,
+  label,
+  value,
+  fieldId,
+  icon,
+  ariaControls,
+  ariaExpanded,
+  actionLabel,
+  removeLabel,
+  disabled,
+  className,
+  children,
+  onClick,
+  onRemove,
+}: FilterBarTagProps): React.JSX.Element => {
+  const item: FilterBarTagItem = {
+    id: id ?? fieldId ?? `${type}-${label}`,
+    type,
+    label,
+    value,
+    fieldId,
+    icon,
+    ariaControls,
+    ariaExpanded,
+    actionLabel,
+    removeLabel,
+    disabled,
+  };
+  const resolvedIcon = icon ?? FILTER_BAR_TYPE_ICONS[type];
+
+  return (
+    <Tag
+      slotStart={<Icon name={resolvedIcon} size={16} />}
+      onClick={onClick ? event => onClick(item, event) : undefined}
+      onRemove={onRemove ? () => onRemove(item) : undefined}
+      actionLabel={actionLabel ?? getTagActionLabel(item)}
+      removeLabel={removeLabel}
+      disabled={disabled}
+      ariaControls={ariaControls}
+      ariaExpanded={ariaExpanded}
+    >
+      <span className={classNames('ds-filter-bar__tag', className)}>
+        {children ?? <FilterBarTagContent label={label} value={value} />}
+      </span>
+    </Tag>
+  );
+};
+
+const FilterBarActiveList = ({
+  items,
+  children,
+  className,
+  ariaLabel = 'Active filters, sorting, and grouping',
+  emptyState,
+  returnFocusRef,
+  wrap = false,
+  collapseOverflow = true,
+  overflowActionLabel = 'Show more applied items',
+  onOverflowClick,
+  overflowAriaControls,
+  overflowAriaExpanded,
+}: FilterBarActiveListProps): React.JSX.Element | null => {
+  if (items) {
+    return (
+      <TagList
+        items={items.map(item => ({
+          id: item.id,
+          slotStart: <Icon name={item.icon ?? FILTER_BAR_TYPE_ICONS[item.type]} size={16} />,
+          children: <FilterBarTagContent label={item.label} value={item.value} />,
+          onClick: item.onClick ? event => item.onClick?.(item, event) : undefined,
+          onRemove: item.onRemove ? () => item.onRemove?.(item) : undefined,
+          ariaControls: item.ariaControls,
+          ariaExpanded: item.ariaExpanded,
+          actionLabel: item.actionLabel ?? getTagActionLabel(item),
+          removeLabel: item.removeLabel,
+          disabled: item.disabled,
+        }))}
+        className={classNames('ds-filter-bar__active-list', className)}
+        ariaLabel={ariaLabel}
+        emptyState={emptyState}
+        returnFocusRef={returnFocusRef}
+        wrap={wrap}
+        collapseOverflow={collapseOverflow}
+        overflowOnClick={onOverflowClick}
+        overflowActionLabel={overflowActionLabel}
+        overflowAriaControls={overflowAriaControls}
+        overflowAriaExpanded={overflowAriaExpanded}
+      />
+    );
+  }
+
+  if (!children) {
+    if (!emptyState) return null;
+    return <div className={classNames('ds-filter-bar__empty-state', className)}>{emptyState}</div>;
+  }
+
+  return (
+    <ul className={classNames('ds-filter-bar__manual-list', className)} aria-label={ariaLabel}>
+      {Children.toArray(children).map((child, index) => (
+        <li key={index} className="ds-filter-bar__manual-list-item">
+          {child}
+        </li>
+      ))}
+    </ul>
+  );
+};
+
+FilterBar.Toolbar = FilterBarToolbar;
+FilterBar.Button = FilterBarButton;
+FilterBar.ActiveList = FilterBarActiveList;
+FilterBar.Tag = FilterBarTag;
+
+export namespace FilterBar {
+  export type Type = FilterBarType;
+  export type Props = FilterBarProps;
+  export type ToolbarProps = FilterBarToolbarProps;
+  export type ButtonProps = FilterBarButtonProps;
+  export type ActiveListProps = FilterBarActiveListProps;
+  export type TagProps = FilterBarTagProps;
+  export type TagItem = FilterBarTagItem;
+}

package/src/components/filterBar/filterBar.scss

@@ -0,0 +1,143 @@
+.ds-filter-bar {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--spacing-small);
+  width: 100%;
+  max-width: 100%;
+  padding: var(--spacing-small);
+  box-sizing: border-box;
+  border: var(--border-weight) solid var(--color-grey-100);
+  border-radius: var(--section-container-radius);
+  background-color: var(--section-container-color-background);
+}
+
+.ds-filter-bar__toolbar {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--spacing-small);
+  flex-shrink: 0;
+}
+
+.ds-filter-bar__button {
+  flex-shrink: 0;
+  border-radius: var(--button-toolbar-radius);
+
+  &.ds-button--tertiary {
+    height: var(--size-medium);
+    padding: 0 var(--button-medium-spacing-horizontal);
+    border: var(--border-weight) solid transparent;
+    background-color: transparent;
+    color: var(--color-grey-900);
+
+    &:hover {
+      background-color: var(--color-grey-050);
+      border-color: transparent;
+    }
+
+    &:active,
+    &:focus {
+      background-color: var(--color-grey-100);
+      border-color: transparent;
+    }
+  }
+
+  &.ds-filter-bar__button--has-applied.ds-button--tertiary {
+    background-color: var(--color-brand-050);
+
+    &:hover {
+      background-color: var(--color-brand-100);
+    }
+
+    &:active,
+    &:focus {
+      background-color: var(--color-brand-100);
+    }
+  }
+
+  &.ds-filter-bar__button--expanded.ds-button--tertiary {
+    background-color: var(--color-grey-100);
+  }
+
+  &.ds-filter-bar__button--expanded.ds-filter-bar__button--has-applied.ds-button--tertiary {
+    background-color: var(--color-brand-100);
+  }
+}
+
+.ds-filter-bar__button-content {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-small);
+}
+
+.ds-filter-bar__button-icon {
+  display: inline-flex;
+  align-items: center;
+  line-height: 0;
+}
+
+.ds-filter-bar__button-label {
+  line-height: 1.5;
+}
+
+.ds-filter-bar__button-badge {
+  flex-shrink: 0;
+}
+
+.ds-filter-bar__active-list {
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.ds-filter-bar__manual-list {
+  display: flex;
+  flex: 1 1 auto;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  overflow: hidden;
+}
+
+.ds-filter-bar__manual-list-item {
+  min-width: 0;
+}
+
+.ds-filter-bar__empty-state {
+  color: var(--color-grey-800);
+  font-size: var(--type-body-p-size);
+  line-height: 1.5;
+}
+
+.ds-filter-bar__tag {
+  display: inline-flex;
+  min-width: 0;
+}
+
+.ds-filter-bar__tag-content {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 4px;
+  min-width: 0;
+}
+
+.ds-filter-bar__tag-label {
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.ds-filter-bar__tag-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+@media (width <= 40rem) {
+  .ds-filter-bar__button-label {
+    display: none;
+  }
+}