An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file TreeList.test.tsx
* @input Uses vitest, @testing-library/react, TreeList
* @output Unit tests for TreeList component
* @position Testing; validates TreeList.tsx implementation
*
* SYNC: When modified, update this header
*/
import {describe, it, expect, vi} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import type {ReactNode} from 'react';
import userEvent from '@testing-library/user-event';
import * as stylex from '@stylexjs/stylex';
import {TreeList} from './TreeList';
import type {TreeListItemData} from './TreeListTypes';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
import {FOCUS_OUTLINE} from '../utils/focusOutline.stylex';
function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
const {prose, component} = generateThemeCSS(theme);
return [prose, component].filter(Boolean).join('\n\n');
}
/**
* Concatenate all StyleX-injected CSS (both CSSOM sheets and <style> text) so
* tests can assert on compiled stylesheet rules — jsdom does not resolve the
* @layer cascade or compute layout, so structural CSS assertions read the
* generated declarations directly.
*/
function collectCssText(): string {
let out = '';
for (const sheet of Array.from(document.styleSheets)) {
try {
for (const rule of Array.from(sheet.cssRules)) {
out += rule.cssText + '\n';
}
} catch {
// ignore cross-origin sheets
}
}
out += Array.from(document.querySelectorAll('style'))
.map(s => s.textContent || '')
.join('\n');
return out;
}
const rowStyles = stylex.create({
custom: {opacity: 0.75},
});
const simpleItems: TreeListItemData[] = [
{id: 'a', label: 'Item A'},
{id: 'b', label: 'Item B'},
];
const nestedItems: TreeListItemData[] = [
{
id: 'parent',
label: 'Parent',
children: [
{id: 'child-1', label: 'Child 1'},
{id: 'child-2', label: 'Child 2'},
],
},
{id: 'sibling', label: 'Sibling'},
];
const nestedItemsExpanded: TreeListItemData[] = [
{
id: 'parent',
label: 'Parent',
isExpanded: true,
children: [
{id: 'child-1', label: 'Child 1'},
{id: 'child-2', label: 'Child 2'},
],
},
{id: 'sibling', label: 'Sibling'},
];
const deepItems: TreeListItemData[] = [
{
id: 'root',
label: 'Root',
isExpanded: true,
children: [
{
id: 'mid',
label: 'Mid',
isExpanded: true,
children: [{id: 'leaf', label: 'Leaf'}],
},
],
},
];
// APG keyboard fixtures (module-level to satisfy no-unstable-default-props).
const flatItems: TreeListItemData[] = [
{id: 'a', label: 'Apple'},
{id: 'b', label: 'Banana'},
{id: 'c', label: 'Cherry'},
];
const withDisabledItems: TreeListItemData[] = [
{id: 'a', label: 'Apple'},
{id: 'b', label: 'Banana', isDisabled: true},
{id: 'c', label: 'Cherry'},
];
const collapsedParentItems: TreeListItemData[] = [
{
id: 'parent',
label: 'Parent',
children: [
{id: 'child-1', label: 'Child 1'},
{id: 'child-2', label: 'Child 2'},
],
},
{id: 'sibling', label: 'Sibling'},
];
const expandedParentItems: TreeListItemData[] = [
{
id: 'parent',
label: 'Parent',
isExpanded: true,
children: [
{id: 'child-1', label: 'Child 1'},
{id: 'child-2', label: 'Child 2'},
],
},
{id: 'sibling', label: 'Sibling'},
];
describe('TreeList', () => {
// ===========================================================================
// Basic rendering
// ===========================================================================
it('renders items', () => {
render(<TreeList items={simpleItems} />);
expect(screen.getByText('Item A')).toBeInTheDocument();
expect(screen.getByText('Item B')).toBeInTheDocument();
});
it('renders with data-testid', () => {
render(<TreeList items={simpleItems} data-testid="tree" />);
expect(screen.getByTestId('tree')).toBeInTheDocument();
});
it('forwards aria-label to the tree element', () => {
render(<TreeList items={simpleItems} aria-label="File tree" />);
const tree = screen.getByRole('tree');
expect(tree).toHaveAttribute('aria-label', 'File tree');
});
it('forwards id to the root element', () => {
render(<TreeList items={simpleItems} id="file-tree" />);
const root = screen.getByRole('tree').parentElement;
expect(root).toHaveAttribute('id', 'file-tree');
});
it('renders description text', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Label', description: 'Description text'},
];
render(<TreeList items={items} />);
expect(screen.getByText('Description text')).toBeInTheDocument();
});
// ===========================================================================
// Row accessible name and description (APG tree view: named by the label)
// ===========================================================================
it('names a parent row by its label alone, not the chevron toggle', () => {
const items: TreeListItemData[] = [
{id: 'docs', label: 'Documents', children: [{id: 'a', label: 'Annual'}]},
];
render(<TreeList items={items} />);
const row = screen.getByText('Documents').closest('li')!;
expect(row).toHaveAccessibleName('Documents');
});
it('names a plain row by its label and describes it with its description', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Budget', description: 'Updated yesterday'},
];
render(<TreeList items={items} />);
const row = screen.getByText('Budget').closest('li')!;
expect(row).toHaveAccessibleName('Budget');
expect(row).toHaveAccessibleDescription('Updated yesterday');
});
it('names and describes link and action rows themselves, not only their inner control', () => {
const items: TreeListItemData[] = [
{id: 'l', label: 'Report', description: 'Opens the report', href: '#'},
{
id: 'b',
label: 'Export',
description: 'Downloads a file',
onClick: () => {},
},
];
render(<TreeList items={items} />);
const link = screen.getByText('Report').closest('li')!;
expect(link).toHaveAccessibleName('Report');
expect(link).toHaveAccessibleDescription('Opens the report');
const action = screen.getByText('Export').closest('li')!;
expect(action).toHaveAccessibleName('Export');
expect(action).toHaveAccessibleDescription('Downloads a file');
});
it('keeps start and end content, including controls, out of the row name', () => {
const items: TreeListItemData[] = [
{
id: 'a',
label: 'Invoices',
startContent: <span>12</span>,
endContent: <button type="button">Pin folder</button>,
},
];
render(<TreeList items={items} />);
const row = screen.getByText('Invoices').closest('li')!;
expect(row).toHaveAccessibleName('Invoices');
});
it('typeahead matches the label, not the description or start content', async () => {
const user = userEvent.setup();
const items: TreeListItemData[] = [
{id: 'a', label: 'Apple', description: 'Cherry-red fruit'},
{id: 'b', label: 'Banana', startContent: <span>Curved</span>},
{id: 'c', label: 'Cherry'},
];
render(<TreeList items={items} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('c');
expect(document.activeElement).toBe(
screen.getByText('Cherry').closest('li'),
);
});
// ===========================================================================
// Semantic HTML
// ===========================================================================
it('renders a tree role on the list', () => {
render(<TreeList items={simpleItems} />);
expect(screen.getByRole('tree')).toBeInTheDocument();
});
it('renders treeitem role on items', () => {
render(<TreeList items={simpleItems} />);
const treeitems = screen.getAllByRole('treeitem');
expect(treeitems).toHaveLength(2);
});
it('renders items as <li> elements', () => {
const {container} = render(<TreeList items={simpleItems} />);
const items = container.querySelectorAll('li');
expect(items).toHaveLength(2);
});
// ===========================================================================
// Header with aria-labelledby
// ===========================================================================
it('renders header and associates via aria-labelledby', () => {
render(<TreeList items={simpleItems} header={<span>File Tree</span>} />);
expect(screen.getByText('File Tree')).toBeInTheDocument();
const tree = screen.getByRole('tree');
const headerId = tree.getAttribute('aria-labelledby');
expect(headerId).toBeTruthy();
const headerEl = document.getElementById(headerId!);
expect(headerEl?.textContent).toBe('File Tree');
});
it('does not render aria-labelledby when no header', () => {
render(<TreeList items={simpleItems} />);
const tree = screen.getByRole('tree');
expect(tree).not.toHaveAttribute('aria-labelledby');
});
it('prefers the visible header id over caller aria-labelledby when header exists', () => {
render(
<TreeList
items={simpleItems}
header={<span>File Tree</span>}
aria-labelledby="external-label"
/>,
);
const tree = screen.getByRole('tree');
const headerId = tree.getAttribute('aria-labelledby');
expect(headerId).toBeTruthy();
expect(headerId).not.toBe('external-label');
const headerEl = document.getElementById(headerId!);
expect(headerEl?.textContent).toBe('File Tree');
});
it('uses caller aria-labelledby on the headerless path', () => {
render(<TreeList items={simpleItems} aria-labelledby="external-label" />);
const tree = screen.getByRole('tree');
expect(tree).toHaveAttribute('aria-labelledby', 'external-label');
});
it('ignores caller aria-label when a header names the tree', () => {
render(
<TreeList
items={simpleItems}
header={<span>File Tree</span>}
aria-label="External name"
/>,
);
const tree = screen.getByRole('tree');
expect(tree).not.toHaveAttribute('aria-label');
const headerId = tree.getAttribute('aria-labelledby');
const headerEl = document.getElementById(headerId!);
expect(headerEl?.textContent).toBe('File Tree');
});
// ===========================================================================
// Expansion (internal state)
// ===========================================================================
it('does not render children by default', () => {
render(<TreeList items={nestedItems} />);
expect(screen.getByText('Parent')).toBeInTheDocument();
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
});
it('renders children when item has isExpanded: true', () => {
render(<TreeList items={nestedItemsExpanded} />);
expect(screen.getByText('Child 1')).toBeInTheDocument();
expect(screen.getByText('Child 2')).toBeInTheDocument();
});
it('sets aria-expanded on items with children', () => {
render(<TreeList items={nestedItemsExpanded} />);
const parent = screen.getByText('Parent').closest('li');
expect(parent).toHaveAttribute('aria-expanded', 'true');
});
it('sets aria-expanded=false on collapsed items with children', () => {
render(<TreeList items={nestedItems} />);
const parent = screen.getByText('Parent').closest('li');
expect(parent).toHaveAttribute('aria-expanded', 'false');
});
it('does not set aria-expanded on leaf items', () => {
render(<TreeList items={simpleItems} />);
const item = screen.getByText('Item A').closest('li');
expect(item).not.toHaveAttribute('aria-expanded');
});
it('renders a keyboard-focusable toggle button for parents without onClick/href', () => {
render(<TreeList items={nestedItems} />);
const toggle = screen.getByRole('button', {name: 'Toggle children'});
expect(toggle).toBeInTheDocument();
expect(toggle).toHaveAttribute('aria-expanded', 'false');
});
it('expands a parent from the keyboard via the toggle button', async () => {
const user = userEvent.setup();
render(<TreeList items={nestedItems} />);
// Collapsed: children are not rendered.
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
const toggle = screen.getByRole('button', {name: 'Toggle children'});
toggle.focus();
expect(toggle).toHaveFocus();
await user.keyboard('{Enter}');
expect(screen.getByText('Child 1')).toBeInTheDocument();
expect(toggle).toHaveAttribute('aria-expanded', 'true');
});
it('renders group role for nested children', () => {
render(<TreeList items={nestedItemsExpanded} />);
const groups = document.querySelectorAll('[role="group"]');
expect(groups.length).toBeGreaterThanOrEqual(1);
});
it('expands a collapsed item when clicked', async () => {
const user = userEvent.setup();
render(<TreeList items={nestedItems} />);
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
await user.click(screen.getByText('Parent'));
expect(screen.getByText('Child 1')).toBeInTheDocument();
});
it('collapses an expanded item when clicked', async () => {
const user = userEvent.setup();
render(<TreeList items={nestedItemsExpanded} />);
expect(screen.getByText('Child 1')).toBeInTheDocument();
await user.click(screen.getByText('Parent'));
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
});
// ===========================================================================
// Deep nesting
// ===========================================================================
it('renders deeply nested items when all expanded', () => {
render(<TreeList items={deepItems} />);
expect(screen.getByText('Root')).toBeInTheDocument();
expect(screen.getByText('Mid')).toBeInTheDocument();
expect(screen.getByText('Leaf')).toBeInTheDocument();
});
// ===========================================================================
// Focus-visible outline scoping (regression: focusing a parent row must not
// leak the ring onto descendant rows — see #4130)
// ===========================================================================
it('scopes the focus-visible outline to the focused row, not its descendants', () => {
render(<TreeList items={deepItems} />);
const root = screen.getByText('Root').closest('li')!;
const mid = screen.getByText('Mid').closest('li')!;
const leaf = screen.getByText('Leaf').closest('li')!;
// A keydown before .focus() establishes keyboard modality so jsdom's
// :focus-visible heuristic applies deterministically, regardless of
// pointer events left over from other tests in this file.
fireEvent.keyDown(document.body, {key: 'Tab'});
root.focus();
expect(root).toHaveFocus();
expect(
getComputedStyle(root).getPropertyValue('--_focus-outline').trim(),
).toBe(FOCUS_OUTLINE);
// Mid and Leaf are DOM descendants of Root's <li> (nested <ul role="group">
// subtrees) — their own outline var must stay unset, not inherit Root's.
expect(getComputedStyle(mid).getPropertyValue('--_focus-outline')).toBe(
'none',
);
expect(getComputedStyle(leaf).getPropertyValue('--_focus-outline')).toBe(
'none',
);
});
// ===========================================================================
// Interactive items
// ===========================================================================
it('renders an invisible button when onClick is provided', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Clickable', onClick: () => {}},
];
const {container} = render(<TreeList items={items} />);
const button = container.querySelector('button');
expect(button).toBeInTheDocument();
expect(button?.textContent).toContain('Clickable');
});
it('fires onClick when invisible button is clicked', async () => {
const user = userEvent.setup();
const onClick = vi.fn();
const items: TreeListItemData[] = [{id: 'a', label: 'Clickable', onClick}];
render(<TreeList items={items} />);
await user.click(screen.getByRole('button'));
expect(onClick).toHaveBeenCalledTimes(1);
});
it('renders an invisible anchor when href is provided', () => {
const items: TreeListItemData[] = [{id: 'a', label: 'Link', href: '/docs'}];
const {container} = render(<TreeList items={items} />);
const anchor = container.querySelector('a');
expect(anchor).toBeInTheDocument();
expect(anchor).toHaveAttribute('href', '/docs');
});
it('does not render button or anchor for static items', () => {
const {container} = render(<TreeList items={simpleItems} />);
expect(container.querySelector('button')).not.toBeInTheDocument();
expect(container.querySelector('a')).not.toBeInTheDocument();
});
// ===========================================================================
// Disabled state
// ===========================================================================
it('applies aria-disabled when isDisabled', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Disabled', isDisabled: true},
];
render(<TreeList items={items} />);
const li = screen.getByText('Disabled').closest('li');
expect(li).toHaveAttribute('aria-disabled', 'true');
});
// ===========================================================================
// Selected state
// ===========================================================================
it('applies aria-selected when isSelected', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Selected', isSelected: true},
];
render(<TreeList items={items} />);
const li = screen.getByText('Selected').closest('li');
expect(li).toHaveAttribute('aria-selected', 'true');
});
it('does not apply aria-selected when not selected', () => {
render(<TreeList items={simpleItems} />);
const li = screen.getByText('Item A').closest('li');
expect(li).not.toHaveAttribute('aria-selected');
});
// ===========================================================================
// startContent and endContent
// ===========================================================================
it('renders startContent', () => {
const items: TreeListItemData[] = [
{
id: 'a',
label: 'With Icon',
startContent: <span data-testid="icon">★</span>,
},
];
render(<TreeList items={items} />);
expect(screen.getByTestId('icon')).toBeInTheDocument();
});
it('renders endContent', () => {
const items: TreeListItemData[] = [
{
id: 'a',
label: 'With Badge',
endContent: <span data-testid="badge">3</span>,
},
];
render(<TreeList items={items} />);
expect(screen.getByTestId('badge')).toBeInTheDocument();
});
it('forwards xstyle, className, and style to an item row', () => {
const items: TreeListItemData[] = [
{
id: 'a',
label: 'Styled row',
xstyle: rowStyles.custom,
className: 'consumer-row',
style: {visibility: 'visible'},
},
];
render(<TreeList items={items} />);
const row = screen
.getByText('Styled row')
.closest('li')!
.querySelector('.astryx-tree-list-item')!;
expect(row).toHaveClass('consumer-row');
expect(row.className).toContain(
stylex.props(rowStyles.custom).className!.split(' ')[0],
);
expect(row).toHaveStyle({visibility: 'visible'});
expect(row.getAttribute('style')).toContain('--_tree-indent');
});
// ===========================================================================
// Density
// ===========================================================================
it('renders with compact density', () => {
render(<TreeList items={simpleItems} density="compact" />);
expect(screen.getByRole('tree')).toBeInTheDocument();
});
it('renders with spacious density', () => {
render(<TreeList items={simpleItems} density="spacious" />);
expect(screen.getByRole('tree')).toBeInTheDocument();
});
// ===========================================================================
// Variant (guide lines)
// ===========================================================================
describe('variant', () => {
it('renders guide lines by default', () => {
const {container} = render(<TreeList items={nestedItemsExpanded} />);
expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
});
it("variant='lineGuides' renders guide lines (explicit == default)", () => {
const {container} = render(
<TreeList items={nestedItemsExpanded} variant="lineGuides" />,
);
expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
});
it("variant='noGuides' renders NO guide lines", () => {
const {container} = render(
<TreeList items={nestedItemsExpanded} variant="noGuides" />,
);
expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
});
it("variant='noGuides' preserves the tree structure and items", () => {
render(<TreeList items={nestedItemsExpanded} variant="noGuides" />);
// Rows, roles, and nesting are all intact — only the connectors are gone.
expect(screen.getByRole('tree')).toBeInTheDocument();
expect(screen.getAllByRole('treeitem')).toHaveLength(4);
expect(screen.getByText('Parent')).toBeInTheDocument();
expect(screen.getByText('Child 1')).toBeInTheDocument();
expect(screen.getByText('Child 2')).toBeInTheDocument();
expect(screen.getByText('Sibling')).toBeInTheDocument();
});
it("variant='noGuides' preserves per-level indentation on the rows", () => {
// Indentation lives inside the row's padding-inline-start (not the
// guide element), so it must survive when the connectors are
// suppressed. The per-row distance is published as the `--_tree-indent`
// custom property (not an inline longhand — see #4308), so the theme
// layer can override the `padding-inline-start` declaration. A deeper
// row is indented more than a shallower one.
const {container} = render(
<TreeList items={deepItems} variant="noGuides" />,
);
const indentOf = (text: string): string => {
const li = screen.getByText(text).closest('li')!;
const styled = li.querySelector('[style*="--_tree-indent"]');
return styled?.getAttribute('style') ?? '';
};
// Guides are gone…
expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
// …but each level still publishes an indent distance, and the level
// multiplier grows with depth (0, 1, 2).
expect(indentOf('Root')).toContain('--_tree-indent');
expect(indentOf('Mid')).toContain('--_tree-indent');
expect(indentOf('Leaf')).toContain('--_tree-indent');
const level = (text: string): number => {
const m = /calc\((\d+)/.exec(indentOf(text));
return m ? Number(m[1]) : NaN;
};
expect(level('Mid')).toBeGreaterThan(level('Root'));
expect(level('Leaf')).toBeGreaterThan(level('Mid'));
});
});
// ===========================================================================
// Guide theme target
// ===========================================================================
describe('guide theme target', () => {
it('renders the astryx-tree-list-guide target on the connector lines', () => {
const {container} = render(<TreeList items={nestedItemsExpanded} />);
const guide = container.querySelector('.astryx-tree-list-guide');
// A dedicated, stable target so a theme can recolor or hide the guides
// without hiding the built-in connectors and reimplementing them.
expect(guide).not.toBeNull();
});
it('exposes tree-list-guide as a themeable defineTheme target', () => {
// jsdom cannot resolve the @layer cascade, so the generated CSS is what
// proves a theme override reaches the guide element.
const theme = defineTheme({
name: 'tree-list-guide-test',
components: {
'tree-list-guide': {
base: {backgroundColor: 'var(--color-accent)'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list-guide {');
expect(css).toContain('background-color: var(--color-accent)');
});
it('lets a theme hide the guides via display: none on the target', () => {
// Hiding the guides is done through the theme target, not a prop — the
// theme rule lands in @layer astryx-theme, above StyleX's base layer.
const theme = defineTheme({
name: 'tree-list-guide-hidden-test',
components: {
'tree-list-guide': {
base: {display: 'none'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list-guide {');
expect(css).toContain('display: none');
});
});
// ===========================================================================
// Indent lever (--tree-list-indent)
// ===========================================================================
describe('indent lever', () => {
it('lets a theme retune the indent step via the tree-list target', () => {
// The per-level step is a public, themeable var (default --spacing-4) set
// on the tree-list root, so a theme can retune the indent metric (e.g. to
// --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
// so the generated CSS is what proves the override reaches the lever.
const theme = defineTheme({
name: 'tree-list-indent-test',
components: {
'tree-list': {
base: {'--tree-list-indent': 'var(--spacing-5)'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list {');
expect(css).toContain('--tree-list-indent: var(--spacing-5)');
});
it('rows consume the indent step in their published indent distance', () => {
// Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
// so retuning the step scales every level uniformly.
render(<TreeList items={deepItems} variant="noGuides" />);
const indentOf = (text: string): string => {
const li = screen.getByText(text).closest('li')!;
const styled = li.querySelector('[style*="--_tree-indent"]');
return styled?.getAttribute('style') ?? '';
};
expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
});
it('indents inside the row so nested rows keep the full list width', () => {
// The row box keeps its own inline padding and stays full width; the
// indent is padding on a child inside it. A nested row's hover and
// selected fill therefore spans the list like a root row's, while its
// content lands where a margin indent would have put it.
render(<TreeList items={deepItems} />);
const rules = collectCssText();
expect(rules).toMatch(
/padding-inline-start:\s*var\(--_tree-indent,\s*0px\)/,
);
expect(rules).not.toMatch(/margin-inline-start:\s*var\(--_tree-indent/);
const row = screen
.getByText('Leaf')
.closest<HTMLElement>('.astryx-tree-list-item')!;
const indented = row.firstElementChild as HTMLElement;
expect(indented.className).toContain('indentedContent');
expect(row.className).not.toContain('indentedContent');
});
it("keeps the indent when a caller sets the row's padding", () => {
// Caller padding lands on the row box; the indent is on a separate
// element inside it, so the two compose instead of one replacing the
// other.
const items = [
{
id: 'root',
label: 'Root',
isExpanded: true,
children: [
{id: 'leaf', label: 'Leaf', style: {paddingInlineStart: '20px'}},
],
},
];
render(<TreeList items={items} />);
const row = screen
.getByText('Leaf')
.closest<HTMLElement>('.astryx-tree-list-item')!;
expect(row.style.paddingInlineStart).toBe('20px');
expect(row.getAttribute('style')).toContain('--_tree-indent');
expect((row.firstElementChild as HTMLElement).className).toContain(
'indentedContent',
);
});
describe('link rows', () => {
const linkItems = (endContent?: ReactNode): TreeListItemData[] => [
{
id: 'docs',
label: 'Docs',
isExpanded: true,
children: [
{id: 'report', label: 'Report', href: '/report', endContent},
],
},
];
const rowSurfaceOf = (link: HTMLElement) =>
link.closest<HTMLElement>('.astryx-tree-list-item')!
.firstElementChild as HTMLElement;
it('follows the link when the row is clicked outside its label', () => {
// The indent is part of the row now, so a click there must do what
// the row does. The click is delegated to the anchor through the
// shared enlarged-surface hook, modifier keys included.
render(<TreeList items={linkItems()} />);
const link = screen.getByRole('link', {name: 'Report'});
const clicks: MouseEvent[] = [];
link.addEventListener('click', e => {
clicks.push(e);
e.preventDefault();
});
fireEvent.click(rowSurfaceOf(link), {metaKey: true});
expect(clicks).toHaveLength(1);
expect(clicks[0].metaKey).toBe(true);
// The row box's own padding follows the link too.
fireEvent.click(rowSurfaceOf(link).parentElement!);
expect(clicks).toHaveLength(2);
// Clicking the label itself reaches the anchor once, not twice.
fireEvent.click(link);
expect(clicks).toHaveLength(3);
});
it('reports one click to ancestors per press', () => {
// The delegated click bubbles from the anchor; the original stops,
// so a listener above the tree sees exactly one click.
const onTreeClick = vi.fn();
render(<TreeList items={linkItems()} onClick={onTreeClick} />);
const link = screen.getByRole('link', {name: 'Report'});
link.addEventListener('click', e => e.preventDefault());
fireEvent.click(rowSurfaceOf(link));
expect(onTreeClick).toHaveBeenCalledTimes(1);
expect(onTreeClick.mock.calls[0][0].target).toBe(link);
});
it('leaves a role-based control in the row to itself', () => {
const onSwitch = vi.fn();
render(
<TreeList
items={linkItems(
<span
role="switch"
aria-checked="false"
aria-label="Pin"
tabIndex={0}
onClick={onSwitch}>
Pin
</span>,
)}
/>,
);
const link = screen.getByRole('link', {name: 'Report'});
const onLinkClick = vi.fn((e: Event) => e.preventDefault());
link.addEventListener('click', onLinkClick);
fireEvent.click(screen.getByRole('switch', {name: 'Pin'}));
expect(onSwitch).toHaveBeenCalledTimes(1);
expect(onLinkClick).not.toHaveBeenCalled();
});
it('opens the link in a new tab on a middle-click in the row', () => {
const open = vi.spyOn(window, 'open').mockImplementation(() => null);
render(<TreeList items={linkItems()} />);
const link = screen.getByRole('link', {name: 'Report'});
fireEvent.mouseUp(rowSurfaceOf(link), {button: 1});
expect(open).toHaveBeenCalledWith('/report', '_blank', 'noopener');
// A middle-click on the label is the browser's own.
open.mockClear();
fireEvent.mouseUp(link, {button: 1});
expect(open).not.toHaveBeenCalled();
open.mockRestore();
});
});
it("keeps focus on an item's inner link when the item becomes disabled (spec:AST-085 FR4)", () => {
const tree = (isDisabled: boolean) => [
{
id: 'docs',
label: 'Docs',
isExpanded: true,
children: [
{id: 'report', label: 'Report', href: '/report', isDisabled},
],
},
];
const {rerender} = render(<TreeList items={tree(false)} />);
// A pointer click leaves focus on the inner link.
screen.getByRole('link', {name: 'Report', hidden: true}).focus();
rerender(<TreeList items={tree(true)} />);
const disabled = screen.getByRole('link', {name: 'Report', hidden: true});
expect(disabled).not.toHaveAttribute('href');
expect(disabled).toHaveFocus();
});
it('does not follow a disabled link row', () => {
const items = [
{
id: 'docs',
label: 'Docs',
isExpanded: true,
children: [
{id: 'report', label: 'Report', href: '/report', isDisabled: true},
],
},
];
render(<TreeList items={items} />);
const link = screen.getByRole('link', {name: 'Report', hidden: true});
const onLinkClick = vi.fn((e: Event) => e.preventDefault());
link.addEventListener('click', onLinkClick);
const row = link.closest<HTMLElement>('.astryx-tree-list-item')!;
fireEvent.click(row.firstElementChild!);
expect(onLinkClick).not.toHaveBeenCalled();
// No destination, so a screen reader's click or a link menu cannot
// navigate either (spec:AST-085 FR2).
expect(link).toHaveAttribute('aria-disabled', 'true');
for (const attribute of ['href', 'target']) {
expect(link).not.toHaveAttribute(attribute);
}
});
describe('row clicks outside the label (FR7)', () => {
// Each row sits under an expanded root, so it has an indent; the click
// lands on the row surface (indent, reserved chevron column, padding),
// not on the label.
const underRoot = (children: TreeListItemData[]): TreeListItemData[] => [
{id: 'root', label: 'Root', isExpanded: true, children},
];
// The row box itself (its own padding) and the indented content inside
// it: FR7 covers clicks on both.
const rowOf = (label: string) =>
screen.getByText(label).closest<HTMLElement>('.astryx-tree-list-item')!;
const rowSurfaceOf = (label: string) =>
rowOf(label).firstElementChild as HTMLElement;
const folder: TreeListItemData = {
id: 'folder',
label: 'Folder',
children: [{id: 'file', label: 'File'}],
};
it("runs an action row's onClick once", () => {
const onClick = vi.fn();
render(
<TreeList items={underRoot([{id: 'run', label: 'Run', onClick}])} />,
);
fireEvent.click(rowSurfaceOf('Run'));
expect(onClick).toHaveBeenCalledTimes(1);
fireEvent.click(rowOf('Run'));
expect(onClick).toHaveBeenCalledTimes(2);
// The label's own button still runs it once per press, not twice.
fireEvent.click(screen.getByRole('button', {name: 'Run'}));
expect(onClick).toHaveBeenCalledTimes(3);
});
it('toggles a parent row', () => {
render(<TreeList items={underRoot([folder])} />);
expect(screen.queryByText('File')).not.toBeInTheDocument();
fireEvent.click(rowSurfaceOf('Folder'));
expect(screen.getByText('File')).toBeInTheDocument();
fireEvent.click(rowOf('Folder'));
expect(screen.queryByText('File')).not.toBeInTheDocument();
});
it('does nothing on a disabled action or parent row', () => {
const onClick = vi.fn();
render(
<TreeList
items={underRoot([
{id: 'run', label: 'Run', onClick, isDisabled: true},
{...folder, isDisabled: true},
])}
/>,
);
fireEvent.click(rowSurfaceOf('Run'));
fireEvent.click(rowOf('Run'));
expect(onClick).not.toHaveBeenCalled();
fireEvent.click(rowSurfaceOf('Folder'));
fireEvent.click(rowOf('Folder'));
expect(screen.queryByText('File')).not.toBeInTheDocument();
});
it("exposes a disabled row's toggle and action as aria-disabled and keeps them inert", () => {
const onClick = vi.fn();
const {container} = render(
<TreeList
items={underRoot([
{id: 'run', label: 'Run', onClick, isDisabled: true},
{...folder, isDisabled: true},
])}
/>,
);
// spec:AST-085 FR1/FR2: no native disabled anywhere, and a click
// dispatched straight on the inner controls does nothing.
expect(container.querySelector('[disabled]')).toBeNull();
const toggle = container.querySelector<HTMLElement>(
'[data-tree-toggle][aria-disabled="true"]',
)!;
expect(toggle).not.toBeNull();
toggle.click();
fireEvent.keyDown(toggle, {key: 'Enter'});
expect(screen.queryByText('File')).not.toBeInTheDocument();
const action = Array.from(container.querySelectorAll('button')).find(
button => button.textContent?.includes('Run'),
)!;
expect(action).toHaveAttribute('aria-disabled', 'true');
action.click();
expect(onClick).not.toHaveBeenCalled();
});
it('leaves a role-based control in start or end content to itself', () => {
// Native and role-based controls alike keep their own activation,
// the same rule link rows get from the shared enlarged-surface hook.
const onClick = vi.fn();
const onSwitch = vi.fn();
const pin = (name: string) => (
<span
role="switch"
aria-checked="false"
aria-label={name}
tabIndex={0}
onClick={onSwitch}>
{name}
</span>
);
render(
<TreeList
items={underRoot([
{
id: 'run',
label: 'Run',
onClick,
startContent: pin('Pin run start'),
endContent: pin('Pin run end'),
},
{
...folder,
startContent: pin('Pin folder start'),
endContent: pin('Pin folder end'),
},
])}
/>,
);
for (const name of [
'Pin run start',
'Pin run end',
'Pin folder start',
'Pin folder end',
]) {
fireEvent.click(screen.getByRole('switch', {name}));
}
expect(onSwitch).toHaveBeenCalledTimes(4);
expect(onClick).not.toHaveBeenCalled();
expect(screen.queryByText('File')).not.toBeInTheDocument();
});
});
it('draws guides above full-width rows without taking pointer input', () => {
// Guide columns now sit inside deeper rows' boxes. They paint above the
// rows so a row fill never breaks the line, and let clicks fall through
// to the row underneath.
const {container} = render(<TreeList items={deepItems} />);
const guide = container.querySelector('.astryx-tree-list-guide');
expect(guide).not.toBeNull();
const column = guide!.parentElement!;
expect(getComputedStyle(column).pointerEvents).toBe('none');
expect(getComputedStyle(column).zIndex).toBe('1');
// The tree contains that stacking so a guide cannot climb over
// positioned content outside the list.
const treeRoot = screen.getByRole('tree').parentElement!;
expect(treeRoot.className).toContain('astryx-tree-list');
expect(getComputedStyle(treeRoot).isolation).toBe('isolate');
});
it('lifts only rows that draw a focus ring above the guides', () => {
// A plain row (no onClick, href or children) draws no focus ring, so it
// stays under the guides: a focused selected plain row must not hide
// them with its fill (DD3). Rows that draw the ring take the lift.
render(
<TreeList
items={[
{
id: 'root',
label: 'Root',
isExpanded: true,
children: [
{id: 'plain', label: 'Plain', isSelected: true},
{id: 'run', label: 'Run', onClick: () => {}},
],
},
]}
/>,
);
const rowOf = (label: string) =>
screen.getByText(label).closest<HTMLElement>('.astryx-tree-list-item')!;
expect(rowOf('Plain').className).not.toContain('focusLift');
expect(rowOf('Run').className).toContain('focusLift');
expect(rowOf('Root').className).toContain('focusLift');
});
it('lifts the focused row above the guides so they never cut its ring', () => {
// Each treeitem publishes its own focus as `--_tree-focus-z`, and the
// row reads it as its z-index, so the focused row paints above the
// guide columns (z-index 1). Nested treeitems redeclare the default.
render(<TreeList items={deepItems} />);
const rules = collectCssText();
expect(rules).toMatch(/--_tree-focus-z:\s*2/);
expect(rules).toMatch(/z-index:\s*var\(--_tree-focus-z,\s*auto\)/);
});
});
// ===========================================================================
// Leaf chevron-column offset (group-expandable-sibling awareness)
// ===========================================================================
describe('leaf chevron-column offset', () => {
// A row publishes its indent as the inline `--_tree-indent` custom property.
// A leaf that reserves the chevron column adds a fixed offset
// (chevron width + gap) on top of its level indent; a flush leaf does not.
// The reserved column is expressed as the literal `+ <spacing-4> + <spacing-2>`
// suffix in the calc(), so its presence is what we assert (jsdom does not
// resolve the token values, so we check the structure, not pixels).
const indentStyleOf = (text: string): string => {
const li = screen.getByText(text).closest('li')!;
const styled = li.querySelector('[style*="--_tree-indent"]');
return styled?.getAttribute('style') ?? '';
};
// A reserved chevron column adds two extra terms to the indent calc()
// beyond the single `level * var(--tree-list-indent)` term.
const reservesColumn = (text: string): boolean => {
const style = indentStyleOf(text);
// count the `var(` occurrences inside --_tree-indent: a flush row has
// exactly one (the indent step); a reserving leaf adds the chevron
// width + gap tokens, so it has more.
const m = /--_tree-indent:\s*calc\(([^;]*)\)/.exec(style);
const body = m?.[1] ?? '';
return (body.match(/\bvar\(/g)?.length ?? 0) > 1 || body.includes('+');
};
it('a leaf in a mixed group reserves the chevron column (aligns under its expandable sibling)', () => {
// Group: [Parent (has children), Sibling (leaf)] → Sibling must line up
// under Parent's caret, so it keeps the chevron-column offset.
render(<TreeList items={nestedItems} />);
expect(reservesColumn('Sibling')).toBe(true);
});
it('a leaf under an expandable ancestor reserves the chevron column even when its own group is all leaves', () => {
// 'Root' → 'Mid' → 'Leaf'; 'Leaf' is the only item in its immediate
// group, but the tree has carets (Root, Mid), so Leaf must reserve the
// chevron column to stay indented past its parent's label. Flushing it
// here would push it left of Mid's label — the all-leaf-group bug.
render(<TreeList items={deepItems} variant="noGuides" />);
expect(reservesColumn('Leaf')).toBe(true);
});
it("an expanded parent's all-leaf children reserve the chevron column (do not flush left of the parent label)", () => {
// Regression: Parent (caret) → [Child 1, Child 2] is an all-leaf group
// nested under an expandable parent. Per-group flushing wrongly dropped
// these children's chevron column, pushing them LEFT of Parent's own
// label. Because the tree has a caret, they must reserve the column and
// stay indented past Parent.
render(<TreeList items={nestedItemsExpanded} />);
expect(reservesColumn('Child 1')).toBe(true);
expect(reservesColumn('Child 2')).toBe(true);
});
it('every row in a flat (all-leaf) tree sits flush — no chevron column reserved', () => {
render(<TreeList items={flatItems} />);
expect(reservesColumn('Apple')).toBe(false);
expect(reservesColumn('Banana')).toBe(false);
expect(reservesColumn('Cherry')).toBe(false);
});
it('leaves flush in an all-leaf group have the same indent structure as a parent at that level', () => {
// In a mixed group the reserving leaf indent has the extra terms; in an
// all-leaf group the leaf indent is the bare level step, exactly like a
// parent row's indent.
render(<TreeList items={flatItems} />);
const flush = indentStyleOf('Apple');
// bare level step: one var(--tree-list-indent), no additive chevron terms
expect(flush).toContain('var(--tree-list-indent)');
expect(/--_tree-indent:\s*calc\([^;]*\+[^;]*\)/.test(flush)).toBe(false);
});
});
// ===========================================================================
// Inter-row gap lever (--tree-list-row-gap) + guide spanning
// ===========================================================================
describe('row gap lever', () => {
it('defaults the row gap to a subtle 2px separation', () => {
// The lever is published on the tree-list root; its default is
// --spacing-0-5 (2px) so rows have a light separation out of the box. A
// theme can widen or close it via the tree-list target. jsdom does not
// resolve token vars, so the declared value is the --spacing-0-5 token.
render(<TreeList items={simpleItems} data-testid="tree" />);
const root = screen.getByTestId('tree');
expect(
getComputedStyle(root).getPropertyValue('--tree-list-row-gap').trim(),
).toBe('var(--spacing-0-5)');
});
it('lets a theme open a row gap via the tree-list target', () => {
// jsdom cannot resolve the @layer cascade, so the generated CSS is what
// proves the override reaches the lever.
const theme = defineTheme({
name: 'tree-list-row-gap-test',
components: {
'tree-list': {
base: {'--tree-list-row-gap': 'var(--spacing-1)'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list {');
expect(css).toContain('--tree-list-row-gap: var(--spacing-1)');
});
it('the guide of a row with a sibling below spans into it (verticalFull)', () => {
// A row that is NOT last in its group bridges the 1px hairline into the
// next contiguous sibling so the connector reads as one continuous line.
// Assert the APPLIED class on that row's own connector — not a global
// stylesheet regex — so the isLast ? verticalLast : verticalFull branch
// is actually exercised (Child 1 has Child 2 below it).
render(<TreeList items={nestedItemsExpanded} />);
const child1 = screen.getByText('Child 1').closest('li')!;
const guide = child1.firstElementChild!.querySelector(
'.astryx-tree-list-guide',
);
expect(guide).not.toBeNull();
expect(guide!.className).toContain('verticalFull');
expect(guide!.className).not.toContain('verticalLast');
});
it('clamps the last-in-group guide so it does not overhang the gap (verticalLast)', () => {
// The last row in a group has nothing below it, so its connector must NOT
// run through the row wrapper's bottom padding into empty space — it uses
// verticalLast, which subtracts half the row gap. Assert the applied class
// on the last child's own connector (Child 2 is last in its group), so a
// reverted branch is caught.
render(<TreeList items={nestedItemsExpanded} />);
const child2 = screen.getByText('Child 2').closest('li')!;
const guide = child2.firstElementChild!.querySelector(
'.astryx-tree-list-guide',
);
expect(guide).not.toBeNull();
expect(guide!.className).toContain('verticalLast');
expect(guide!.className).not.toContain('verticalFull');
});
it('carries the inter-row gap as collapse-proof padding on the row wrapper, not the paint target', () => {
// Finding from review: the gap must be `padding-block` (which cannot
// collapse) on the row WRAPPER, not `margin-block` on the row box — a
// margin there collapses through the position:relative wrapper and the
// <li>, delivering only half the configured gap. It also must not sit on
// `tree-list-item`, which is a paint seam (per the theming-target
// guidelines): layout longhands do not belong on a paintable target.
const {container} = render(<TreeList items={simpleItems} />);
const item = container.querySelector<HTMLElement>(
'.astryx-tree-list-item',
);
expect(item).not.toBeNull();
const rowWrapper = item!.parentElement!;
const rules = collectCssText();
// Map the rowWrapper's compiled class to its declaration block and assert
// it declares padding-block from the row-gap lever (half above/below).
const rowWrapperClass = Array.from(rowWrapper.classList).find(c =>
c.includes('rowWrapper'),
);
expect(rowWrapperClass).toBeDefined();
// The gap rides padding-block (collapse-proof), keyed off the lever.
expect(rules).toMatch(
/padding-block:\s*calc\(\s*var\(--tree-list-row-gap[^)]*\)\s*\/\s*2\s*\)/,
);
// And the paint target (tree-list-item / contentWrapper) must NOT carry a
// margin-block gap — the layout seam has moved off the paintable element.
const itemClass = Array.from(item!.classList).find(c =>
c.includes('contentWrapper'),
);
expect(itemClass).toBeDefined();
expect(rules).not.toMatch(
/margin-block:\s*calc\([^;]*var\(--tree-list-row-gap/,
);
});
});
// ===========================================================================
// xds class name
// ===========================================================================
it('applies astryx-tree-list class name', () => {
render(<TreeList items={simpleItems} data-testid="tree" />);
const root = screen.getByTestId('tree');
expect(root.className).toContain('astryx-tree-list');
});
// ===========================================================================
// Chevron theme target
// ===========================================================================
describe('chevron theme target', () => {
it('renders the astryx-tree-list-chevron target on the toggle button', () => {
render(<TreeList items={nestedItems} />);
const toggle = screen
.getByText('Parent')
.closest('li')!
.querySelector('[data-tree-toggle]')!;
// Dedicated, stable theme target on the expand/collapse control, so a
// theme can restyle the chevron without a fragile [data-tree-toggle] hook.
expect(toggle).toHaveClass('astryx-tree-list-chevron');
// Open/closed state is reflected so a theme can target each state alone.
expect(toggle).toHaveAttribute('data-state', 'collapsed');
});
it('reflects the expanded state on the toggle when open', () => {
render(<TreeList items={nestedItemsExpanded} />);
const toggle = screen
.getByText('Parent')
.closest('li')!
.querySelector('[data-tree-toggle]')!;
expect(toggle).toHaveClass('astryx-tree-list-chevron');
expect(toggle).toHaveAttribute('data-state', 'expanded');
});
it('keeps the functional data-tree-toggle hook alongside the new target', () => {
// The theme target is additive — the toggle is still a real <button> and
// still carries the functional activation attribute TreeList relies on.
render(<TreeList items={nestedItems} />);
const toggle = screen
.getByText('Parent')
.closest('li')!
.querySelector('[data-tree-toggle]')!;
expect(toggle.tagName).toBe('BUTTON');
expect(toggle).toHaveAttribute('data-tree-toggle');
});
it('exposes tree-list-chevron as a themeable defineTheme target', () => {
// The generated CSS is what proves the target is reachable by a theme:
// jsdom cannot resolve the @layer cascade, so the DOM-class assertions
// above and this generation assertion together cover the seam.
const theme = defineTheme({
name: 'tree-list-chevron-test',
components: {
'tree-list-chevron': {
base: {color: 'var(--color-accent)'},
'state:expanded': {color: 'var(--color-text-primary)'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list-chevron {');
expect(css).toContain('color: var(--color-accent)');
expect(css).toContain('.astryx-tree-list-chevron[data-state="expanded"]');
expect(css).toContain('color: var(--color-text-primary)');
});
});
// ===========================================================================
// Item label theme target
// ===========================================================================
describe('item label theme target', () => {
it('renders the astryx-tree-list-item-label target on the label span', () => {
render(<TreeList items={simpleItems} />);
const label = screen.getByText('Item A');
// Dedicated, stable theme target on the label text, so a theme can style
// just the label without a fragile `button:not([data-tree-toggle]) > span`
// structural selector.
expect(label).toHaveClass('astryx-tree-list-item-label');
// A non-selected item's label carries no selected reflection.
expect(label).not.toHaveAttribute('data-selected');
});
it('reflects the selected state on the selected item label', () => {
render(
<TreeList items={[{id: 'a', label: 'Item A', isSelected: true}]} />,
);
const label = screen.getByText('Item A');
expect(label).toHaveClass('astryx-tree-list-item-label');
expect(label).toHaveAttribute('data-selected', 'selected');
});
it('keeps the label linked to its row via aria-labelledby', () => {
// The theme target is additive — the label still owns the id the
// interactive row references for its accessible name.
render(
<TreeList items={[{id: 'a', label: 'Item A', onClick: () => {}}]} />,
);
const label = screen.getByText('Item A');
const action = screen.getByRole('button');
expect(action).toHaveAttribute('aria-labelledby', label.id);
});
it('exposes tree-list-item-label as a themeable defineTheme target', () => {
// The generated CSS is what proves the target is reachable by a theme:
// jsdom cannot resolve the @layer cascade, so the DOM-class assertions
// above and this generation assertion together cover the seam.
const theme = defineTheme({
name: 'tree-list-item-label-test',
components: {
'tree-list-item-label': {
base: {color: 'var(--color-text-primary)'},
selected: {fontWeight: 'var(--font-weight-bold)'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-tree-list-item-label {');
expect(css).toContain('color: var(--color-text-primary)');
expect(css).toContain(
'.astryx-tree-list-item-label[data-selected="selected"]',
);
expect(css).toContain('font-weight: var(--font-weight-bold)');
});
});
// ===========================================================================
// APG structural ARIA (aria-level / aria-posinset / aria-setsize)
// ===========================================================================
it('sets aria-level, aria-posinset, and aria-setsize at the top level', () => {
render(<TreeList items={flatItems} />);
const apple = screen.getByText('Apple').closest('li');
expect(apple).toHaveAttribute('aria-level', '1');
expect(apple).toHaveAttribute('aria-posinset', '1');
expect(apple).toHaveAttribute('aria-setsize', '3');
const cherry = screen.getByText('Cherry').closest('li');
expect(cherry).toHaveAttribute('aria-posinset', '3');
expect(cherry).toHaveAttribute('aria-setsize', '3');
});
it('sets aria-level/posinset/setsize correctly at deeper levels', () => {
render(<TreeList items={expandedParentItems} />);
const parent = screen.getByText('Parent').closest('li');
expect(parent).toHaveAttribute('aria-level', '1');
expect(parent).toHaveAttribute('aria-setsize', '2');
const child1 = screen.getByText('Child 1').closest('li');
expect(child1).toHaveAttribute('aria-level', '2');
expect(child1).toHaveAttribute('aria-posinset', '1');
expect(child1).toHaveAttribute('aria-setsize', '2');
const child2 = screen.getByText('Child 2').closest('li');
expect(child2).toHaveAttribute('aria-level', '2');
expect(child2).toHaveAttribute('aria-posinset', '2');
});
it('sets aria-level across three depths', () => {
render(<TreeList items={deepItems} />);
expect(screen.getByText('Root').closest('li')).toHaveAttribute(
'aria-level',
'1',
);
expect(screen.getByText('Mid').closest('li')).toHaveAttribute(
'aria-level',
'2',
);
expect(screen.getByText('Leaf').closest('li')).toHaveAttribute(
'aria-level',
'3',
);
});
// ===========================================================================
// Roving tabindex
// ===========================================================================
it('makes exactly one treeitem tabbable by default (the first enabled)', () => {
render(<TreeList items={flatItems} />);
const treeitems = screen.getAllByRole('treeitem');
const tabbable = treeitems.filter(
el => el.getAttribute('tabindex') === '0',
);
expect(tabbable).toHaveLength(1);
expect(tabbable[0]).toBe(screen.getByText('Apple').closest('li'));
expect(screen.getByText('Banana').closest('li')).toHaveAttribute(
'tabindex',
'-1',
);
});
it('defaults the tab stop to the selected item when one is selected', () => {
const items: TreeListItemData[] = [
{id: 'a', label: 'Apple'},
{id: 'b', label: 'Banana', isSelected: true},
{id: 'c', label: 'Cherry'},
];
render(<TreeList items={items} />);
expect(screen.getByText('Banana').closest('li')).toHaveAttribute(
'tabindex',
'0',
);
expect(screen.getByText('Apple').closest('li')).toHaveAttribute(
'tabindex',
'-1',
);
});
it('moves the single tab stop when focus moves via keyboard', async () => {
const user = userEvent.setup();
render(<TreeList items={flatItems} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('{ArrowDown}');
const treeitems = screen.getAllByRole('treeitem');
const tabbable = treeitems.filter(
el => el.getAttribute('tabindex') === '0',
);
expect(tabbable).toHaveLength(1);
expect(tabbable[0]).toBe(screen.getByText('Banana').closest('li'));
});
// ===========================================================================
// APG keyboard navigation
// ===========================================================================
it('ArrowDown / ArrowUp move focus between visible treeitems', async () => {
const user = userEvent.setup();
render(<TreeList items={flatItems} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('{ArrowDown}');
expect(document.activeElement).toBe(
screen.getByText('Banana').closest('li'),
);
await user.keyboard('{ArrowDown}');
expect(document.activeElement).toBe(
screen.getByText('Cherry').closest('li'),
);
await user.keyboard('{ArrowUp}');
expect(document.activeElement).toBe(
screen.getByText('Banana').closest('li'),
);
});
it('ArrowDown / ArrowUp skip disabled treeitems', async () => {
const user = userEvent.setup();
render(<TreeList items={withDisabledItems} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('{ArrowDown}');
// Banana is disabled → skipped, lands on Cherry.
expect(document.activeElement).toBe(
screen.getByText('Cherry').closest('li'),
);
await user.keyboard('{ArrowUp}');
expect(document.activeElement).toBe(
screen.getByText('Apple').closest('li'),
);
});
it('ArrowRight expands a collapsed parent, then enters the first child', async () => {
const user = userEvent.setup();
render(<TreeList items={collapsedParentItems} />);
const parent = screen.getByText('Parent').closest('li')!;
parent.focus();
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
await user.keyboard('{ArrowRight}');
// First ArrowRight expands.
expect(screen.getByText('Child 1')).toBeInTheDocument();
expect(document.activeElement).toBe(parent);
await user.keyboard('{ArrowRight}');
// Second ArrowRight moves into first child.
expect(document.activeElement).toBe(
screen.getByText('Child 1').closest('li'),
);
});
it('ArrowRight on a leaf is a no-op', async () => {
const user = userEvent.setup();
render(<TreeList items={flatItems} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('{ArrowRight}');
expect(document.activeElement).toBe(apple);
});
it('ArrowLeft collapses an expanded parent, then moves to parent', async () => {
const user = userEvent.setup();
render(<TreeList items={expandedParentItems} />);
const parent = screen.getByText('Parent').closest('li')!;
// Focus a child first.
const child1 = screen.getByText('Child 1').closest('li')!;
child1.focus();
await user.keyboard('{ArrowLeft}');
// Child is a leaf → ArrowLeft moves to parent.
expect(document.activeElement).toBe(parent);
await user.keyboard('{ArrowLeft}');
// Parent is expanded → ArrowLeft collapses it.
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
});
it('Home and End move to the first and last visible treeitems', async () => {
const user = userEvent.setup();
render(<TreeList items={flatItems} />);
const banana = screen.getByText('Banana').closest('li')!;
banana.focus();
await user.keyboard('{End}');
expect(document.activeElement).toBe(
screen.getByText('Cherry').closest('li'),
);
await user.keyboard('{Home}');
expect(document.activeElement).toBe(
screen.getByText('Apple').closest('li'),
);
});
it('Enter activates the item onClick', async () => {
const user = userEvent.setup();
const onClick = vi.fn();
const items: TreeListItemData[] = [{id: 'a', label: 'Apple', onClick}];
render(<TreeList items={items} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('{Enter}');
expect(onClick).toHaveBeenCalledTimes(1);
});
it('Space activates the item onClick', async () => {
const user = userEvent.setup();
const onClick = vi.fn();
const items: TreeListItemData[] = [{id: 'a', label: 'Apple', onClick}];
render(<TreeList items={items} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard(' ');
expect(onClick).toHaveBeenCalledTimes(1);
});
it('Enter toggles expansion for a parent without its own action', async () => {
const user = userEvent.setup();
render(<TreeList items={collapsedParentItems} />);
const parent = screen.getByText('Parent').closest('li')!;
parent.focus();
expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
await user.keyboard('{Enter}');
expect(screen.getByText('Child 1')).toBeInTheDocument();
});
it('typeahead moves focus to the next item matching typed characters', async () => {
const user = userEvent.setup();
render(<TreeList items={flatItems} />);
const apple = screen.getByText('Apple').closest('li')!;
apple.focus();
await user.keyboard('c');
expect(document.activeElement).toBe(
screen.getByText('Cherry').closest('li'),
);
});
it('typeahead reaches an accented label with a plain letter (INV17)', async () => {
const user = userEvent.setup();
render(
<TreeList
items={[
{id: 'dung', label: 'Dung', description: 'Đà Lạt'},
{id: 'dao', label: 'Đào', description: 'Hà Nội'},
{id: 'lodz', label: 'Łódź'},
]}
/>,
);
screen.getByText('Dung').closest('li')!.focus();
await user.keyboard('l');
expect(document.activeElement).toBe(screen.getByText('Łódź').closest('li'));
});
it('typeahead puts the exact match first for a typed mark (INV17)', async () => {
const user = userEvent.setup();
render(
<TreeList
items={[
{id: 'lodz', label: 'Łódź'},
{id: 'dung', label: 'Dung'},
{id: 'dao', label: 'Đào'},
]}
/>,
);
screen.getByText('Łódź').closest('li')!.focus();
await user.keyboard('đ');
expect(document.activeElement).toBe(screen.getByText('Đào').closest('li'));
});
it('lets a consumer prevent built-in TreeList keyboard navigation while receiving root div as event.currentTarget', () => {
let capturedCurrentTarget: Element | null = null;
const ref = {current: null as HTMLDivElement | null};
render(
<TreeList
ref={el => {
ref.current = el;
}}
items={[
{id: 'one', label: 'One'},
{id: 'two', label: 'Two'},
]}
onKeyDown={event => {
capturedCurrentTarget = event.currentTarget;
event.preventDefault();
}}
/>,
);
const items = screen.getAllByRole('treeitem');
items[0].focus();
fireEvent.keyDown(items[0], {key: 'ArrowDown'});
expect(capturedCurrentTarget).toBe(ref.current);
expect(ref.current).toBeInstanceOf(HTMLDivElement);
expect(items[0]).toHaveFocus();
expect(items[0]).toHaveAttribute('tabindex', '0');
expect(items[1]).toHaveAttribute('tabindex', '-1');
});
it('fires non-canceling consumer onKeyDown with root div as event.currentTarget while built-in navigation works', () => {
let capturedCurrentTarget: Element | null = null;
const ref = {current: null as HTMLDivElement | null};
const onKeyDown = vi.fn((event: React.KeyboardEvent<HTMLDivElement>) => {
capturedCurrentTarget = event.currentTarget;
});
render(
<TreeList
ref={el => {
ref.current = el;
}}
items={[
{id: 'one', label: 'One'},
{id: 'two', label: 'Two'},
]}
onKeyDown={onKeyDown}
/>,
);
const items = screen.getAllByRole('treeitem');
items[0].focus();
fireEvent.keyDown(items[0], {key: 'ArrowDown'});
expect(onKeyDown).toHaveBeenCalledTimes(1);
expect(capturedCurrentTarget).toBe(ref.current);
expect(ref.current).toBeInstanceOf(HTMLDivElement);
expect(items[1]).toHaveFocus();
expect(items[1]).toHaveAttribute('tabindex', '0');
});
it('does not trigger built-in tree navigation when keydown originates inside the header slot', () => {
let capturedCurrentTarget: Element | null = null;
const ref = {current: null as HTMLDivElement | null};
const onKeyDown = vi.fn((event: React.KeyboardEvent<HTMLDivElement>) => {
capturedCurrentTarget = event.currentTarget;
});
render(
<TreeList
ref={el => {
ref.current = el;
}}
header={<button type="button">Header Action</button>}
items={[
{id: 'one', label: 'One'},
{id: 'two', label: 'Two'},
]}
onKeyDown={onKeyDown}
/>,
);
const headerButton = screen.getByRole('button', {name: 'Header Action'});
headerButton.focus();
fireEvent.keyDown(headerButton, {key: 'ArrowDown'});
expect(onKeyDown).toHaveBeenCalledTimes(1);
expect(capturedCurrentTarget).toBe(ref.current);
expect(ref.current).toBeInstanceOf(HTMLDivElement);
// Focus remains on header button, internal tree navigation was not triggered
expect(document.activeElement).toBe(headerButton);
const items = screen.getAllByRole('treeitem');
expect(items[0]).toHaveAttribute('tabindex', '0');
});
});
// A slot is empty for exactly the values React renders as nothing.
describe('TreeList empty slots', () => {
it.each([
['an empty string', ''],
['false', false],
['true', true],
['null', null],
])(
'a header of %s names nothing; the tree keeps its own label',
(_name, header) => {
render(
<TreeList
items={simpleItems}
header={header as ReactNode}
aria-label="Files"
/>,
);
const tree = screen.getByRole('tree');
expect(tree).not.toHaveAttribute('aria-labelledby');
expect(tree).toHaveAccessibleName('Files');
},
);
it.each([
['an empty string', ''],
['false', false],
['true', true],
['null', null],
])('renders no start or end wrapper for %s', (_name, value) => {
const html = (element: HTMLElement) =>
element.innerHTML.replace(/(id|aria-[a-z]+)="[^"]*"/g, '$1');
const {container: withSlots} = render(
<TreeList
items={[
{
id: 'a',
label: 'Item A',
startContent: value as ReactNode,
endContent: value as ReactNode,
},
]}
/>,
);
const {container: without} = render(
<TreeList items={[{id: 'a', label: 'Item A'}]} />,
);
expect(html(withSlots)).toBe(html(without));
});
it('renders 0 as a header and in the start and end slots, as React does', () => {
render(
<TreeList
header={0}
items={[{id: 'a', label: 'Item A', startContent: 0, endContent: 0}]}
/>,
);
expect(screen.getAllByText('0')).toHaveLength(3);
expect(screen.getByRole('tree')).toHaveAttribute('aria-labelledby');
});
});
describe('TreeList collapse focus (AR2)', () => {
function Example({isExpanded}: {isExpanded: boolean}) {
return (
<>
<TreeList
aria-label="Files"
items={[
{id: 'readme', label: 'README.md'},
{
id: 'src',
label: 'src',
isExpanded,
children: [{id: 'index', label: 'index.ts'}],
},
]}
/>
<button type="button">Elsewhere</button>
</>
);
}
const row = (id: string) =>
document.querySelector<HTMLElement>(`[data-tree-id="${id}"]`);
it('moves focus inside a collapsing branch to its row', () => {
const {rerender} = render(<Example isExpanded />);
expect(row('readme')).toHaveAttribute('tabindex', '0');
row('index')?.focus();
expect(row('index')).toHaveFocus();
rerender(<Example isExpanded={false} />);
expect(row('index')).toBeNull();
expect(row('src')).toHaveFocus();
// It holds the one Tab stop, which was on README.md.
expect(row('src')).toHaveAttribute('tabindex', '0');
expect(row('readme')).toHaveAttribute('tabindex', '-1');
});
it('moves focus in a nested group to the outermost row that collapsed, and to the inner row when only it collapses', () => {
const Nested = ({outer, inner}: {outer: boolean; inner: boolean}) => (
<TreeList
aria-label="Files"
items={[
{
id: 'src',
label: 'src',
isExpanded: outer,
children: [
{
id: 'lib',
label: 'lib',
isExpanded: inner,
children: [{id: 'util', label: 'util.ts'}],
},
],
},
]}
/>
);
const {rerender} = render(<Nested outer inner />);
row('util')?.focus();
rerender(<Nested outer={false} inner />);
expect(row('src')).toHaveFocus();
rerender(<Nested outer inner />);
row('util')?.focus();
rerender(<Nested outer inner={false} />);
expect(row('lib')).toHaveFocus();
});
it('moves focus to a disabled collapsing row, which leaves the Tab stop where it is', () => {
const Disabled = ({isExpanded}: {isExpanded: boolean}) => (
<TreeList
aria-label="Files"
items={[
{id: 'readme', label: 'README.md'},
{
id: 'src',
label: 'src',
isDisabled: true,
isExpanded,
children: [{id: 'index', label: 'index.ts'}],
},
]}
/>
);
const {rerender} = render(<Disabled isExpanded />);
row('index')?.focus();
rerender(<Disabled isExpanded={false} />);
expect(row('src')).toHaveFocus();
expect(row('src')).toHaveAttribute('tabindex', '-1');
expect(row('readme')).toHaveAttribute('tabindex', '0');
});
it('hands the Tab stop to the first enabled row when a disabled row collapses away the child that held it', () => {
const Disabled = ({isExpanded}: {isExpanded: boolean}) => (
<TreeList
aria-label="Files"
items={[
{id: 'readme', label: 'README.md'},
{
id: 'src',
label: 'src',
isDisabled: true,
isExpanded,
children: [{id: 'index', label: 'index.ts'}],
},
]}
/>
);
const {rerender} = render(<Disabled isExpanded />);
// The keyboard path: arrowing past the disabled row onto its child gives
// the child the stop.
row('readme')?.focus();
fireEvent.keyDown(row('readme') as HTMLElement, {key: 'ArrowDown'});
expect(row('index')).toHaveFocus();
expect(row('index')).toHaveAttribute('tabindex', '0');
rerender(<Disabled isExpanded={false} />);
expect(row('src')).toHaveFocus();
expect(row('src')).toHaveAttribute('tabindex', '-1');
expect(row('readme')).toHaveAttribute('tabindex', '0');
});
it('moves no focus that is outside the collapsing branch', () => {
const {rerender} = render(<Example isExpanded />);
row('readme')?.focus();
rerender(<Example isExpanded={false} />);
expect(row('readme')).toHaveFocus();
screen.getByRole('button', {name: 'Elsewhere'}).focus();
rerender(<Example isExpanded />);
rerender(<Example isExpanded={false} />);
expect(screen.getByRole('button', {name: 'Elsewhere'})).toHaveFocus();
});
});