@astryxdesign/core 0.5.0 → 0.5.1-canary.f64186a

package/dist/Icon/globalIconRegistry.js

@@ -26,6 +26,19 @@ import { warnOnce } from "../utils/devWarning.js";
  */
 // SYNC: packages/cli/assets/docs/icons.doc.mjs — update USAGE_HINTS when adding names
 
+/**
+ * A namespaced extension key, `'<namespace>:<name>'`.
+ *
+ * This is the tier for a glyph that belongs to one component or library rather
+ * than to the system: `'richtext:bold'`, `'numberInput:stepperDown'`. A theme
+ * overrides it by key through `registerIcons` or `defineTheme({icons})`,
+ * exactly as it overrides a built-in name, and the core {@link IconName} union
+ * stays reserved for glyphs the whole system shares.
+ *
+ * Accepted anywhere a built-in name is, including `<Icon icon>` — which is
+ * what lets a namespaced glyph keep `size`, `color` and `xstyle`.
+ */
+
 /**
  * A semantic icon name — either one of the built-in {@link IconName}s or an
  * arbitrary string key contributed by a library/app.
@@ -45,6 +58,16 @@ import { warnOnce } from "../utils/devWarning.js";
 // =============================================================================
 
 let globalRegistry = {};
+
+/**
+ * A key is namespaced when it carries a `<namespace>:` prefix — the runtime
+ * form of {@link NamespacedIconName}, which is how the typed
+ * {@link getIconRegistry} snapshot tells a built-in name from a component- or
+ * library-owned one.
+ */
+function isNamespacedKey(name) {
+  return name.includes(':');
+}
 function getThemeIconOverrides(source) {
   if (source == null) {
     return null;
@@ -95,19 +118,24 @@ export function registerIcons(icons) {
  * resolves against.
  */
 export function getIconRegistry(source) {
-  const registry = {
-    ...defaultIcons
-  };
+  const registry = {};
 
-  // Only surface built-in IconName keys here — extension keys registered by
-  // libraries are resolved via getIcon/getExtendedIcon and intentionally kept
-  // out of the typed IconRegistry snapshot.
+  // Only surface built-in IconName keys here — namespaced keys, whether
+  // contributed by a library or shipped as a component's own default, are
+  // resolved via getIcon/getExtendedIcon and intentionally kept out of the
+  // typed IconRegistry snapshot.
   for (const name of Object.keys(defaultIcons)) {
+    if (isNamespacedKey(name)) {
+      continue;
+    }
     registry[name] = globalRegistry[name] ?? defaultIcons[name];
   }
   const themeIcons = getThemeIconOverrides(source);
   if (themeIcons != null) {
     for (const name of Object.keys(themeIcons)) {
+      if (isNamespacedKey(name)) {
+        continue;
+      }
       registry[name] = themeIcons[name] ?? registry[name];
     }
   }

package/dist/Icon/index.d.ts

@@ -10,5 +10,5 @@ export { Icon, renderIconSlot } from './Icon';
 export { useIcon } from './useIcon';
 export type { IconProps, IconColor, IconSize, IconType } from './Icon';
 export { registerIcons, getIconRegistry, getIcon, getExtendedIcon, resetIcons, } from './globalIconRegistry';
-export type { IconName, ExtendedIconName, IconRegistry, IconRegistrySource, } from './globalIconRegistry';
+export type { IconName, ExtendedIconName, NamespacedIconName, IconRegistry, IconRegistrySource, } from './globalIconRegistry';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Icon/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,YAAY,EAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAGrE,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,eAAe,EACf,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Icon/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,YAAY,EAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAGrE,OAAO,EACL,aAAa,EACb,eAAe,EACf,OAAO,EACP,eAAe,EACf,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}

package/dist/Icon/useIcon.d.ts

@@ -5,10 +5,13 @@
  * @position Client hook for components that render registry icons directly
  */
 import type { ReactNode } from 'react';
-import { type IconName } from './globalIconRegistry';
+import { type IconName, type NamespacedIconName } from './globalIconRegistry';
 /**
  * Resolve a semantic icon name from the nearest Theme, falling back through
  * root theme registration, global icon overrides, and built-in defaults.
+ *
+ * Accepts a namespaced extension key (`'richtext:bold'`) as well as a built-in
+ * name; both resolve through the same registry.
  */
-export declare function useIcon(name: IconName): ReactNode;
+export declare function useIcon(name: IconName | NamespacedIconName): ReactNode;
 //# sourceMappingURL=useIcon.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useIcon.d.ts","sourceRoot":"","sources":["../../src/Icon/useIcon.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAU,KAAK,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAGjD"}
+{"version":3,"file":"useIcon.d.ts","sourceRoot":"","sources":["../../src/Icon/useIcon.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAGtE"}

package/dist/Icon/useIcon.js

@@ -14,6 +14,9 @@ import { getIcon } from "./globalIconRegistry.js";
 /**
  * Resolve a semantic icon name from the nearest Theme, falling back through
  * root theme registration, global icon overrides, and built-in defaults.
+ *
+ * Accepts a namespaced extension key (`'richtext:bold'`) as well as a built-in
+ * name; both resolve through the same registry.
  */
 export function useIcon(name) {
   const themeName = useThemeName();

package/dist/Indicator/CheckboxIndicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CheckboxIndicator.d.ts","sourceRoot":"","sources":["../../src/Indicator/CheckboxIndicator.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAwI5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,IAAW,EACX,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,gBAAgB,CAAC,+BAwElC;yBAlFe,iBAAiB"}
+{"version":3,"file":"CheckboxIndicator.d.ts","sourceRoot":"","sources":["../../src/Indicator/CheckboxIndicator.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAwI5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,IAAW,EACX,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,gBAAgB,CAAC,+BA8ElC;yBAxFe,iBAAiB"}

package/dist/Indicator/CheckboxIndicator.js

@@ -155,7 +155,9 @@ export function CheckboxIndicator({
     children: isRenderable(children) ? children : /*#__PURE__*/_jsxs(_Fragment, {
       children: [/*#__PURE__*/_jsx("svg", {
         viewBox: "0 0 10 10",
-        ...stylex.props(styles.checkmark, checkmarkSizeStyles[size], isChecked && styles.checkmarkVisible),
+        ...mergeProps(themeProps('checkbox-indicator-check', {
+          size
+        }), stylex.props(styles.checkmark, checkmarkSizeStyles[size], isChecked && styles.checkmarkVisible)),
         children: /*#__PURE__*/_jsx("path", {
           d: "M8.5 2.5L4 7.5L1.5 5",
           stroke: "currentColor",
@@ -165,7 +167,9 @@ export function CheckboxIndicator({
           strokeLinejoin: "round"
         })
       }), /*#__PURE__*/_jsx("span", {
-        ...stylex.props(styles.indeterminateMark, indeterminateSizeStyles[size], isIndeterminate && styles.indeterminateMarkVisible)
+        ...mergeProps(themeProps('checkbox-indicator-dash', {
+          size
+        }), stylex.props(styles.indeterminateMark, indeterminateSizeStyles[size], isIndeterminate && styles.indeterminateMarkVisible))
       })]
     })
   });

package/dist/Item/Item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAc5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,MAAkB,EAClB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BAqNX;yBA/Oe,IAAI"}
+{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAe5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,MAAkB,EAClB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BAsNX;yBAhPe,IAAI"}

package/dist/Item/Item.js

@@ -27,6 +27,7 @@ import { useClickableContainer } from "../hooks/useClickableContainer.js";
 import { useDevWarning } from "../hooks/useDevWarning.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
+import { interactionOverlayStyles } from "../utils/interactionOverlay.stylex.js";
 
 // =============================================================================
 // Types
@@ -67,7 +68,6 @@ const styles = {
     k1ekBW: "x15406qy",
     kIyJzY: "xkvfbh3",
     kAMwcw: "xlr8y92",
-    kWkggS: "xjbqb8w xoevpu5 xyxi2l3",
     $$css: true
   },
   highlighted: {
@@ -368,7 +368,7 @@ export function Item({
     ...mergeProps(themeProps('item', {
       density,
       align
-    }), focusOutlineProps.focusWithin(styles.root, densityStyles[density], align === 'start' && styles.alignStart, isInteractive && styles.interactive, isHighlighted && styles.highlighted, isSelected && styles.selected, isDisabled && !hasParentRole && styles.disabled, xstyle), className, style),
+    }), focusOutlineProps.focusWithin(styles.root, densityStyles[density], align === 'start' && styles.alignStart, isInteractive && styles.interactive, isInteractive && interactionOverlayStyles.backgroundColor, isHighlighted && styles.highlighted, isSelected && styles.selected, isDisabled && !hasParentRole && styles.disabled, xstyle), className, style),
     role: role,
     onClick: isDelegate ? delegatedOnClick : hasParentRole ? onClick : isInteractive ? handleContainerClick : undefined,
     children: innerContent

package/dist/Kbd/Kbd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmI5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBAgC3E;yBAhCe,GAAG"}
+{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAIlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA0G5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBAgC3E;yBAhCe,GAAG"}

package/dist/Kbd/Kbd.js

@@ -15,6 +15,7 @@
 import React, { useSyncExternalStore } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { mergeProps } from "../utils/index.js";
+import { isApplePlatform } from "../utils/isApplePlatform.js";
 import { themeProps } from "../utils/themeProps.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars, typographyVars, fontWeightVars, typeScaleVars } from "../theme/tokens.stylex.js";
@@ -98,31 +99,6 @@ function subscribeToPlatformChanges() {
 function getServerPlatformSnapshot() {
   return false;
 }
-
-/**
- * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when it names a platform (modern
- * Chrome/Edge), falls back to navigator.platform (deprecated but universally
- * supported) when it is absent or blank.
- */
-function detectMac() {
-  if (typeof navigator === 'undefined') {
-    return false;
-  }
-  // Prefer User-Agent Client Hints API (not deprecated)
-  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
-  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    const uaPlatform = uaData.platform;
-    // A blank platform is no answer, not a negative one. Builds that rewrite
-    // their client-hints identity ship '', so fall through rather than
-    // reading it as "not Apple".
-    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
-      return /mac/i.test(uaPlatform);
-    }
-  }
-  // Fallback: navigator.platform (deprecated but still shipped everywhere)
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
 /**
  * Displays a keyboard shortcut as styled <kbd> elements.
  *
@@ -146,7 +122,7 @@ export function Kbd({
   style,
   ...rest
 }) {
-  const isMac = useSyncExternalStore(subscribeToPlatformChanges, detectMac, getServerPlatformSnapshot);
+  const isMac = useSyncExternalStore(subscribeToPlatformChanges, isApplePlatform, getServerPlatformSnapshot);
   const parts = keys.split('+').map(key => key.trim().toLowerCase());
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since

package/dist/Layer/gestureCounter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Identifies the user gesture in flight. Two reads returning the same value
+ * happened within one press (or one keystroke).
+ */
+export declare function currentGesture(): number;
+/** Whether the click belonging to the current gesture already bubbled. */
+export declare function currentGestureHasClicked(): boolean;
+//# sourceMappingURL=gestureCounter.d.ts.map

package/dist/Layer/gestureCounter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gestureCounter.d.ts","sourceRoot":"","sources":["../../src/Layer/gestureCounter.ts"],"names":[],"mappings":"AA2CA;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,IAAI,OAAO,CAGlD"}

package/dist/Layer/gestureCounter.js

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file gestureCounter.ts
+ * @input Listens for pointerdown, keydown, and click on the document
+ * @output Exports the current gesture identity and whether its click has run
+ * @position Internal to Layer; used by useLayer to tell a click that belongs
+ *   to a dismissing press from a fresh one
+ *
+ * A browser light-dismiss and the trigger's own click come from ONE press, and
+ * which of them React sees first is a race. Comparing timestamps against a
+ * window guesses; counting gestures does not. The counter advances on every
+ * new press or keystroke, so "the click from the gesture that dismissed the
+ * layer" is exactly "the click while the counter still reads what it read at
+ * the dismissal", no matter how long the main thread was blocked in between.
+ */
+let gesture = 0;
+let clickedGesture = null;
+let isListening = false;
+function advance() {
+  gesture += 1;
+}
+function markClicked() {
+  clickedGesture = gesture;
+}
+function listen() {
+  if (isListening || typeof document === 'undefined') {
+    return;
+  }
+  isListening = true;
+  // Capture phase: the count must advance before any handler reads it.
+  document.addEventListener('pointerdown', advance, true);
+  document.addEventListener('keydown', advance, true);
+  // Capture phase observes the click even when a consumer stops propagation.
+  document.addEventListener('click', markClicked, true);
+}
+
+/**
+ * Identifies the user gesture in flight. Two reads returning the same value
+ * happened within one press (or one keystroke).
+ */
+export function currentGesture() {
+  listen();
+  return gesture;
+}
+
+/** Whether the click belonging to the current gesture already bubbled. */
+export function currentGestureHasClicked() {
+  listen();
+  return clickedGesture === gesture;
+}

package/dist/Layer/useLayer.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file useLayer.tsx
  * @input Uses React hooks, Popover API, CSS anchor positioning, typography tokens
- * @output Exports useLayer hook for layer positioning and visibility
+ * @output Exports the public useLayer hook plus internal trigger helpers.
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
  * SYNC: When modified, update:
@@ -11,6 +11,17 @@
  */
 import React, { type ReactNode, type RefCallback } from 'react';
 import type { StyleXStyles } from '@stylexjs/stylex';
+/**
+ * Props for a control that sits on the trigger but must not dismiss the layer.
+ */
+interface KeepLayerOpenProps {
+    onPointerDown: React.PointerEventHandler<HTMLElement>;
+    /**
+     * Capture phase, so spreading these props never collides with the control's
+     * own `onClick`.
+     */
+    onClickCapture: React.MouseEventHandler<HTMLElement>;
+}
 /**
  * Position placement relative to anchor.
  * Logical: start/end resolve against the popover's own inherited direction
@@ -243,6 +254,11 @@ export interface FixedLayerReturn {
      */
     render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
 }
+interface InternalLayerFields {
+    wasJustDismissed: () => boolean;
+}
+type InternalContextLayerReturn = ContextLayerReturn & InternalLayerFields;
+type InternalFixedLayerReturn = FixedLayerReturn & InternalLayerFields;
 /**
  * Compute the `position-try-fallbacks` list for a placement/alignment pair.
  *
@@ -254,20 +270,14 @@ export interface FixedLayerReturn {
  */
 export declare function getPositionTryFallbacks(placement?: LayerPlacement, alignment?: LayerAlignment): string;
 /**
- * Core layer hook that handles popover behavior and positioning.
- *
- * Supports two positioning modes with type-safe render props:
- * - `context`: CSS anchor positioning relative to a trigger element
- * - `fixed`: Fixed positioning at specified coordinates
- *
- * @example
- * ```
- * const layer = useLayer({ mode: 'context' });
- * <button ref={layer.ref}>Trigger</button>
- * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
- * ```
+ * Internal props for controls that sit beside an open layer. This stays out of
+ * the public useLayer/usePopover return types until the input family adopts it.
  */
+export declare function useKeepLayerOpenProps(id: string, isOpen: boolean): KeepLayerOpenProps;
 export declare function useLayer(options: ContextLayerOptions): ContextLayerReturn;
 export declare function useLayer(options: FixedLayerOptions): FixedLayerReturn;
+/** @internal Shared with usePopover; not exported from the package barrel. */
+export declare function useLayerInternal(options: ContextLayerOptions): InternalContextLayerReturn;
+export declare function useLayerInternal(options: FixedLayerOptions): InternalFixedLayerReturn;
 export {};
 //# sourceMappingURL=useLayer.d.ts.map

package/dist/Layer/useLayer.d.ts.map

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

package/dist/Layer/useLayer.js

@@ -5,7 +5,7 @@
 /**
  * @file useLayer.tsx
  * @input Uses React hooks, Popover API, CSS anchor positioning, typography tokens
- * @output Exports useLayer hook for layer positioning and visibility
+ * @output Exports the public useLayer hook plus internal trigger helpers.
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
  * SYNC: When modified, update:
@@ -13,10 +13,11 @@
  * - /packages/core/src/Layer/useLayer.test.tsx
  * - /packages/core/src/Layer/index.ts
  */
-import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { createPortal } from 'react-dom';
 import { addAnchorName, removeAnchorName } from "./anchorName.js";
+import { currentGesture, currentGestureHasClicked } from "./gestureCounter.js";
 import { resolveLayerPortalTarget } from "./layerHost.js";
 import "../theme/tokens.stylex.js";
 import { typeScaleVars, typographyVars } from "../theme/tokens.stylex.js";
@@ -64,6 +65,10 @@ const styles = {
   }]
 };
 
+/**
+ * Props for a control that sits on the trigger but must not dismiss the layer.
+ */
+
 /**
  * Position placement relative to anchor.
  * Logical: start/end resolve against the popover's own inherited direction
@@ -188,6 +193,44 @@ export function getPositionTryFallbacks(placement = 'above', alignment = 'center
   return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
 }
 
+/**
+ * Internal props for controls that sit beside an open layer. This stays out of
+ * the public useLayer/usePopover return types until the input family adopts it.
+ */
+export function useKeepLayerOpenProps(id, isOpen) {
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+  return useMemo(() => ({
+    onPointerDown: event => {
+      if (!isOpenRef.current) {
+        return;
+      }
+      // The browser reads the invoker relationship at both ends of the press.
+      const control = event.currentTarget;
+      const doc = control.ownerDocument;
+      control.setAttribute('popovertarget', id);
+      const onPressEnd = () => {
+        doc.removeEventListener('pointerup', onPressEnd);
+        doc.removeEventListener('pointercancel', onPressEnd);
+        // Light dismiss runs as the pointerup default action after listeners.
+        doc.defaultView?.setTimeout(() => {
+          control.removeAttribute('popovertarget');
+        }, 0);
+      };
+      doc.addEventListener('pointerup', onPressEnd);
+      doc.addEventListener('pointercancel', onPressEnd);
+    },
+    onClickCapture: event => {
+      const control = event.currentTarget;
+      if (control.hasAttribute('popovertarget')) {
+        // Being an invoker would otherwise toggle the layer shut.
+        event.preventDefault();
+        control.removeAttribute('popovertarget');
+      }
+    }
+  }), [id]);
+}
+
 /**
  * Core layer hook that handles popover behavior and positioning.
  *
@@ -202,8 +245,7 @@ export function getPositionTryFallbacks(placement = 'above', alignment = 'center
  * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
  * ```
  */
-
-export function useLayer(options) {
+function useLayerImplementation(options) {
   const {
     mode,
     onShow,
@@ -234,6 +276,16 @@ export function useLayer(options) {
   // State drives re-renders; the ref lets the imperative calls avoid
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
+
+  // The gesture during which the browser last closed this layer on its own.
+  // Read through wasJustDismissed by triggers deciding whether a click is
+  // theirs to act on.
+  const dismissedByGestureRef = useRef(null);
+  const forgetDismissalRef = useRef(null);
+  const wasJustDismissed = useCallback(() => {
+    const gesture = currentGesture();
+    return dismissedByGestureRef.current === gesture;
+  }, []);
   const showPopoverElement = useCallback(popover => {
     // Finding infra-4: the Popover API is unsupported on Safari <17 and
     // Firefox <125. On those browsers `showPopover` does not exist, so fall
@@ -287,6 +339,11 @@ export function useLayer(options) {
     setContextMount(null);
   }, [mode, lazyMount]);
   const show = useCallback(() => {
+    // Every caller lands here, so this is where the dismissing press is
+    // absorbed: opening now would reopen the popup that same press closed.
+    if (wasJustDismissed()) {
+      return;
+    }
     // A context popover left over until React commits a previous hide must not
     // be reopened. The synchronous mount ref is the source of truth.
     const candidate = popoverRef.current;
@@ -302,11 +359,16 @@ export function useLayer(options) {
       setIsOpen(true);
       onShow?.();
     }
-  }, [onShow, requestContextMount, showPopoverElement, isCurrentContextPopover]);
+  }, [onShow, requestContextMount, showPopoverElement, isCurrentContextPopover, wasJustDismissed]);
   const hide = useCallback(() => {
     pendingShowRef.current = false;
     if (isOpenRef.current) {
       const el = popoverRef.current;
+      // Clear the open state BEFORE hiding: hidePopover fires `toggle`, and
+      // the reconciler below reads this ref to tell the browser's own
+      // dismissals from ours.
+      openedPopoverRef.current = null;
+      isOpenRef.current = false;
       // See finding infra-4 note in `show`: mirror the same guard on hide so
       // unsupported browsers degrade gracefully instead of throwing.
       if (el) {
@@ -316,16 +378,14 @@ export function useLayer(options) {
           el.style.display = 'none';
         }
       }
-      openedPopoverRef.current = null;
-      isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
     }
     clearContextMount();
   }, [onHide, clearContextMount]);
 
-  // Ref for trigger element (context mode only)
-  const ref = mode === 'context' ? el => {
+  // Stable ref for the trigger element (context mode only).
+  const contextRef = useCallback(el => {
     // Remove only THIS layer's anchor name from the previous element so
     // other layers sharing the same trigger keep their anchors.
     if (triggerRef.current && triggerRef.current !== el) {
@@ -335,7 +395,51 @@ export function useLayer(options) {
       addAnchorName(el, anchorId);
     }
     triggerRef.current = el;
-  } : undefined;
+  }, [anchorId]);
+
+  // Arm only when the dismissing gesture's click is still ahead of us. Some
+  // engines deliver click first; in that order there is nothing left to absorb.
+  const rememberDismissal = useCallback(doc => {
+    forgetDismissalRef.current?.();
+    if (currentGestureHasClicked()) {
+      return;
+    }
+    dismissedByGestureRef.current = currentGesture();
+    const view = doc.defaultView;
+    let forgetTimer = null;
+    const forget = () => {
+      dismissedByGestureRef.current = null;
+      doc.removeEventListener('click', scheduleForget, true);
+      if (forgetTimer !== null) {
+        view?.clearTimeout(forgetTimer);
+        forgetTimer = null;
+      }
+      if (forgetDismissalRef.current === forget) {
+        forgetDismissalRef.current = null;
+      }
+    };
+    const scheduleForget = () => {
+      doc.removeEventListener('click', scheduleForget, true);
+      // The next task keeps the dismissal armed through React's click handler.
+      if (view) {
+        forgetTimer = view.setTimeout(() => {
+          forgetTimer = null;
+          if (forgetDismissalRef.current === forget) {
+            forget();
+          }
+        }, 0);
+      } else {
+        forget();
+      }
+    };
+    doc.addEventListener('click', scheduleForget, true);
+    forgetDismissalRef.current = forget;
+  }, []);
+  useEffect(() => {
+    // Install capture-phase gesture tracking before the first interaction.
+    currentGesture();
+    return () => forgetDismissalRef.current?.();
+  }, []);
 
   // Reconcile browser-initiated closes (light-dismiss, popover="auto" stack
   // eviction). These are the only cases where the DOM mutates without going
@@ -352,11 +456,12 @@ export function useLayer(options) {
     if (toggleEvent.newState === 'closed' && isOpenRef.current) {
       openedPopoverRef.current = null;
       isOpenRef.current = false;
+      rememberDismissal(e.currentTarget?.ownerDocument ?? document);
       setIsOpen(false);
       onHide?.();
       clearContextMount();
     }
-  }, [onHide, clearContextMount]);
+  }, [onHide, clearContextMount, rememberDismissal]);
 
   // Ref callback for popover element — sets up the `toggle` listener.
   // Tracks the element + handler currently bound so the listener is removed
@@ -512,23 +617,40 @@ export function useLayer(options) {
       children: children
     });
   }, [popoverRefCallback, id, lightDismiss]);
-  if (mode === 'context') {
-    return {
-      ref: ref,
-      anchorId,
-      show,
-      hide,
-      isOpen,
-      id,
-      render: renderContext
-    };
-  }
-  return {
+  const contextResult = useMemo(() => ({
+    ref: contextRef,
+    anchorId,
+    show,
+    hide,
+    isOpen,
+    wasJustDismissed,
+    id,
+    render: renderContext
+  }), [contextRef, anchorId, show, hide, isOpen, wasJustDismissed, id, renderContext]);
+  const fixedResult = useMemo(() => ({
     ref: undefined,
     show,
     hide,
     isOpen,
+    wasJustDismissed,
     id,
     render: renderFixed
-  };
+  }), [show, hide, isOpen, wasJustDismissed, id, renderFixed]);
+  return mode === 'context' ? contextResult : fixedResult;
+}
+export function useLayer(options) {
+  const internalLayer = useLayerImplementation(options);
+  return useMemo(() => {
+    const {
+      wasJustDismissed: _,
+      ...layer
+    } = internalLayer;
+    return layer;
+  }, [internalLayer]);
+}
+
+/** @internal Shared with usePopover; not exported from the package barrel. */
+
+export function useLayerInternal(options) {
+  return useLayerImplementation(options);
 }