@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

package/dist/DateTimeInput/TouchDateTimeField.js

@@ -45,10 +45,11 @@ import { rtlStyles } from "../utils/rtlStyles.js";
 import { themeProps } from "../utils/themeProps.js";
 import { normalizeDayOfWeek } from "../utils/dateTypes.js";
 import { formatLocaleTime } from "../utils/timeFormat.js";
+import { getWeekdayHeaders } from "../Calendar/getWeekdayHeaderNames.js";
 import { formatISOTime, isImeKeyEvent, isRenderable, isTimeInRange, clampTime, mergeProps, parseISOTime } from "../utils/index.js";
 import { chainEventHandlers } from "../utils/chainEventHandlers.js";
 import { joinAriaIDs } from "../utils/inputAria.js";
-import { DATE_FORMAT_LONG, DATE_FORMAT_WEEKDAY_ONLY, plainDateFormat, plainDateFromISO, plainDateToday } from "../utils/plainDate.js";
+import { DATE_FORMAT_LONG, plainDateFormat, plainDateFromISO, plainDateToday } from "../utils/plainDate.js";
 import { plainDateFormatStandaloneMonthYear } from "../utils/plainDate.js";
 import { MonthScroller } from "../DateInput/MonthScroller.js";
 import { MonthYearWheels } from "../DateInput/MonthYearWheels.js";
