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

package/src/hooks/useListFocus.doc.mjs

@@ -19,6 +19,13 @@ export const docs = {
       default: "'[role=\"menuitem\"]'",
       required: false,
     },
+    {
+      name: 'options.boundarySelector',
+      type: 'string',
+      description:
+        "Selector identifying a list boundary, for lists that contain nested lists of the same kind (e.g. a menu with submenu flyouts). When set, item collection and key handling are scoped to this level's own container. Typically '[role=\"menu\"]'.",
+      required: false,
+    },
     {
       name: 'options.wrap',
       type: 'boolean',
@@ -49,8 +56,8 @@ export const docs = {
     {
       name: 'options.isRtl',
       type: 'boolean',
-      description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction.',
-      default: 'false',
+      description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction. When omitted, auto-detected from the container computed direction on keydown.',
+      default: "undefined (auto-detect from the container's computed direction)",
       required: false,
     },
     {
@@ -99,6 +106,18 @@ export const docs = {
       type: '() => boolean',
       description: 'Focus the last enabled item. Returns true when an item was focused.',
     },
+    {
+      name: 'ownsEvent',
+      type: '(e: React.KeyboardEvent) => boolean',
+      description:
+        "Whether a key event belongs to this list level rather than a nested list sharing the same boundarySelector. Always true when no boundarySelector is set. Use to guard consumer-added key handling (Enter/Space, typeahead).",
+    },
+    {
+      name: 'getItems',
+      type: '() => HTMLElement[]',
+      description:
+        "This level's focusable items in DOM order (already scoped by boundarySelector). Build typeahead targets from this instead of re-querying.",
+    },
   ],
   usage: {
     description:
@@ -123,11 +142,12 @@ export const docsDense = {
   paramDescriptions: {
     options: 'config for list focus behavior. All fields optional.',
     'options.itemSelector': 'selector for focusable items in list.',
+    'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
     'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
-    'options.isRtl': 'when true, ArrowLeft/ArrowRight swap for horizontal nav (RTL).',
+    'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',
     'options.hasRovingTabIndex': 'opt into roving-tabindex ownership: hook stamps + repairs a single tab stop across items.',
     'options.hasCaretGuard': "when true, don't steal arrow keys from a nested text input/textarea mid-line or from a contenteditable.",
   },
@@ -138,6 +158,8 @@ export const docsDense = {
     focusItem: 'focus specific item by index (clamped to valid range).',
     focusFirst: 'focus first enabled item; returns true when focused.',
     focusLast: 'focus last enabled item; returns true when focused.',
+    ownsEvent: 'whether a key event is this level\'s vs a nested list\'s (boundarySelector); always true without one.',
+    getItems: "this level's focusable items in DOM order, scoped by boundarySelector.",
   },
   usage: {
     description:

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/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.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');
+  });
+});

package/src/i18n/getLocaleDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getLocaleDirection.ts
+ * @input BCP 47 locale tag
+ * @output 'ltr' | 'rtl'
+ * @position Server-safe helper for computing text direction from a locale.
+ *   Callable in React Server Components / Next.js layouts to set <html dir>.
+ *
+ * Uses Intl.Locale.getTextInfo() (CLDR-backed) with a try/catch fallback to
+ * 'ltr'. React 19 baseline covers all target browsers + Node ≥20; the older
+ * accessor form (`.textInfo`) is handled as a fallback for defensive parity.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx (uses this to derive default)
+ * - /packages/core/src/i18n/useDirection.ts (client-side hook counterpart)
+ * - /packages/core/src/i18n/index.ts (public export)
+ */
+
+export function getLocaleDirection(locale: string): 'ltr' | 'rtl' {
+  try {
+    const loc = new Intl.Locale(locale);
+    // @ts-expect-error — older engines expose accessor form `.textInfo`
+    const info = typeof loc.getTextInfo === 'function' ? loc.getTextInfo() : loc.textInfo;
+    return info?.direction === 'rtl' ? 'rtl' : 'ltr';
+  } catch {
+    return 'ltr';
+  }
+}

package/src/i18n/index.ts

@@ -10,10 +10,14 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useDirection                — hook returning the ambient text direction
+ *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
  */
 
 export {InternationalizationProvider} from './InternationalizationProvider';
@@ -22,6 +26,8 @@ export {InternationalizationContext} from './InternationalizationContext';
 export type {InternationalizationContextValue} from './InternationalizationContext';
 export {useTranslator} from './useTranslator';
 export type {TranslatorFn} from './useTranslator';
+export {useDirection} from './useDirection';
+export {getLocaleDirection} from './getLocaleDirection';
 export type {Translator} from './translator';
 export type {
   Locale,