@astryxdesign/core 0.1.8 → 0.1.9-canary.1887ee2

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';
 
 /**
@@ -62,7 +66,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;
 
@@ -275,7 +284,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     onEscape,
     orientation = 'vertical',
     hasHomeEnd = true,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false,
     hasCaretGuard = false,
   } = options;
@@ -486,11 +495,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');

package/src/hooks/useOverflow.test.ts

@@ -14,12 +14,15 @@ function mockContainer(width: number): HTMLElement {
 function mockMeasure(
   itemWidths: number[],
   indicatorWidth?: number,
+  itemHeight = 0,
 ): HTMLElement {
-  const children: {offsetWidth: number}[] = itemWidths.map(w => ({
-    offsetWidth: w,
-  }));
+  const children: {offsetWidth: number; offsetHeight: number}[] =
+    itemWidths.map(w => ({
+      offsetWidth: w,
+      offsetHeight: itemHeight,
+    }));
   if (indicatorWidth != null) {
-    children.push({offsetWidth: indicatorWidth});
+    children.push({offsetWidth: indicatorWidth, offsetHeight: itemHeight});
   }
   return {children} as unknown as HTMLElement;
 }
@@ -332,6 +335,95 @@ describe('useOverflow', () => {
   });
 });
 
+describe('useOverflow with maxVisibleItems (cap)', () => {
+  it('caps visible items even when they all fit', () => {
+    const {result} = renderHook(() =>
+      useOverflow(5, {gap: 10, maxVisibleItems: 3}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(10000));
+    });
+
+    expect(result.current.visibleCount).toBe(3);
+    expect(result.current.hasOverflow).toBe(true);
+  });
+
+  it('cap does not raise a fit-limited count', () => {
+    const {result} = renderHook(() =>
+      useOverflow(4, {gap: 10, maxVisibleItems: 4}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(150));
+    });
+
+    expect(result.current.visibleCount).toBe(2);
+  });
+
+  it('min wins when maxVisibleItems < minVisibleItems and warns in dev', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {result} = renderHook(() =>
+      useOverflow(5, {gap: 10, minVisibleItems: 3, maxVisibleItems: 1}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(10000));
+    });
+
+    expect(result.current.visibleCount).toBe(3);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('useOverflow with maxRows (multi-row)', () => {
+  it('exposes rows and rowHeight', () => {
+    const {result} = renderHook(() => useOverflow(6, {gap: 10, maxRows: 2}));
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50, 50], 40, 24));
+      result.current.containerRef(mockContainer(170));
+    });
+
+    // 3 items per row (170), 2 rows → all 6 fit
+    expect(result.current.visibleCount).toBe(6);
+    expect(result.current.rows).toBe(2);
+    expect(result.current.rowHeight).toBe(24);
+    expect(result.current.hasOverflow).toBe(false);
+  });
+
+  it('collapses items beyond maxRows into the indicator', () => {
+    const {result} = renderHook(() => useOverflow(8, {gap: 10, maxRows: 2}));
+
+    act(() => {
+      result.current.measureRef(
+        mockMeasure([50, 50, 50, 50, 50, 50, 50, 50], 40, 24),
+      );
+      result.current.containerRef(mockContainer(170));
+    });
+
+    expect(result.current.visibleCount).toBe(5);
+    expect(result.current.rows).toBe(2);
+    expect(result.current.hasOverflow).toBe(true);
+  });
+
+  it('maxRows=1 matches single-line behavior', () => {
+    const {result} = renderHook(() => useOverflow(4, {gap: 10, maxRows: 1}));
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50], 30, 24));
+      result.current.containerRef(mockContainer(150));
+    });
+
+    expect(result.current.visibleCount).toBe(2);
+    expect(result.current.rows).toBe(1);
+  });
+});
+
 describe('useOverflow with behavior=observeParent', () => {
   function mockContainerWithParent(
     parentWidth: number,

package/src/hooks/useOverflow.ts

@@ -10,15 +10,20 @@
  *
  * Measures children rendered in a hidden container to determine how many fit
  * in the available width, without flickering. Uses ResizeObserver to react
- * to container size changes.
+ * to container size changes. Supports an optional item cap (`maxVisibleItems`)
+ * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math
+ * lives in the pure `computeOverflow` helper.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/computeOverflow.ts (the pure computation)
  */
 
 import {useState, useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
+import {computeOverflow} from './computeOverflow';
+import {useDevWarning} from './useDevWarning';
 
 export interface UseOverflowOptions {
   /**
@@ -33,6 +38,23 @@ export interface UseOverflowOptions {
    */
   minVisibleItems?: number;
 
+  /**
+   * Maximum number of items to ever show, even if they all fit. The ceiling
+   * partner to `minVisibleItems`. `undefined` means no cap. When it is less
+   * than `minVisibleItems`, the floor wins and a dev-only warning is emitted.
+   * @default undefined
+   */
+  maxVisibleItems?: number;
+
+  /**
+   * Wrap items across up to this many rows before collapsing the rest into the
+   * overflow indicator. `undefined` (or `1`) keeps the single-line behavior.
+   * A number, not a boolean: unbounded wrapping is a plain flex-wrap layout,
+   * not overflow collapse. Assumes uniform row height.
+   * @default undefined
+   */
+  maxRows?: number;
+
   /**
    * Which end to collapse items from.
    * @default 'end'
@@ -61,6 +83,10 @@ export interface UseOverflowReturn {
   visibleCount: number;
   /** Whether any items are overflowing */
   hasOverflow: boolean;
+  /** Number of rows the visible items occupy (1 for the single-line path) */
+  rows: number;
+  /** Measured max item height in pixels; used to size the multi-row container */
+  rowHeight: number;
 }
 
 /**
@@ -88,13 +114,25 @@ export function useOverflow(
   const {
     gap = 0,
     minVisibleItems = 0,
+    maxVisibleItems,
+    maxRows,
     collapseFrom = 'end',
     behavior = 'observeSelf',
   } = options;
 
+  useDevWarning(
+    'useOverflow',
+    `maxVisibleItems (${maxVisibleItems}) is less than ` +
+      `minVisibleItems (${minVisibleItems}); the floor wins and ` +
+      `minVisibleItems items will be shown.`,
+    maxVisibleItems != null && maxVisibleItems < minVisibleItems,
+  );
+
   const observeParent = behavior === 'observeParent';
 
   const [visibleCount, setVisibleCount] = useState(itemCount);
+  const [rows, setRows] = useState(1);
+  const [rowHeight, setRowHeight] = useState(0);
   const containerElRef = useRef<HTMLElement | null>(null);
   const measureElRef = useRef<HTMLElement | null>(null);
   const observedElRef = useRef<HTMLElement | null>(null);
@@ -134,44 +172,45 @@ export function useOverflow(
     if (children.length === 0) {
       // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
       setVisibleCount(0);
+      // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+      setRows(0);
       return;
     }
 
-    // Collect widths of all children
     const widths = children.map(child => child.offsetWidth);
-
-    // Determine how many items fit
-    let totalWidth = 0;
-    let count = 0;
-
-    const orderedWidths =
-      collapseFrom === 'end' ? widths : [...widths].reverse();
-
-    for (let i = 0; i < orderedWidths.length; i++) {
-      const itemWidth = orderedWidths[i];
-      const gapWidth = i > 0 ? gap : 0;
-      const candidateWidth = totalWidth + itemWidth + gapWidth;
-
-      // If this isn't the last item, we need to reserve space for the indicator
-      const isLastItem = i === orderedWidths.length - 1;
-      const reservedWidth = isLastItem
-        ? 0
-        : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
-
-      if (
-        candidateWidth + reservedWidth > availableWidth &&
-        count >= minVisibleItems
-      ) {
-        break;
-      }
-
-      totalWidth = candidateWidth;
-      count++;
-    }
+    const measuredRowHeight = children.reduce(
+      (max, child) => Math.max(max, child.offsetHeight || 0),
+      0,
+    );
+
+    const {visibleCount: nextVisible, rows: nextRows} = computeOverflow({
+      widths,
+      gap,
+      availableWidth,
+      indicatorWidth,
+      minVisibleItems,
+      maxVisibleItems,
+      maxRows,
+      collapseFrom,
+    });
 
     // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-    setVisibleCount(Math.max(Math.min(count, itemCount), minVisibleItems));
-  }, [itemCount, gap, minVisibleItems, collapseFrom, observeParent]);
+    setVisibleCount(nextVisible);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRows(prev => (prev === nextRows ? prev : nextRows));
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRowHeight(prev =>
+      prev === measuredRowHeight ? prev : measuredRowHeight,
+    );
+  }, [
+    itemCount,
+    gap,
+    minVisibleItems,
+    maxVisibleItems,
+    maxRows,
+    collapseFrom,
+    observeParent,
+  ]);
 
   const containerRef = useCallback(
     (el: HTMLElement | null) => {
@@ -217,5 +256,7 @@ export function useOverflow(
     measureRef,
     visibleCount,
     hasOverflow,
+    rows,
+    rowHeight,
   };
 }

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

@@ -20,7 +20,29 @@ export const docs = {
   ],
   usage: {
     description:
-      "Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.",
+      'Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use shipped Astryx locale catalogs from `@astryxdesign/core/locales/*` when one exists for your target locale.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use a same-shape local catalog only when Astryx has not shipped that locale yet or you are testing in-progress translations.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',
+      },
+      {
+        guidance: false,
+        description:
+          'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',
+      },
+    ],
   },
   props: [
     {
@@ -35,7 +57,7 @@ export const docs = {
       type: 'MessagesByLocale',
       required: false,
       description:
-        'Optional map of BCP 47 tag to translation catalog. The shipped "en" catalog is always available and does not need to be listed here.',
+        'Optional map of BCP 47 tag to translation catalog. Import shipped catalogs from `@astryxdesign/core/locales/*`; the shipped "en" catalog is always available and does not need to be listed here.',
     },
     {
       name: 'overrides',
@@ -51,6 +73,59 @@ export const docs = {
       description: 'Content to render with the internationalization provider.',
     },
   ],
+  examples: [
+    {
+      label: 'Load a shipped Astryx locale catalog',
+      code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import frFR from '@astryxdesign/core/locales/fr-FR.json';
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider locale="fr-FR" messages={{'fr-FR': frFR}}>
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+    {
+      label: 'Override one Astryx string',
+      code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider
+      locale="en"
+      overrides={{
+        en: {'@astryx.selector.placeholder': 'Choose...'},
+      }}
+    >
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+    {
+      label: 'Provide a local fallback catalog',
+      code: `import type {ReactNode} from 'react';
+import {
+  InternationalizationProvider,
+  type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
+import ptBR from './locales/pt-BR.json';
+
+const messages: MessagesByLocale = {'pt-BR': ptBR};
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider locale="pt-BR" messages={messages}>
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+  ],
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
@@ -60,6 +135,28 @@ export const docsDense = {
   usage: {
     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.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use shipped Astryx locale catalogs from `@astryxdesign/core/locales/*` when one exists for the target locale.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use a same-shape local catalog only when Astryx has not shipped that locale yet or when testing in-progress translations.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use real BCP 47 tags like `fr`, `pt-BR`, or `ar`; regional locales fall back to base language before English.',
+      },
+      {
+        guidance: false,
+        description:
+          'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',
+      },
+    ],
   },
   propDescriptions: {
     locale:

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