@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/dist/Dialog/Dialog.js

@@ -8,6 +8,13 @@
  * @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
  * @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
  *
+ * The standard variant treats `width` as the preferred surface width, then
+ * clamps it to the dynamic viewport with spacing-token gutters so narrow
+ * viewports keep content and controls on screen without changing the public API.
+ * Fullscreen dialogs add safe-area protection to the default padding fallback
+ * while preserving explicit prop/theme padding overrides, and fade in without
+ * the centered-dialog translate/scale motion.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
@@ -18,18 +25,18 @@
 import { useCallback, useEffect, useId, useMemo, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { useScrollLock } from "../hooks/useScrollLock.js";
-import { hasActiveFocusTrapEscape } from "../hooks/useFocusTrap.js";
-import { isImeKeyEvent } from "../utils/ime.js";
+import { LayerDepthProvider } from "../Layer/LayerDepthContext.js";
+import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import "../theme/tokens.stylex.js";
-import { colorVars, radiusVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
+import { colorVars, radiusVars, durationVars, easeVars, shadowVars, spacingVars } from "../theme/tokens.stylex.js";
 import { container } from "../Layout/container.stylex.js";
 import { paddingStyles, containerPaddingInlineVarStyles, containerPaddingBlockStartVarStyles, containerPaddingBlockEndVarStyles, spacingStepToToken, overlayPaddingReset } from "../Layout/padding.stylex.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
 import { devWarn } from "../utils/devWarning.js";
 import { DialogContext } from "./DialogContext.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
-
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 /**
  * Calculate a directional translate offset for dialog entry animation.
  * Returns a normalized vector from the trigger element toward the viewport
@@ -72,6 +79,27 @@ function getDialogDirection(triggerEl, distance = 16) {
  */
 
 const enterDirectional = "x11lauxq-B";
+const enterFullscreen = "x18re5ia-B";
+const dialogFullscreenSafeAreaBlockStartPadding = `var(--astryx-dialog-padding-block-start, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))))`;
+const dialogFullscreenSafeAreaBlockEndPadding = `var(--astryx-dialog-padding-block-end, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingLtr = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingRtl = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingLtr = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingRtl = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+
+/** @internal Verified by Dialog.test.tsx; not re-exported from the package entry point. */
+export const dialogFullscreenSafeAreaPaddingContract = {
+  blockStart: dialogFullscreenSafeAreaBlockStartPadding,
+  blockEnd: dialogFullscreenSafeAreaBlockEndPadding,
+  inlineStart: {
+    ltr: dialogFullscreenSafeAreaInlineStartPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineStartPaddingRtl
+  },
+  inlineEnd: {
+    ltr: dialogFullscreenSafeAreaInlineEndPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineEndPaddingRtl
+  }
+};
 
 /**
  * Dialog styles using native <dialog> element
@@ -117,6 +145,17 @@ const styles = {
     kpwlN0: "x10a8y8t",
     $$css: true
   },
+  fullscreenOpen: {
+    kKVMdj: "xqcmdr3 x1aquc0h",
+    $$css: true
+  },
+  fullscreenSafeArea: {
+    kLKAdn: "x15ld1ci",
+    kGO01o: "x1rgxemn",
+    kZCmMZ: "xqmdmw x1i7f2ot",
+    kwRFfy: "x1by8st6 xtjjor6",
+    $$css: true
+  },
   inner: {
     k1xSpc: "x78zum5",
     kXwgrk: "xdt5ytf",
@@ -139,26 +178,35 @@ const styles = {
     $$css: true
   }
 };
-
-// Dynamic styles for width, maxHeight, and position
+const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
+const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;
+function formatSizeValue(value) {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+function resolveDialogSizing(width, maxHeight) {
+  return {
+    width: formatSizeValue(width),
+    maxWidth: STANDARD_DIALOG_MAX_WIDTH,
+    maxHeight: formatSizeValue(maxHeight)
+  };
+}
 const _temp = {
-  ks0D6T: "x95b5qq",
-  "$$css": true
-};
-const _temp2 = {
   kogj98: "x1ghz6dp",
   "$$css": true
 };
 const dynamicStyles = {
-  sizing: (width, maxHeight) => [_temp, {
-    kzqmXN: (typeof width === 'number' ? `${width}px` : width) != null ? "x5lhr3w" : typeof width === 'number' ? `${width}px` : width,
-    kskxy: (typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight) != null ? "x1jols5v" : typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
+  sizing: (width, maxWidth, maxHeight) => [{
+    kzqmXN: width != null ? "x5lhr3w" : width,
+    ks0D6T: maxWidth != null ? "xf68679" : maxWidth,
+    kskxy: maxHeight != null ? "x1jols5v" : maxHeight,
     $$css: true
   }, {
-    "--x-width": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(typeof width === 'number' ? `${width}px` : width),
-    "--x-maxHeight": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight)
+    "--x-width": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(width),
+    "--x-maxWidth": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(maxWidth),
+    "--x-maxHeight": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(maxHeight)
   }],
-  position: (top, insetInlineStart, insetInlineEnd, bottom) => [_temp2, {
+  position: (top, insetInlineStart, insetInlineEnd, bottom) => [_temp, {
     k87sOh: top != null ? "xjbys53" : top,
     kLqNvP: insetInlineStart != null ? "x1lxsm33" : insetInlineStart,
     kt4wiu: insetInlineEnd != null ? "xqxgn94" : insetInlineEnd,
@@ -230,7 +278,7 @@ export function Dialog({
   isInline = false,
   onOpenChange,
   width = 400,
-  maxHeight = '75vh',
+  maxHeight = '75dvh',
   position,
   variant = 'standard',
   purpose = 'info',
@@ -247,6 +295,7 @@ export function Dialog({
   const effectivePadding = padding ?? 4;
   const paddingToken = spacingStepToToken[effectivePadding];
   const isFullscreen = variant === 'fullscreen';
+  const standardSizing = isFullscreen ? null : resolveDialogSizing(width, maxHeight);
 
   // Default accessible name: publish a title id through DialogContext so a
   // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
@@ -281,6 +330,7 @@ export function Dialog({
       node.removeAttribute('aria-labelledby');
     }
   }, [titleId, hasConsumerName]);
+  const mergedDialogRef = useMergedRefs(ref, attachDialog);
 
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
@@ -338,32 +388,26 @@ export function Dialog({
   // Skip for inline rendering — no modal overlay to compensate for.
   useScrollLock(isOpen && !isInline);
 
-  // Handle Escape key — skip for inline rendering
-  useEffect(() => {
-    if (isInline) {
-      return;
-    }
-    const dialog = dialogRef.current;
-    if (!dialog || !isOpen) {
-      return;
+  // Join the shared layer dismissal stack. The stack owns the Escape listener
+  // and routes each press to the top-most layer, so this dialog does not listen
+  // itself — that is what stops a modal opened from inside another modal (or a
+  // popover opened inside this one) from closing two layers on one press.
+  //
+  // A `required` dialog registers as `block`: it must not be dismissed, and the
+  // press must not fall through and dismiss a layer behind it either.
+  //
+  // Inline mode opts out — it renders dialog content in normal flow, with
+  // nothing layered over anything.
+  const {
+    shouldDismissOnCloseRequest
+  } = useLayerDismissal({
+    isActive: isOpen,
+    isEnabled: !isInline,
+    escapeBehavior: allowEscape ? 'close' : 'block',
+    onDismiss: () => {
+      onOpenChange(false);
     }
-    const handleKeyDown = event => {
-      if (event.key === 'Escape') {
-        // Ignore IME composition-cancel, and defer to any popover/menu layered
-        // on top of this dialog so a single Escape closes only the top-most
-        // layer (the popover's own focus trap handles it and stops propagation).
-        if (isImeKeyEvent(event) || hasActiveFocusTrapEscape()) {
-          return;
-        }
-        event.preventDefault();
-        if (allowEscape) {
-          onOpenChange(false);
-        }
-      }
-    };
-    dialog.addEventListener('keydown', handleKeyDown);
-    return () => dialog.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, isInline, allowEscape, onOpenChange]);
+  });
 
   // Dev-time guardrail: an open modal should always have an accessible name.
   // The header-title check reads the DOM, so this stays in an effect; the ref
@@ -388,31 +432,35 @@ export function Dialog({
     }
   };
 
-  // Handle native cancel event (browser Escape handling)
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer the request with the stack's own rules:
+  // only the top-most layer dismisses, a `required` dialog swallows it, and
+  // nothing dismisses while an IME composition is in progress.
   const handleCancel = event => {
     event.preventDefault();
-    // Defer to a popover/menu layered on top of this dialog; it will dismiss
-    // itself on the same Escape press.
-    if (hasActiveFocusTrapEscape()) {
+    if (!shouldDismissOnCloseRequest()) {
       return;
     }
     if (allowEscape) {
       onOpenChange(false);
     }
   };
-
-  // Shared inner content wrapper
   const innerContent = /*#__PURE__*/_jsx("div", {
     ...stylex.props(styles.inner, ...container(useThemeDefault ? {
       useThemeDefault: 'dialog',
-      maxHeight: isFullscreen ? undefined : typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight
+      maxHeight: standardSizing?.maxHeight
     } : {
       paddingInnerX: paddingToken,
       paddingInnerY: paddingToken,
       paddingOuterX: paddingToken,
       paddingOuterY: paddingToken,
-      maxHeight: isFullscreen ? undefined : typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight
-    }), !useThemeDefault && effectivePadding !== 4 && paddingStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingInlineVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockStartVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockEndVarStyles[effectivePadding]),
+      maxHeight: standardSizing?.maxHeight
+    }), !useThemeDefault && effectivePadding !== 4 && paddingStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingInlineVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockStartVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockEndVarStyles[effectivePadding], isFullscreen && useThemeDefault && styles.fullscreenSafeArea),
     children: /*#__PURE__*/_jsx(DialogContext, {
       value: dialogContextValue,
       children: children
@@ -435,23 +483,25 @@ export function Dialog({
       ...safeProps,
       ...mergeProps(themeProps('dialog', {
         variant
-      }), stylex.props(styles.inlineWrapper, overlayPaddingReset.reset, !isFullscreen && dynamicStyles.sizing(width, maxHeight), isFullscreen && styles.fullscreen, xstyle), className, style),
+      }), stylex.props(styles.inlineWrapper, overlayPaddingReset.reset, standardSizing && dynamicStyles.sizing(standardSizing.width, standardSizing.maxWidth, standardSizing.maxHeight), isFullscreen && styles.fullscreen, xstyle), className, style),
       "data-testid": props['data-testid'],
-      children: innerContent
+      children: /*#__PURE__*/_jsx(LayerDepthProvider, {
+        children: innerContent
+      })
     });
   }
 
   // --- Standard modal rendering path ---
 
   return /*#__PURE__*/_jsx("dialog", {
-    ref: mergeRefs(ref, attachDialog),
+    ref: mergedDialogRef,
     ...safeProps,
     ...mergeProps(themeProps('dialog', {
       variant
-    }), focusOutlineProps.focusVisible(styles.dialog, overlayPaddingReset.reset, isOpen && styles.open, styles.backdrop, !isFullscreen && dynamicStyles.sizing(width, maxHeight), hasPosition && (() => {
+    }), focusOutlineProps.focusVisible(styles.dialog, overlayPaddingReset.reset, isOpen && styles.open, styles.backdrop, standardSizing && dynamicStyles.sizing(standardSizing.width, standardSizing.maxWidth, standardSizing.maxHeight), hasPosition && (() => {
       const o = resolveDialogPositionOffsets(position);
       return dynamicStyles.position(o.top, o.insetInlineStart, o.insetInlineEnd, o.bottom);
-    })(), isFullscreen && styles.fullscreen, xstyle), className, style),
+    })(), isFullscreen && styles.fullscreen, isFullscreen && isOpen && styles.fullscreenOpen, xstyle), className, style),
     onClick: handleClick,
     onCancel: handleCancel,
     "aria-modal": "true"
@@ -462,7 +512,9 @@ export function Dialog({
     ...(purpose === 'required' ? {
       role: 'alertdialog'
     } : undefined),
-    children: innerContent
+    children: /*#__PURE__*/_jsx(LayerDepthProvider, {
+      children: innerContent
+    })
   });
 }
 Dialog.displayName = 'Dialog';

package/dist/DropdownMenu/DropdownMenuSubMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenuSubMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuSubMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAc,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAoB5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAwF5C,UAAU,4BAA6B,SAAQ,IAAI,CACjD,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAyB,SAAQ,4BAA4B;IAC5E;;;;;;;;OAQG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,SAAS,CAwVX;yBA1Ve,mBAAmB"}
+{"version":3,"file":"DropdownMenuSubMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuSubMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAc,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAoB5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAwF5C,UAAU,4BAA6B,SAAQ,IAAI,CACjD,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAyB,SAAQ,4BAA4B;IAC5E;;;;;;;;OAQG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,SAAS,CAqVX;yBAvVe,mBAAmB"}

package/dist/DropdownMenu/DropdownMenuSubMenu.js

@@ -352,20 +352,21 @@ export function DropdownMenuSubMenu(props) {
     }
   }), [menuSize, close, menuCtx]);
   const endAffordance = hasSpinner ? /*#__PURE__*/_jsx("span", {
-    ...mergeProps(themeProps('dropdown-menu-indicator-icon'), {
+    ...{
       className: "x78zum5 x6s0dn4"
-    }),
+    },
     children: /*#__PURE__*/_jsx(Spinner, {
       size: "sm"
     })
   }) : /*#__PURE__*/_jsx("span", {
-    ...mergeProps(themeProps('dropdown-menu-indicator-icon'), {
+    ...{
       className: "x78zum5 x6s0dn4"
-    }),
+    },
     children: /*#__PURE__*/_jsx(Icon, {
       icon: "chevronRight",
       size: "sm",
-      color: "secondary"
+      color: "secondary",
+      ...themeProps('dropdown-menu-indicator-icon')
     })
   });
   const popoverXstyle = menuWidth ? flyoutStyles.popoverCustomWidth(menuWidth) : flyoutStyles.popover;

package/dist/Field/FieldLabel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldLabel.d.ts","sourceRoot":"","sources":["../../src/Field/FieldLabel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAuB,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAU5C,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAgE5D,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,gBAAgB,CAAC;IAClE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,OAAO,EACP,OAAO,EACP,YAAoB,EACpB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,EACH,GAAG,IAAI,EACR,EAAE,eAAe,+BAsHjB;yBAxIe,UAAU"}
+{"version":3,"file":"FieldLabel.d.ts","sourceRoot":"","sources":["../../src/Field/FieldLabel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAuB,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAU5C,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAgE5D,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,gBAAgB,CAAC;IAClE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,OAAO,EACP,OAAO,EACP,YAAoB,EACpB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,EACH,GAAG,IAAI,EACR,EAAE,eAAe,+BA6HjB;yBA/Ie,UAAU"}

package/dist/Field/FieldLabel.js

@@ -178,7 +178,15 @@ export function FieldLabel({
       ,
       htmlFor: isGroupLabel ? undefined : inputID,
       ...rest,
-      ...mergeProps(themeProps('field-label'), stylex.props(styles.label, isDisabled && styles.labelDisabled, isLabelHidden && styles.srOnly, xstyle), className, style),
+      ...mergeProps(
+      // A control that knows what kind of label this is passes its own
+      // target down (CheckboxInput's `checkbox-label`, Switch's
+      // `switch-label`); it arrives as `className` and composes onto this
+      // one. The label itself does not describe its own placement — it
+      // cannot know it, and any encoding it guessed would be wrong for a
+      // caller that arranges labels differently (Field's
+      // `horizontal-labels`).
+      themeProps('field-label'), stylex.props(styles.label, isDisabled && styles.labelDisabled, isLabelHidden && styles.srOnly, xstyle), className, style),
       children: labelContent
     }), description && /*#__PURE__*/_jsx("span", {
       ref: forwardsDescriptionClick ? descriptionRef : undefined,

package/dist/FileInput/FileInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileInput.d.ts","sourceRoot":"","sources":["../../src/FileInput/FileInput.tsx"],"names":[],"mappings":"AAsCA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AASlB,YAAY,EACV,WAAW,IAAI,eAAe,EAC9B,eAAe,IAAI,mBAAmB,GACvC,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AA+N9C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,UAAU,GAAG,cAAc,GAAG,OAAO,CACtC;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,aAAqB,EACrB,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,UAAkB,EAClB,OAAO,EACP,QAAQ,EACR,UAAkB,EAClB,eAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,MAAM,EAAE,UAAU,EAClB,aAA0B,EAC1B,WAAW,EACX,WAAW,EACX,IAAc,EACd,UAAkB,EAClB,YAAY,EACZ,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,cAAc,+BA+ZhB;yBA1be,SAAS"}
+{"version":3,"file":"FileInput.d.ts","sourceRoot":"","sources":["../../src/FileInput/FileInput.tsx"],"names":[],"mappings":"AAsCA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AASlB,YAAY,EACV,WAAW,IAAI,eAAe,EAC9B,eAAe,IAAI,mBAAmB,GACvC,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAgO9C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,UAAU,GAAG,cAAc,GAAG,OAAO,CACtC;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,aAAqB,EACrB,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,UAAkB,EAClB,OAAO,EACP,QAAQ,EACR,UAAkB,EAClB,eAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,MAAM,EAAE,UAAU,EAClB,aAA0B,EAC1B,WAAW,EACX,WAAW,EACX,IAAc,EACd,UAAkB,EAClB,YAAY,EACZ,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,cAAc,+BA+ZhB;yBA1be,SAAS"}

package/dist/FileInput/FileInput.js

@@ -27,9 +27,10 @@ import { useAnnounce } from "../hooks/useAnnounce.js";
 import { useInputStatusIcon } from "../hooks/useInputStatusIcon.js";
 import { useClickableContainer } from "../hooks/useClickableContainer.js";
 import { useTooltip } from "../Tooltip/index.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 function formatFileSize(bytes) {
   if (bytes < 1024) {
@@ -510,7 +511,7 @@ export function FileInput({
         })
       }), /*#__PURE__*/_jsx("input", {
         ...rest,
-        ref: mergeRefs(ref, inputRef),
+        ref: useMergedRefs(ref, inputRef),
         id: id,
         type: "file",
         accept: accept,

package/dist/Heading/Heading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../src/Heading/Heading.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE7D,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAiBxB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,UAAU,CAAC;AAE7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAElE,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,CAAC,kBAAkB,CAAC,EAC7B,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,kBAAkB,EAClB,KAAiB,EACjB,OAAiB,EACjB,QAAY,EACZ,kBAAyB,EACzB,SAAS,EACT,QAAQ,EACR,OAAiB,EACjB,UAAkB,EAClB,gBAAwB,EACxB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,YAAY,+BAmFd;yBAtGe,OAAO"}
+{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../src/Heading/Heading.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE7D,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAiBxB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,UAAU,CAAC;AAG7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAElE,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,CAAC,kBAAkB,CAAC,EAC7B,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,kBAAkB,EAClB,KAAiB,EACjB,OAAiB,EACjB,QAAY,EACZ,kBAAyB,EACzB,SAAS,EACT,QAAQ,EACR,OAAiB,EACjB,UAAkB,EAClB,gBAAwB,EACxB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,YAAY,+BAsFd;yBAzGe,OAAO"}

package/dist/Heading/Heading.js

@@ -21,7 +21,8 @@ import * as stylex from '@stylexjs/stylex';
 import { colorStyles, sizeByLevelStyles, sizeByTypeStyles, defaultWeightByTypeStyles, displayStyles, justifyStyles, truncationStyles, wordBreakStyles, textWrapStyles, capsizeStyles, decorationStyles, truncationTooltipStyles } from "../Text/text.stylex.js";
 import { useTruncation } from "../Text/useTruncation.js";
 import { resolveStyleColor } from "../Text/Text.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const LazyXDSTooltip = /*#__PURE__*/lazy(async () => import("../Tooltip/Tooltip.js").then(mod => ({
@@ -107,13 +108,16 @@ export function Heading({
   // Ref for the heading element (used as tooltip anchor)
   const headingRef = useRef(null);
 
+  // Keep the merged ref stable across rerenders.
+  const mergedRef = useMergedRefs(ref, truncation.ref, headingRef);
+
   // Build inline style for -webkit-line-clamp (dynamic value)
   const inlineStyle = maxLines > 1 ? {
     WebkitLineClamp: maxLines
   } : undefined;
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Component, {
-      ref: mergeRefs(ref, truncation.ref, headingRef),
+      ref: mergedRef,
       ...mergeProps(themeProps('heading', {
         level,
         color,

package/dist/HoverCard/HoverCard.d.ts

@@ -97,6 +97,12 @@ export interface HoverCardProps extends Pick<BaseProps, 'xstyle' | 'className' |
      * - `true`: force-show the hover card (hover/focus hide is suppressed)
      * - `false`: force-hide the hover card
      * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+     *
+     * A controlled hover card still takes Escape when it is the top-most layer,
+     * and answers by calling `onOpenChange(false)` without hiding itself —
+     * closing is your update's decision, exactly as for a controlled Dialog.
+     * Ignore the call and the card stays, and so does the press: nothing
+     * underneath dismisses.
      */
     isOpen?: boolean;
     /**

package/dist/HoverCard/HoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,YAAqB,EACrB,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CA0G/B;yBA5He,SAAS"}
+{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AA6ExB,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,YAAqB,EACrB,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAoL/B;yBAtMe,SAAS"}

package/dist/HoverCard/HoverCard.js

@@ -21,6 +21,45 @@ import { useHoverCard } from "./useHoverCard.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars } from "../theme/tokens.stylex.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// `aria-haspopup` and `aria-controls` are global, so any trigger may carry
+// them. `aria-expanded` is not. This is the ARIA 1.2 "Supported States and
+// Properties" list for it — deliberately the narrow reading: axe accepts the
+// attribute on rather more roles, since it also allows every subclass of these,
+// so a role outside this set is not necessarily a violation. Widening it is
+// safe; the set is a floor, not the spec's ceiling. The same rule is applied in
+// Chat/useTriggerMenu.tsx, which only emits the combobox attributes once the
+// element is actually a combobox.
+const EXPANDABLE_ROLES = new Set(['application', 'button', 'checkbox', 'columnheader', 'combobox', 'gridcell', 'link', 'listbox', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'row', 'rowheader', 'switch', 'tab', 'treeitem']);
+const BUTTON_INPUT_TYPES = new Set(['button', 'submit', 'reset', 'image']);
+
+// Deliberately partial, and unlisted elements are read as role-less: dropping
+// aria-expanded where it might have been legal costs an AT user a state they
+// can still infer, whereas emitting it where it is illegal is a critical
+// aria-allowed-attr defect.
+function supportsAriaExpanded(el) {
+  const explicit = el.getAttribute('role')?.trim().split(/\s+/)[0];
+  if (explicit) {
+    return EXPANDABLE_ROLES.has(explicit);
+  }
+  switch (el.tagName) {
+    case 'BUTTON':
+    case 'SUMMARY':
+      return true;
+    case 'A':
+    case 'AREA':
+      return el.hasAttribute('href');
+    case 'INPUT':
+      // The button-flavoured input types map to role="button"; every other
+      // type maps to a textbox-family role, which does not take it.
+      return BUTTON_INPUT_TYPES.has(el.type?.toLowerCase());
+    case 'SELECT':
+      // combobox when it is a single-line picker, listbox otherwise; both
+      // support aria-expanded.
+      return true;
+    default:
+      return false;
+  }
+}
 /**
  * Check if children are text-only (no React elements)
  */
@@ -115,8 +154,65 @@ export function HoverCard({
 
     // Use combined ref for position + interaction
     hoverCard.ref(firstChild);
+    if (label) {
+      // When named, the hover card is a dialog. The trigger should advertise the
+      // popup relationship with aria-haspopup/aria-expanded, not describe the
+      // trigger with the dialog's content (aria-describedby is for plain-text
+      // descriptions, not navigable regions). See #5049.
+      //
+      // aria-expanded only goes on a trigger whose role permits it. A role-less
+      // trigger (Timestamp's <time>/<span>) gets haspopup + controls, which are
+      // global, and no expanded state.
+      //
+      // Merge rather than overwrite: the trigger may already carry its own
+      // popup semantics (e.g. a menu button wrapped in a labelled HoverCard),
+      // so preserve the existing values and restore them on cleanup.
+      const existingHaspopup = firstChild.getAttribute('aria-haspopup');
+      const existingControls = firstChild.getAttribute('aria-controls');
+      const existingExpanded = firstChild.getAttribute('aria-expanded');
+      const canExpand = supportsAriaExpanded(firstChild);
+      firstChild.setAttribute('aria-haspopup', 'dialog');
+      // Only point aria-controls at the layer while it is open and in the DOM.
+      // While closed, useLayer leaves only an inert <template> marker, so the
+      // id would reference nothing. DateInput gates it the same way. The
+      // trigger's own aria-controls (if any) is preserved either way.
+      if (hoverCard.isOpen) {
+        firstChild.setAttribute('aria-controls', mergeIds(existingControls, hoverCard.id) ?? '');
+      } else if (existingControls) {
+        firstChild.setAttribute('aria-controls', existingControls);
+      } else {
+        firstChild.removeAttribute('aria-controls');
+      }
+      if (canExpand) {
+        firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));
+      } else if (existingExpanded) {
+        firstChild.setAttribute('aria-expanded', existingExpanded);
+      } else {
+        firstChild.removeAttribute('aria-expanded');
+      }
+      return () => {
+        hoverCard.ref(null);
+        if (existingHaspopup) {
+          firstChild.setAttribute('aria-haspopup', existingHaspopup);
+        } else {
+          firstChild.removeAttribute('aria-haspopup');
+        }
+        if (existingControls) {
+          firstChild.setAttribute('aria-controls', existingControls);
+        } else {
+          firstChild.removeAttribute('aria-controls');
+        }
+        if (existingExpanded) {
+          firstChild.setAttribute('aria-expanded', existingExpanded);
+        } else {
+          firstChild.removeAttribute('aria-expanded');
+        }
+      };
+    }
 
-    // Set aria-describedby, merging with existing
+    // Unnamed fallback: the popup remains role="group", which is not a dialog,
+    // so keep the previous description relationship until a naming decision is
+    // made for the no-label case (tracked in #5049).
     const existingDescribedBy = firstChild.getAttribute('aria-describedby');
     firstChild.setAttribute('aria-describedby', mergeIds(existingDescribedBy, hoverCard.describedBy) ?? '');
     return () => {
@@ -127,7 +223,7 @@ export function HoverCard({
         firstChild.removeAttribute('aria-describedby');
       }
     };
-  }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
+  }, [textOnly, label, hoverCard.ref, hoverCard.id, hoverCard.isOpen, hoverCard.describedBy]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX
   // position. When the card needs to open, it uses that marker to keep the
@@ -145,7 +241,12 @@ export function HoverCard({
       children: [/*#__PURE__*/_jsx("span", {
         ref: hoverCard.ref,
         tabIndex: 0,
-        "aria-describedby": hoverCard.describedBy,
+        "aria-haspopup": label ? 'dialog' : undefined,
+        "aria-controls": label && hoverCard.isOpen ? hoverCard.id : undefined
+        // No aria-expanded: this wrapper is a role-less <span>, and
+        // aria-expanded is invalid on it (see EXPANDABLE_ROLES above).
+        ,
+        "aria-describedby": label ? undefined : hoverCard.describedBy,
         ...{
           0: {
             className: "xt0psk2"

package/dist/HoverCard/useHoverCard.d.ts

@@ -78,6 +78,11 @@ export interface HoverCardOptions {
      * - `true`: force-show the hover card (hover/focus hide is suppressed)
      * - `false`: force-hide the hover card
      * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+     *
+     * A controlled hover card still takes Escape when it is the top-most layer,
+     * and answers by calling `onHide` without hiding itself — closing is your
+     * update's decision, exactly as for a controlled Dialog. Ignore the call and
+     * the card stays, and so does the press: nothing underneath dismisses.
      */
     isOpen?: boolean;
     /**
@@ -119,10 +124,22 @@ export interface HoverCardReturn {
      */
     anchorId: string;
     /**
-     * ID for aria-describedby on the trigger element.
-     * Caller should compose with other IDs using mergeIds utility.
+     * Unique ID for the hover card container.
+     * Useful for `aria-controls` or `aria-owns` on the trigger.
+     */
+    id: string;
+    /**
+     * Deprecated alias of `id`. Kept for backwards compatibility; prefer `id`.
      */
     describedBy: string;
+    /**
+     * Whether the hover card is currently open.
+     * Useful for driving `aria-expanded` on the trigger — but only when the
+     * trigger's role permits it (`button`, `link`, `combobox`, …). On a role-less
+     * trigger `aria-expanded` is invalid; use `aria-haspopup`/`aria-controls`
+     * alone there.
+     */
+    isOpen: boolean;
     /**
      * Render function for hover card content.
      * Returns anchor-positioned popover element.

package/dist/HoverCard/useHoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AA4BlC;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,KAC5C,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA8X5E"}
+{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AA6BlC;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;;OAOG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,KAC5C,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAib5E"}