@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/hooks/useInputStatusIcon.test.tsx

@@ -160,3 +160,62 @@ describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', ()
     expectNoDanglingDescribedBy(container);
   });
 });
+
+describe('useInputStatusIcon — input-status-icon theme target', () => {
+  // The stable theme target lands on the on-field status glyph itself, so a
+  // theme can restyle (e.g. resize) just this icon via `defineTheme`. It is
+  // rendered by the attached and tooltip variants; detached suppresses the
+  // on-field icon in favour of the detached message box's leading glyph.
+  const getStatusIcon = (root: HTMLElement): HTMLElement => {
+    const icon = root.querySelector('.astryx-input-status-icon');
+    if (icon == null) {
+      throw new Error('status icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  for (const variant of ['attached', 'tooltip'] as const) {
+    it(`renders the target on the on-field icon (statusVariant="${variant}")`, () => {
+      const {container} = render(
+        <TextInput
+          label="Field"
+          value=""
+          onChange={() => {}}
+          status={{type: 'warning', message: 'Message'}}
+          statusVariant={variant}
+        />,
+      );
+      const icon = getStatusIcon(container);
+      expect(icon).toHaveClass('astryx-input-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-size', 'md');
+      expect(icon).toHaveAttribute('data-status', 'warning');
+    });
+  }
+
+  it('reflects the status type per status', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'success', message: 'Message'}}
+        statusVariant="attached"
+      />,
+    );
+    expect(getStatusIcon(container)).toHaveAttribute('data-status', 'success');
+  });
+
+  it('does not render the on-field target for the detached variant', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-input-status-icon')).toBeNull();
+  });
+});

package/src/hooks/useInputStatusIcon.tsx

@@ -41,6 +41,7 @@ import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
+import {themeProps} from '../utils/themeProps';
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -194,7 +195,17 @@ export function useInputStatusIcon({
   }
 
   const icon = (
-    <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+    <Icon
+      icon={STATUS_ICON[status.type]}
+      size={size}
+      color={status.type}
+      // Stable theme target on the status glyph itself, so a theme can restyle
+      // just this icon (color, size) — and each status — via `defineTheme`.
+      // Same-element rules in @layer astryx-theme win over the icon's own base
+      // width/height/fontSize, which a field-level target could not reach.
+      // Shared by the attached and tooltip variants across all bordered inputs.
+      {...themeProps('input-status-icon', {size, status: status.type})}
+    />
   );
 
   // Attached (and tooltip-without-message) variants: plain, non-interactive

package/src/hooks/useKeyboardHint.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useKeyboardHint',
   displayName: 'useKeyboardHint',
@@ -72,7 +72,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',

package/src/hooks/useKeyboardHint.test.tsx

@@ -9,6 +9,7 @@
 import {render} from '@testing-library/react';
 import {describe, expect, it} from 'vitest';
 import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
+import {InternationalizationProvider} from '../i18n';
 
 function TestHint({orientation}: {orientation?: KeyboardHintOrientation}) {
   const {hintElement} = useKeyboardHint({orientation});
@@ -67,4 +68,25 @@ describe('useKeyboardHint', () => {
 
     expect(hint.className).toContain('useKeyboardHint__styles.hint');
   });
+
+  it('renders the "to navigate" label from the i18n catalog', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.textContent).toContain('to navigate');
+  });
+
+  it('localizes the "to navigate" label through the i18n catalog', () => {
+    const {container} = render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.keyboardHint.toNavigate': 'pour naviguer'}}}>
+        <TestHint />
+      </InternationalizationProvider>,
+    );
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.textContent).toContain('pour naviguer');
+    expect(hint.textContent).not.toContain('to navigate');
+  });
 });

package/src/hooks/useKeyboardHint.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
  * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
  * @position Core hook; shows sighted keyboard users how to navigate composite
  *   widgets that use roving tabindex (single Tab stop, arrows inside)
@@ -13,7 +13,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
@@ -27,6 +27,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Kbd} from '../Kbd';
 import {useLayer} from '../Layer/useLayer';
+import {useTranslator} from '../i18n';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -179,6 +180,7 @@ export function useKeyboardHint(
     isEnabled = true,
   } = options;
 
+  const t = useTranslator();
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const dismissedRef = useRef(false);
   const isVisibleRef = useRef(false);
