@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/useDevWarning.js

@@ -6,14 +6,9 @@
  * @file useDevWarning.ts
  * @input A component name, a message, and a boolean condition
  * @output Fires a dev-only `Component: message` warning once per mount
- * @position Core hook; the render-safe way to warn the builder from a component
- *
- * The right way to surface a dev guardrail from inside a component. A naive
- * `if (condition) console.warn(...)` in the render body repeats on every
- * render, and reaching for `useState` to gate it adds needless state and
- * re-renders. This hook uses a ref + effect: the warning fires once per mount
- * when the condition holds, never during render, and never triggers a
- * re-render. Messages use the standardized `Component: message` format.
+ * @position Core hook; the render-safe way to warn the builder from a component.
+ *   A ref and an effect fire the warning once per mount, never during
+ *   render, and without a re-render.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts

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

@@ -1 +1 @@
-{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgFnD,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAMrB"}
+{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgFnD,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAMrB"}

package/dist/hooks/useEntryAnimation.js

@@ -8,9 +8,7 @@
  * @output Exports useEntryAnimation hook for mount-only entry animations
  * @position Hook utility; consumed by FieldStatus and available to consumers
  *
- * Provides entry animations for conditionally rendered elements.
- * Only animates when the element is dynamically mounted after the initial
- * page paint — statically rendered elements on page load are not animated.
+ * It animates only an element that mounts after the first page paint.
  * Server-rendered elements hydrate without the entry style and never play it
  * (spec:AST-013 FR13).
  */

package/dist/hooks/useFocusReturnVisibility.d.ts

@@ -1,4 +1,11 @@
-export declare function useFocusReturnVisibility(): {
+import type { InteractionModalityTracking } from '../utils/interactionModality.js';
+/**
+ * Pass the component's one modality tracking (its `ref` attached to the
+ * overlay's element or trigger) so the ring follows the last input in that
+ * element's own document (a same-origin iframe, a Document Picture-in-Picture
+ * window), not the page's.
+ */
+export declare function useFocusReturnVisibility({ readModality, }: Pick<InteractionModalityTracking, 'readModality'>): {
     isFocusRingSuppressed: boolean;
     onFocusReturnTargetFocus: () => void;
     prepareFocusReturn: () => void;

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

@@ -1 +1 @@
-{"version":3,"file":"useFocusReturnVisibility.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusReturnVisibility.ts"],"names":[],"mappings":"AAiBA,wBAAgB,wBAAwB;;;;;EAyBvC"}
+{"version":3,"file":"useFocusReturnVisibility.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusReturnVisibility.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,8BAA8B,CAAC;AAE9E;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,YAAY,GACb,EAAE,IAAI,CAAC,2BAA2B,EAAE,cAAc,CAAC;;;;;EAuBnD"}

package/dist/hooks/useFocusReturnVisibility.js

@@ -4,26 +4,32 @@
 
 /**
  * @file useFocusReturnVisibility.ts
- * @input Uses the shared interaction-modality tracker
+ * @input The component's shared interaction-modality tracking
  * @output Preserves returned focus while suppressing pointer-only focus rings
  * @position Internal focus-return policy for adaptive overlays
  */
 import { useCallback, useState } from 'react';
-import { getInteractionModality, useInteractionModalityTracking } from "../utils/interactionModality.js";
-export function useFocusReturnVisibility() {
+/**
+ * Pass the component's one modality tracking (its `ref` attached to the
+ * overlay's element or trigger) so the ring follows the last input in that
+ * element's own document (a same-origin iframe, a Document Picture-in-Picture
+ * window), not the page's.
+ */
+export function useFocusReturnVisibility({
+  readModality
+}) {
   const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
-  useInteractionModalityTracking();
   const prepareFocusReturn = useCallback(() => {
-    setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
-  }, []);
+    setIsFocusRingSuppressed(readModality() === 'pointer');
+  }, [readModality]);
   const resetFocusReturn = useCallback(() => {
     setIsFocusRingSuppressed(false);
   }, []);
   const onFocusReturnTargetFocus = useCallback(() => {
-    if (getInteractionModality() === 'keyboard') {
+    if (readModality() === 'keyboard') {
       setIsFocusRingSuppressed(false);
     }
-  }, []);
+  }, [readModality]);
   return {
     isFocusRingSuppressed,
     onFocusReturnTargetFocus,

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

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CA8QvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAuQvB"}

package/dist/hooks/useFocusTrap.js

@@ -16,6 +16,7 @@
  * - /packages/core/src/hooks/index.ts
  */
 import { useCallback, useEffect, useRef } from 'react';
+import { isFocusLost } from "../utils/focusReturn.js";
 import { FOCUSABLE_SELECTOR } from "./focusableSelector.js";
 import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 
@@ -291,9 +292,7 @@ export function useFocusTrap(options) {
       if (!hadFocusInside) {
         return;
       }
-      const active = doc.activeElement;
-      const focusWasLost = active == null || active === doc.body || active === doc.documentElement || container != null && container.contains(active);
-      if (!focusWasLost) {
+      if (!isFocusLost(container, doc)) {
         return;
       }
       if (previouslyFocused != null && previouslyFocused.isConnected && typeof previouslyFocused.focus === 'function') {

package/dist/hooks/useHighlightedOptionScroll.d.ts

@@ -5,9 +5,7 @@ interface UseHighlightedOptionScrollOptions {
     getOptionId: (index: number) => string;
     /**
      * Current option count, when the list can change while open (filtered or
-     * min/max-clamped lists). A count change re-runs the scroll, matching the
-     * list-length dependency the per-component effects carried before this hook
-     * existed.
+     * min/max-clamped lists). A count change runs the scroll again.
      */
     itemCount?: number;
 }
@@ -15,7 +13,7 @@ interface UseHighlightedOptionScrollOptions {
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
  * option under the stationary pointer, whose mouseenter re-highlights and
- * scrolls again — a runaway auto-scroll loop with no user input (#6077).
+ * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"useHighlightedOptionScroll.d.ts","sourceRoot":"","sources":["../../src/hooks/useHighlightedOptionScroll.ts"],"names":[],"mappings":"AAiBA,UAAU,iCAAiC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,SAAS,GACV,EAAE,iCAAiC,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CA2B7D"}
+{"version":3,"file":"useHighlightedOptionScroll.d.ts","sourceRoot":"","sources":["../../src/hooks/useHighlightedOptionScroll.ts"],"names":[],"mappings":"AAiBA,UAAU,iCAAiC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,SAAS,GACV,EAAE,iCAAiC,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CA2B7D"}

package/dist/hooks/useHighlightedOptionScroll.js

@@ -17,7 +17,7 @@ import { useCallback, useEffect, useRef } from 'react';
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
  * option under the stationary pointer, whose mouseenter re-highlights and
- * scrolls again — a runaway auto-scroll loop with no user input (#6077).
+ * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"useHotkeys.d.ts","sourceRoot":"","sources":["../../src/hooks/useHotkeys.ts"],"names":[],"mappings":"AAgCA;;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;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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":"AAoBA;;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;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAkClD"}

package/dist/hooks/useHotkeys.js

@@ -4,22 +4,10 @@
 
 /**
  * @file useHotkeys.ts
- * @input Uses React useEffect, useRef
- * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts
- * @position Core hook; used by consumers for app-level keyboard shortcuts
- *
- * Registers a single window keydown listener per hook instance. Handlers
- * are kept in a ref so re-renders never re-subscribe (subscribe once on
- * mount, unsubscribe on unmount). SSR-safe — window is only touched
- * inside the effect.
- *
- * Skips events that are already handled (defaultPrevented) or during IME composition,
- * and events targeting typing surfaces (input, textarea, select, contenteditable)
- * unless a hotkey opts in via `allowInInputs`.
- *
- * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
- * ctrlKey elsewhere, through the same isApplePlatform util Kbd reads, so
- * displayed and handled shortcuts cannot disagree.
+ * @input React effects and refs
+ * @output useHotkeys hook and Hotkey interface for global keyboard shortcuts
+ * @position Core hook for app-level keyboard shortcuts. `mod` uses the same
+ *   isApplePlatform util as Kbd, so shown and handled shortcuts agree.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts

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

@@ -1 +1 @@
-{"version":3,"file":"useImageMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useImageMode.ts"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,CAAC,EAAE,MAAM,CAAC;IACV,qCAAqC;IACrC,CAAC,EAAE,MAAM,CAAC;IACV,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACpC;AAsBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,OAAO,GAAG,IAAI,CA4FzB"}
+{"version":3,"file":"useImageMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useImageMode.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,CAAC,EAAE,MAAM,CAAC;IACV,qCAAqC;IACrC,CAAC,EAAE,MAAM,CAAC;IACV,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACpC;AAaD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,OAAO,GAAG,IAAI,CAyFzB"}

package/dist/hooks/useImageMode.js

@@ -7,31 +7,6 @@
  * @input Image source URL
  * @output Detected mode luminance: 'dark' | 'light' | null
  * @position Hook; used alongside MediaTheme for auto-detection
- *
- * Detects whether an image is predominantly dark or light by sampling
- * its pixels via OffscreenCanvas. Runs entirely off the paint path —
- * no visible canvas element, no layout thrash.
- *
- * Uses APCA perceptual lightness (sRGB linearization + power curve)
- * which handles saturated colors better than BT.709 gamma-luma or
- * WCAG 2 relative luminance.
- *
- * For regional detection (e.g. "what's the luminance where the text
- * overlay sits"), pass a `region` option to sample a specific area.
- *
- * @example
- * ```tsx
- * function ImageCard({ src }: { src: string }) {
- *   const mode = useImageMode(src);
- *   return (
- *     <div style={{ backgroundImage: `url(${src})` }}>
- *       <MediaTheme mode={mode ?? 'dark'}>
- *         <Text>Auto-detected text color</Text>
- *       </MediaTheme>
- *     </div>
- *   );
- * }
- * ```
  */
 import { useState, useEffect } from 'react';
 
@@ -42,18 +17,9 @@ import { useState, useEffect } from 'react';
  */
 
 /**
- * APCA perceptual lightness from sRGB values (0-255).
- *
- * Linearizes sRGB with a 2.4 exponent, computes luminance Y using
- * APCA coefficients (slightly refined from BT.709), then applies a
- * perceptual power curve (Y^0.56) that maps linear light to a scale
- * where 0.5 ≈ perceptual mid-gray.
- *
- * This outperforms both raw BT.709 gamma-luma and WCAG 2 relative
- * luminance for dark/light surface detection — especially on saturated
- * colors (reds, blues) where gamma-encoded luma overestimates brightness.
- *
- * Returns 0–1 where 0 is black, 1 is white.
+ * APCA perceptual lightness from sRGB values (0-255), from 0 (black) to 1
+ * (white). It handles saturated colors better than BT.709 gamma-luma or WCAG
+ * 2 relative luminance, which overestimate the brightness of reds and blues.
  */
 function perceptualLightness(r, g, b) {
   const lin = c => Math.pow(c / 255, 2.4);
@@ -82,7 +48,6 @@ export function useImageMode(src, options = {}) {
     let cancelled = false;
     async function detect() {
       try {
-        // Load image as bitmap (async, doesn't block rendering)
         const response = await fetch(srcUrl, {
           mode: 'cors'
         });
@@ -91,16 +56,14 @@ export function useImageMode(src, options = {}) {
         if (cancelled) {
           return;
         }
-
-        // Determine source region
         const sx = region ? Math.round(region.x * bitmap.width) : 0;
         const sy = region ? Math.round(region.y * bitmap.height) : 0;
         const sw = region ? Math.round(region.width * bitmap.width) : bitmap.width;
         const sh = region ? Math.round(region.height * bitmap.height) : bitmap.height;
 
-        // Sample at a small size and average all pixels manually.
-        // OffscreenCanvas 1×1 drawImage can produce inaccurate results
-        // depending on the browser's resampling algorithm.
+        // Sample at a small size and average the pixels here. A 1×1
+        // OffscreenCanvas drawImage can be inaccurate, because browsers
+        // resample in different ways.
         const sampleSize = 10;
         const canvas = new OffscreenCanvas(sampleSize, sampleSize);
         const ctx = canvas.getContext('2d');
@@ -109,8 +72,6 @@ export function useImageMode(src, options = {}) {
         }
         ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, sampleSize, sampleSize);
         const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize).data;
-
-        // Average all sampled pixels
         let totalR = 0,
           totalG = 0,
           totalB = 0;

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

@@ -1 +1 @@
-{"version":3,"file":"useIndicatorFocusRing.d.ts","sourceRoot":"","sources":["../../src/hooks/useIndicatorFocusRing.tsx"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAMjD,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,UAAU,EAAE;QACV,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAClD,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAC3C,UAAU,UAAQ,GACjB,2BAA2B,CAkC7B"}
+{"version":3,"file":"useIndicatorFocusRing.d.ts","sourceRoot":"","sources":["../../src/hooks/useIndicatorFocusRing.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAMjD,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,UAAU,EAAE;QACV,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAClD,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAC3C,UAAU,UAAQ,GACjB,2BAA2B,CAiC7B"}

package/dist/hooks/useIndicatorFocusRing.js

@@ -10,42 +10,18 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (exports)
- *
- * A checkbox or radio focuses a native `<input>` that is `opacity: 0`, so the
- * visible focus indicator has to appear on the picture beside it — and that
- * picture is a themeable indicator, which is what makes "who draws the ring"
- * awkward:
- *
- * - Only the indicator's own element can shape the ring: `outline` follows
- *   that element's `border-radius`. Draw it on a wrapper and the owner has to
- *   hardcode a guess about whatever indicator it hosts (RadioListItem used to
- *   carry `border-radius: 50%` for a circle it did not own).
- * - But an indicator supplied by a theme is third-party code. If drawing the
- *   ring is its job, a replacement that simply doesn't ships a control with no
- *   visible focus (WCAG 2.4.7) — and that is the DEFAULT outcome: the sample
- *   replacement in our own Storybook destructures `{state, size, isDisabled}`
- *   and drops the rest, which is what a theme author plausibly writes. Nothing
- *   can enforce otherwise; a component ignoring every prop is still assignable
- *   to `IndicatorComponent`, and branding the return type does not work either
- *   (JSX types every expression as `JSX.Element`).
- *
- * So the owner draws it, on the indicator's own element, imperatively at focus
- * time. No cooperation is required and none can be forgotten.
- *
- * Two details that are load-bearing, both measured rather than assumed:
- *
- * 1. **Inline style, not a class.** React replaces `className` wholesale on
- *    re-render, so an injected class disappears the moment the control changes
- *    state — pressing Space on a focused checkbox lost the ring. React
- *    reconciles `style` per property, so an `outline` set here survives.
- * 2. **`:focus-visible`, not `:focus`.** The CSS this replaces got
- *    keyboard-vs-pointer for free; an event handler has to ask. Checking the
- *    element keeps the browser's heuristic, including `focus({focusVisible:
- *    true})`, which a hand-rolled modality guess would miss.
- *
- * Imperative styling on an interaction event follows `useTableSelection`,
- * which sets row-selection styles the same way.
  */
+
+// The owner draws the ring on the indicator's own element, at focus time:
+// - Only that element can shape the ring, because `outline` follows its
+//   `border-radius`.
+// - A theme can replace the indicator, and a replacement can drop any prop.
+//   If the indicator drew the ring, such a replacement would have no visible
+//   focus. No type can make it keep the props.
+// - The ring is an inline style, not a class. React replaces `className` on
+//   re-render, but it updates `style` per property, so the outline stays.
+// - The handler checks `:focus-visible`, not focus. This keeps the browser's
+//   heuristic, including `focus({focusVisible: true})`.
 import { useCallback, useMemo } from 'react';
 import { FOCUS_OUTLINE_PARTS, FOCUS_OUTLINE_PARTS_NONE } from "../utils/focusOutline.stylex.js";
 /**
@@ -68,9 +44,8 @@ import { FOCUS_OUTLINE_PARTS, FOCUS_OUTLINE_PARTS_NONE } from "../utils/focusOut
  */
 export function useIndicatorFocusRing(containerRef, isDisabled = false) {
   const paint = useCallback(on => {
-    // `firstElementChild`, not a search: the container holds the indicator
-    // and nothing else, so there is no ambiguity — and no way for a later
-    // sibling to quietly become the target.
+    // The container holds only the indicator, so its first child is the
+    // target. A later sibling can never become the target.
     const indicator = containerRef.current?.firstElementChild;
     if (indicator instanceof HTMLElement) {
       Object.assign(indicator.style, on ? FOCUS_OUTLINE_PARTS : FOCUS_OUTLINE_PARTS_NONE);

package/dist/hooks/useInputStatusIcon.d.ts

@@ -1,12 +1,12 @@
 import type { ReactNode } from 'react';
 import { type IconSize } from '../Icon/index.js';
-import type { FieldStatusVariant } from '../FieldStatus/FieldStatus.js';
 import type { InputStatus } from '../Field/types.js';
+import type { FieldStatusPlacement } from '../Field/fieldStatusPlacement.js';
 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;
+    statusVariant?: FieldStatusPlacement;
     /** Whether the input is inside an InputGroup (which owns status rendering). */
     isInGroup?: boolean;
     /** Size of the on-field icon. @default 'md' */
@@ -32,7 +32,15 @@ export interface UseInputStatusIconReturn {
 }
 /**
  * Builds the on-field status icon and its accessibility wiring for a bordered
- * input. See the file header for the per-variant behavior.
+ * input, so every bordered input shows status the same way:
+ * - `attached`: the icon is in the control, and the message box below has
+ *   the text.
+ * - `detached`: the message box shows its own leading icon, so this hook
+ *   shows none.
+ * - `tooltip`: no message box. The icon is a focusable `<button>` with an
+ *   info-tip, so every user can reach the status. Focus or a fine-pointer
+ *   hover opens it, and a tap toggles it on touch. Its accessible name is the
+ *   status type, and the message describes it. Escape dismisses it.
  */
 export declare function useInputStatusIcon({ status, statusVariant, isInGroup, size, }: UseInputStatusIconOptions): UseInputStatusIconReturn;
 //# sourceMappingURL=useInputStatusIcon.d.ts.map

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

@@ -1 +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;AA+DjE,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,CAwGtD"}
+{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAKjE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,+BAA+B,CAAC;AA8DxE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,+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;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CAoGtD"}

package/dist/hooks/useInputStatusIcon.js

@@ -10,42 +10,24 @@
  *
  * 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 { radiusVars } from "../theme/tokens.stylex.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineStyles } from "../utils/focusOutline.stylex.js";
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/hooks/useInputStatusIcon.generated.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+registerEnglishFallback(english);
 
 /**
  * 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',
@@ -80,7 +62,15 @@ const styles = {
 };
 /**
  * Builds the on-field status icon and its accessibility wiring for a bordered
- * input. See the file header for the per-variant behavior.
+ * input, so every bordered input shows status the same way:
+ * - `attached`: the icon is in the control, and the message box below has
+ *   the text.
+ * - `detached`: the message box shows its own leading icon, so this hook
+ *   shows none.
+ * - `tooltip`: no message box. The icon is a focusable `<button>` with an
+ *   info-tip, so every user can reach the status. Focus or a fine-pointer
+ *   hover opens it, and a tap toggles it on touch. Its accessible name is the
+ *   status type, and the message describes it. Escape dismisses it.
  */
 export function useInputStatusIcon({
   status,
@@ -88,7 +78,7 @@ export function useInputStatusIcon({
   isInGroup = false,
   size = 'md'
 }) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const isTooltipVariant = statusVariant === 'tooltip';
   const hasTooltip = isTooltipVariant && !!status?.message;
 
@@ -103,9 +93,8 @@ export function useInputStatusIcon({
     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.
+  // Give control back to hover and focus after a tap-opened tooltip is
+  // dismissed.
   const handleButtonBlur = useCallback(() => {
     setTapOpen(undefined);
   }, []);
@@ -119,9 +108,8 @@ export function useInputStatusIcon({
     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).
+  // Escape dismisses a tap-opened tooltip and returns to the uncontrolled
+  // state. useTooltip handles Escape only when it is uncontrolled.
   useEffect(() => {
     if (tapOpen !== true) {
       return;
@@ -148,11 +136,9 @@ export function useInputStatusIcon({
     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.
+    // A stable theme target on the glyph, so a theme can restyle this icon
+    // for each status. Same-element rules in @layer astryx-theme override
+    // the icon's base size, which a field-level target cannot reach.
     ,
     ...themeProps('input-status-icon', {
       size,

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

@@ -1 +1 @@
-{"version":3,"file":"useInteractiveRole.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteractiveRole.ts"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEjD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,OAAO,EACP,UAAkB,GACnB,EAAE,yBAAyB,GAAG,eAAe,CAqB7C"}
+{"version":3,"file":"useInteractiveRole.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteractiveRole.ts"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEjD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,OAAO,EACP,UAAkB,GACnB,EAAE,yBAAyB,GAAG,eAAe,CAkB7C"}

package/dist/hooks/useInteractiveRole.js

@@ -4,24 +4,11 @@
 
 /**
  * @file useInteractiveRole.ts
- * @input Uses useInteractiveTrigger
- * @output Exports useInteractiveRole hook and InteractiveRole type
- * @position Hook utility; consumed by Token, Thumbnail, Item, ClickableCard, etc.
- *
- * Centralizes the "what element should I render as?" decision for
- * polymorphic components. The priority order:
- *
- *   1. href → 'link' (navigation always wins, unless disabled)
- *   2. onClick → 'button' (explicit interactivity)
- *   3. interactive trigger context → 'button' (implicit via parent)
- *   4. else → 'inert' (non-interactive)
- *
- * A disabled `href` is excluded at step 1 and therefore resolves via the
- * remaining steps — 'inert' when no onClick or context applies.
- *
- * This hook is the single place to add new context-based triggers
- * (e.g., Popover, DropdownMenu, Disclosure). Components that consume
- * this hook never need updating when new trigger contexts are added.
+ * @input useInteractiveTrigger
+ * @output useInteractiveRole hook and InteractiveRole type
+ * @position Hook utility for polymorphic components such as Token, Thumbnail,
+ *   Item and ClickableCard. Add new context-based triggers here, so the
+ *   components that use this hook need no change.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -63,13 +50,10 @@ export function useInteractiveRole({
 }) {
   const contextRole = useInteractiveRoleContext();
 
-  // 1. href → link (unless disabled — a disabled href is skipped here and
-  // resolved by the checks below, landing on 'inert' if nothing else applies)
+  // A disabled href is skipped, so the checks below decide the role.
   if (href != null && !isDisabled) {
     return 'link';
   }
-
-  // 2. Explicit onClick → button
   if (onClick != null) {
     return 'button';
   }
@@ -78,7 +62,5 @@ export function useInteractiveRole({
   if (contextRole != null) {
     return contextRole;
   }
-
-  // 4. Nothing interactive → inert
   return 'inert';
 }

package/dist/hooks/useKeyboardHint.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useComponentTranslator)
  * @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)

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;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;AAmED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAgKvB"}
+{"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;AAuB5E,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;AAmED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAsKvB"}