@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/hooks/computeOverflow.ts

@@ -0,0 +1,290 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file computeOverflow.ts
+ * @input Plain measurements (item widths, gap, available width, indicator width, limits)
+ * @output Pure overflow computation: how many items are visible and their row layout
+ * @position Pure helper consumed by useOverflow; contains no DOM or React code so the
+ *           fit/clamp math and the multi-row packing can be unit-tested in isolation.
+ *
+ * There is a single source of truth for `visibleCount`:
+ *   visibleCount = clamp(fitCount, minVisibleItems, maxVisibleItems ?? itemCount)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useOverflow.ts (the only caller)
+ */
+
+export interface ComputeOverflowInput {
+  /** Measured widths of each item, in original DOM order. */
+  widths: number[];
+  /** Gap between items, in pixels. */
+  gap: number;
+  /** Width available to lay items out, in pixels. */
+  availableWidth: number;
+  /** Measured width of the overflow indicator (0 if none). */
+  indicatorWidth: number;
+  /** Floor — always show at least this many items. */
+  minVisibleItems: number;
+  /** Ceiling — never show more than this many items. `undefined` = no cap. */
+  maxVisibleItems?: number;
+  /**
+   * Bounded multi-row: wrap items across up to this many rows, then collapse
+   * the rest into the overflow indicator. `undefined` (or `1`) = single line.
+   */
+  maxRows?: number;
+  /** Which end items collapse from. */
+  collapseFrom: 'start' | 'end';
+}
+
+export interface ComputeOverflowResult {
+  /** Number of items that should be rendered in the visible container. */
+  visibleCount: number;
+  /** Number of rows the visible items occupy (always 1 for the single-line path). */
+  rows: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(Math.min(value, max), min);
+}
+
+/**
+ * Resolve the ceiling and floor into a single [floor, ceiling] pair.
+ *
+ * `maxVisibleItems` is clamped to `itemCount` (a cap larger than the list is a
+ * no-op). When `maxVisibleItems < minVisibleItems`, the floor wins (D1) via the
+ * final clamp — the hook is responsible for the dev-only warning.
+ */
+function resolveBounds(
+  itemCount: number,
+  minVisibleItems: number,
+  maxVisibleItems: number | undefined,
+): {floor: number; ceiling: number} {
+  const floor = Math.max(0, Math.min(minVisibleItems, itemCount));
+  const rawCeiling = maxVisibleItems == null ? itemCount : maxVisibleItems;
+  const ceiling = Math.max(0, Math.min(rawCeiling, itemCount));
+  return {floor, ceiling};
+}
+
+/**
+ * Single-line greedy fit: how many items fit in one row of `availableWidth`,
+ * reserving indicator space for every non-final admitted item. Mirrors the
+ * original in-hook loop so single-line behavior is unchanged.
+ */
+function computeSingleLineFit(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorWidth: number,
+  floor: number,
+  ceiling: number,
+): number {
+  let totalWidth = 0;
+  let count = 0;
+
+  for (let i = 0; i < orderedWidths.length; i++) {
+    if (count >= ceiling) {
+      break;
+    }
+
+    const itemWidth = orderedWidths[i];
+    const gapWidth = i > 0 ? gap : 0;
+    const candidateWidth = totalWidth + itemWidth + gapWidth;
+
+    const isLastItem = i === orderedWidths.length - 1;
+    const reservedWidth = isLastItem
+      ? 0
+      : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
+
+    if (candidateWidth + reservedWidth > availableWidth && count >= floor) {
+      break;
+    }
+
+    totalWidth = candidateWidth;
+    count++;
+  }
+
+  return count;
+}
+
+/**
+ * Pack items into rows, wrapping when the next item would exceed
+ * `availableWidth`. On the last allowed row, keep `indicatorReserve` px free so
+ * the overflow indicator fits. Stops admitting once no further item can be
+ * placed within `maxRows`.
+ */
+function packRows(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorReserve: number,
+  maxRows: number,
+): {placed: number; rows: number} {
+  let placed = 0;
+  let row = 1;
+  let rowWidth = 0;
+
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+
+    const onLastRow = row === maxRows;
+    const reserve =
+      onLastRow && indicatorReserve > 0 ? indicatorReserve + gap : 0;
+
+    if (candidate + reserve <= availableWidth) {
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+
+    if (isFirstInRow) {
+      // A single item wider than the row occupies this row alone (it will be
+      // clipped visually). But if it can't coexist with the reserved indicator
+      // on the last row, stop here.
+      if (onLastRow && reserve > 0) {
+        break;
+      }
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+
+    if (row >= maxRows) {
+      break;
+    }
+    row++;
+    rowWidth = 0;
+    i--; // re-attempt this item as the first on the new row
+  }
+
+  return {placed, rows: row};
+}
+
+/** Count how many rows a set of items occupies when wrapped at availableWidth. */
+function countRows(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+): number {
+  if (orderedWidths.length === 0) {
+    return 0;
+  }
+  let rows = 1;
+  let rowWidth = 0;
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+    if (candidate <= availableWidth || isFirstInRow) {
+      rowWidth = candidate;
+    } else {
+      rows++;
+      rowWidth = w;
+    }
+  }
+  return rows;
+}
+
+/**
+ * Multi-row packing (Strategy A): simulate wrapping items into rows of
+ * `availableWidth`, admitting items until a new item would require a row beyond
+ * `maxRows`, reserving indicator space on the final row when items overflow.
+ * Returns the admitted count and how many rows those items occupy. Assumes
+ * uniform row height.
+ */
+function computeMultiRowFit(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorWidth: number,
+  maxRows: number,
+): {count: number; rows: number} {
+  const n = orderedWidths.length;
+  if (n === 0) {
+    return {count: 0, rows: 0};
+  }
+
+  // If everything fits within maxRows without reserving indicator space, there
+  // is no overflow and no indicator is needed.
+  const packAll = packRows(orderedWidths, gap, availableWidth, 0, maxRows);
+  if (packAll.placed === n) {
+    return {count: n, rows: packAll.rows};
+  }
+
+  // Overflow → reserve indicator space on the final row and re-pack.
+  const packWithIndicator = packRows(
+    orderedWidths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    maxRows,
+  );
+
+  const count = packWithIndicator.placed;
+  const rows = countRows(orderedWidths.slice(0, count), gap, availableWidth);
+
+  return {count, rows: Math.max(count > 0 ? 1 : 0, rows)};
+}
+
+/**
+ * Pure overflow computation. Given plain measurements and the configured
+ * limits, return how many items should be visible and how many rows they
+ * occupy. No DOM, no React — safe to unit-test directly.
+ */
+export function computeOverflow(
+  input: ComputeOverflowInput,
+): ComputeOverflowResult {
+  const {
+    widths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    minVisibleItems,
+    maxVisibleItems,
+    maxRows,
+    collapseFrom,
+  } = input;
+
+  const itemCount = widths.length;
+  if (itemCount === 0) {
+    return {visibleCount: 0, rows: 0};
+  }
+
+  const {floor, ceiling} = resolveBounds(
+    itemCount,
+    minVisibleItems,
+    maxVisibleItems,
+  );
+
+  const orderedWidths = collapseFrom === 'end' ? widths : [...widths].reverse();
+
+  const multiRow = maxRows != null && maxRows > 1;
+
+  if (!multiRow) {
+    const fitCount = computeSingleLineFit(
+      orderedWidths,
+      gap,
+      availableWidth,
+      indicatorWidth,
+      floor,
+      ceiling,
+    );
+    const visibleCount = clamp(fitCount, floor, ceiling);
+    return {visibleCount, rows: visibleCount > 0 ? 1 : 0};
+  }
+
+  const {count, rows} = computeMultiRowFit(
+    orderedWidths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    maxRows,
+  );
+  const visibleCount = clamp(count, floor, ceiling);
+  const resolvedRows =
+    visibleCount === count
+      ? rows
+      : countRows(orderedWidths.slice(0, visibleCount), gap, availableWidth);
+  return {visibleCount, rows: visibleCount > 0 ? Math.max(1, resolvedRows) : 0};
+}

