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

package/dist/hooks/useInputStatusIcon.js

@@ -0,0 +1,169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInputStatusIcon.tsx
+ * @input Input status, statusVariant, and InputGroup awareness
+ * @output The on-field status icon element (with tooltip) and aria-describedby wiring
+ * @position Shared hook for bordered inputs that render a status affordance inside the control
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * Centralizes the on-field status icon across the bordered inputs (TextInput,
+ * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,
+ * FileInput) so the three statusVariants behave consistently:
+ *
+ * - `attached`  → icon sits inside the control; the message box below carries
+ *   the text.
+ * - `detached`  → the detached message box renders its OWN leading icon, so the
+ *   on-field icon is suppressed here to avoid a duplicate glyph.
+ * - `tooltip`   → no message box renders; the status is surfaced through an
+ *   info-tip on the on-field icon. The icon is a real focusable `<button>` so
+ *   the status is reachable by every user, not just those with hover or a
+ *   screen reader:
+ *     - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a
+ *       visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.
+ *     - Pointer: hover opens it (guarded to fine pointers).
+ *     - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.
+ *     - Assistive tech: the button has an accessible name (its status type,
+ *       WCAG 4.1.2) and is described by the message via `aria-describedby`.
+ *     - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { Icon } from "../Icon/index.js";
+import { useTooltip } from "../Tooltip/index.js";
+import { useTranslator } from "../i18n/index.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, radiusVars } from "../theme/tokens.stylex.js";
+import { themeProps } from "../utils/themeProps.js";
+
+/**
+ * Maps each status type to its glyph. Shared so every input shows the same icon
+ * for a given status, matching the detached message box's leading icon.
+ */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const STATUS_ICON = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success'
+};
+
+/**
+ * Accessible-name i18n keys for the focusable status button, keyed by type.
+ */
+const STATUS_BUTTON_LABEL_KEY = {
+  warning: '@astryx.input.statusButton.warning',
+  error: '@astryx.input.statusButton.error',
+  success: '@astryx.input.statusButton.success'
+};
+/**
+ * Builds the on-field status icon and its accessibility wiring for a bordered
+ * input. See the file header for the per-variant behavior.
+ */
+export function useInputStatusIcon({
+  status,
+  statusVariant = 'attached',
+  isInGroup = false,
+  size = 'md'
+}) {
+  const t = useTranslator();
+  const isTooltipVariant = statusVariant === 'tooltip';
+  const hasTooltip = isTooltipVariant && !!status?.message;
+
+  // Touch tap-to-toggle. Hover is unavailable on touch, and useTooltip
+  // suppresses simulated hover there, so on touch a tap controls visibility.
+  // `undefined` leaves the tooltip uncontrolled (pointer + keyboard drive it);
+  // a boolean takes control for the current open/close cycle.
+  const [tapOpen, setTapOpen] = useState(undefined);
+  const tooltip = useTooltip({
+    placement: 'above',
+    isEnabled: hasTooltip,
+    isOpen: tapOpen
+  });
+
+  // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed
+  // (Escape/outside interaction), so subsequent pointer/keyboard use behaves
+  // normally.
+  const handleButtonBlur = useCallback(() => {
+    setTapOpen(undefined);
+  }, []);
+  const handleButtonClick = useCallback(() => {
+    // Only take control on touch/hover-less devices. On hover-capable devices
+    // pointer hover and keyboard focus already drive the tooltip (uncontrolled),
+    // so a click-toggle would fight them; leave it uncontrolled there.
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function' || !window.matchMedia('(hover: none)').matches) {
+      return;
+    }
+    setTapOpen(prev => prev === true ? false : true);
+  }, []);
+
+  // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled
+  // state (useTooltip owns Escape for the uncontrolled case, but while we hold
+  // control via isOpen it does not, so mirror it here).
+  useEffect(() => {
+    if (tapOpen !== true) {
+      return;
+    }
+    const onKeyDown = e => {
+      if (e.key === 'Escape') {
+        setTapOpen(undefined);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [tapOpen]);
+
+  // Inside a group the group owns status rendering; the detached message box
+  // renders its own leading icon, so the on-field icon would duplicate it.
+  const shouldRenderIcon = !!status && !isInGroup && statusVariant !== 'detached';
+  if (!shouldRenderIcon) {
+    return {
+      statusIcon: null,
+      describedBy: undefined
+    };
+  }
+  const icon = /*#__PURE__*/_jsx(Icon, {
+    icon: STATUS_ICON[status.type],
+    size: size,
+    color: status.type
+    // Stable theme target on the status glyph itself, so a theme can restyle
+    // just this icon (color, size) — and each status — via `defineTheme`.
+    // Same-element rules in @layer astryx-theme win over the icon's own base
+    // width/height/fontSize, which a field-level target could not reach.
+    // Shared by the attached and tooltip variants across all bordered inputs.
+    ,
+    ...themeProps('input-status-icon', {
+      size,
+      status: status.type
+    })
+  });
+
+  // Attached (and tooltip-without-message) variants: plain, non-interactive
+  // icon. The message box (attached) already carries the text.
+  if (!hasTooltip) {
+    return {
+      statusIcon: icon,
+      describedBy: undefined
+    };
+  }
+  return {
+    statusIcon: /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx("button", {
+        type: "button",
+        ref: tooltip.ref,
+        "aria-label": t(STATUS_BUTTON_LABEL_KEY[status.type]),
+        "aria-describedby": tooltip.describedBy,
+        onClick: handleButtonClick,
+        onBlur: handleButtonBlur,
+        ...{
+          className: "x3nfvp2 x6s0dn4 xl56j7k x1717udv x1ghz6dp x1heor9g x1ypdohk xjspbzw x784prv x9v5kkp xzunyri x7s97pk"
+        },
+        children: icon
+      }), tooltip.renderTooltip(status.message)]
+    }),
+    describedBy: tooltip.describedBy
+  };
+}

