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

package/dist/hooks/isRtlElement.js

@@ -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) {
+  if (!el || typeof window === 'undefined') {
+    return false;
+  }
+  return window.getComputedStyle(el).direction === 'rtl';
+}

package/dist/hooks/useAnnounce.d.ts

@@ -17,6 +17,9 @@ export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => v
  * The polite and assertive regions are created once on first use and kept
  * mounted, so announcements are reliable even for messages that appear
  * immediately (unlike a live region rendered together with its content).
+ * Each message is automatically cleared a couple of seconds after being
+ * announced, so users browsing the DOM later do not encounter stale status
+ * text; announcing again before the clear simply resets the countdown.
  *
  * @example
  * ```

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,KAC5B,IAAI,CAAC;AAyFV;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAaxC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD"}
+{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,KAC5B,IAAI,CAAC;AAgIV;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAaxC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAQhD"}

package/dist/hooks/useAnnounce.js

@@ -7,7 +7,9 @@
  * @input Uses React useCallback; DOM APIs for a singleton live-region pair
  * @output Exports useAnnounce hook and AnnouncePoliteness type
  * @position Core a11y hook; provides imperative screen-reader announcements
- *   via persistently-mounted polite/assertive live regions
+ *   via persistently-mounted polite/assertive live regions; regions are
+ *   auto-cleared shortly after announcing so stale status text does not
+ *   linger in the accessibility tree
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -31,6 +33,32 @@ const CONTAINER_ATTR = 'data-astryx-live-region';
 // Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
 // inline so the regions work without any stylesheet being present.
 const VISUALLY_HIDDEN_CSS = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;' + 'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;' + 'inset-block-start:0;inset-inline-start:0;pointer-events:none;' + 'user-select:none;';
+/**
+ * How long an announcement stays in its region before being auto-cleared.
+ * Long enough for screen readers to pick the message up and finish reading
+ * it; clearing afterwards keeps stale status text out of the accessibility
+ * tree for users who browse the DOM later. Each announce resets the timer.
+ */
+const CLEAR_DELAY_MS = 2000;
+const clearTimers = {
+  polite: null,
+  assertive: null
+};
+function cancelScheduledClear(politeness) {
+  const timer = clearTimers[politeness];
+  if (timer != null) {
+    clearTimeout(timer);
+    clearTimers[politeness] = null;
+  }
+}
+function scheduleClear(politeness, target) {
+  cancelScheduledClear(politeness);
+  clearTimers[politeness] = setTimeout(() => {
+    clearTimers[politeness] = null;
+    target.textContent = '';
+  }, CLEAR_DELAY_MS);
+}
+
 // Singleton: the live regions are created ONCE and stay mounted for the
 // lifetime of the document. This is the crux of reliable announcements — many
 // screen readers will not announce content injected into a live region that is
@@ -81,6 +109,10 @@ function announceMessage(message, politeness) {
   requestAnimationFrame(() => {
     target.textContent = message;
   });
+  // Auto-clear so the last message does not linger in the accessibility tree
+  // indefinitely. Scheduled per announce, so a newer announcement always
+  // resets the countdown (the delay comfortably outlasts the rAF re-set).
+  scheduleClear(politeness, target);
 }
 
 /**
@@ -89,6 +121,7 @@ function announceMessage(message, politeness) {
  * so stale status text does not linger in the accessibility tree.
  */
 function clearRegion(politeness) {
+  cancelScheduledClear(politeness);
   if (!regions) {
     return;
   }
@@ -103,6 +136,9 @@ function clearRegion(politeness) {
  * The polite and assertive regions are created once on first use and kept
  * mounted, so announcements are reliable even for messages that appear
  * immediately (unlike a live region rendered together with its content).
+ * Each message is automatically cleared a couple of seconds after being
+ * announced, so users browsing the DOM later do not encounter stale status
+ * text; announcing again before the clear simply resets the countdown.
  *
  * @example
  * ```