package/src/hooks/index.ts

@@ -84,3 +84,5 @@ export type {
 
 export {useLongPress} from './useLongPress';
 export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';
+
+export {useDevWarning} from './useDevWarning';

package/src/hooks/isRtlElement.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file isRtlElement.ts
+ * @input DOM element (nullable)
+ * @output Exports isRtlElement helper resolving an element's computed text
+ *   direction
+ * @position Internal hook utility; used by useListFocus and useGridFocus to
+ *   auto-detect RTL for arrow-key navigation (same getComputedStyle precedent
+ *   as Resizable's ResizeHandle drag deltas).
+ */
+
+/**
+ * Whether `el` renders right-to-left, per its computed `direction`.
+ *
+ * SSR-safe: returns false when `el` is null or no DOM is available. Callers
+ * should invoke this lazily (on keydown, not on render) so getComputedStyle
+ * runs only when a horizontal arrow key is actually handled.
+ */
+export function isRtlElement(el: HTMLElement | null): boolean {
+  if (!el || typeof window === 'undefined') {
+    return false;
+  }
+  return window.getComputedStyle(el).direction === 'rtl';
+}

package/src/hooks/useDevWarning.test.tsx

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {render} from '@testing-library/react';
+import {useDevWarning} from './useDevWarning';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function Probe({
+  condition,
+  message = 'boom',
+}: {
+  condition: boolean;
+  message?: string;
+}) {
+  useDevWarning('TestComponent', message, condition);
+  return null;
+}
+
+describe('useDevWarning', () => {
+  it('warns once, in the standardized format, when the condition is true', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {rerender} = render(<Probe condition={true} />);
+    rerender(<Probe condition={true} />);
+    rerender(<Probe condition={true} />);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('TestComponent: boom');
+  });
+
+  it('does not warn when the condition is false', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Probe condition={false} />);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('warns after the condition flips from false to true', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {rerender} = render(<Probe condition={false} />);
+    expect(warn).not.toHaveBeenCalled();
+    rerender(<Probe condition={true} />);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useDevWarning.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDevWarning.ts
+ * @input A component name, a message, and a boolean condition
+ * @output Fires a dev-only `Component: message` warning once per mount
+ * @position Core hook; the render-safe way to warn the builder from a component
+ *
+ * The right way to surface a dev guardrail from inside a component. A naive
+ * `if (condition) console.warn(...)` in the render body repeats on every
+ * render, and reaching for `useState` to gate it adds needless state and
+ * re-renders. This hook uses a ref + effect: the warning fires once per mount
+ * when the condition holds, never during render, and never triggers a
+ * re-render. Messages use the standardized `Component: message` format.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/utils/devWarning.ts (the imperative counterpart)
+ */
+
+import {useEffect, useRef} from 'react';
+import {devWarn} from '../utils/devWarning';
+
+/**
+ * Fire a dev-only warning once per mount while `condition` is true.
+ *
+ * @param component - Component or hook name (message prefix)
+ * @param message - What went wrong and how to fix it
+ * @param condition - Whether to warn; defaults to `true`
+ *
+ * @example
+ * ```
+ * useDevWarning(
+ *   'Field',
+ *   'isOptional and isRequired are mutually exclusive. isOptional takes precedence.',
+ *   isOptional && isRequired,
+ * );
+ * ```
+ */
+export function useDevWarning(
+  component: string,
+  message: string,
+  condition: boolean = true,
+): void {
+  const hasWarnedRef = useRef(false);
+  useEffect(() => {
+    if (condition && !hasWarnedRef.current) {
+      hasWarnedRef.current = true;
+      devWarn(component, message);
+    }
+  }, [component, message, condition]);
+}

package/src/hooks/useGridFocus.doc.mjs

@@ -64,8 +64,8 @@ export const docs = {
     {
       name: 'options.isRtl',
       type: 'boolean',
-      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts.',
-      default: 'false',
+      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts. When omitted, auto-detected from the container computed direction on keydown.',
+      default: "undefined (auto-detect from the container's computed direction)",
       required: false,
     },
     {
@@ -138,7 +138,7 @@ export const docsDense = {
     'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',
     'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',
     'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',
-    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default false.',
+    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default: auto-detect from container computed direction; explicit boolean wins.',
     'options.hasRovingTabIndex': 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
   },
   returnDescriptions: {

package/src/hooks/useGridFocus.test.tsx

@@ -23,10 +23,12 @@ const NO_DISABLED: number[] = [];
 function Grid({
   disabled = NO_DISABLED,
   seed = 0,
+  dir,
   ...opts
 }: {
   disabled?: number[];
   seed?: number;
+  dir?: 'ltr' | 'rtl';
 } & Partial<Parameters<typeof useGridFocus>[0]>) {
   const {gridRef, handleKeyDown, handleFocus} = useGridFocus<HTMLDivElement>({
     columns: 3,
@@ -41,6 +43,7 @@ function Grid({
     <div
       ref={gridRef}
       role="grid"
+      dir={dir}
       onKeyDown={handleKeyDown}
       onFocus={handleFocus}>
       {Array.from({length: 9}, (_, i) => (
@@ -130,3 +133,41 @@ describe('useGridFocus roving tabindex (hasRovingTabIndex)', () => {
     expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
   });
 });
+
+describe('useGridFocus RTL auto-detection (WCAG 1.3.2)', () => {
+  // jsdom reflects the `dir` attribute into computed style only on the element
+  // that carries it, so tests set dir="rtl" on the grid container itself — the
+  // element the hook reads via gridRef.
+
+  it('auto-detects dir="rtl": ArrowLeft moves forward (next cell)', () => {
+    render(<Grid seed={1} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves backward (previous cell)', () => {
+    render(<Grid seed={1} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-0')).toHaveFocus();
+  });
+
+  it('leaves vertical navigation unaffected under dir="rtl"', () => {
+    render(<Grid seed={0} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowDown'});
+    expect(screen.getByTestId('cell-3')).toHaveFocus();
+  });
+
+  it('explicit isRtl={false} overrides a dir="rtl" container', () => {
+    render(<Grid seed={1} dir="rtl" isRtl={false} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+});

package/src/hooks/useGridFocus.ts

@@ -4,9 +4,12 @@
 
 /**
  * @file useGridFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect,
+ *   isRtlElement
  * @output Exports useGridFocus hook for grid keyboard navigation
- * @position Core hook; used by Calendar for date grid navigation
+ * @position Core hook; used by Calendar for date grid navigation. 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
@@ -14,6 +17,7 @@
  */
 
 import {useCallback, useRef} from 'react';
+import {isRtlElement} from './isRtlElement';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 
 /**
@@ -88,7 +92,12 @@ export interface UseGridFocusOptions {
   /**
    * Whether the grid is in a right-to-left context. When true, ArrowLeft and
    * ArrowRight are swapped so horizontal navigation follows visual direction.
-   * @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
+   * grids inside `dir="rtl"` subtrees flip automatically. Pass an explicit
+   * boolean to override detection.
+   * @default undefined (auto-detect from the container)
    */
   isRtl?: boolean;
 
@@ -217,7 +226,7 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
     onNavigateAfter,
     onPageUp,
     onPageDown,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false,
   } = options;
 
@@ -455,13 +464,15 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
 
       // In RTL, ArrowLeft/ArrowRight are swapped so horizontal navigation
       // follows visual direction. Vertical keys (Up/Down) are unaffected.
+      // 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.
       let key = e.key;
-      if (isRtl) {
-        if (key === 'ArrowLeft') {
-          key = 'ArrowRight';
-        } else if (key === 'ArrowRight') {
-          key = 'ArrowLeft';
-        }
+      if (
+        (key === 'ArrowLeft' || key === 'ArrowRight') &&
+        (isRtl ?? isRtlElement(gridRef.current))
+      ) {
+        key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';
       }
 
       switch (key) {

package/src/hooks/useListFocus.doc.mjs

@@ -49,8 +49,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,
     },
     {
@@ -127,7 +127,7 @@ export const docsDense = {
     '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.",
   },

package/src/hooks/useListFocus.test.tsx

@@ -3,7 +3,8 @@
 /**
  * @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
@@ -373,3 +374,68 @@ 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();
+  });
+});