An open source design system that's fully customizable and agent ready
TypeScript
fix(core): RTL arrow-key nav for TreeList + auto-detect direction across focus hooks (#4682)
nynexman446499a25c8d5a3b
diff --git a/.changeset/deprecate-focus-hook-isrtl.md b/.changeset/deprecate-focus-hook-isrtl.mdnew file mode 100644index 0000000000..2c37d59943--- /dev/null+++ b/.changeset/deprecate-focus-hook-isrtl.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] Deprecate the `isRtl` option on `useListFocus` and `useGridFocus`. Right-to-left arrow-key direction is now auto-detected from the container, so the explicit override is redundant and will be removed in an upcoming major — omit it and RTL is handled automatically.+@nynexman4464diff --git a/.changeset/tree-focus-rtl-arrows.md b/.changeset/tree-focus-rtl-arrows.mdnew file mode 100644index 0000000000..381c81aa81--- /dev/null+++ b/.changeset/tree-focus-rtl-arrows.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] TreeList arrow-key navigation now follows visual direction in RTL: ArrowLeft expands and ArrowRight collapses under `dir="rtl"` (mirrored from LTR). Detected automatically; LTR is unchanged.+@nynexman4464diff --git a/packages/core/src/AvatarGroup/AvatarGroup.tsx b/packages/core/src/AvatarGroup/AvatarGroup.tsxindex 02c0adc586..b3086100e5 100644--- a/packages/core/src/AvatarGroup/AvatarGroup.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroup.tsx@@ -108,11 +108,9 @@ export function AvatarGroup({);// The keyboard hint and roving tab stop only make sense once the group has- // interactive children. Detect their presence (and the writing direction for- // RTL-correct arrow navigation) from the rendered DOM after commit, matching- // how the codebase reads direction elsewhere (`getComputedStyle(el).direction`).+ // interactive children. Detect their presence from the rendered DOM after+ // commit. (Arrow-key direction is auto-detected inside useListFocus.)const [hasInteractiveItems, setHasInteractiveItems] = useState(false);- const [isRtl, setIsRtl] = useState(false);// Single tab stop + roving arrow focus over the group's interactive items.// `itemSelector` targets the shared `[data-avatar-item]` marker stamped on@@ -123,7 +121,6 @@ export function AvatarGroup({itemSelector: '[data-avatar-item]',orientation: 'horizontal',hasRovingTabIndex: true,- isRtl,});useIsomorphicLayoutEffect(() => {@@ -132,7 +129,6 @@ export function AvatarGroup({return;}setHasInteractiveItems(root.querySelector('[data-avatar-item]') != null);- setIsRtl(getComputedStyle(root).direction === 'rtl');});const hintId = useId();diff --git a/packages/core/src/hooks/useGridFocus.ts b/packages/core/src/hooks/useGridFocus.tsindex 0182c5d54a..0268afdd93 100644--- a/packages/core/src/hooks/useGridFocus.ts+++ b/packages/core/src/hooks/useGridFocus.ts@@ -90,13 +90,15 @@ export interface UseGridFocusOptions {onPageDown?: () => void;/**- * Whether the grid is in a right-to-left context. When true, ArrowLeft and- * ArrowRight are swapped so horizontal navigation follows visual direction.+ * @deprecated Direction is auto-detected from the container's computed+ * `direction` — omit this. The explicit override is redundant (there's no+ * valid reason to force RTL arrows in an LTR context) and will be removed in+ * an upcoming major.*- * When omitted, the direction is auto-detected from the container's computed- * `direction` (read lazily on keydown, only for horizontal arrow keys), so- * grids inside `dir="rtl"` subtrees flip automatically. Pass an explicit- * boolean to override detection.+ * When set, forces whether the grid is right-to-left: ArrowLeft/ArrowRight+ * are swapped so horizontal navigation follows visual direction. When+ * omitted (preferred), the direction is auto-detected from the container's+ * computed `direction` (read lazily on keydown, horizontal arrows only).* @default undefined (auto-detect from the container)*/isRtl?: boolean;diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex 3c4fe4aea7..388646bb75 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -82,14 +82,15 @@ export interface UseListFocusOptions {hasHomeEnd?: boolean;/**- * Whether the list is in a right-to-left context. When true, ArrowLeft and- * ArrowRight are swapped so horizontal navigation follows visual direction.- * Only affects horizontal (`'horizontal'`/`'both'`) navigation.+ * @deprecated Direction is auto-detected from the container's computed+ * `direction` — omit this. The explicit override is redundant (there's no+ * valid reason to force RTL arrows in an LTR context) and will be removed in+ * an upcoming major.*- * When omitted, the direction is auto-detected from the container's computed- * `direction` (read lazily on keydown, only for horizontal arrow keys), so- * lists inside `dir="rtl"` subtrees flip automatically. Pass an explicit- * boolean to override detection.+ * When set, forces whether the list is right-to-left: ArrowLeft/ArrowRight+ * are swapped so horizontal navigation follows visual direction. When+ * omitted (preferred), the direction is auto-detected from the container's+ * computed `direction` (read lazily on keydown, horizontal arrows only).* @default undefined (auto-detect from the container)*/isRtl?: boolean;diff --git a/packages/core/src/hooks/useTreeFocus.test.tsx b/packages/core/src/hooks/useTreeFocus.test.tsxindex 1376988774..e5182fb711 100644--- a/packages/core/src/hooks/useTreeFocus.test.tsx+++ b/packages/core/src/hooks/useTreeFocus.test.tsx@@ -35,10 +35,12 @@ function Tree({collapsed = NO_NODES,expanded = NO_NODES,onActivate,+ dir,}: {collapsed?: Node[];expanded?: Node[];onActivate?: (id: string | undefined) => boolean | undefined;+ dir?: 'ltr' | 'rtl';}) {const [isOpen, setIsOpen] = useState(false);const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;@@ -47,7 +49,7 @@ function Tree({onActivate: onActivate ? (_item, id) => onActivate(id) : undefined,});return (- <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>+ <ul ref={treeRef} role="tree" dir={dir} onKeyDown={handleKeyDown}>{nodes.map(n => (<likey={n.id}@@ -172,6 +174,56 @@ describe('useTreeFocus tree semantics (Arrow Left/Right)', () => {});});+describe('useTreeFocus RTL tree semantics (WAI-ARIA Tree View)', () => {+ const COLLAPSED: Node[] = [+ {id: 'p', label: 'Parent', level: 1, expanded: false},+ ];+ const EXPANDED: Node[] = [+ {id: 'p', label: 'Parent', level: 1, expanded: true},+ {id: 'c1', label: 'Child 1', level: 2},+ {id: 'c2', label: 'Child 2', level: 2},+ ];++ it('auto-detects dir="rtl": ArrowLeft expands a collapsed parent, then enters the first child', () => {+ render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);+ const tree = screen.getByRole('tree');+ screen.getByTestId('p').focus();++ expect(screen.queryByTestId('c1')).not.toBeInTheDocument();+ fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → expand+ expect(screen.getByTestId('c1')).toBeInTheDocument();+ expect(screen.getByTestId('p')).toHaveFocus();++ fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → into first child+ expect(screen.getByTestId('c1')).toHaveFocus();+ });++ it('auto-detects dir="rtl": ArrowRight moves to parent, then collapses', () => {+ render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);+ const tree = screen.getByRole('tree');+ screen.getByTestId('p').focus();+ fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // expand+ fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // into child 1+ expect(screen.getByTestId('c1')).toHaveFocus();++ fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → child leaf → parent+ expect(screen.getByTestId('p')).toHaveFocus();++ fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → expanded parent → collapse+ expect(screen.queryByTestId('c1')).not.toBeInTheDocument();+ });++ it('vertical keys (ArrowDown/ArrowUp) are unaffected by RTL', () => {+ render(<Tree collapsed={FLAT} dir="rtl" />);+ const tree = screen.getByRole('tree');+ screen.getByTestId('a').focus();+ fireEvent.keyDown(tree, {key: 'ArrowDown'});+ expect(screen.getByTestId('b')).toHaveFocus();+ fireEvent.keyDown(tree, {key: 'ArrowUp'});+ expect(screen.getByTestId('a')).toHaveFocus();+ });+});+describe('useTreeFocus activation + typeahead', () => {it('Enter/Space call onActivate for the focused item', () => {const onActivate = vi.fn(() => true);diff --git a/packages/core/src/hooks/useTreeFocus.ts b/packages/core/src/hooks/useTreeFocus.tsindex 2cb2d74853..b233676e09 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, useIsomorphicLayoutEffect+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect, isRtlElement* @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation* @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model*@@ -16,6 +16,7 @@import {useCallback, useRef} from 'react';import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';+import {isRtlElement} from './isRtlElement';/** Keys handled by the tree keyboard model (used to gate typeahead). */const NAVIGATION_KEYS = new Set([@@ -429,7 +430,17 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(return;}- switch (e.key) {+ // Under RTL, swap the horizontal arrows to a logical key so the+ // expand/collapse case bodies (written LTR-first) stay unchanged.+ let key = e.key;+ if (key === 'ArrowLeft' || key === 'ArrowRight') {+ const rtl = isRtlElement(treeRef.current);+ if (rtl) {+ key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';+ }+ }++ switch (key) {case 'ArrowDown': {e.preventDefault();focusEnabledFrom(items, currentIndex < 0 ? 0 : currentIndex + 1, 1);