@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/dist/hooks/containerReveal.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"containerReveal.stylex.d.ts","sourceRoot":"","sources":["../../src/hooks/containerReveal.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2MjB,CAAC"}
+{"version":3,"file":"containerReveal.stylex.d.ts","sourceRoot":"","sources":["../../src/hooks/containerReveal.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+OjB,CAAC"}

package/dist/hooks/containerReveal.stylex.js

@@ -29,30 +29,30 @@ const HOVER_DELAY = 'var(--_hover-delay, 0s)';
 export const styles = {
   container: {
     "--_hover-delay": "xhg274n",
-    "--_reveal-opacity": "xct0gwe x1wblmmc xi33vf3 xi7d7de",
-    "--_reveal-position": "xp0pj8v x106rhu xoa21yc xarvkxi",
-    "--_reveal-delay": "x1xiarpw x1qamfbu x1mjsb9v x1pn63d7",
-    "--_reveal-delay-reduced": "xdjmrzf x1g1w2pt x1z42dm xm1aeao",
-    "--_conceal-opacity": "x1kgmhs9 xb9fdgj",
-    "--_fade-delay": "x13l1x9d x1ho7nxo x1wfyzv7 x1hl81f0",
+    "--_reveal-opacity": "xct0gwe x2xrgwu xi33vf3 xi7d7de",
+    "--_reveal-position": "xp0pj8v x1or4zte xoa21yc xarvkxi",
+    "--_reveal-delay": "x1xiarpw xi1ebb6 x1mjsb9v x1pn63d7",
+    "--_reveal-delay-reduced": "xdjmrzf xvd8mm8 x1z42dm xm1aeao",
+    "--_conceal-opacity": "x1kgmhs9 x1316hva",
+    "--_fade-delay": "x13l1x9d x14nxqze x1wfyzv7 x1hl81f0",
     $$css: true
   },
   stateInactive: {
-    "--_reveal-opacity": "xct0gwe xichi0p xi33vf3 xi7d7de",
-    "--_reveal-position": "xp0pj8v x1sacq21 xoa21yc xarvkxi",
-    "--_reveal-delay": "x1xiarpw x619wqp x1mjsb9v x1pn63d7",
-    "--_reveal-delay-reduced": "xdjmrzf xfu6dsl x1z42dm xm1aeao",
-    "--_conceal-opacity": "x1kgmhs9 xflzsy",
-    "--_fade-delay": "x13l1x9d x3tau1w x1wfyzv7 x1hl81f0",
+    "--_reveal-opacity": "xct0gwe xfqgg65 xi33vf3 xi7d7de",
+    "--_reveal-position": "xp0pj8v x17ock8y xoa21yc xarvkxi",
+    "--_reveal-delay": "x1xiarpw x1tx49wl x1mjsb9v x1pn63d7",
+    "--_reveal-delay-reduced": "xdjmrzf xap96qf x1z42dm xm1aeao",
+    "--_conceal-opacity": "x1kgmhs9 xuzfaso",
+    "--_fade-delay": "x13l1x9d xq03417 x1wfyzv7 x1hl81f0",
     $$css: true
   },
   stateActive: {
-    "--_reveal-opacity": "x5setjs x1wblmmc xi33vf3 xi7d7de",
-    "--_reveal-position": "x1r6s5ct x106rhu xoa21yc xarvkxi",
-    "--_reveal-delay": "x1dejzja xp1dr9k x1mjsb9v x1pn63d7",
-    "--_reveal-delay-reduced": "xdjmrzf xfu6dsl x1z42dm xm1aeao",
-    "--_conceal-opacity": "x9pmotm xb9fdgj",
-    "--_fade-delay": "x13l1x9d x3tau1w x1wfyzv7 x1hl81f0",
+    "--_reveal-opacity": "x5setjs x2xrgwu xi33vf3 xi7d7de",
+    "--_reveal-position": "x1r6s5ct x1or4zte xoa21yc xarvkxi",
+    "--_reveal-delay": "x1dejzja x1t6fdr0 x1mjsb9v x1pn63d7",
+    "--_reveal-delay-reduced": "xdjmrzf xap96qf x1z42dm xm1aeao",
+    "--_conceal-opacity": "x9pmotm x1316hva",
+    "--_fade-delay": "x13l1x9d xq03417 x1wfyzv7 x1hl81f0",
     $$css: true
   },
   hoverDelay: delay => [{

package/dist/hooks/scrollbarGutter.d.ts

@@ -0,0 +1,28 @@
+export interface ScrollbarGutterHold {
+    /**
+     * Call once the lock's own styles are applied: measures whether the element
+     * grew anyway and, only then, pads the difference away.
+     */
+    settle(): void;
+    /** Call on unlock: restores everything this hold changed. */
+    release(): void;
+}
+/**
+ * Keeps `element`'s content box the width it is right now, across a scroll
+ * lock that is about to hide the document's scrollbar.
+ *
+ * Call it *before* applying the lock's styles, then {@link
+ * ScrollbarGutterHold.settle} immediately after, and {@link
+ * ScrollbarGutterHold.release} on unlock:
+ *
+ * ```
+ * const hold = holdScrollbarGutter(document.body);
+ * body.style.position = 'fixed';
+ * hold.settle();
+ * ```
+ *
+ * Overlay scrollbars (mobile, default macOS) take no layout space, so there is
+ * nothing to hold and nothing is touched.
+ */
+export declare function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold;
+//# sourceMappingURL=scrollbarGutter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CA+D7E"}

package/dist/hooks/scrollbarGutter.js

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollbarGutter.ts
+ * @input The element a scroll lock pins, plus live layout measurements
+ * @output Exports holdScrollbarGutter and the ScrollbarGutterHold it returns
+ * @position Internal hook utility; used by useScrollLock and MobileNav so that
+ *   locking background scroll does not resize the layout viewport.
+ *
+ * Locking scroll hides the document's scrollbar. Where that scrollbar is a
+ * classic (space-taking) one — Windows/Linux desktop, and macOS set to
+ * "Always" show scroll bars — hiding it widens the layout viewport by the
+ * scrollbar's width and the whole page jumps sideways behind the overlay.
+ *
+ * The fix is `scrollbar-gutter: stable`, which holds the gutter open once the
+ * scrollbar goes away. Being a real layout change it holds `position: fixed`
+ * chrome (sticky headers, toast viewports) as well as in-flow content, which
+ * padding fundamentally cannot: fixed elements resolve against the viewport,
+ * not against the padded element.
+ *
+ * Padding is kept only as a fallback for engines without `scrollbar-gutter`
+ * (Safari shipped it in 18.2), and it is applied by measuring whether the
+ * element actually moved rather than by assuming it did.
+ */
+
+const NOOP = {
+  settle() {},
+  release() {}
+};
+/**
+ * Keeps `element`'s content box the width it is right now, across a scroll
+ * lock that is about to hide the document's scrollbar.
+ *
+ * Call it *before* applying the lock's styles, then {@link
+ * ScrollbarGutterHold.settle} immediately after, and {@link
+ * ScrollbarGutterHold.release} on unlock:
+ *
+ * ```
+ * const hold = holdScrollbarGutter(document.body);
+ * body.style.position = 'fixed';
+ * hold.settle();
+ * ```
+ *
+ * Overlay scrollbars (mobile, default macOS) take no layout space, so there is
+ * nothing to hold and nothing is touched.
+ */
+export function holdScrollbarGutter(element) {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return NOOP;
+  }
+  const root = document.documentElement;
+  const viewportWidth = root.clientWidth;
+
+  // 0 means "no layout to measure" (jsdom, and any non-visual environment),
+  // not "the scrollbar is as wide as the window".
+  if (viewportWidth === 0) {
+    return NOOP;
+  }
+  const previousGutter = root.style.scrollbarGutter;
+  const previousPadding = element.style.paddingRight;
+  const widthBefore = element.getBoundingClientRect().width;
+  let heldGutter = false;
+  let padded = false;
+  let settled = false;
+
+  // Only when a space-taking scrollbar is actually there. Holding the gutter
+  // open on a page that never had one would carve out 15px that was never
+  // reserved — the same shift, in the other direction.
+  if (window.innerWidth > viewportWidth) {
+    root.style.scrollbarGutter = 'stable';
+    heldGutter = true;
+  }
+  return {
+    settle() {
+      if (settled) {
+        return;
+      }
+      settled = true;
+
+      // What the lock actually did to this element, rather than what we
+      // assumed it would do. 0 on any engine where the gutter held — and on a
+      // page that already sets `scrollbar-gutter: stable` itself, where the
+      // scrollbar was never taking the space back.
+      const grew = element.getBoundingClientRect().width - widthBefore;
+      if (grew <= 0) {
+        return;
+      }
+      const existing = Number.parseFloat(window.getComputedStyle(element).paddingRight) || 0;
+      element.style.paddingRight = `${existing + grew}px`;
+      padded = true;
+    },
+    release() {
+      if (padded) {
+        element.style.paddingRight = previousPadding;
+        padded = false;
+      }
+      if (heldGutter) {
+        root.style.scrollbarGutter = previousGutter;
+        heldGutter = false;
+      }
+    }
+  };
+}

package/dist/hooks/useAutoMediaMode.d.ts

@@ -0,0 +1,31 @@
+import type { RefObject } from 'react';
+import type { RGBA } from '../utils/color';
+/** A surface luminance context, or `"off"` when no media context is wanted. */
+export type DetectedMediaMode = 'dark' | 'light' | 'off';
+/**
+ * Which media context a surface wants: `'off'` when its ambient text already
+ * reads on the surface, otherwise whichever on-color reads better. Pure — the
+ * DOM read is the caller's. Ties between the two sides go to dark, matching
+ * the convention that an inverted surface is usually the dark one.
+ *
+ * The `'off'` answer is the point of measuring at all. A surface that a theme
+ * calls inverted but paints pale does not want an inverted context; its own
+ * text is already correct for it, and forcing one is how white-on-pale-grey
+ * happens.
+ */
+export declare function pickMediaMode(background: RGBA, ambient: RGBA | null, onDark: RGBA | null, onLight: RGBA | null): DetectedMediaMode | null;
+/**
+ * Detect the media context for the element's surroundings.
+ *
+ * Measures `ref`'s PARENT, never `ref` itself: MediaTheme sets its media
+ * attribute on its own element, so measuring that would feed the decision
+ * back into its own input and let it oscillate. The parent owns the
+ * background and sits outside the media context, so both inputs stay
+ * independent of the result.
+ *
+ * Returns null until a measurement succeeds — on the server, before the
+ * layout effect runs, and whenever the backdrop is not knowable from CSS.
+ * The caller renders its fallback for those.
+ */
+export declare function useAutoMediaMode(ref: RefObject<HTMLElement | null>, isEnabled: boolean): DetectedMediaMode | null;
+//# sourceMappingURL=useAutoMediaMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAutoMediaMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useAutoMediaMode.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAMzC,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAqFzD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,IAAI,EAChB,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,OAAO,EAAE,IAAI,GAAG,IAAI,GACnB,iBAAiB,GAAG,IAAI,CAe1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CAsD1B"}

package/dist/hooks/useAutoMediaMode.js

@@ -0,0 +1,201 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAutoMediaMode.ts
+ * @input Ref to the element whose backdrop should be measured
+ * @output 'dark' | 'light' | null (not yet measurable)
+ * @position INTERNAL — powers `MediaTheme mode="auto"`. Not exported from the
+ *   package: MediaTheme is the supported surface for this behavior.
+ *   Sibling to useImageMode, which answers the same question for images.
+ *
+ * Picks the media context a surface wants by measuring what the browser
+ * actually painted, rather than trusting a token's name.
+ *
+ * The bug it exists for: `--color-background-inverted` is not required to be
+ * inverted. A theme can define it as a pale grey, and a hardcoded
+ * `mode="dark"` then paints white text on it at 1.25:1. Because the surface
+ * colour is a runtime value and the mode is a compile-time guess, no amount
+ * of care in the component can catch that.
+ *
+ * The answer can also be `'off'`: when the surface's own ambient text already
+ * reads on it, the surface is not effectively inverted and does not want a
+ * media context. Verified in Chromium that this loses nothing on a surface
+ * that is chromatic but legible — the dark-mode error toast renders
+ * identically either way, because a dark page already resolves those tokens
+ * to the values the media context would install.
+ *
+ * @example
+ * ```
+ * // Inside MediaTheme; see its `mode="auto"`.
+ * const detected = useAutoMediaMode(ref, mode === 'auto');
+ * ```
+ */
+import { useRef, useState } from 'react';
+import { parseColor, formatColor } from "../utils/color.js";
+import { contrastRatio, compositeOver } from "../theme/contrast.js";
+import { useTheme } from "../theme/useTheme.js";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+
+/** A surface luminance context, or `"off"` when no media context is wanted. */
+
+/**
+ * Resolve token references to the colors they actually paint, by reading them
+ * back off a hidden probe.
+ *
+ * A custom property cannot simply be read: `getPropertyValue` returns the
+ * token's *specified* text, and Astryx tokens are `light-dark(a, b)` pairs
+ * that resolve only once used in a real property. The probe assigns each
+ * token to `color` and reads the computed value back, which the browser has
+ * resolved against the host's own color-scheme and any overrides.
+ *
+ * `display: none` keeps the probe out of layout — computed color still
+ * resolves — so this costs a style recalc and no reflow.
+ */
+function resolvePaintedColors(host, tokens) {
+  const probe = document.createElement('span');
+  probe.style.display = 'none';
+  host.appendChild(probe);
+  try {
+    return tokens.map(token => {
+      probe.style.color = `var(${token})`;
+      return parseColor(getComputedStyle(probe).color);
+    });
+  } finally {
+    probe.remove();
+  }
+}
+
+/**
+ * The color actually behind an element: its own background if opaque,
+ * otherwise its translucent layers composited down onto the first opaque
+ * ancestor.
+ *
+ * Returns null when the paint is not knowable from CSS:
+ * - a `background-image` (gradient, photo, video poster) anywhere in the
+ *   chain — its pixels need sampling, which is `useImageMode`'s job and
+ *   needs CORS access the stylesheet cannot give us;
+ * - no opaque layer at all, where the paint is the browser canvas.
+ */
+function resolveBackdrop(element) {
+  const layers = [];
+  let node = element;
+  while (node !== null) {
+    const style = getComputedStyle(node);
+    if (style.backgroundImage !== 'none') {
+      return null;
+    }
+    const color = parseColor(style.backgroundColor);
+    if (color !== null && color.a > 0) {
+      layers.push(color);
+      if (color.a >= 1) {
+        break;
+      }
+    }
+    node = node.parentElement;
+  }
+  const base = layers.pop();
+  if (base === undefined || base.a < 1) {
+    return null;
+  }
+  // layers is now top-first; composite downward so the topmost lands last.
+  return layers.reduceRight((backdrop, layer) => compositeOver(layer, backdrop), base);
+}
+
+/**
+ * Contrast at which a surface's own ambient text counts as reading well
+ * enough that no media context is wanted.
+ *
+ * WCAG's non-text / large-text line. It is deliberately low: this decides
+ * whether a surface is *effectively inverted*, not whether its text meets a
+ * standard. A pairing that clears 3:1 is one the theme is rendering
+ * successfully, and swapping in a media context there changes accent,
+ * overlays and borders for no legibility gain.
+ */
+const AMBIENT_READS_AT = 3;
+
+/**
+ * Which media context a surface wants: `'off'` when its ambient text already
+ * reads on the surface, otherwise whichever on-color reads better. Pure — the
+ * DOM read is the caller's. Ties between the two sides go to dark, matching
+ * the convention that an inverted surface is usually the dark one.
+ *
+ * The `'off'` answer is the point of measuring at all. A surface that a theme
+ * calls inverted but paints pale does not want an inverted context; its own
+ * text is already correct for it, and forcing one is how white-on-pale-grey
+ * happens.
+ */
+export function pickMediaMode(background, ambient, onDark, onLight) {
+  if (onDark === null || onLight === null) {
+    return null;
+  }
+  if (ambient !== null && contrastRatio(ambient, background) >= AMBIENT_READS_AT) {
+    return 'off';
+  }
+  return contrastRatio(onDark, background) >= contrastRatio(onLight, background) ? 'dark' : 'light';
+}
+
+/**
+ * Detect the media context for the element's surroundings.
+ *
+ * Measures `ref`'s PARENT, never `ref` itself: MediaTheme sets its media
+ * attribute on its own element, so measuring that would feed the decision
+ * back into its own input and let it oscillate. The parent owns the
+ * background and sits outside the media context, so both inputs stay
+ * independent of the result.
+ *
+ * Returns null until a measurement succeeds — on the server, before the
+ * layout effect runs, and whenever the backdrop is not knowable from CSS.
+ * The caller renders its fallback for those.
+ */
+export function useAutoMediaMode(ref, isEnabled) {
+  const [detected, setDetected] = useState(null);
+  // `tokens` is a stable reference unless the theme or color mode changes.
+  const {
+    tokens
+  } = useTheme();
+  const lastRef = useRef(null);
+
+  // Deliberately no dependency array. A surface's color is a painted value:
+  // it changes when a prop on some ancestor changes, and no dependency this
+  // hook could name would catch that (an earlier revision took a `watch`
+  // array and silently went stale whenever a caller forgot an entry). So the
+  // measurement re-runs whenever anything re-renders, and skips its own
+  // expensive half when nothing moved — see the early return below.
+  useIsomorphicLayoutEffect(() => {
+    const surface = ref.current?.parentElement ?? null;
+    if (!isEnabled || surface === null) {
+      return;
+    }
+    const background = resolveBackdrop(surface);
+    if (background === null) {
+      return;
+    }
+
+    // The backdrop walk above is a couple of getComputedStyle reads; the
+    // probe below appends a node and forces another style resolution. Skip
+    // it when neither the painted backdrop nor the theme has moved, which is
+    // the overwhelmingly common render.
+    const backgroundKey = formatColor(background);
+    const last = lastRef.current;
+    if (last !== null && last.background === backgroundKey && last.tokens === tokens) {
+      return;
+    }
+    lastRef.current = {
+      background: backgroundKey,
+      tokens
+    };
+    const [ambient, onDark, onLight] = resolvePaintedColors(surface, ['--color-text-primary', '--color-on-dark', '--color-on-light']);
+    const next = pickMediaMode(background, ambient, onDark, onLight);
+    if (next === null) {
+      return;
+    }
+
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- the mode is derived from painted DOM colors
+    setDetected(current => current === next ? current : next);
+  });
+
+  // A disabled hook must not answer with a value measured while it was on.
+  return isEnabled ? detected : null;
+}

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;AA2DjE,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":"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;AA8DjE,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"}

package/dist/hooks/useInputStatusIcon.js

@@ -68,7 +68,7 @@ const styles = {
     kmVPX3: "x1717udv",
     kogj98: "x1ghz6dp",
     kMwMTN: "x1heor9g",
-    kkrTdU: "x1ypdohk",
+    kkrTdU: "x1ypdohk x16khyan",
     kfzvcC: "x67bb7w",
     kaIpWk: "xjspbzw",
     kInvED: "x7s97pk",

package/dist/hooks/useListFocus.d.ts

@@ -38,7 +38,9 @@ export interface UseListFocusOptions {
      */
     wrap?: boolean;
     /**
-     * Callback when Escape key is pressed.
+     * Callback when Escape key is pressed. Supplying it also makes the list
+     * consume the key (`preventDefault`); without it Escape passes through to
+     * the surrounding layer.
      */
     onEscape?: () => void;
     /**
@@ -144,7 +146,8 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook

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

@@ -1 +1 @@
-{"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;;;;;;;;;;;OAWG;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"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAwBA;;;;;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;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;OAWG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2VvB"}

package/dist/hooks/useListFocus.js

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useListFocus.doc.mjs
+ * - /packages/core/src/hooks/useListFocus.test.tsx
  */
 import { useCallback, useRef } from 'react';
 import { isRtlElement } from "./isRtlElement.js";
@@ -127,7 +129,8 @@ function shouldDeferToCaret(target, key) {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
@@ -380,12 +383,15 @@ export function useListFocus(options = {}) {
       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.
+    // Escape is handled regardless of orientation, but only *consumed* when
+    // a handler asked for it: a list with no dismissal to perform must leave
+    // the key to whatever host layer does have one, and those defer to
+    // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
     if (e.key === 'Escape') {
-      e.preventDefault();
-      onEscape?.();
+      if (onEscape) {
+        e.preventDefault();
+        onEscape();
+      }
       return;
     }
     const horizontal = orientation === 'horizontal' || orientation === 'both';

package/dist/hooks/useScrollLock.d.ts

@@ -6,6 +6,10 @@
  * does not prevent body scroll behind modals. Restores scroll position
  * on unlock.
  *
+ * Pinning also hides the document's scrollbar, so the gutter that scrollbar
+ * occupied is held open for the duration of the lock — without it the page
+ * reflows sideways by ~15px the moment an overlay opens.
+ *
  * @example
  * ```
  * useScrollLock(isOpen);

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

@@ -1 +1 @@
-{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollLock.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAiDrD"}
+{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollLock.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAwDrD"}

package/dist/hooks/useScrollLock.js

@@ -13,8 +13,10 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/scrollbarGutter.ts
  */
 import { useEffect } from 'react';
+import { holdScrollbarGutter } from "./scrollbarGutter.js";
 let lockCount = 0;
 let originalBodyState = null;
 
@@ -26,6 +28,10 @@ let originalBodyState = null;
  * does not prevent body scroll behind modals. Restores scroll position
  * on unlock.
  *
+ * Pinning also hides the document's scrollbar, so the gutter that scrollbar
+ * occupied is held open for the duration of the lock — without it the page
+ * reflows sideways by ~15px the moment an overlay opens.
+ *
  * @example
  * ```
  * useScrollLock(isOpen);
@@ -42,6 +48,9 @@ export function useScrollLock(isLocked) {
     if (lockCount === 0) {
       const scrollX = window.scrollX;
       const scrollY = window.scrollY;
+
+      // Taken before the pinning styles below hide the scrollbar.
+      const gutter = holdScrollbarGutter(body);
       originalBodyState = {
         scrollX,
         scrollY,
@@ -49,13 +58,15 @@ export function useScrollLock(isLocked) {
         position: body.style.position,
         top: body.style.top,
         left: body.style.left,
-        right: body.style.right
+        right: body.style.right,
+        gutter
       };
       body.style.overflow = 'hidden';
       body.style.position = 'fixed';
       body.style.top = `-${scrollY}px`;
       body.style.left = '0';
       body.style.right = '0';
+      gutter.settle();
     }
     lockCount += 1;
     return () => {
@@ -70,6 +81,7 @@ export function useScrollLock(isLocked) {
       body.style.top = state.top;
       body.style.left = state.left;
       body.style.right = state.right;
+      state.gutter.release();
       window.scrollTo(state.scrollX, state.scrollY);
     };
   }, [isLocked]);

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"InternationalizationContext.d.ts","sourceRoot":"","sources":["../../src/i18n/InternationalizationContext.ts"],"names":[],"mappings":"AAyBA,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

@@ -16,6 +16,8 @@
  * - /packages/core/src/i18n/InternationalizationProvider.tsx
  * - /packages/core/src/i18n/t.client.ts
  * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/useLocale.ts
+ * - /packages/core/src/i18n/useCollator.ts
  * - /packages/core/src/i18n/getLocaleDirection.ts
  * - /packages/core/src/i18n/index.ts
  */

package/dist/i18n/index.d.ts

@@ -8,12 +8,16 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useLocale                   — hook returning the provider locale
+ *   - useCollator                 — provider-bound locale-aware comparison
  *   - useDirection                — hook returning the ambient text direction
  *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useLocale.ts
+ * - /packages/core/src/i18n/useCollator.ts
  * - /packages/core/src/i18n/useDirection.ts
  * - /packages/core/src/i18n/getLocaleDirection.ts
  */
@@ -23,6 +27,8 @@ export { InternationalizationContext } from './InternationalizationContext';
 export type { InternationalizationContextValue } from './InternationalizationContext';
 export { useTranslator } from './useTranslator';
 export type { TranslatorFn } from './useTranslator';
+export { useLocale } from './useLocale';
+export { useCollator } from './useCollator';
 export { useDirection } from './useDirection';
 export { getLocaleDirection } from './getLocaleDirection';
 export type { Translator } from './translator';

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

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