@@ -398,13 +399,7 @@ export function TouchDateTimeField({
   } = fromMonthIndex(monthIndex);
   const canStepBack = monthIndex > minMonthIndex;
   const canStepForward = monthIndex < maxMonthIndex;
-  const dayNames = useMemo(() => Array.from({
-    length: 7
-  }, (_, offset) => plainDateFormat({
-    year: 1970,
-    month: 1,
-    day: 4 + (weekStartsOn + offset) % 7
-  }, DATE_FORMAT_WEEKDAY_ONLY, locale)), [weekStartsOn, locale]);
+  const weekdayHeaders = useMemo(() => getWeekdayHeaders(locale, weekStartsOn), [locale, weekStartsOn]);
   const monthYearLabel = plainDateFormatStandaloneMonthYear({
     year,
     month,
@@ -545,6 +540,8 @@ export function TouchDateTimeField({
       return {
         value: hour,
         label: String(hour),
+        // Keys step in time order: 12 PM comes before 1 PM.
+        order: hour24,
         isDisabled: !rangeOverlaps(hour24 * 3600, hour24 * 3600 + 3599, timeBounds.min, timeBounds.max)
       };
     });
@@ -755,12 +752,15 @@ export function TouchDateTimeField({
               ...{
                 className: "xrvj5dj x1mzazjb x6k0iem x6s0dn4"
               },
-              children: dayNames.map(name => /*#__PURE__*/_jsx("div", {
+              children: weekdayHeaders.map(({
+                dayOfWeek,
+                name
+              }) => /*#__PURE__*/_jsx("div", {
                 ...{
                   className: "x2b8uid x141an7d x1sodnla xv1l7n4"
                 },
                 children: name
-              }, name))
+              }, dayOfWeek))
             }), /*#__PURE__*/_jsx(MonthScroller, {
               handleRef: scrollerHandleRef,
               minMonthIndex: minMonthIndex,

package/dist/Dialog/Dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../../src/Dialog/Dialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA6B5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,SAAS,CAAC;AA+B9C;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,4EAA4E;AAC5E,UAAU,mBAAmB;IAC3B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAuBD,2FAA2F;AAC3F,eAAO,MAAM,uCAAuC;;;;;;;;;;;CAW1C,CAAC;AAwLX;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,cAAc;;;;;EAUpE;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EAAE,UAAU,EAClB,QAAgB,EAChB,YAAY,EACZ,KAAW,EACX,SAAmB,EACnB,QAAQ,EACR,OAAoB,EACpB,OAAgB,EAChB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,sCAgbb;yBAhce,MAAM"}
+{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../../src/Dialog/Dialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA6B5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,SAAS,CAAC;AAkC9C;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,4EAA4E;AAC5E,UAAU,mBAAmB;IAC3B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAuBD,2FAA2F;AAC3F,eAAO,MAAM,uCAAuC;;;;;;;;;;;CAW1C,CAAC;AAwLX;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,cAAc;;;;;EAUpE;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EAAE,UAAU,EAClB,QAAgB,EAChB,YAAY,EACZ,KAAW,EACX,SAAmB,EACnB,QAAQ,EACR,OAAoB,EACpB,OAAgB,EAChB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,sCAyZb;yBAzae,MAAM"}

package/dist/Dialog/Dialog.js

@@ -55,7 +55,7 @@ import { DialogContext } from "./DialogContext.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
 import { useInteractionModalityTracking } from "../utils/interactionModality.js";
-import { focusForLastInput, isFocusLost } from "../utils/focusReturn.js";
+import { focusForLastInput, prepareFocusReturnOnRemoval } from "../utils/focusReturn.js";
 import { ModalAnnounceProvider } from "../hooks/ModalAnnounceProvider.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -414,7 +414,8 @@ export function Dialog({
   const allowEscape = purpose !== 'required';
   const allowBackdropClick = purpose === 'info';
 
-  // Handle open/close state — skip for inline rendering
+  // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
+  // An inline dialog is not in the top layer, so it skips this.
   useEffect(() => {
     if (isInline) {
       return;
@@ -461,39 +462,15 @@ export function Dialog({
   }, [isOpen, isInline]);
 
   // A dialog that unmounts while open (rendered only while open, or removed
-  // with the rest of a view) never runs the close branch above, and removing a
-  // <dialog> does not run the browser's own focus return. Focus left inside
-  // it, or dropped to the body by the removal, goes back to the opener.
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener.
   useEffect(() => {
-    if (isInline) {
+    const dialog = dialogRef.current;
+    if (isInline || dialog == null) {
       return;
     }
-    const dialog = dialogRef.current;
-    // Read now: a removed iframe's document has no window, so its frame
-    // element can no longer be found once the dialog is gone.
-    const host = dialog?.ownerDocument.defaultView?.frameElement ?? null;
-    return () => {
-      const trigger = triggerElementRef.current;
-      if (dialog == null || trigger == null) {
-        return;
-      }
-      // Checked once the commit has finished: StrictMode's simulated unmount
-      // leaves the dialog in the document, and only a real removal returns
-      // focus.
-      queueMicrotask(() => {
-        if (dialog.isConnected || !trigger.isConnected) {
-          return;
-        }
-        // isFocusLost reads the dialog's own document. For a dialog in an
-        // iframe, the document that hosts the frame must also have lost focus
-        // or keep it on that frame, wherever the opener is: a control the
-        // user pressed outside the frame to remove the dialog, or the frame
-        // itself, keeps its focus.
-        if (isFocusLost(dialog) && (host == null || isFocusLost(host))) {
-          focusForLastInput(trigger);
-        }
-      });
-    };
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => returnFocusOnRemoval(triggerElementRef.current);
   }, [isInline]);
 
   // Host app-global surfaces (toasts) inside this modal while it is open, so

package/dist/Drawer/useDrawerDialogPresence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDrawerDialogPresence.d.ts","sourceRoot":"","sources":["../../src/Drawer/useDrawerDialogPresence.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAef,KAAK,8BAA8B,GAAG;IACpC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;AA6DF;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,SAAS,EACT,MAAM,EACN,OAAO,EACP,aAAa,GACd,EAAE,8BAA8B,GAAG,IAAI,CAoEvC"}
+{"version":3,"file":"useDrawerDialogPresence.d.ts","sourceRoot":"","sources":["../../src/Drawer/useDrawerDialogPresence.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAef,KAAK,8BAA8B,GAAG;IACpC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;AA6DF;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,SAAS,EACT,MAAM,EACN,OAAO,EACP,aAAa,GACd,EAAE,8BAA8B,GAAG,IAAI,CAsEvC"}

package/dist/Drawer/useDrawerDialogPresence.js

@@ -109,6 +109,9 @@ export function useDrawerDialogPresence({
 }) {
   // Element focused when the drawer opened — restored on close.
   const triggerElementRef = useRef(null);
+
+  // Syncs the drawer's native host with `isOpen`. It shows or hides the
+  // top-layer host, keeps the opener, waits for the exit, and returns focus.
   useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) {

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

@@ -1 +1 @@
-{"version":3,"file":"useMenuOverflow.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/useMenuOverflow.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACtC,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,OAAO,EACf,gBAAgB,CAAC,EAAE,OAAO,GACzB,OAAO,CA4ET"}
+{"version":3,"file":"useMenuOverflow.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/useMenuOverflow.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACtC,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,OAAO,EACf,gBAAgB,CAAC,EAAE,OAAO,GACzB,OAAO,CA+ET"}

package/dist/DropdownMenu/useMenuOverflow.js

@@ -43,6 +43,9 @@ export function useMenuOverflow(menuRef, content, isOpen, expectedOverflow) {
       hasOverflow
     });
   }, [menuRef]);
+
+  // Syncs the overflow measurement with the open menu. It measures, then
+  // observes resize, DOM changes and window resize.
   useIsomorphicLayoutEffect(() => {
     if (!isOpen) {
       return;
@@ -71,6 +74,8 @@ export function useMenuOverflow(menuRef, content, isOpen, expectedOverflow) {
       window.visualViewport?.removeEventListener('resize', measureOverflow);
     };
   }, [isOpen, measureOverflow, menuRef]);
+
+  // Measures overflow again after the content changes while the menu is open.
   useIsomorphicLayoutEffect(() => {
     if (isOpen) {
       measureOverflow();

package/dist/Field/Field.js

@@ -22,11 +22,11 @@ import { FieldStatus } from "../FieldStatus/FieldStatus.js";
 import { useFieldStatusAnnouncement } from "../FieldStatus/useFieldStatusAnnouncement.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars, borderVars, sizeVars } from "../theme/tokens.stylex.js";
-import { mergeProps } from "../utils/index.js";
+import { mergeProps } from "../utils/mergeProps.js";
 import { useDevWarning } from "../hooks/useDevWarning.js";
 import { FormLayoutContext } from "../FormLayout/FormLayoutContext.js";
 import { Text } from "../Text/Text.js";
-import { VisuallyHidden } from "../VisuallyHidden/index.js";
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.js";
 import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const styles = {

package/dist/FieldStatus/useFieldStatusAnnouncement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFieldStatusAnnouncement.d.ts","sourceRoot":"","sources":["../../src/FieldStatus/useFieldStatusAnnouncement.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,eAAe,GAAG,SAAS,GAChC,IAAI,CAON"}
+{"version":3,"file":"useFieldStatusAnnouncement.d.ts","sourceRoot":"","sources":["../../src/FieldStatus/useFieldStatusAnnouncement.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,eAAe,GAAG,SAAS,GAChC,IAAI,CAQN"}

package/dist/FieldStatus/useFieldStatusAnnouncement.js

@@ -30,6 +30,7 @@ import { useAnnounce } from "../hooks/useAnnounce.js";
  */
 export function useFieldStatusAnnouncement(message, type) {
   const announce = useAnnounce();
+  // Syncs the live region with the status message.
   useEffect(() => {
     if (message) {
       announce(message, type === 'error' ? 'assertive' : 'polite');

package/dist/FormLayout/FormLayout.d.ts

@@ -48,7 +48,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
      *   shows an indicator (the "required" one).
      * - `'required'` — fields read as required; only a field with `isOptional`
      *   shows an indicator (the "optional" one). Fields without `isOptional`
-     *   expose `aria-required` even though they show no indicator.
+     *   expose `aria-required` even though they show no indicator. Checkboxes,
+     *   switches and checkbox groups are the exception: an unchecked box, an off
+     *   switch or an empty group is an answer, so they take no required state
+     *   from the default. A checkbox or switch is required only through its own
+     *   `isRequired`.
      * - unset — today's behavior: `isRequired` and `isOptional` each show their
      *   own indicator independently.
      *

package/dist/FormLayout/FormLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormLayout.d.ts","sourceRoot":"","sources":["../../src/FormLayout/FormLayout.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AA2C7B,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA0BjB;yBAnCe,UAAU"}
+{"version":3,"file":"FormLayout.d.ts","sourceRoot":"","sources":["../../src/FormLayout/FormLayout.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AA2C7B,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA0BjB;yBAnCe,UAAU"}

package/dist/HoverCard/HoverCard.d.ts

@@ -47,9 +47,10 @@ export interface HoverCardProps extends Pick<BaseProps, 'xstyle' | 'className' |
     hideDelay?: number;
     /**
      * When to trigger on focus:
-     * - `auto`: Only if element is naturally focusable
-     * - `always`: Always attach focus listeners
-     * - `never`: Never attach focus listeners (for composite widgets)
+     * - `auto`: focus on the trigger itself, or within a trigger that is
+     *   focusable when focus arrives
+     * - `always`: focus on the trigger or anything inside it
+     * - `never`: never on focus (for composite widgets)
      *
      * @default 'auto'
      */
@@ -87,7 +88,8 @@ export interface HoverCardProps extends Pick<BaseProps, 'xstyle' | 'className' |
     /**
      * Whether to show hover indication (dashed underline) on a text trigger.
      * An element trigger keeps its own styling, so this has no effect on it.
-     * - `'auto'`: Show when children is a single string or number
+     * - `'auto'`: Show when children is text: strings and numbers, such as
+     *   `Edited {when}`, with holes such as `false` and `null` ignored
      * - `true`: Show on a text trigger
      * - `false`: Never show
      *

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

@@ -1 +1 @@
-{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;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;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;;;;;;;;OAYG;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"}
+{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,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;;;;;;;;OAQG;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;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAoCD;;;;;;;;;;;;;;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,CA2M/B;yBA7Ne,SAAS"}

package/dist/HoverCard/HoverCard.js

@@ -15,7 +15,9 @@
  * - /apps/storybook/stories/HoverCard.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
-import { useCallback, useRef } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { isRenderable } from "../utils/isRenderable.js";
+import { observeMutations } from "../utils/sharedMutationObserver.js";
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 import * as stylex from '@stylexjs/stylex';
 import { useHoverCard } from "./useHoverCard.js";
@@ -65,7 +67,26 @@ function supportsAriaExpanded(el) {
  * Check if children are text-only (no React elements)
  */
 function isTextOnly(children) {
-  return typeof children === 'string' || typeof children === 'number';
+  if (typeof children === 'string' || typeof children === 'number') {
+    return true;
+  }
+  // Text written around an expression, such as `Edited {when}`, reaches React
+  // as several strings. Holes that render nothing do not change that; one
+  // element does.
+  if (!Array.isArray(children)) {
+    return false;
+  }
+  let hasText = false;
+  for (const child of children.flat(Infinity)) {
+    if (!isRenderable(child)) {
+      continue;
+    }
+    if (typeof child !== 'string' && typeof child !== 'number') {
+      return false;
+    }
+    hasText = true;
+  }
+  return hasText;
 }
 
 /**
@@ -138,6 +159,30 @@ export function HoverCard({
     onHide: handleHide
   });
 
+  // The wrapper's first element is the trigger, and it can be replaced after
+  // mount: by new children, or by a child component that swaps its own root
+  // without a render here. Syncs with the DOM: on a replacement the wiring
+  // below re-runs, so the old element is released before the new one is wired.
+  const [triggerReplacements, setTriggerReplacements] = useState(0);
+  const observedTriggerRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (textOnly || wrapper == null) {
+      return;
+    }
+    observedTriggerRef.current = wrapper.firstElementChild;
+    return observeMutations(wrapper, {
+      childList: true
+    }, () => {
+      const trigger = wrapper.firstElementChild;
+      if (trigger === observedTriggerRef.current) {
+        return;
+      }
+      observedTriggerRef.current = trigger;
+      setTriggerReplacements(count => count + 1);
+    });
+  }, [textOnly]);
+
   // For element children with display:contents, attach ref to first child
   useIsomorphicLayoutEffect(() => {
     if (textOnly) {
@@ -224,7 +269,7 @@ export function HoverCard({
         firstChild.removeAttribute('aria-describedby');
       }
     };
-  }, [textOnly, label, hoverCard.ref, hoverCard.id, hoverCard.isOpen, hoverCard.describedBy]);
+  }, [textOnly, label, hoverCard.ref, hoverCard.id, hoverCard.isOpen, hoverCard.describedBy, triggerReplacements]);
 
   // 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

package/dist/HoverCard/useHoverCard.d.ts

@@ -11,7 +11,7 @@ import { type ReactNode, type RefCallback } from 'react';
 import { type ContextRenderProps, type LayerAlignment, type LayerPlacement } from '../Layer/useLayer.js';
 import { type LayerTouchTrigger } from '../Layer/useTouchTrigger.js';
 /**
- * Focus trigger behavior for hover cards
+ * When focus on the trigger opens the hover card
  */
 export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';
 /**
@@ -41,9 +41,10 @@ export interface HoverCardOptions {
     hideDelay?: number;
     /**
      * When to trigger on focus:
-     * - `auto`: Only if element is naturally focusable
-     * - `always`: Always attach focus listeners
-     * - `never`: Never attach focus listeners (for composite widgets)
+     * - `auto`: focus on the trigger itself, or within a trigger that is
+     *   focusable when focus arrives
+     * - `always`: focus on the trigger or anything inside it
+     * - `never`: never on focus (for composite widgets)
      *
      * @default 'auto'
      */

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;AA8BlC;;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;;;;;;;;;;;OAWG;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;AAEH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA8c5E"}
+{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAGf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AA8BlC;;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;;;;;;;;OAQG;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;;;;;;;;;;;OAWG;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;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA6d5E"}

package/dist/HoverCard/useHoverCard.js

@@ -11,7 +11,8 @@
  * SYNC: When modified, update:
  * - /packages/core/src/HoverCard/index.ts
  */
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createTriggerFocusGate } from "../utils/triggerFocus.js";
 import * as stylex from '@stylexjs/stylex';
 import { useLayer } from "../Layer/useLayer.js";
 import { useTouchTrigger } from "../Layer/useTouchTrigger.js";
@@ -33,35 +34,13 @@ const styles = {
 };
 
 /**
- * Focus trigger behavior for hover cards
+ * When focus on the trigger opens the hover card
  */
 
 /**
  * Touch trigger behavior for hover cards
  */
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element) {
-  // Elements with explicit tabindex
-  if (element.hasAttribute('tabindex')) {
-    return element.tabIndex >= 0;
-  }
-
-  // Naturally focusable elements
-  const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
-  if (focusableTags.includes(element.tagName)) {
-    return !element.disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-  return false;
-}
-
 /**
  * Hook for hover card behavior with hover/focus triggers.
  *
@@ -220,8 +199,12 @@ export function useHoverCard(options = {}) {
   const handlePointerDown = useCallback(event => {
     handleTouchPointerDown(event);
   }, [handleTouchPointerDown]);
-  const handleFocusIn = useCallback(() => {
-    if (!isEnabled) {
+
+  // Under `auto`, whether focus counts is decided when it arrives, and a
+  // focus that counted still hides on blur (utils/triggerFocus.ts).
+  const [focusGate] = useState(createTriggerFocusGate);
+  const handleFocusIn = useCallback(e => {
+    if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
       return;
     }
     // A tap focuses the trigger it activates. Opening on that focus would
@@ -237,8 +220,11 @@ export function useHoverCard(options = {}) {
     }
     clearTimeouts();
     showLayer();
-  }, [isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
+  }, [focusGate, focusTrigger, isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
   const handleFocusOut = useCallback(e => {
+    if (!focusGate.focusOut(e, focusTrigger)) {
+      return;
+    }
     // Check if focus is moving to the hover card content
     const relatedTarget = e.relatedTarget;
     const popoverElement = document.getElementById(layerId);
@@ -247,7 +233,7 @@ export function useHoverCard(options = {}) {
       return;
     }
     scheduleHide();
-  }, [layerId, scheduleHide]);
+  }, [focusGate, focusTrigger, layerId, scheduleHide]);
 
   // Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
   // visible card is the top-most layer, so it takes the press and consumes it.
@@ -329,9 +315,9 @@ export function useHoverCard(options = {}) {
       el.addEventListener('mouseleave', handleMouseLeave);
       el.addEventListener('pointerdown', handlePointerDown);
 
-      // Attach focus listeners based on focusTrigger option
-      const shouldAttachFocus = focusTrigger === 'always' || focusTrigger === 'auto' && isFocusable(el);
-      if (shouldAttachFocus) {
+      // Focus listeners unless focus never opens the card; `auto` decides
+      // per event (utils/triggerFocus.ts).
+      if (focusTrigger !== 'never') {
         el.addEventListener('focusin', handleFocusIn);
         el.addEventListener('focusout', handleFocusOut);
       }
@@ -345,7 +331,7 @@ export function useHoverCard(options = {}) {
     interactionRef(el);
   }, [layerRef, interactionRef]);
 
-  // Cleanup on unmount
+  // Releases the hover-card timers on unmount.
   useEffect(() => {
     return () => {
       clearTimeouts();
@@ -360,7 +346,8 @@ export function useHoverCard(options = {}) {
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- intentionally only on mount
   }, []);
 
-  // Controlled open state — overrides hover/focus triggers
+  // Syncs the layer with the controlled `isOpen`. A close moves focus back to
+  // the trigger when the card holds it.
   useEffect(() => {
     if (isOpen === undefined) {
       return;

package/dist/Icon/Icon.d.ts

@@ -105,7 +105,11 @@ export type IconType = ComponentType<SVGProps<SVGSVGElement>>;
  * Extends SVGProps to allow passing additional SVG attributes (used when icon is a component).
  */
 export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'> {
-    /** Ref forwarded to the root element */
+    /**
+     * Ref to the rendered SVG element when `icon` is an icon component. A
+     * semantic or namespaced name renders inside an internal wrapper, and the
+     * ref is not attached.
+     */
     ref?: React.Ref<SVGSVGElement>;
     /**
      * Icon to render. Can be:

package/dist/Icon/Icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAC,QAAQ,EAAE,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAEhE,YAAY,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAiDhD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8Df,CAAC;AAMH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,KAAK,EACL,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACT,EAAE,SAAS,qBAoDX;yBA/De,IAAI;;;AA2IpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAC,QAAQ,EAAE,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAEhE,YAAY,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAiDhD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8Df,CAAC;AAMH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC;;;;OAIG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AA6BD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,KAAK,EACL,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACT,EAAE,SAAS,qBAoDX;yBA/De,IAAI;;;AA2IpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}

package/dist/Icon/Icon.js

@@ -193,7 +193,9 @@ const colorStyles = {
  *
  * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
  *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
- *   tree, so its accessible name would be ignored).
+ *   tree, so its accessible name would be ignored). Icon passes
+ *   `aria-hidden: undefined`. Many icon components, such as Heroicons, write
+ *   `aria-hidden="true"` unless a prop replaces it.
  * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
  *
  * The result is spread BEFORE `{...props}` in both render modes so an explicit
@@ -202,7 +204,8 @@ const colorStyles = {
 function getIconA11yProps(label) {
   return label != null && label !== '' ? {
     role: 'img',
-    'aria-label': label
+    'aria-label': label,
+    'aria-hidden': undefined
   } : {
     'aria-hidden': 'true'
   };

package/dist/InfoTip/InfoTip.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file InfoTip.tsx
- * @input Uses React, StyleX, Tooltip, Icon, useComponentTranslator, the shared
- *   touch hit area, color/spacing/radius/duration/ease tokens
+ * @input Uses React, StyleX, useTooltip, Icon, useComponentTranslator, the
+ *   shared touch hit area, color/spacing/radius/duration/ease tokens
  * @output Exports InfoTip component, InfoTipProps, InfoTipSize types
  * @position Core implementation; consumed by index.ts, tested by
  *   InfoTip.test.tsx; `@astryxdesign/lab` re-exports it, deprecated
@@ -46,9 +46,9 @@ export interface InfoTipProps extends Pick<BaseProps, 'xstyle' | 'className' | '
  * labels, values, and metrics for permission notes, metric definitions, and
  * field help.
  *
- * InfoTip is a press-to-pin Tooltip on a named button: Tooltip opens, pins,
- * announces, and closes the help. The info icon resolves from
- * the icon registry, so themes can replace it.
+ * InfoTip is a named button that toggles `useTooltip`'s `show()` and `hide()`:
+ * the hook previews, holds, announces, and closes the help. The info icon
+ * resolves from the icon registry, so themes can replace it.
  *
  * @example
  * ```

package/dist/InfoTip/InfoTip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InfoTip.d.ts","sourceRoot":"","sources":["../../src/InfoTip/InfoTip.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAG5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAO,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAC;AAoBjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEnC,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,IAAW,EACX,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,GAAG,SAAS,CAyC1B;yBAjDe,OAAO"}
+{"version":3,"file":"InfoTip.d.ts","sourceRoot":"","sources":["../../src/InfoTip/InfoTip.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,GAAG,EACT,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAO,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAC;AAqBjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEnC,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,IAAW,EACX,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,GAAG,SAAS,CAyF1B;yBAjGe,OAAO"}