@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/dist/hooks/useInputStatusIcon.js

@@ -0,0 +1,158 @@
+// 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";
+
+/**
+ * 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
+  });
+
+  // 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/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/hooks/useOverflow.d.ts

@@ -9,6 +9,21 @@ export interface UseOverflowOptions {
      * @default 0
      */
     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'
@@ -35,6 +50,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;
 }
 /**
  * Hook for managing horizontal overflow of a list of items.

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

@@ -1 +1 @@
-{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAsInB"}
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAqJnB"}

package/dist/hooks/useOverflow.js

@@ -10,14 +10,19 @@
  *
  * 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.js";
 import { observeResize, unobserveResize } from "../utils/sharedResizeObserver.js";
+import { computeOverflow } from "./computeOverflow.js";
+import { useDevWarning } from "./useDevWarning.js";
 /**
  * Hook for managing horizontal overflow of a list of items.
  *
@@ -40,11 +45,16 @@ export function useOverflow(itemCount, options = {}) {
   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(null);
   const measureElRef = useRef(null);
   const observedElRef = useRef(null);
@@ -72,34 +82,33 @@ export function useOverflow(itemCount, options = {}) {
     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 => {
     containerElRef.current = el;
 
@@ -132,6 +141,8 @@ export function useOverflow(itemCount, options = {}) {
     containerRef,
     measureRef,
     visibleCount,
-    hasOverflow
+    hasOverflow,
+    rows,
+    rowHeight
   };
 }

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