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

package/src/components/tagList/TagList.test.tsx

@@ -0,0 +1,342 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Icon } from 'Components/icon/Icon';
+import { useRef, useState } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import { TagList } from './TagList.js';
+
+const mockTagListCollapseRects = () =>
+  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 = 72;
+    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;
+  });
+
+describe('TagList', () => {
+  test('renders empty state when there are no items', () => {
+    render(<TagList items={[]} emptyState={<span>No filters set</span>} />);
+    expect(screen.getByText('No filters set')).toBeInTheDocument();
+  });
+
+  test('calls the item action when a tag is clicked', async () => {
+    const onClick = vi.fn();
+    render(<TagList items={[{ id: 'attendance', children: 'Attendance', onClick }]} />);
+
+    await userEvent.click(screen.getByRole('button', { name: 'Attendance' }));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  test('forwards item-level aria-controls and aria-expanded to the tag action button', () => {
+    render(
+      <TagList
+        items={[
+          {
+            id: 'attendance',
+            children: 'Attendance',
+            onClick: vi.fn(),
+            ariaControls: 'filter-modal',
+            ariaExpanded: true,
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveAttribute('aria-controls', 'filter-modal');
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  test('moves roving focus between interactive tags with arrow keys', async () => {
+    const user = userEvent.setup();
+    render(
+      <TagList
+        items={[
+          { id: 'attendance', children: 'Attendance', onClick: vi.fn() },
+          { id: 'registers', children: 'Registers', onClick: vi.fn() },
+          { id: 'interventions', children: 'Interventions', onClick: vi.fn() },
+        ]}
+      />,
+    );
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Registers' })).toHaveFocus();
+
+    await user.keyboard('{End}');
+    expect(screen.getByRole('button', { name: 'Interventions' })).toHaveFocus();
+  });
+
+  test('ArrowRight moves from the tag action to its remove button, then to the next tag', async () => {
+    const user = userEvent.setup();
+    render(
+      <TagList
+        items={[
+          {
+            id: 'attendance',
+            children: 'Attendance',
+            onClick: vi.fn(),
+            onRemove: vi.fn(),
+            removeLabel: 'Remove Attendance',
+          },
+          {
+            id: 'registers',
+            children: 'Registers',
+            onClick: vi.fn(),
+          },
+        ]}
+      />,
+    );
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveFocus();
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveAttribute('tabindex', '-1');
+
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveAttribute('tabindex', '0');
+
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Registers' })).toHaveFocus();
+  });
+
+  test('ArrowLeft moves from the remove button back to the tag action', async () => {
+    const user = userEvent.setup();
+    render(
+      <TagList
+        items={[
+          {
+            id: 'attendance',
+            children: 'Attendance',
+            onClick: vi.fn(),
+            onRemove: vi.fn(),
+            removeLabel: 'Remove Attendance',
+          },
+        ]}
+      />,
+    );
+
+    await user.tab();
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+
+    await user.keyboard('{ArrowLeft}');
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveFocus();
+  });
+
+  test('Delete triggers the focused tag remove callback', async () => {
+    const user = userEvent.setup();
+    const onRemove = vi.fn();
+    render(
+      <TagList
+        items={[
+          {
+            id: 'attendance',
+            children: 'Attendance',
+            slotStart: <Icon name="funnel" size={12} />,
+            onClick: vi.fn(),
+            onRemove,
+            removeLabel: 'Remove Attendance',
+          },
+        ]}
+      />,
+    );
+
+    await user.tab();
+    await user.keyboard('{Delete}');
+
+    expect(onRemove).toHaveBeenCalledOnce();
+  });
+
+  test('focuses the next available target after a removable tag is deleted', async () => {
+    const user = userEvent.setup();
+
+    const Example = () => {
+      const [itemIds, setItemIds] = useState(['attendance', 'registers']);
+      const items: TagList.Item[] = itemIds.map(itemId => ({
+        id: itemId,
+        children: itemId === 'attendance' ? 'Attendance' : 'Registers',
+        onRemove: () => setItemIds(current => current.filter(id => id !== itemId)),
+        removeLabel: itemId === 'attendance' ? 'Remove Attendance' : 'Remove Registers',
+      }));
+
+      return <TagList items={items} />;
+    };
+
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove Attendance' }));
+    expect(screen.getByRole('button', { name: 'Remove Registers' })).toHaveFocus();
+  });
+
+  test('returns focus to the provided fallback element when the last removable tag is deleted', async () => {
+    const user = userEvent.setup();
+
+    const Example = () => {
+      const [items, setItems] = useState<TagList.Item[]>([
+        {
+          id: 'attendance',
+          children: 'Attendance',
+          onRemove: () => setItems([]),
+          removeLabel: 'Remove Attendance',
+        },
+      ]);
+      const returnFocusRef = useRef<HTMLButtonElement>(null);
+
+      return (
+        <>
+          <TagList items={items} returnFocusRef={returnFocusRef} />
+          <button ref={returnFocusRef} type="button">
+            Return home
+          </button>
+        </>
+      );
+    };
+
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove Attendance' }));
+    expect(screen.getByRole('button', { name: 'Return home' })).toHaveFocus();
+  });
+
+  test('returns focus to the fallback element when the last removal unmounts TagList immediately', async () => {
+    const user = userEvent.setup();
+
+    const Example = () => {
+      const [items, setItems] = useState<TagList.Item[]>([
+        {
+          id: 'attendance',
+          children: 'Attendance',
+          onRemove: () => setItems([]),
+          removeLabel: 'Remove Attendance',
+        },
+      ]);
+      const returnFocusRef = useRef<HTMLButtonElement>(null);
+
+      return (
+        <>
+          {items.length > 0 && <TagList items={items} returnFocusRef={returnFocusRef} />}
+          <button ref={returnFocusRef} type="button">
+            Return home
+          </button>
+        </>
+      );
+    };
+
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+
+    await user.click(screen.getByRole('button', { name: 'Remove Attendance' }));
+    expect(screen.getByRole('button', { name: 'Return home' })).toHaveFocus();
+  });
+
+  test('deleting a focused remove button in the composite model focuses the next available tag target', async () => {
+    const user = userEvent.setup();
+
+    const Example = () => {
+      const [itemIds, setItemIds] = useState(['attendance', 'registers']);
+      const items: TagList.Item[] = itemIds.map(itemId => ({
+        id: itemId,
+        children: itemId === 'attendance' ? 'Attendance' : 'Registers',
+        onClick: vi.fn(),
+        onRemove: itemId === 'attendance'
+          ? () => setItemIds(current => current.filter(id => id !== itemId))
+          : undefined,
+        removeLabel: itemId === 'attendance' ? 'Remove Attendance' : undefined,
+      }));
+
+      return <TagList items={items} />;
+    };
+
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Attendance' })).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Remove Attendance' })).toHaveFocus();
+
+    await user.keyboard('{Delete}');
+    expect(screen.getByRole('button', { name: 'Registers' })).toHaveFocus();
+  });
+
+  test('collapses overflowing items into a trailing summary', () => {
+    const rectSpy = mockTagListCollapseRects();
+
+    try {
+      render(
+        <TagList
+          collapseOverflow
+          items={[
+            { id: 'date', children: 'Wed, 05 Feb 2025 AM' },
+            { id: 'registers', children: 'Attendance registers' },
+            { id: 'interventions', children: 'Interventions' },
+            { id: 'exclusions', children: 'Internal exclusions' },
+          ]}
+        />,
+      );
+
+      expect(screen.getByText('+3 more')).toBeInTheDocument();
+    }
+    finally {
+      rectSpy.mockRestore();
+    }
+  });
+
+  test('makes the +N more summary focusable and clickable when an overflow action is provided', async () => {
+    const user = userEvent.setup();
+    const onOverflowClick = vi.fn();
+    const rectSpy = mockTagListCollapseRects();
+
+    try {
+      render(
+        <TagList
+          collapseOverflow
+          overflowOnClick={onOverflowClick}
+          overflowActionLabel="Show more filters"
+          items={[
+            { id: 'date', children: 'Wed, 05 Feb 2025 AM', onClick: vi.fn() },
+            { id: 'registers', children: 'Attendance registers', onClick: vi.fn() },
+            { id: 'interventions', children: 'Interventions', onClick: vi.fn() },
+            { id: 'exclusions', children: 'Internal exclusions', onClick: vi.fn() },
+          ]}
+        />,
+      );
+
+      await user.tab();
+      await user.keyboard('{ArrowRight}');
+      expect(screen.getByRole('button', { name: 'Show more filters' })).toHaveFocus();
+
+      await user.keyboard('{Enter}');
+      expect(onOverflowClick).toHaveBeenCalledOnce();
+    }
+    finally {
+      rectSpy.mockRestore();
+    }
+  });
+});

package/src/components/tagList/TagList.tsx

@@ -0,0 +1,296 @@
+import classNames from 'classnames';
+import { Tag, type TagColor } from 'Components/tag/Tag';
+import { useRovingFocus } from 'Utils/hooks/useRovingFocus';
+import { useCallback, useMemo, type RefObject } from 'react';
+import { useTagListCollapsedLayout } from './useTagListCollapsedLayout.js';
+
+export type TagListItem = {
+  id: string;
+  children: React.ReactNode;
+  color?: TagColor;
+  selected?: boolean;
+  slotStart?: React.ReactNode;
+  slotEnd?: React.ReactNode;
+  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+  onRemove?: () => void;
+  removeLabel?: string;
+  actionLabel?: string;
+  disabled?: boolean;
+  ariaControls?: string;
+  ariaExpanded?: boolean;
+};
+
+export type TagListOverflowRenderArgs = {
+  hiddenItemCount: number;
+  totalItemCount: number;
+  visibleItemCount: number;
+};
+
+export type TagListOverflowTarget = 'overflow';
+type TagListItemTarget = `action:${string}` | `remove:${string}`;
+type TagListTarget = TagListItemTarget | TagListOverflowTarget;
+
+const getActionTarget = (itemId: string): TagListItemTarget => `action:${itemId}`;
+const getRemoveTarget = (itemId: string): TagListItemTarget => `remove:${itemId}`;
+const getTargetItemId = (target: TagListItemTarget): string => target.slice(target.indexOf(':') + 1);
+
+export type TagListProps = {
+  items: TagListItem[];
+  className?: string;
+  ariaLabel?: string;
+  emptyState?: React.ReactNode;
+  returnFocusRef?: RefObject<HTMLElement | null>;
+  wrap?: boolean;
+  collapseOverflow?: boolean;
+  highlightedItemIndex?: number | null;
+  onHighlightedItemIndexChange?: (index: number | null) => void;
+  overflowRenderer?: (args: TagListOverflowRenderArgs) => React.ReactNode;
+  overflowOnClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+  overflowActionLabel?: string;
+  overflowDisabled?: boolean;
+  overflowColor?: TagColor;
+  overflowAriaControls?: string;
+  overflowAriaExpanded?: boolean;
+};
+
+const defaultOverflowRenderer = ({
+  hiddenItemCount,
+}: TagListOverflowRenderArgs): React.ReactNode => `+${hiddenItemCount} more`;
+
+export const TagList = ({
+  items,
+  className,
+  ariaLabel,
+  emptyState,
+  returnFocusRef,
+  wrap = false,
+  collapseOverflow = false,
+  highlightedItemIndex,
+  onHighlightedItemIndexChange,
+  overflowRenderer = defaultOverflowRenderer,
+  overflowOnClick,
+  overflowActionLabel,
+  overflowDisabled = false,
+  overflowColor = 'neutral',
+  overflowAriaControls,
+  overflowAriaExpanded,
+}: TagListProps): React.JSX.Element | null => {
+  const {
+    contentRef,
+    measureTrackRef,
+    overflowProbeRef,
+    shouldCollapse,
+    visibleItemIndices,
+    visibleItems,
+    hiddenItemCount,
+    overflowArgs,
+  } = useTagListCollapsedLayout({
+    items,
+    wrap,
+    collapseOverflow,
+  });
+  const itemIndexById = useMemo(
+    () => new Map(items.map((item, index) => [item.id, index])),
+    [items],
+  );
+  const hasInteractiveOverflow = hiddenItemCount > 0 && Boolean(overflowOnClick) && !overflowDisabled;
+  const visibleInteractiveTargets = useMemo<TagListTarget[]>(
+    () =>
+      [
+        ...visibleItemIndices.flatMap((index) => {
+          const item = items[index];
+          if (!item) return [];
+
+          const targets: TagListTarget[] = [];
+          if (item.onClick) {
+            targets.push(getActionTarget(item.id));
+          }
+          if (item.onRemove) {
+            targets.push(getRemoveTarget(item.id));
+          }
+          return targets;
+        }),
+        ...(hasInteractiveOverflow ? ['overflow' as const] : []),
+      ],
+    [hasInteractiveOverflow, items, visibleItemIndices],
+  );
+  const hasInteractiveItems = visibleInteractiveTargets.length > 0;
+
+  const getHighlightedIndexForTarget = useCallback((target: TagListTarget | null): number | null => {
+    if (!target || target === 'overflow') return null;
+
+    return itemIndexById.get(getTargetItemId(target)) ?? null;
+  }, [itemIndexById]);
+
+  const handleActiveTargetChange = useCallback((target: TagListTarget | null) => {
+    onHighlightedItemIndexChange?.(getHighlightedIndexForTarget(target));
+  }, [getHighlightedIndexForTarget, onHighlightedItemIndexChange]);
+
+  const handleDeleteKey = useCallback((target: TagListTarget, event: React.KeyboardEvent<HTMLElement>): boolean => {
+    if (target === 'overflow') return false;
+
+    const item = items[getHighlightedIndexForTarget(target) ?? -1];
+    if (item?.onRemove) {
+      event.preventDefault();
+      item.onRemove();
+      return true;
+    }
+
+    return false;
+  }, [getHighlightedIndexForTarget, items]);
+
+  const {
+    getTargetTabIndex,
+    handleTargetKeyDown,
+    queueFocusRecovery,
+    registerTarget,
+    setActiveTarget,
+  } = useRovingFocus<TagListTarget>({
+    targets: hasInteractiveItems ? visibleInteractiveTargets : [],
+    returnFocusRef,
+    onActiveTargetChange: handleActiveTargetChange,
+    onDeleteKey: handleDeleteKey,
+  });
+
+  const renderTagItem = useCallback((item: TagListItem, index: number, includeInteractiveProps = true): React.ReactNode => {
+    const actionTarget = getActionTarget(item.id);
+    const removeTarget = getRemoveTarget(item.id);
+
+    return (
+      <Tag
+        color={item.color}
+        selected={item.selected || highlightedItemIndex === index}
+        slotStart={item.slotStart}
+        slotEnd={item.slotEnd}
+        onClick={includeInteractiveProps && item.onClick
+          ? (event) => {
+              setActiveTarget(actionTarget);
+              item.onClick?.(event);
+            }
+          : undefined}
+        onKeyDown={includeInteractiveProps && item.onClick ? event => handleTargetKeyDown(event, actionTarget) : undefined}
+        onFocus={includeInteractiveProps && item.onClick ? () => setActiveTarget(actionTarget) : undefined}
+        actionLabel={item.actionLabel}
+        actionButtonTabIndex={includeInteractiveProps && item.onClick ? getTargetTabIndex(actionTarget) : 0}
+        actionRef={includeInteractiveProps && item.onClick ? node => registerTarget(actionTarget, node) : undefined}
+        onRemove={includeInteractiveProps && item.onRemove
+          ? () => {
+              queueFocusRecovery(removeTarget);
+              item.onRemove?.();
+            }
+          : undefined}
+        onRemoveKeyDown={includeInteractiveProps && item.onRemove ? event => handleTargetKeyDown(event, removeTarget) : undefined}
+        onRemoveFocus={includeInteractiveProps && item.onRemove ? () => setActiveTarget(removeTarget) : undefined}
+        removeLabel={item.removeLabel}
+        removeButtonTabIndex={includeInteractiveProps && item.onRemove ? getTargetTabIndex(removeTarget) : 0}
+        removeButtonRef={includeInteractiveProps && item.onRemove ? node => registerTarget(removeTarget, node) : undefined}
+        disabled={item.disabled}
+        ariaControls={item.ariaControls}
+        ariaExpanded={item.ariaExpanded}
+      >
+        {item.children}
+      </Tag>
+    );
+  }, [
+    getTargetTabIndex,
+    handleTargetKeyDown,
+    highlightedItemIndex,
+    queueFocusRecovery,
+    registerTarget,
+    setActiveTarget,
+  ]);
+
+  const overflowContent = hiddenItemCount > 0
+    ? overflowRenderer(overflowArgs)
+    : null;
+
+  const overflowTag = overflowContent
+    ? (
+        <Tag
+          color={overflowColor}
+          onClick={overflowOnClick
+            ? (event) => {
+                setActiveTarget('overflow');
+                overflowOnClick(event);
+              }
+            : undefined}
+          onKeyDown={overflowOnClick ? event => handleTargetKeyDown(event, 'overflow') : undefined}
+          onFocus={overflowOnClick ? () => setActiveTarget('overflow') : undefined}
+          actionLabel={overflowActionLabel}
+          actionButtonTabIndex={overflowOnClick ? getTargetTabIndex('overflow') : 0}
+          actionRef={overflowOnClick ? node => registerTarget('overflow', node) : undefined}
+          disabled={overflowDisabled}
+          ariaControls={overflowAriaControls}
+          ariaExpanded={overflowAriaExpanded}
+        >
+          {overflowContent}
+        </Tag>
+      )
+    : null;
+
+  if (items.length === 0) {
+    if (!emptyState) return null;
+    return <div className={classNames('ds-tag-list', 'ds-tag-list--empty', className)}>{emptyState}</div>;
+  }
+
+  return (
+    <div className={classNames('ds-tag-list', className, {
+      'ds-tag-list--wrap': wrap,
+    })}
+    >
+      <div
+        className={classNames('ds-tag-list__viewport', {
+          'ds-tag-list__viewport--clip': shouldCollapse,
+        })}
+        ref={contentRef}
+      >
+        <ul
+          className={classNames('ds-tag-list__list', {
+            'ds-tag-list__list--wrap': wrap,
+          })}
+          aria-label={ariaLabel}
+        >
+          {visibleItems.map((item, visibleIndex) => {
+            const actualIndex = visibleItemIndices[visibleIndex]!;
+            return (
+              <li key={item.id} className="ds-tag-list__item">
+                {renderTagItem(item, actualIndex)}
+              </li>
+            );
+          })}
+        </ul>
+        {overflowTag && (
+          <div className="ds-tag-list__overflow">
+            {overflowTag}
+          </div>
+        )}
+      </div>
+
+      {shouldCollapse && (
+        <div className="ds-tag-list__measure" aria-hidden="true">
+          <ul className="ds-tag-list__list" ref={measureTrackRef}>
+            {items.map((item, index) => (
+              <li key={`measure-${item.id}`} className="ds-tag-list__item">
+                {renderTagItem(item, index, false)}
+              </li>
+            ))}
+          </ul>
+          <div ref={overflowProbeRef} className="ds-tag-list__overflow">
+            {overflowRenderer({
+              hiddenItemCount: items.length,
+              totalItemCount: items.length,
+              visibleItemCount: 0,
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export namespace TagList {
+  export type Props = TagListProps;
+  export type Item = TagListItem;
+  export type OverflowRenderArgs = TagListOverflowRenderArgs;
+  export type OverflowTarget = TagListOverflowTarget;
+}

package/src/components/tagList/tagList.scss

@@ -0,0 +1,56 @@
+.ds-tag-list {
+  min-width: 0;
+}
+
+.ds-tag-list--empty {
+  min-width: 0;
+}
+
+.ds-tag-list__viewport {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  min-width: 0;
+  padding-block: var(--focus-border);
+  margin-block: calc(var(--focus-border) * -1);
+}
+
+.ds-tag-list__viewport--clip {
+  overflow-x: hidden;
+}
+
+.ds-tag-list__list {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ds-tag-list__list--wrap {
+  flex-wrap: wrap;
+}
+
+.ds-tag-list__item {
+  min-width: 0;
+}
+
+.ds-tag-list__overflow {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.ds-tag-list__measure {
+  position: absolute;
+  visibility: hidden;
+  pointer-events: none;
+  left: -9999px;
+  top: -9999px;
+  white-space: nowrap;
+  width: max-content;
+  height: 0;
+  overflow: hidden;
+}