@@ -316,7 +318,9 @@ export function useKeyboardHint(
   const hintElement = layer.render(
     <span aria-hidden="true">
       {arrowContent}
-      <span {...stylex.props(styles.label)}>to navigate</span>
+      <span {...stylex.props(styles.label)}>
+        {t('@astryx.keyboardHint.toNavigate')}
+      </span>
     </span>,
     {
       placement: 'below',

package/src/hooks/useListFocus.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useListFocus',
   displayName: 'useListFocus',
@@ -135,7 +135,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',

package/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;

package/src/hooks/useLongPress.test.tsx

@@ -81,6 +81,24 @@ describe('useLongPress', () => {
     expect(onLongPress).not.toHaveBeenCalled();
   });
 
+  it('cancels when a second finger touches down mid-press', () => {
+    const onLongPress = vi.fn();
+    const {result} = renderHook(() => useLongPress({onLongPress}));
+
+    act(() => {
+      result.current.onTouchStart(touchEvent([{clientX: 0, clientY: 0}]));
+      // A second finger joins before the press fires (e.g. pinch-to-zoom).
+      result.current.onTouchStart(
+        touchEvent([
+          {clientX: 0, clientY: 0},
+          {clientX: 50, clientY: 50},
+        ]),
+      );
+      vi.advanceTimersByTime(500);
+    });
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
   it('cancels when the finger moves past the threshold', () => {
     const onLongPress = vi.fn();
     const {result} = renderHook(() => useLongPress({onLongPress}));

package/src/hooks/useLongPress.ts

@@ -70,7 +70,12 @@ export function useLongPress(
 
   const onTouchStart = useCallback(
     (e: React.TouchEvent) => {
-      if (disabled || e.touches.length !== 1) {
+      if (disabled) {
+        return;
+      }
+      if (e.touches.length !== 1) {
+        // Multi-touch cancels any pending long-press.
+        clear();
         return;
       }
       const touch = e.touches[0];
@@ -92,7 +97,12 @@ export function useLongPress(
   const onTouchMove = useCallback(
     (e: React.TouchEvent) => {
       const start = startRef.current;
-      if (start == null || e.touches.length !== 1) {
+      if (start == null) {
+        return;
+      }
+      if (e.touches.length !== 1) {
+        // Multi-touch cancels the pending long-press.
+        clear();
         return;
       }
       const touch = e.touches[0];

package/src/hooks/useMediaQuery.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useMediaQuery',
   displayName: 'useMediaQuery',
@@ -34,7 +34,7 @@ export const docs = {
   category: 'media',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
   paramDescriptions: {

package/src/hooks/useOverflow.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useOverflow',
   displayName: 'useOverflow',
@@ -84,7 +84,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Measures children rendered in hidden container to determine how many fit in available width w/o flickering. Uses ResizeObserver to react to container size changes. Measurement container should hold all items plus optional overflow indicator element (identified by data-overflow-indicator attribute).',

package/src/hooks/useScrollLock.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useScrollLock',
   displayName: 'useScrollLock',
@@ -29,7 +29,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',

package/src/hooks/useScrollOverflow.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useScrollOverflow',
   displayName: 'useScrollOverflow',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'layout',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Tracks scroll overflow state for horizontally scrollable container. Returns ref callback + state booleans that update as user scrolls / container resizes. Uses scroll event listeners + ResizeObserver for reactive updates. Tolerance of 1px applied to avoid sub-pixel false positives.',

package/src/hooks/useStreamingText.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useStreamingText',
   displayName: 'useStreamingText',
@@ -55,7 +55,7 @@ export const docs = {
   category: 'streaming',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',

package/src/hooks/useStreamingText.test.ts

@@ -2,7 +2,7 @@
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {renderHook, act} from '@testing-library/react';
-import {useStreamingText} from './useStreamingText';
+import {snapToGraphemeBoundary, useStreamingText} from './useStreamingText';
 
 describe('useStreamingText', () => {
   let rafCallbacks: ((time: number) => void)[];
@@ -189,4 +189,49 @@ describe('useStreamingText', () => {
     // (or close to it — the hook drains charsPerTick per tickMs)
     expect(result.current.length).toBeGreaterThan(targetText.length * 0.5);
   });
+
+  it('never reveals a tick boundary landing mid-surrogate-pair or mid-ZWJ-emoji-sequence (#4779)', () => {
+    // natural speed advances 10 UTF-16 code units per tick. 9 ASCII chars
+    // (indices 0-8) followed by a 4-person ZWJ family emoji (indices 9-19,
+    // one grapheme cluster, 11 code units) means the first tick's raw
+    // boundary (index 10) lands one code unit into the family emoji's first
+    // surrogate pair -- exactly the failure case from the issue.
+    const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}';
+    const targetText = 'a'.repeat(9) + family + 'end';
+    const {result} = renderHook(() => useStreamingText(targetText, true));
+
+    expect(rafCallbacks.length).toBeGreaterThan(0);
+    const cb = rafCallbacks.pop()!;
+    act(() => cb(performance.now() + 20));
+
+    // Without the fix this would be 'a'.repeat(9) + a lone high surrogate
+    // (renders as U+FFFD). With the fix, the whole not-yet-complete family
+    // cluster is held back rather than rendering a broken glyph.
+    expect(result.current).toBe('a'.repeat(9));
+  });
+});
+
+describe('snapToGraphemeBoundary', () => {
+  it('does not split a surrogate pair', () => {
+    const text = 'a\u{1F389}b'; // 🎉 is a surrogate pair: indices 1 (high) and 2 (low)
+    expect(snapToGraphemeBoundary(text, 2)).toBe(1);
+    expect(snapToGraphemeBoundary(text, 1)).toBe(1);
+  });
+
+  it('does not split a ZWJ emoji sequence', () => {
+    const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}';
+    const text = 'x' + family + 'y';
+    const familyStart = 1;
+    const familyEnd = 1 + family.length;
+    for (let offset = familyStart + 1; offset < familyEnd; offset++) {
+      expect(snapToGraphemeBoundary(text, offset)).toBe(familyStart);
+    }
+  });
+
+  it('leaves boundary offsets (start, end, plain-ASCII midpoints) unchanged', () => {
+    const text = 'hello';
+    expect(snapToGraphemeBoundary(text, 0)).toBe(0);
+    expect(snapToGraphemeBoundary(text, 5)).toBe(5);
+    expect(snapToGraphemeBoundary(text, 3)).toBe(3);
+  });
 });

package/src/hooks/useStreamingText.ts

@@ -9,9 +9,12 @@
  * @position Core hook; smooths bursty streamed text into steady character reveal
  *
  * Decouples the arrival rate of streamed chunks from the display rate,
- * draining characters at a steady pace using requestAnimationFrame.
- * Advances on word/syntax boundaries to avoid slicing mid-markdown or
- * mid-word, preventing visual glitches when used with markdown renderers.
+ * draining characters at a steady pace using requestAnimationFrame. The
+ * reveal cadence advances by a fixed number of UTF-16 code units per tick;
+ * the rendered slice is then snapped back to the nearest grapheme cluster
+ * boundary (see snapToGraphemeBoundary) so a tick landing inside a
+ * surrogate pair, flag sequence, or ZWJ emoji doesn't render a lone
+ * surrogate or a partial glyph for one frame.
  *
  * Animation timing derives from Astryx motion tokens (via useTheme) when
  * an Theme provider is present. Falls back to sensible defaults when
@@ -68,6 +71,43 @@ const CHARS_PER_TICK = {
   instant: Infinity,
 } as const;
 
+// Reuse a single segmenter when the runtime supports Intl.Segmenter.
+// Granularity is fixed and locale doesn't affect grapheme-cluster
+// boundaries, so one instance is safe to share across calls.
+const graphemeSegmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
+    : null;
+
+function isLowSurrogate(codeUnit: number): boolean {
+  return codeUnit >= 0xdc00 && codeUnit <= 0xdfff;
+}
+
+/**
+ * Snap a UTF-16 code-unit offset down to the start of the grapheme cluster
+ * it falls inside, so slicing `text` at the returned offset never splits a
+ * surrogate pair, flag sequence, or ZWJ emoji mid-glyph. Offsets at the
+ * start/end of the string are returned unchanged (nothing to snap).
+ *
+ * Falls back to snapping off a lone low surrogate when `Intl.Segmenter` is
+ * unavailable — narrower than full grapheme-cluster awareness (a ZWJ
+ * sequence or flag pair can still split in that path), but it's what's
+ * achievable without a full grapheme-aware dependency, and it's strictly
+ * better than the unguarded default of never checking at all.
+ */
+export function snapToGraphemeBoundary(text: string, offset: number): number {
+  if (offset <= 0 || offset >= text.length) {
+    return offset;
+  }
+  if (graphemeSegmenter) {
+    // `containing` only returns undefined for an out-of-range index; offset
+    // is already guarded to [1, text.length - 1] above, so this is always
+    // defined at runtime — the `??` is to satisfy the type, which is wider.
+    return graphemeSegmenter.segment(text).containing(offset)?.index ?? offset;
+  }
+  return isLowSurrogate(text.charCodeAt(offset)) ? offset - 1 : offset;
+}
+
 /**
  * Smooths bursty streamed text into a steady character-by-character reveal.
  *
@@ -76,9 +116,11 @@ const CHARS_PER_TICK = {
  * reduced motion, the progressive reveal is skipped entirely and the full
  * `targetText` is returned immediately.
  *
- * The hook advances on word and syntax boundaries, avoiding slices inside
- * markdown markers like `**`, backticks, `[]()`, etc. This prevents visual
- * glitches when the output is rendered through a markdown parser.
+ * The reveal cadence itself advances by a fixed number of UTF-16 code units
+ * per tick, not on word or markdown-syntax boundaries — but the rendered
+ * slice is always snapped back to the nearest grapheme cluster boundary, so
+ * a tick landing mid-surrogate-pair or mid-emoji-sequence never renders a
+ * broken glyph.
  *
  * @example
  * ```
@@ -191,5 +233,5 @@ export function useStreamingText(
     return targetText;
   }
 
-  return targetText.slice(0, displayedLen);
+  return targetText.slice(0, snapToGraphemeBoundary(targetText, displayedLen));
 }

package/src/hooks/useTreeFocus.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTreeFocus',
   displayName: 'useTreeFocus',
@@ -106,7 +106,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages roving-tabindex focus + WAI-ARIA tree keyboard model. ArrowUp/Down/Home/End roam linearly over visible treeitems (skip disabled); ArrowRight/Left carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate; printable chars trigger typeahead.',

package/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 => (
         <li
           key={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);

package/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);