@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/hooks/useListFocus.test.tsx

@@ -3,13 +3,15 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping + navigation
+ * @output Unit tests for useListFocus disabled-item skipping, navigation, and
+ *   RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
 import {describe, it, expect} from 'vitest';
+import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
 
@@ -373,3 +375,153 @@ describe('useListFocus shortcut passthrough', () => {
     expect(screen.getByTestId('A')).toHaveFocus();
   });
 });
+
+/**
+ * A horizontal list (menubar-like) for RTL direction tests. jsdom reflects the
+ * `dir` attribute into computed style only on the element that carries it, so
+ * `dir` is set on the list container itself — the element the hook reads via
+ * listRef.
+ */
+function HorizontalMenu({dir, isRtl}: {dir?: 'ltr' | 'rtl'; isRtl?: boolean}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
+    orientation: 'horizontal',
+    isRtl,
+  });
+  const items = ['One', 'Two', 'Three'];
+  return (
+    <div ref={listRef} role="menu" dir={dir} onKeyDown={handleKeyDown}>
+      {items.map(label => (
+        <div key={label} role="menuitem" tabIndex={-1} data-testid={label}>
+          {label}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+describe('useListFocus RTL auto-detection (WCAG 1.3.2)', () => {
+  it('auto-detects dir="rtl": ArrowLeft moves to the next item', () => {
+    render(<HorizontalMenu dir="rtl" />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves to the previous item', () => {
+    render(<HorizontalMenu dir="rtl" />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Two').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('One')).toHaveFocus();
+  });
+
+  it('stays LTR without a direction: ArrowRight moves to the next item', () => {
+    render(<HorizontalMenu />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('explicit isRtl={false} overrides a dir="rtl" container', () => {
+    render(<HorizontalMenu dir="rtl" isRtl={false} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('explicit isRtl={true} flips arrows without a dir attribute', () => {
+    render(<HorizontalMenu isRtl />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});
+
+// A menu whose second item contains a NESTED role="menu" (mirrors an inline
+// submenu flyout). Exercises boundarySelector: item scoping + event ownership.
+function NestedMenu() {
+  const {listRef, handleKeyDown, ownsEvent} = useListFocus<HTMLDivElement>({
+    boundarySelector: '[role="menu"]',
+    wrap: false,
+  });
+  return (
+    <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer1">
+        Outer1
+      </div>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer2">
+        Outer2
+        {/* Nested submenu rendered inline (like a popover flyout). */}
+        <div role="menu" data-testid="inner-menu">
+          <div role="menuitem" tabIndex={-1} data-testid="Inner1">
+            Inner1
+          </div>
+          <div role="menuitem" tabIndex={-1} data-testid="Inner2">
+            Inner2
+          </div>
+        </div>
+      </div>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer3">
+        Outer3
+      </div>
+      {/* Surface ownership for assertions. */}
+      <input
+        data-testid="probe-owns"
+        onKeyDown={e => {
+          e.currentTarget.setAttribute('data-owns', String(ownsEvent(e)));
+        }}
+      />
+    </div>
+  );
+}
+
+// Variant with the ownsEvent probe placed INSIDE the nested menu, so a key
+// event from it reports as not-owned by the outer list.
+function NestedMenuWithInnerProbe() {
+  const {listRef, handleKeyDown, ownsEvent} = useListFocus<HTMLDivElement>({
+    boundarySelector: '[role="menu"]',
+    wrap: false,
+  });
+  const report = (e: ReactKeyboardEvent<HTMLInputElement>) => {
+    e.currentTarget.setAttribute('data-owns', String(ownsEvent(e)));
+  };
+  return (
+    <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer1">
+        Outer1
+      </div>
+      <div role="menu" data-testid="inner-menu">
+        <input data-testid="inner-probe" onKeyDown={report} />
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus boundarySelector (nested lists)', () => {
+  it("ArrowDown skips over a nested list's items to the next own item", () => {
+    render(<NestedMenu />);
+    const menu = screen.getAllByRole('menu')[0];
+    screen.getByTestId('Outer2').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    // Lands on Outer3, not Inner1 (which is inside the nested menu).
+    expect(screen.getByTestId('Outer3')).toHaveFocus();
+  });
+
+  it('ownsEvent is true for an event originating at this level', () => {
+    render(<NestedMenu />);
+    const ownProbe = screen.getByTestId('probe-owns');
+    fireEvent.keyDown(ownProbe, {key: 'ArrowDown'});
+    expect(ownProbe).toHaveAttribute('data-owns', 'true');
+  });
+
+  it('ownsEvent is false for an event from inside a nested list', () => {
+    render(<NestedMenuWithInnerProbe />);
+    const innerProbe = screen.getByTestId('inner-probe');
+    fireEvent.keyDown(innerProbe, {key: 'ArrowDown'});
+    expect(innerProbe).toHaveAttribute('data-owns', 'false');
+  });
+});

package/src/hooks/useListFocus.ts

@@ -4,16 +4,20 @@
 
 /**
  * @file useListFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect,
+ *   isRtlElement
  * @output Exports useListFocus hook for linear list keyboard navigation
  * @position Core hook; used by TabMenu for dropdown menu navigation, Toolbar
  *   for roving tabindex, ButtonGroup, ContextMenu, NavHeadingMenu, and more.
+ *   Auto-detects RTL from the container's computed direction so horizontal
+ *   arrow keys follow visual direction (WCAG 1.3.2).
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
 
 import {useCallback, useRef} from 'react';
+import {isRtlElement} from './isRtlElement';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 
 /**
@@ -34,6 +38,25 @@ export interface UseListFocusOptions {
    */
   itemSelector?: string;
 
+  /**
+   * Selector identifying a list boundary — used to scope a list that contains
+   * *nested* lists of the same kind (e.g. a menu with submenu flyouts).
+   *
+   * Overlays like submenu flyouts render inline (native popover, not a
+   * portal), so a nested list's items are DOM descendants of the parent list.
+   * Without scoping, the parent's `querySelectorAll` sweeps the nested items
+   * into its roving order (leaving hidden items `.focus()` can't land on), and
+   * key events from the nested list bubble into the parent's handler (moving
+   * focus twice). When set, `useListFocus`:
+   *   - counts an item as its own only when the item's nearest
+   *     `boundarySelector` ancestor is this list's container, and
+   *   - ignores key events whose nearest `boundarySelector` ancestor is not
+   *     this list's container (i.e. they originated in a nested list).
+   *
+   * Typically `'[role="menu"]'` for menus. Omit for flat lists.
+   */
+  boundarySelector?: string;
+
   /**
    * Whether arrow navigation wraps around at the ends.
    * @default true
@@ -62,7 +85,12 @@ export interface UseListFocusOptions {
    * 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.
-   * @default false
+   *
+   * 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.
+   * @default undefined (auto-detect from the container)
    */
   isRtl?: boolean;
 
@@ -128,6 +156,23 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
    * Focus the last enabled item. Returns true when an item was focused.
    */
   focusLast: () => boolean;
+
+  /**
+   * Whether a key event belongs to this list level (vs. a nested list that
+   * shares the same `boundarySelector`). Useful when a consumer wraps
+   * `handleKeyDown` with extra behavior (Enter/Space activation, typeahead)
+   * and must apply it only to events this level owns. Always true when no
+   * `boundarySelector` is configured.
+   */
+  ownsEvent: (e: React.KeyboardEvent) => boolean;
+
+  /**
+   * The current, in-DOM-order list of this level's focusable items (already
+   * scoped by `boundarySelector`). Exposed so consumers can build typeahead
+   * targets from the same source of truth as roving focus, rather than
+   * re-querying and re-filtering.
+   */
+  getItems: () => HTMLElement[];
 }
 
 // Text-editing inputs whose caret must not be hijacked by arrow navigation.
@@ -271,11 +316,12 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
 ): UseListFocusReturn<T> {
   const {
     itemSelector = '[role="menuitem"]',
+    boundarySelector,
     wrap = true,
     onEscape,
     orientation = 'vertical',
     hasHomeEnd = true,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false,
     hasCaretGuard = false,
   } = options;
@@ -299,13 +345,43 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
    * Get all focusable items in the list.
    */
   const getItems = useCallback((): HTMLElement[] => {
-    if (!listRef.current) {
+    const listEl = listRef.current;
+    if (!listEl) {
       return [];
     }
-    return Array.from(
-      listRef.current.querySelectorAll<HTMLElement>(itemSelector),
+    const matched = Array.from(
+      listEl.querySelectorAll<HTMLElement>(itemSelector),
     );
-  }, [itemSelector]);
+    // When a boundary is set, keep only items that belong to THIS list level —
+    // i.e. whose nearest boundary ancestor is our own container. This excludes
+    // items inside nested lists (e.g. inline submenu flyouts) that would
+    // otherwise be swept in by querySelectorAll.
+    if (!boundarySelector) {
+      return matched;
+    }
+    return matched.filter(el => el.closest(boundarySelector) === listEl);
+  }, [itemSelector, boundarySelector]);
+
+  /**
+   * Whether a key event belongs to this list level rather than a nested list.
+   * With a boundary set, an event that originated inside a nested boundary
+   * (e.g. a submenu flyout) has bubbled up to us and must be ignored so we
+   * don't double-handle navigation. Without a boundary, every event is ours.
+   */
+  const ownsEvent = useCallback(
+    (e: React.KeyboardEvent): boolean => {
+      const listEl = listRef.current;
+      if (!listEl || !boundarySelector) {
+        return true;
+      }
+      const target = e.target as HTMLElement | null;
+      if (!target) {
+        return true;
+      }
+      return target.closest(boundarySelector) === listEl;
+    },
+    [boundarySelector],
+  );
 
   /**
    * Find the next enabled item index from `start`, moving by `step`, optionally
@@ -473,6 +549,13 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
+      // Ignore events that bubbled up from a nested list (e.g. a submenu
+      // flyout, which renders inline inside this container). That level owns
+      // and already handled them; re-handling here would move focus twice.
+      if (!ownsEvent(e)) {
+        return;
+      }
+
       // Escape is handled regardless of orientation. Preserve the historical
       // behavior of always consuming Escape here (preventDefault) so consumers
       // that relied on it are unaffected.
@@ -486,11 +569,18 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
       const vertical = orientation === 'vertical' || orientation === 'both';
 
       // Resolve which keys advance vs retreat, honoring RTL for horizontal.
+      // Direction is resolved lazily — getComputedStyle runs only when a
+      // horizontal arrow key is actually pressed (SSR-safe, no layout thrash
+      // on unrelated keys) — and an explicit `isRtl` always wins.
       const nextKeys: string[] = [];
       const prevKeys: string[] = [];
       if (horizontal) {
-        nextKeys.push(isRtl ? 'ArrowLeft' : 'ArrowRight');
-        prevKeys.push(isRtl ? 'ArrowRight' : 'ArrowLeft');
+        const rtl =
+          e.key === 'ArrowLeft' || e.key === 'ArrowRight'
+            ? (isRtl ?? isRtlElement(listRef.current))
+            : false;
+        nextKeys.push(rtl ? 'ArrowLeft' : 'ArrowRight');
+        prevKeys.push(rtl ? 'ArrowRight' : 'ArrowLeft');
       }
       if (vertical) {
         nextKeys.push('ArrowDown');
@@ -553,6 +643,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
       focusFirst,
       focusLast,
       onEscape,
+      ownsEvent,
     ],
   );
 
@@ -563,5 +654,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     focusItem,
     focusFirst,
     focusLast,
+    ownsEvent,
+    getItems,
   };
 }

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/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/i18n/InternationalizationContext.ts

@@ -15,6 +15,8 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/i18n/InternationalizationProvider.tsx
  * - /packages/core/src/i18n/t.client.ts
+ * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
  * - /packages/core/src/i18n/index.ts
  */
 
@@ -23,6 +25,7 @@ import type {Locale, MessagesByLocale, Overrides} from './types';
 
 export interface InternationalizationContextValue {
   locale: Locale;
+  direction: 'ltr' | 'rtl';
   messages: MessagesByLocale;
   overrides?: Overrides;
 }
@@ -34,6 +37,7 @@ export interface InternationalizationContextValue {
 export const InternationalizationContext =
   createContext<InternationalizationContextValue>({
     locale: 'en',
+    direction: 'ltr',
     messages: {},
   });
 InternationalizationContext.displayName = 'InternationalizationContext';

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InternationalizationProvider',
@@ -128,7 +128,7 @@ export function AppI18n({children}: {children: ReactNode}) {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',

package/src/i18n/InternationalizationProvider.tsx

@@ -21,6 +21,7 @@
 
 import {useMemo, type ReactNode} from 'react';
 import {InternationalizationContext} from './InternationalizationContext';
+import {getLocaleDirection} from './getLocaleDirection';
 import type {Locale, MessagesByLocale, Overrides} from './types';
 
 export interface InternationalizationProviderProps {
@@ -55,6 +56,13 @@ export interface InternationalizationProviderProps {
    * ```
    */
   overrides?: Overrides;
+  /**
+   * Optional explicit text direction override. When omitted, direction is derived
+   * from `locale` via `Intl.Locale.getTextInfo()`. Provide this to force a
+   * direction (e.g. RTL layout testing under an English catalog) or to skip the
+   * derivation when you already know the direction.
+   */
+  dir?: 'ltr' | 'rtl';
   children: ReactNode;
 }
 
@@ -66,11 +74,13 @@ export function InternationalizationProvider({
   locale,
   messages,
   overrides,
+  dir,
   children,
 }: InternationalizationProviderProps) {
+  const direction = dir ?? getLocaleDirection(locale);
   const value = useMemo(
-    () => ({locale, messages: messages ?? {}, overrides}),
-    [locale, messages, overrides],
+    () => ({locale, direction, messages: messages ?? {}, overrides}),
+    [locale, direction, messages, overrides],
   );
   return (
     <InternationalizationContext value={value}>

package/src/i18n/__tests__/getLocaleDirection.test.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getLocaleDirection.test.ts
+ * @input packages/core/src/i18n/getLocaleDirection.ts
+ * @output Unit tests for the server-safe locale → direction helper
+ * @position Colocated tests; targets LTR/RTL classification and the
+ *   try/catch fallback for malformed input.
+ */
+
+import {describe, expect, test} from 'vitest';
+import {getLocaleDirection} from '../getLocaleDirection';
+
+describe('getLocaleDirection', () => {
+  test('returns ltr for English', () => {
+    expect(getLocaleDirection('en')).toBe('ltr');
+  });
+
+  test('returns rtl for RTL languages', () => {
+    expect(getLocaleDirection('ar')).toBe('rtl');
+    expect(getLocaleDirection('he')).toBe('rtl');
+    expect(getLocaleDirection('fa')).toBe('rtl');
+    expect(getLocaleDirection('ur')).toBe('rtl');
+  });
+
+  test('returns ltr for regional LTR tags', () => {
+    expect(getLocaleDirection('pt-BR')).toBe('ltr');
+    expect(getLocaleDirection('zh-CN')).toBe('ltr');
+  });
+
+  test('falls back to ltr for a malformed locale without throwing', () => {
+    expect(() => getLocaleDirection('not_a_locale')).not.toThrow();
+    expect(getLocaleDirection('not_a_locale')).toBe('ltr');
+  });
+
+  test('falls back to ltr for an empty string without throwing', () => {
+    expect(() => getLocaleDirection('')).not.toThrow();
+    expect(getLocaleDirection('')).toBe('ltr');
+  });
+});

package/src/i18n/__tests__/useDirection.test.tsx

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useDirection.test.tsx
+ * @input packages/core/src/i18n/useDirection.ts, InternationalizationProvider
+ * @output Unit tests for the ambient text-direction hook
+ * @position Colocated tests; targets the default (no-provider) fallback,
+ *   locale-derived direction, and the explicit `dir` override.
+ */
+
+import type {ReactNode} from 'react';
+import {describe, expect, test} from 'vitest';
+import {renderHook} from '@testing-library/react';
+import {useDirection} from '../useDirection';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+
+describe('useDirection', () => {
+  test('returns ltr when rendered without a provider', () => {
+    const {result} = renderHook(() => useDirection());
+    expect(result.current).toBe('ltr');
+  });
+
+  test('returns ltr under an English provider', () => {
+    const {result} = renderHook(() => useDirection(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <InternationalizationProvider locale="en">
+          {children}
+        </InternationalizationProvider>
+      ),
+    });
+    expect(result.current).toBe('ltr');
+  });
+
+  test('returns rtl under an Arabic provider', () => {
+    const {result} = renderHook(() => useDirection(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <InternationalizationProvider locale="ar">
+          {children}
+        </InternationalizationProvider>
+      ),
+    });
+    expect(result.current).toBe('rtl');
+  });
+
+  test('explicit dir="rtl" wins over an LTR locale', () => {
+    const {result} = renderHook(() => useDirection(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <InternationalizationProvider locale="en" dir="rtl">
+          {children}
+        </InternationalizationProvider>
+      ),
+    });
+    expect(result.current).toBe('rtl');
+  });
+
+  test('explicit dir="ltr" wins over an RTL locale', () => {
+    const {result} = renderHook(() => useDirection(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <InternationalizationProvider locale="ar" dir="ltr">
+          {children}
+        </InternationalizationProvider>
+      ),
+    });
+    expect(result.current).toBe('ltr');
+  });
+});