Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(TreeList): respect consumer onKeyDown preventDefault cancellation (#5606)

Geervanf0e2b49fd024
diff --git a/.changeset/treelist-onkeydown-cancellation.md b/.changeset/treelist-onkeydown-cancellation.md
new file mode 100644
index 0000000000..a6c3b2cef5
--- /dev/null
+++ b/.changeset/treelist-onkeydown-cancellation.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TreeList: respect consumer `onKeyDown` `preventDefault` cancellation for APG tree keyboard navigation
+
+`TreeList` previously processed built-in APG keyboard navigation on the inner `<ul role="tree">` before consumer `onKeyDown` ran on the root `<div>`, preventing consumer `event.preventDefault()` from suppressing built-in arrow navigation.
+
+Root `onKeyDown` now invokes consumer `onKeyDown` on the root container first and checks `event.defaultPrevented` before handling internal tree navigation for keydown events originating inside the `<ul role="tree">`. Calling `event.preventDefault()` in `onKeyDown` now successfully cancels built-in navigation and leaves focus and roving tabindex unchanged while preserving root handler target contracts.
+
+@Geervan
+
diff --git a/packages/core/src/TreeList/TreeList.test.tsx b/packages/core/src/TreeList/TreeList.test.tsx
index ea0dca44b5..87aad95a34 100644
--- a/packages/core/src/TreeList/TreeList.test.tsx
+++ b/packages/core/src/TreeList/TreeList.test.tsx
@@ -1162,4 +1162,98 @@ describe('TreeList', () => {
screen.getByText('Cherry').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');
+ });
});
diff --git a/packages/core/src/TreeList/TreeList.tsx b/packages/core/src/TreeList/TreeList.tsx
index 3578d9da6f..eb800f21ba 100644
--- a/packages/core/src/TreeList/TreeList.tsx
+++ b/packages/core/src/TreeList/TreeList.tsx
@@ -191,6 +191,7 @@ export function TreeList({
'aria-label': ariaLabel,
'aria-labelledby': ariaLabelledby,
ref,
+ onKeyDown: onKeyDownProp,
...restProps
}: TreeListProps) {
const headerId = useId();
@@ -260,6 +261,23 @@ export function TreeList({
hasRovingTabIndex: true,
});
+ const handleRootKeyDown = useCallback(
+ (e: React.KeyboardEvent<HTMLDivElement>) => {
+ onKeyDownProp?.(e);
+ if (e.defaultPrevented) {
+ return;
+ }
+ if (
+ treeRef.current != null &&
+ e.target instanceof Node &&
+ treeRef.current.contains(e.target)
+ ) {
+ handleKeyDown(e);
+ }
+ },
+ [onKeyDownProp, handleKeyDown, treeRef],
+ );
+
const hasExpandableItems = items.some(
item => item.children != null && item.children.length > 0,
);
@@ -334,6 +352,7 @@ export function TreeList({
<div
ref={ref}
data-testid={testId}
+ onKeyDown={handleRootKeyDown}
{...mergeProps(
themeProps('tree-list', {density, variant}),
stylex.props(styles.root, xstyle),
@@ -351,7 +370,6 @@ export function TreeList({
role="tree"
aria-label={header != null ? undefined : ariaLabel}
aria-labelledby={header != null ? headerId : ariaLabelledby}
- onKeyDown={handleKeyDown}
onFocus={handleFocus}
{...stylex.props(styles.list)}>
{renderItems(items, 0, [])}