@@ -134,6 +170,8 @@ export function useAnnounce() {
  * @internal
  */
 export function __resetLiveRegionsForTest() {
+  cancelScheduledClear('polite');
+  cancelScheduledClear('assertive');
   if (regions) {
     regions.polite.remove();
     regions.assertive.remove();

package/dist/hooks/useContainerReveal.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file useContainerReveal.ts
+ * @input Uses React, the generated marker pool, useDevWarning
+ * @output Exports useContainerReveal — a headless hover/focus reveal primitive
+ * @position Core hook. Consumed by any component that reveals (or conceals)
+ *   content when its container is hovered or focused — e.g. Thumbnail's remove
+ *   button, TreeList row actions.
+ *
+ * Gives a container a scoped hover/focus-within trigger that reveals or
+ * conceals content inside it, entirely in CSS (no hover state in JS, no
+ * re-render on hover). The caller authors NO StyleX: the hook hands out a
+ * marker + matching reveal styles from a pre-compiled pool.
+ *
+ * ACCESSIBILITY (WCAG 2.2 by construction):
+ * - Revealed content is visually hidden at rest via position + opacity, so it
+ *   stays in the accessibility tree and tab order — never display:none.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Touch: always visible on coarse pointers; never gated behind hover.
+ * - Concealed (inverted) content is a mouse-only visual swap: it ignores
+ *   :focus-within (a keyboard user must never watch content vanish) and stays
+ *   visible on touch and in the a11y tree.
+ * - Motion: honors prefers-reduced-motion.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ */
+import { type CSSProperties } from 'react';
+export interface UseContainerRevealOptions {
+    /**
+     * When false the hook is inert: no marker is applied and content getters
+     * return no styles, so content is always shown. Lets a component gate on its
+     * own prop (e.g. `revealOn === 'hover'`).
+     * @default true
+     */
+    isEnabled?: boolean;
+}
+export interface ContentRevealOptions {
+    /**
+     * Conceal-on-hover instead of reveal-on-hover: content is visible at rest
+     * and fades out while the container is hovered. Mouse-only and visual —
+     * stays in the a11y tree, ignores focus-within, stays visible on touch.
+     * @default false
+     */
+    isRevealInverted?: boolean;
+    /**
+     * Reserve the content's layout box while hidden (opacity-only) instead of
+     * collapsing it, to avoid layout shift when it appears.
+     * @default false
+     */
+    isLayoutPreserved?: boolean;
+}
+export interface UseContainerRevealReturn {
+    /** Spread onto the container whose hover/focus-within drives the reveal. */
+    getContainerProps: () => {
+        className?: string;
+        style?: CSSProperties;
+    };
+    /** Spread onto each revealed / concealed child. */
+    getContentRevealProps: (options?: ContentRevealOptions) => {
+        className?: string;
+        style?: CSSProperties;
+    };
+}
+/**
+ * Scoped, CSS-only hover/focus reveal for content inside a container.
+ *
+ * @example
+ * ```tsx
+ * const {getContainerProps, getContentRevealProps} = useContainerReveal({
+ *   isEnabled: revealOn === 'hover',
+ * });
+ *
+ * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ *   {label}
+ *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
+ *     {actions}
+ *   </span>
+ * </div>
+ * ```
+ */
+export declare function useContainerReveal(options?: UseContainerRevealOptions): UseContainerRevealReturn;
+//# sourceMappingURL=useContainerReveal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useContainerReveal.d.ts","sourceRoot":"","sources":["../../src/hooks/useContainerReveal.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAsB,KAAK,aAAa,EAAC,MAAM,OAAO,CAAC;AA0C9D,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,iBAAiB,EAAE,MAAM;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,aAAa,CAAA;KAAC,CAAC;IACrE,mDAAmD;IACnD,qBAAqB,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK;QACzD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CAiD1B"}

package/dist/hooks/useContainerReveal.js

@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useContainerReveal.ts
+ * @input Uses React, the generated marker pool, useDevWarning
+ * @output Exports useContainerReveal — a headless hover/focus reveal primitive
+ * @position Core hook. Consumed by any component that reveals (or conceals)
+ *   content when its container is hovered or focused — e.g. Thumbnail's remove
+ *   button, TreeList row actions.
+ *
+ * Gives a container a scoped hover/focus-within trigger that reveals or
+ * conceals content inside it, entirely in CSS (no hover state in JS, no
+ * re-render on hover). The caller authors NO StyleX: the hook hands out a
+ * marker + matching reveal styles from a pre-compiled pool.
+ *
+ * ACCESSIBILITY (WCAG 2.2 by construction):
+ * - Revealed content is visually hidden at rest via position + opacity, so it
+ *   stays in the accessibility tree and tab order — never display:none.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Touch: always visible on coarse pointers; never gated behind hover.
+ * - Concealed (inverted) content is a mouse-only visual swap: it ignores
+ *   :focus-within (a keyboard user must never watch content vanish) and stays
+ *   visible on touch and in the a11y tree.
+ * - Motion: honors prefers-reduced-motion.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ */
+import { useState, useEffect } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { POOL, POOL_SIZE } from "./containerReveal.pool.stylex.js";
+import { useDevWarning } from "./useDevWarning.js";
+
+// Module-level free-list. Each mounted, enabled useContainerReveal claims a
+// distinct pool slot so that any two CONCURRENTLY mounted containers — in
+// particular a nested container inside another's revealed content — get
+// different markers and cannot leak hover/focus into one another. Slots are
+// returned on unmount. Sibling containers that would only ever collide when
+// the pool is exhausted are harmless (a sibling is never an ancestor), so the
+// pool only needs to cover the number of concurrently mounted containers, not
+// instances over time.
+const claimed = new Array(POOL_SIZE).fill(false);
+function claimSlot() {
+  for (let i = 0; i < POOL_SIZE; i++) {
+    if (!claimed[i]) {
+      claimed[i] = true;
+      return {
+        index: i,
+        isExhausted: false
+      };
+    }
+  }
+  // Exhausted: fall back to slot 0. Safe for siblings (a sibling is never an
+  // ancestor); only nesting deeper than POOL_SIZE could reintroduce a leak.
+  // Surfaced via useDevWarning so the pool can be grown.
+  return {
+    index: 0,
+    isExhausted: true
+  };
+}
+function releaseSlot(index, isExhausted) {
+  // A fallback claim never owned the slot exclusively; leave it as-is.
+  if (!isExhausted) {
+    claimed[index] = false;
+  }
+}
+const EMPTY = Object.freeze({});
+
+/**
+ * Scoped, CSS-only hover/focus reveal for content inside a container.
+ *
+ * @example
+ * ```tsx
+ * const {getContainerProps, getContentRevealProps} = useContainerReveal({
+ *   isEnabled: revealOn === 'hover',
+ * });
+ *
+ * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ *   {label}
+ *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
+ *     {actions}
+ *   </span>
+ * </div>
+ * ```
+ */
+export function useContainerReveal(options = {}) {
+  const {
+    isEnabled = true
+  } = options;
+
+  // Claim a slot for this container's lifetime. Assigned in the initializer
+  // (not the render body) and released on unmount so the free-list stays
+  // effect-scoped and StrictMode-safe.
+  const [claim] = useState(() => isEnabled ? claimSlot() : null);
+  useEffect(() => {
+    if (claim == null) {
+      return;
+    }
+    return () => releaseSlot(claim.index, claim.isExhausted);
+  }, [claim]);
+  useDevWarning('useContainerReveal', `More than ${POOL_SIZE} reveal containers are mounted at once; nested ` + `containers beyond the pool may share a marker. Add markers to ` + `containerReveal.pool.stylex.ts and raise POOL_SIZE.`, claim?.isExhausted ?? false);
+  if (claim == null) {
+    return {
+      getContainerProps: () => EMPTY,
+      getContentRevealProps: () => EMPTY
+    };
+  }
+  const slot = POOL[claim.index];
+  return {
+    getContainerProps: () => stylex.props(slot.marker),
+    getContentRevealProps: (contentOptions = {}) => {
+      const {
+        isRevealInverted = false,
+        isLayoutPreserved = false
+      } = contentOptions;
+      const style = isRevealInverted ? isLayoutPreserved ? slot.concealLayoutPreserved : slot.conceal : isLayoutPreserved ? slot.revealLayoutPreserved : slot.reveal;
+      return stylex.props(style);
+    }
+  };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AAgDA;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAEV;AA0ED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAiMvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AAsFA;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAEV;AAgFD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAsMvB"}

package/dist/hooks/useFocusTrap.js

@@ -24,21 +24,51 @@ import { FOCUSABLE_SELECTOR } from "./focusableSelector.js";
  * Every active `useFocusTrap` used to attach its own document-level `keydown`
  * listener with no coordination, so a single Escape press closed *every* open
  * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
- * traps in a shared stack lets only the most recently activated (top-most)
- * trap respond to Escape.
+ * traps in a shared stack lets only the top-most trap respond to Escape.
+ *
+ * "Top-most" is resolved by DOM containment first, push order second. Push
+ * order alone is not reliable: React runs child effects before parent
+ * effects, so when an outer and an inner (DOM-nested) trap mount in the SAME
+ * commit, the inner trap pushes first and the outer trap would wrongly win a
+ * pure last-pushed comparison.
  */
+
 const escapeStack = [];
-function pushEscapeHandler(handler) {
-  escapeStack.push(handler);
+function pushEscapeHandler(entry) {
+  escapeStack.push(entry);
 }
 function removeEscapeHandler(handler) {
-  const index = escapeStack.lastIndexOf(handler);
-  if (index !== -1) {
-    escapeStack.splice(index, 1);
+  for (let i = escapeStack.length - 1; i >= 0; i--) {
+    if (escapeStack[i].handler === handler) {
+      escapeStack.splice(i, 1);
+      return;
+    }
   }
 }
+
+/**
+ * Resolve the top-most trap: walk the stack in push order, keeping the
+ * deepest container by DOM containment. When a later entry's container
+ * contains the current candidate's container, the candidate is nested inside
+ * it and stays on top; otherwise the later push wins (containment for nested
+ * traps, push order as the tiebreaker for unrelated ones).
+ */
 function isTopEscapeHandler(handler) {
-  return escapeStack[escapeStack.length - 1] === handler;
+  if (escapeStack.length === 0) {
+    return false;
+  }
+  let top = escapeStack[0];
+  for (let i = 1; i < escapeStack.length; i++) {
+    const entry = escapeStack[i];
+    const topContainer = top.getContainer();
+    const entryContainer = entry.getContainer();
+    if (topContainer != null && entryContainer != null && entryContainer !== topContainer && entryContainer.contains(topContainer)) {
+      // The current top is nested inside this entry — it stays on top.
+      continue;
+    }
+    top = entry;
+  }
+  return top.handler === handler;
 }
 
 /**
@@ -65,7 +95,9 @@ export function isImeKeyEvent(event) {
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
- * which the browser skips for Tab.
+ * which the browser skips for Tab, and ones inside an `aria-hidden="true"`
+ * subtree, which sighted-keyboard users could Tab to while AT skips them
+ * (WCAG 4.1.2 — focusable content must be exposed to assistive tech).
  */
 function isVisiblyFocusable(el) {
   if (el.hasAttribute('inert') || el.closest('[inert]')) {
@@ -74,6 +106,10 @@ function isVisiblyFocusable(el) {
   if (el.hidden || el.closest('[hidden]')) {
     return false;
   }
+  // closest() matches the element itself as well as any ancestor.
+  if (el.closest('[aria-hidden="true"]')) {
+    return false;
+  }
   // offsetParent is null for display:none (and fixed elements); pair with a
   // visibility check via getComputedStyle when available.
   if (typeof window !== 'undefined' && window.getComputedStyle) {
@@ -274,12 +310,17 @@ export function useFocusTrap(options) {
 
     // Register this trap on the shared Escape stack so only the top-most
     // active trap responds to Escape. A stable identity per active period is
-    // enough — we push on activate and remove on cleanup.
+    // enough — we push on activate and remove on cleanup. The container is
+    // read lazily: the ref may not be attached yet at effect time, and the
+    // stack resolves top-most by DOM containment at keydown time.
     const escapeHandler = () => {
       onEscape?.();
     };
     if (onEscape) {
-      pushEscapeHandler(escapeHandler);
+      pushEscapeHandler({
+        handler: escapeHandler,
+        getContainer: () => containerRef.current
+      });
     }
     const handleKeyDown = event => {
       const container = containerRef.current;

package/dist/hooks/useGridFocus.d.ts

@@ -62,7 +62,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;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"useGridFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useGridFocus.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEjD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,WAAW,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;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,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAuYvB"}
+{"version":3,"file":"useGridFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useGridFocus.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEjD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,WAAW,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;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,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAyYvB"}

package/dist/hooks/useGridFocus.js

@@ -4,15 +4,19 @@
 
 /**
  * @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
  * - /packages/core/src/hooks/useGridFocus.test.tsx
  */
 import { useCallback, useRef } from 'react';
+import { isRtlElement } from "./isRtlElement.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
 /**
@@ -87,7 +91,7 @@ export function useGridFocus(options) {
     onNavigateAfter,
     onPageUp,
     onPageDown,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false
   } = options;
   const gridRef = useRef(null);
@@ -297,13 +301,12 @@ export function useGridFocus(options) {
 
     // 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) {
       case 'ArrowRight':

package/dist/hooks/useHotkeys.d.ts

@@ -36,6 +36,15 @@ export interface Hotkey {
  * definitions live in a ref, so re-renders update behavior without
  * re-subscribing. First matching hotkey wins per event.
  *
+ * Accessibility (WCAG 2.1.4 — Character Key Shortcuts): a shortcut whose
+ * combo is a single unmodified character (letter, digit, punctuation or
+ * symbol — e.g. 'c' or '/') is easily triggered by accident by speech-input
+ * users and keyboard users with motor impairments. If you register one, you
+ * MUST also provide at least one of: (a) a way to turn the shortcut off,
+ * (b) a way to remap it to include a modifier, or (c) scope it so it is only
+ * active while the relevant component has focus. Prefer `mod`-based combos
+ * where possible; the `isDisabled` flag can back a user-facing off switch.
+ *
  * @param hotkeys - Shortcut registrations to listen for.
  *
  * @example

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

@@ -1 +1 @@
-{"version":3,"file":"useHotkeys.d.ts","sourceRoot":"","sources":["../../src/hooks/useHotkeys.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA2FD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAkClD"}
+{"version":3,"file":"useHotkeys.d.ts","sourceRoot":"","sources":["../../src/hooks/useHotkeys.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAkClD"}

package/dist/hooks/useHotkeys.js

@@ -115,6 +115,15 @@ function matchesCombo(keys, event, isApple) {
  * definitions live in a ref, so re-renders update behavior without
  * re-subscribing. First matching hotkey wins per event.
  *
+ * Accessibility (WCAG 2.1.4 — Character Key Shortcuts): a shortcut whose
+ * combo is a single unmodified character (letter, digit, punctuation or
+ * symbol — e.g. 'c' or '/') is easily triggered by accident by speech-input
+ * users and keyboard users with motor impairments. If you register one, you
+ * MUST also provide at least one of: (a) a way to turn the shortcut off,
+ * (b) a way to remap it to include a modifier, or (c) scope it so it is only
+ * active while the relevant component has focus. Prefer `mod`-based combos
+ * where possible; the `isDisabled` flag can back a user-facing off switch.
+ *
  * @param hotkeys - Shortcut registrations to listen for.
  *
  * @example

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

@@ -1 +1 @@
-{"version":3,"file":"useInputContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAsBlD,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,iDAAiD;IACjD,QAAQ,EAAE,SAAS,CACjB,gBAAgB,GAAG,mBAAmB,GAAG,WAAW,GAAG,IAAI,CAC5D,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,QAAQ,EACR,QAAgB,GACjB,EAAE,wBAAwB,8DA0B1B"}
+{"version":3,"file":"useInputContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAoDlD,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,iDAAiD;IACjD,QAAQ,EAAE,SAAS,CACjB,gBAAgB,GAAG,mBAAmB,GAAG,WAAW,GAAG,IAAI,CAC5D,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,QAAQ,EACR,QAAgB,GACjB,EAAE,wBAAwB,8DA+B1B"}

package/dist/hooks/useInputContainer.js

@@ -20,6 +20,29 @@ import { useClickableContainer } from "./useClickableContainer.js";
  * Other input types (e.g. checkbox, radio, file) use `.click()` instead.
  */
 const FOCUS_INPUT_TYPES = new Set(['text', 'password', 'email', 'number', 'search', 'tel', 'url', 'date', 'datetime-local', 'month', 'time', 'week']);
+
+/**
+ * `aria-haspopup` values that advertise a control opens a popup on activation.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-haspopup
+ */
+const HASPOPUP_VALUES = new Set(['true', 'menu', 'listbox', 'tree', 'grid', 'dialog']);
+
+/**
+ * Whether an element is a popup trigger — a combobox or any control that
+ * advertises `aria-haspopup`. Such controls activate their popup on *click*
+ * (e.g. DateInput's `<input type="text" role="combobox" aria-haspopup="dialog">`
+ * opens its calendar via `onClick`, with no `onFocus` opener). Forwarding a
+ * container click to `.focus()` would focus the control but leave the popup
+ * closed — so we `.click()` these instead. Plain text inputs (no popup) are
+ * unaffected and keep `.focus()`.
+ */
+function isPopupTrigger(el) {
+  if (el.getAttribute('role') === 'combobox') {
+    return true;
+  }
+  const haspopup = el.getAttribute('aria-haspopup');
+  return haspopup != null && HASPOPUP_VALUES.has(haspopup);
+}
 /**
  * Hook that makes an input container wrapper clickable, delegating focus
  * to the inner input/textarea when the user clicks non-interactive areas
@@ -57,7 +80,12 @@ export function useInputContainer({
     if (input == null) {
       return;
     }
-    if (input instanceof HTMLInputElement && FOCUS_INPUT_TYPES.has(input.type)) {
+    // Popup triggers (combobox / aria-haspopup) activate their popup on
+    // *click*, not focus — so check this BEFORE the type check, otherwise a
+    // `type="text"` combobox (DateInput) would `.focus()` and never open.
+    if (input instanceof HTMLElement && isPopupTrigger(input)) {
+      input.click();
+    } else if (input instanceof HTMLInputElement && FOCUS_INPUT_TYPES.has(input.type)) {
       input.focus();
     } else if (input instanceof HTMLTextAreaElement) {
       input.focus();

package/dist/hooks/useInputStatusIcon.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import { type IconSize } from '../Icon';
+import type { FieldStatusVariant } from '../FieldStatus/FieldStatus';
+import type { InputStatus } from '../Field/types';
+export interface UseInputStatusIconOptions {
+    /** The input's status, or undefined when there is none. */
+    status?: InputStatus;
+    /** How the status is presented relative to the input. */
+    statusVariant?: FieldStatusVariant;
+    /** Whether the input is inside an InputGroup (which owns status rendering). */
+    isInGroup?: boolean;
+    /** Size of the on-field icon. @default 'md' */
+    size?: IconSize;
+}
+export interface UseInputStatusIconReturn {
+    /**
+     * The on-field status affordance to render inside the input container —
+     * the status icon (plain, for attached) or a focusable info-tip button plus
+     * its tooltip layer (for the `tooltip` variant). `null` when no icon should
+     * render (no status, `detached` variant, or inside a group).
+     */
+    statusIcon: ReactNode;
+    /**
+     * ID to add to the input's `aria-describedby` when — and only when — the
+     * status is surfaced through a rendered tooltip layer (the `tooltip` variant
+     * with a message). It is `undefined` in every other case (no status, no
+     * message, `attached`/`detached`, or inside a group), so call-sites can drop
+     * it straight into their described-by list without a dangling reference: the
+     * id is present exactly when its tooltip element is in the DOM.
+     */
+    describedBy: string | undefined;
+}
+/**
+ * Builds the on-field status icon and its accessibility wiring for a bordered
+ * input. See the file header for the per-variant behavior.
+ */
+export declare function useInputStatusIcon({ status, statusVariant, isInGroup, size, }: UseInputStatusIconOptions): UseInputStatusIconReturn;
+//# sourceMappingURL=useInputStatusIcon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAuDjE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CAqGtD"}