package/dist/hooks/useKeyboardHint.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
  * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
  * @position Core hook; shows sighted keyboard users how to navigate composite
  *   widgets that use roving tabindex (single Tab stop, arrows inside)
@@ -9,7 +9,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 import React, { type ReactNode } from 'react';
 export type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';

package/dist/hooks/useKeyboardHint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useKeyboardHint.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardHint.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAgB5E,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,uBAAuB,CAAC;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,WAAW,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEvC;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEtC;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;CAC7C;AAkED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA6JvB"}
+{"version":3,"file":"useKeyboardHint.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardHint.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAiB5E,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,uBAAuB,CAAC;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,WAAW,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEvC;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEtC;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;CAC7C;AAkED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAgKvB"}

package/dist/hooks/useKeyboardHint.js

@@ -4,7 +4,7 @@
 
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
  * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
  * @position Core hook; shows sighted keyboard users how to navigate composite
  *   widgets that use roving tabindex (single Tab stop, arrows inside)
@@ -13,7 +13,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 import React, { useCallback, useEffect, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -21,6 +21,7 @@ import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars, shadowVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
 import { Kbd } from "../Kbd/index.js";
 import { useLayer } from "../Layer/useLayer.js";
+import { useTranslator } from "../i18n/index.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -90,6 +91,7 @@ export function useKeyboardHint(options = {}) {
     dismissAfterMs = 3000,
     isEnabled = true
   } = options;
+  const t = useTranslator();
   const timeoutRef = useRef(null);
   const dismissedRef = useRef(false);
   const isVisibleRef = useRef(false);
