Skip to content

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

TypeScript

refactor(TreeList): let useTreeFocus own roving tabindex (#3488)

Cindy Zhangfc6ce12d75a2
diff --git a/.changeset/usetreefocus-roving-tabindex.md b/.changeset/usetreefocus-roving-tabindex.md
new file mode 100644
index 0000000000..a46b471e1e
--- /dev/null
+++ b/.changeset/usetreefocus-roving-tabindex.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[refactor] useTreeFocus gains `hasRovingTabIndex` + `handleFocus` for internal tab-stop management; TreeList drops its inline `activeId` state and lets the hook own the roving tab stop (#3488).
+@cixzhang
diff --git a/packages/core/src/TreeList/TreeList.tsx b/packages/core/src/TreeList/TreeList.tsx
index 2f83949252..04faa79725 100644
--- a/packages/core/src/TreeList/TreeList.tsx
+++ b/packages/core/src/TreeList/TreeList.tsx
@@ -99,12 +99,13 @@ function collectExpandedKeys(items: TreeListItemData[]): string[] {
}
/**
- * Compute the initial roving-tabindex owner: the first selected enabled item
- * in document order, else the first enabled item, else the first item.
- * Only the top-level candidates are considered for the default so the tab stop
- * is reachable even when the tree is fully collapsed.
+ * Compute the initial roving-tabindex seed: the first selected enabled item in
+ * document order, else the first enabled item, else the first item. The hook
+ * (useTreeFocus with hasRovingTabIndex) takes ownership after mount — it
+ * preserves this seeded `tabindex="0"` on its repair pass and moves the stop
+ * with keyboard navigation.
*/
-function findDefaultActiveId(items: TreeListItemData[]): string | undefined {
+function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
let firstEnabled: string | undefined;
const walk = (list: TreeListItemData[]): string | undefined => {
for (const item of list) {
@@ -193,28 +194,15 @@ export function TreeList({
// Roving tabindex + APG tree keyboard model (via useTreeFocus)
// ---------------------------------------------------------------------------
- // The treeitem that currently owns the tree's single tab stop. The hook moves
- // it around via onActiveChange; a data-driven default seeds it (selected item
- // or first enabled).
- const [activeId, setActiveId] = useState<string | undefined>(() =>
- findDefaultActiveId(items),
+ // The hook (hasRovingTabIndex) owns the tree's single tab stop: it repairs
+ // the stop on mount and moves it with keyboard navigation. We only seed the
+ // initially-tabbable treeitem in the render (selected item or first enabled);
+ // the hook's repair pass preserves that seeded `tabindex="0"`.
+ const initialTabbableId = useMemo(
+ () => findInitialTabbableId(items),
+ [items],
);
- // If the seed id is no longer present (items changed), fall back to a valid
- // default so the tree always has exactly one reachable tab stop.
- const resolvedActiveId = useMemo(() => {
- if (activeId == null) {
- return findDefaultActiveId(items);
- }
- const exists = (list: TreeListItemData[]): boolean =>
- list.some(
- item =>
- item.id === activeId ||
- (item.children != null && exists(item.children)),
- );
- return exists(items) ? activeId : findDefaultActiveId(items);
- }, [activeId, items]);
-
// Enter/Space activation: prefer the treeitem's own inner action (link or
// button); return true when handled so the hook does not also toggle. Scoped
// to this treeitem's own row — never a descendant treeitem's action inside an
@@ -232,10 +220,10 @@ export function TreeList({
return false;
}, []);
- const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+ const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
onToggleExpand: handleToggle,
onActivate: activateItem,
- onActiveChange: setActiveId,
+ hasRovingTabIndex: true,
});
function renderItems(
@@ -286,7 +274,7 @@ export function TreeList({
renderedChildren={renderedChildren}
posInSet={index + 1}
setSize={items.length}
- isTabbable={item.id === resolvedActiveId}
+ isTabbable={item.id === initialTabbableId}
/>
);
});
@@ -312,6 +300,7 @@ export function TreeList({
role="tree"
aria-labelledby={header != null ? headerId : undefined}
onKeyDown={handleKeyDown}
+ onFocus={handleFocus}
{...stylex.props(styles.list)}>
{renderItems(items, 0, [])}
</ul>
diff --git a/packages/core/src/TreeList/TreeListItem.tsx b/packages/core/src/TreeList/TreeListItem.tsx
index 818c484e3d..991010ee5c 100644
--- a/packages/core/src/TreeList/TreeListItem.tsx
+++ b/packages/core/src/TreeList/TreeListItem.tsx
@@ -265,8 +265,9 @@ export interface TreeListItemInternalProps {
/** Number of siblings at this level (aria-setsize). */
setSize: number;
/**
- * Whether this treeitem currently owns the tree's single tab stop
- * (roving tabindex). Exactly one visible treeitem is tabbable at a time.
+ * Whether this treeitem is the initial roving-tabindex seed. Exactly one
+ * treeitem is seeded tabbable at mount; useTreeFocus (hasRovingTabIndex)
+ * then owns the tab stop dynamically.
*/
isTabbable: boolean;
}
diff --git a/packages/core/src/hooks/useTreeFocus.doc.mjs b/packages/core/src/hooks/useTreeFocus.doc.mjs
index 9112bc08d1..dbeb08475d 100644
--- a/packages/core/src/hooks/useTreeFocus.doc.mjs
+++ b/packages/core/src/hooks/useTreeFocus.doc.mjs
@@ -49,6 +49,13 @@ export const docs = {
description: 'Notified when the hook moves focus to a treeitem. Consumers use this to move a single roving tab stop.',
required: false,
},
+ {
+ name: 'options.hasRovingTabIndex',
+ type: 'boolean',
+ description: 'When true, the hook owns a single roving tab stop across the visible treeitems (stamps tabindex 0/-1, repairs on mount, moves with navigation). Preserves an existing tabindex="0" seed on mount. Attach the returned `handleFocus` to keep the stop in sync after clicks.',
+ default: 'false',
+ required: false,
+ },
{
name: 'options.typeahead',
type: 'boolean',
@@ -68,6 +75,11 @@ export const docs = {
type: '(e: React.KeyboardEvent) => void',
description: 'Key down handler to attach to the tree container.',
},
+ {
+ name: 'handleFocus',
+ type: '(e: React.FocusEvent) => void',
+ description: 'Focus handler to attach to the container\'s onFocus. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so always safe to attach.',
+ },
{
name: 'focusFirst',
type: '() => void',
@@ -106,11 +118,13 @@ export const docsDense = {
'options.onToggleExpand': 'expand/collapse treeitem by id (ArrowRight collapsed parent, ArrowLeft expanded parent, Enter/Space parent w/o own action).',
'options.onActivate': 'called on Enter/Space activation. Return true when handled; else hook falls back to toggling expansion.',
'options.onActiveChange': 'notified when focus moves to a treeitem. Use to move a single roving tab stop.',
+ 'options.hasRovingTabIndex': 'hook owns a single roving tab stop (stamps tabindex 0/-1, repairs on mount, moves w/ nav). Preserves an existing tabindex="0" seed. Attach handleFocus to sync after clicks.',
'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars).',
},
returnDescriptions: {
treeRef: 'ref to attach to tree container (role="tree").',
handleKeyDown: 'key down handler for tree container.',
+ handleFocus: 'onFocus handler; keeps roving tab stop in sync when hasRovingTabIndex on (no-op otherwise).',
focusFirst: 'focus first enabled visible treeitem.',
focusLast: 'focus last enabled visible treeitem.',
},
diff --git a/packages/core/src/hooks/useTreeFocus.ts b/packages/core/src/hooks/useTreeFocus.ts
index 5e4b1b5064..2cb2d74853 100644
--- a/packages/core/src/hooks/useTreeFocus.ts
+++ b/packages/core/src/hooks/useTreeFocus.ts
@@ -4,7 +4,7 @@
/**
* @file useTreeFocus.ts
- * @input Uses React useCallback, useRef
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
* @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
* @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
*
@@ -15,6 +15,7 @@
*/
import {useCallback, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
/** Keys handled by the tree keyboard model (used to gate typeahead). */
const NAVIGATION_KEYS = new Set([
@@ -109,7 +110,10 @@ export interface UseTreeFocusOptions {
* @param item The focused treeitem element.
* @param id The treeitem's id (per `getItemId`), if any.
*/
- onActivate?: (item: HTMLElement, id: string | undefined) => boolean | undefined;
+ onActivate?: (
+ item: HTMLElement,
+ id: string | undefined,
+ ) => boolean | undefined;
/**
* Whether typeahead (jump to next item whose text starts with the typed
@@ -126,6 +130,25 @@ export interface UseTreeFocusOptions {
* TreeList uses this to move its single roving tab stop.
*/
onActiveChange?: (id: string | undefined) => void;
+
+ /**
+ * Roving-tabindex ownership. When true, the hook manages a single tab stop
+ * across the visible treeitems: exactly one enabled treeitem carries
+ * `tabindex="0"` and the rest `tabindex="-1"`. The tab stop is repaired on
+ * mount and whenever items mount/unmount or toggle disabled, and moves with
+ * keyboard navigation. Attach the returned {@link UseTreeFocusReturn.handleFocus}
+ * to the container's `onFocus` to keep the stop in sync after clicks or
+ * programmatic focus.
+ *
+ * On mount the hook preserves an existing `tabindex="0"` treeitem (so a
+ * consumer can seed the active item in its render); if none exists it
+ * promotes the first enabled treeitem.
+ *
+ * When false (the default), the hook only *moves* focus (`.focus()`) and
+ * never touches `tabindex` — the caller owns tab-stop management.
+ * @default false
+ */
+ hasRovingTabIndex?: boolean;
}
/**
@@ -138,6 +161,13 @@ export interface UseTreeFocusReturn<T extends HTMLElement = HTMLElement> {
/** Key down handler to attach to the tree container. */
handleKeyDown: (e: React.KeyboardEvent) => void;
+ /**
+ * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
+ * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it
+ * is always safe to attach.
+ */
+ handleFocus: (e: React.FocusEvent) => void;
+
/** Focus the first enabled visible treeitem. */
focusFirst: () => void;
@@ -167,12 +197,12 @@ export interface UseTreeFocusReturn<T extends HTMLElement = HTMLElement> {
*
* @example
* ```
- * const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+ * const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
* onToggleExpand: id => toggle(id),
- * onActiveChange: id => setActiveId(id),
+ * hasRovingTabIndex: true,
* });
*
- * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+ * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown} onFocus={handleFocus}>
* {items.map(item => <li role="treeitem" tabIndex={-1}>{item.label}</li>)}
* </ul>
* ```
@@ -192,6 +222,7 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
typeahead = true,
typeaheadResetMs = DEFAULT_TYPEAHEAD_RESET_MS,
onActiveChange,
+ hasRovingTabIndex = false,
} = options;
const treeRef = useRef<T>(null);
@@ -245,16 +276,68 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
[getItemId],
);
+ // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
+ /**
+ * Set `tabindex` on a treeitem, but only when it differs (avoids redundant
+ * DOM writes).
+ */
+ const setTabIndex = useCallback((el: HTMLElement, value: 0 | -1) => {
+ if (el.getAttribute('tabindex') !== String(value)) {
+ el.setAttribute('tabindex', String(value));
+ }
+ }, []);
+
+ /**
+ * Make `target` the sole tabbable treeitem: 0 on it, -1 on every other
+ * visible treeitem.
+ */
+ const moveTabStop = useCallback(
+ (items: HTMLElement[], target: HTMLElement) => {
+ for (const el of items) {
+ setTabIndex(el, el === target ? 0 : -1);
+ }
+ },
+ [setTabIndex],
+ );
+
+ /**
+ * Repair the roving tab stop: exactly one enabled treeitem is tabbable (0),
+ * the rest are -1. Prefer an existing `tabindex="0"` treeitem (so a consumer
+ * can seed the active item in its render); otherwise promote the first
+ * enabled treeitem.
+ */
+ const syncTabStops = useCallback(() => {
+ const items = getItems();
+ const enabled = items.filter(el => !itemDisabled(el));
+ if (enabled.length === 0) {
+ return;
+ }
+ const current = enabled.find(el => el.getAttribute('tabindex') === '0');
+ moveTabStop(items, current ?? enabled[0]);
+ }, [getItems, itemDisabled, moveTabStop]);
+
+ // Keep the tab stop valid across renders (items added/removed, disabled
+ // toggled). Runs after every commit but only when roving tabindex is on.
+ useIsomorphicLayoutEffect(() => {
+ if (hasRovingTabIndex) {
+ syncTabStops();
+ }
+ });
+
/** Move focus to a treeitem and notify the active-change listener. */
const focusItem = useCallback(
(el: HTMLElement | undefined) => {
if (el == null) {
return;
}
+ if (hasRovingTabIndex) {
+ moveTabStop(getItems(), el);
+ }
onActiveChange?.(idOf(el));
el.focus();
},
- [idOf, onActiveChange],
+ [idOf, onActiveChange, hasRovingTabIndex, moveTabStop, getItems],
);
/**
@@ -455,9 +538,21 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
],
);
+ /**
+ * Keep the roving stop pointing at whatever ended up focused (e.g. a click
+ * or programmatic focus) so the next Tab behaves correctly. No-op unless
+ * roving tabindex is enabled.
+ */
+ const handleFocus = useCallback(() => {
+ if (hasRovingTabIndex) {
+ syncTabStops();
+ }
+ }, [hasRovingTabIndex, syncTabStops]);
+
return {
treeRef,
handleKeyDown,
+ handleFocus,
focusFirst,
focusLast,
};