@@ -201,7 +203,7 @@ export function useKeyboardHint(options = {}) {
       ...{
         className: "x11g1kdw"
       },
-      children: "to navigate"
+      children: t('@astryx.keyboardHint.toNavigate')
     })]
   }), {
     placement: 'below',

package/dist/hooks/useListFocus.d.ts

@@ -14,6 +14,24 @@ export interface UseListFocusOptions {
      * @default '[role="menuitem"]'
      */
     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
@@ -38,7 +56,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;
     /**
@@ -96,6 +119,21 @@ 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[];
 }
 /**
  * Hook for managing keyboard navigation within a linear list.

package/dist/hooks/useListFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwSvB"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;CAC/B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwVvB"}

package/dist/hooks/useListFocus.js

@@ -4,15 +4,19 @@
 
 /**
  * @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.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
 /**
@@ -161,11 +165,12 @@ function shouldDeferToCaret(target, key) {
 export function useListFocus(options = {}) {
   const {
     itemSelector = '[role="menuitem"]',
+    boundarySelector,
     wrap = true,
     onEscape,
     orientation = 'vertical',
     hasHomeEnd = true,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false,
     hasCaretGuard = false
   } = options;
@@ -184,11 +189,38 @@ export function useListFocus(options = {}) {
    * Get all focusable items in the list.
    */
   const getItems = useCallback(() => {
-    if (!listRef.current) {
+    const listEl = listRef.current;
+    if (!listEl) {
       return [];
     }
-    return Array.from(listRef.current.querySelectorAll(itemSelector));
-  }, [itemSelector]);
+    const matched = Array.from(listEl.querySelectorAll(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 => {
+    const listEl = listRef.current;
+    if (!listEl || !boundarySelector) {
+      return true;
+    }
+    const target = e.target;
+    if (!target) {
+      return true;
+    }
+    return target.closest(boundarySelector) === listEl;
+  }, [boundarySelector]);
 
   /**
    * Find the next enabled item index from `start`, moving by `step`, optionally
@@ -341,6 +373,13 @@ export function useListFocus(options = {}) {
       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.
@@ -353,11 +392,15 @@ export function useListFocus(options = {}) {
     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 = [];
     const prevKeys = [];
     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');
@@ -397,13 +440,15 @@ export function useListFocus(options = {}) {
       focusLast();
     }
     e.preventDefault();
-  }, [getCurrentIndex, getItems, wrap, orientation, isRtl, hasHomeEnd, hasCaretGuard, findEnabledIndex, focusIndex, focusFirst, focusLast, onEscape]);
+  }, [getCurrentIndex, getItems, wrap, orientation, isRtl, hasHomeEnd, hasCaretGuard, findEnabledIndex, focusIndex, focusFirst, focusLast, onEscape, ownsEvent]);
   return {
     listRef,
     handleKeyDown,
     handleFocus,
     focusItem,
     focusFirst,
-    focusLast
+    focusLast,
+    ownsEvent,
+    getItems
   };
 }

package/dist/i18n/InternationalizationContext.d.ts

@@ -1,6 +1,7 @@
 import type { Locale, MessagesByLocale, Overrides } from './types';
 export interface InternationalizationContextValue {
     locale: Locale;
+    direction: 'ltr' | 'rtl';
     messages: MessagesByLocale;
     overrides?: Overrides;
 }

package/dist/i18n/InternationalizationContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InternationalizationContext.d.ts","sourceRoot":"","sources":["../../src/i18n/InternationalizationContext.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEjE,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,2DAIpC,CAAC"}
+{"version":3,"file":"InternationalizationContext.d.ts","sourceRoot":"","sources":["../../src/i18n/InternationalizationContext.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEjE,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,KAAK,GAAG,KAAK,CAAC;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,2DAKpC,CAAC"}

package/dist/i18n/InternationalizationContext.js

@@ -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
  */
 import { createContext } from 'react';
@@ -24,6 +26,7 @@ import { createContext } from 'react';
  */
 export const InternationalizationContext = /*#__PURE__*/createContext({
   locale: 'en',
+  direction: 'ltr',
   messages: {}
 });
 InternationalizationContext.displayName = 'InternationalizationContext';

package/dist/i18n/InternationalizationProvider.d.ts

@@ -48,13 +48,20 @@ 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;
 }
 /**
  * Provides locale + additional messages + overrides to all astryx
  * components in the subtree.
  */
-export declare function InternationalizationProvider({ locale, messages, overrides, children, }: InternationalizationProviderProps): import("react").JSX.Element;
+export declare function InternationalizationProvider({ locale, messages, overrides, dir, children, }: InternationalizationProviderProps): import("react").JSX.Element;
 export declare namespace InternationalizationProvider {
     var displayName: string;
 }

package/dist/i18n/InternationalizationProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InternationalizationProvider.d.ts","sourceRoot":"","sources":["../../src/i18n/InternationalizationProvider.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9C,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEjE,MAAM,WAAW,iCAAiC;IAChD;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,GACT,EAAE,iCAAiC,+BAUnC;yBAfe,4BAA4B"}
+{"version":3,"file":"InternationalizationProvider.d.ts","sourceRoot":"","sources":["../../src/i18n/InternationalizationProvider.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG9C,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEjE,MAAM,WAAW,iCAAiC;IAChD;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,MAAM,EACN,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,GACT,EAAE,iCAAiC,+BAWnC;yBAjBe,4BAA4B"}

package/dist/i18n/InternationalizationProvider.js

@@ -20,6 +20,7 @@
  */
 import { useMemo } from 'react';
 import { InternationalizationContext } from "./InternationalizationContext.js";
+import { getLocaleDirection } from "./getLocaleDirection.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * Provides locale + additional messages + overrides to all astryx
@@ -29,13 +30,16 @@ export function InternationalizationProvider({
   locale,
   messages,
   overrides,
+  dir,
   children
 }) {
+  const direction = dir ?? getLocaleDirection(locale);
   const value = useMemo(() => ({
     locale,
+    direction,
     messages: messages ?? {},
     overrides
-  }), [locale, messages, overrides]);
+  }), [locale, direction, messages, overrides]);
   return /*#__PURE__*/_jsx(InternationalizationContext, {
     value: value,
     children: children

package/dist/i18n/getLocaleDirection.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 declare function getLocaleDirection(locale: string): 'ltr' | 'rtl';
+//# sourceMappingURL=getLocaleDirection.d.ts.map

package/dist/i18n/getLocaleDirection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getLocaleDirection.d.ts","sourceRoot":"","sources":["../../src/i18n/getLocaleDirection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAShE"}

package/dist/i18n/getLocaleDirection.js

@@ -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) {
+  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/dist/i18n/index.d.ts

@@ -8,10 +8,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';
 export type { InternationalizationProviderProps } from './InternationalizationProvider';
@@ -19,6 +23,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, Catalog, MessageEntry, MessagesByLocale, Overrides, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/i18n/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,4BAA4B,EAAC,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAC,iCAAiC,EAAC,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAC,2BAA2B,EAAC,MAAM,+BAA+B,CAAC;AAC1E,YAAY,EAAC,gCAAgC,EAAC,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AAC7C,YAAY,EACV,MAAM,EACN,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,4BAA4B,EAAC,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAC,iCAAiC,EAAC,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAC,2BAA2B,EAAC,MAAM,+BAA+B,CAAC;AAC1E,YAAY,EAAC,gCAAgC,EAAC,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AAC7C,YAAY,EACV,MAAM,EACN,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,SAAS,CAAC"}

package/dist/i18n/index.js

@@ -10,12 +10,18 @@
  * 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.js";
 export { InternationalizationContext } from "./InternationalizationContext.js";
-export { useTranslator } from "./useTranslator.js";
+export { useTranslator } from "./useTranslator.js";
+export { useDirection } from "./useDirection.js";
+export { getLocaleDirection } from "./getLocaleDirection.js";

package/dist/i18n/useDirection.d.ts

@@ -0,0 +1,2 @@
+export declare function useDirection(): 'ltr' | 'rtl';
+//# sourceMappingURL=useDirection.d.ts.map

package/dist/i18n/useDirection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDirection.d.ts","sourceRoot":"","sources":["../../src/i18n/useDirection.ts"],"names":[],"mappings":"AAyBA,wBAAgB,YAAY,IAAI,KAAK,GAAG,KAAK,CAG5C"}