@astryxdesign/core 0.4.1 → 0.4.2-canary.464a445

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,EAAe,KAAK,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAiB1D,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;;;;;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,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAiH/B;yBAlIe,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,EAAe,KAAK,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAiB1D,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;;;;;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,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAyG/B;yBA1He,SAAS"}

package/dist/HoverCard/HoverCard.js

@@ -6,7 +6,7 @@
  * @file HoverCard.tsx
  * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
+ * @position Layer component; inline-safe trigger wrapper, floating layer hosted by useLayer
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -127,18 +127,10 @@ export function HoverCard({
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
 
-  // Render the floating layer inline, in the same place on the server and the
-  // client. The layer is a `popover` element opened via the Popover API, so the
-  // browser promotes it to the top layer when shown — that already escapes
-  // ancestor clipping, stacking, and transform containing-block traps, and CSS
-  // anchor positioning resolves the trigger reference regardless of where the
-  // element sits in the DOM, so no portal is needed to "escape" layout.
-  //
-  // The layer renders as inline-safe phrasing markup (a `<span>`, see
-  // useHoverCard), which stays put inside a `<p>` instead of being reparented
-  // by the HTML parser. That keeps the server markup and the first client
-  // render identical, so there is no hydration mismatch — and it preserves the
-  // inline-safety guarantee (no block elements injected into a paragraph).
+  // 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
+  // final layer inline when the parent is safe or portal it outside a <p>,
+  // link, or other ancestor that cannot contain it safely.
   const renderedHoverCard = hoverCard.renderHoverCard(content, {
     xstyle,
     className,

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;AAgC3B;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,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;;;;;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,CAiT5E"}
+{"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;AA4B3B;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,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;;;;;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,CAkT5E"}

package/dist/HoverCard/useHoverCard.js

@@ -88,6 +88,7 @@ export function useHoverCard(options = {}) {
   } = options;
   const layer = useLayer({
     mode: 'context',
+    lazyMount: true,
     onShow,
     onHide
   });
@@ -254,15 +255,15 @@ export function useHoverCard(options = {}) {
       // Consumer surface style props land on the layer container — the
       // themed surface (bg/radius/shadow) where the theme class lives — so
       // customizing the card targets the same element as the theme. The inner
-      // span keeps `styles.content` for padding.
+      // div keeps `styles.content` for padding.
       xstyle: [popoverXstyle, layerAnimations[renderPlacement], props?.xstyle],
       className: props?.className ? `${themeClassName} ${props.className}` : themeClassName,
       style: props?.style,
-      // Render the layer as inline-safe phrasing markup so HoverCard stays
-      // valid (and hydration-stable) inside inline contexts like a `<p>`.
-      as: 'span'
+      // useLayer mounts only after it has verified or corrected the parent,
+      // so rich HoverCard content can use block-safe markup.
+      as: 'div'
     };
-    return layer.render(/*#__PURE__*/_jsx("span", {
+    return layer.render(/*#__PURE__*/_jsx("div", {
       ...{
         className: "x1lliihq x1vlblms xvmdzux x126nfab x1t818jl"
       },

package/dist/InputGroup/groupStyles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"groupStyles.d.ts","sourceRoot":"","sources":["../../src/InputGroup/groupStyles.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,eAAO,MAAM,WAAW;;;;;;;;;;;;;;EAmCtB,CAAC"}
+{"version":3,"file":"groupStyles.d.ts","sourceRoot":"","sources":["../../src/InputGroup/groupStyles.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAQ3C,eAAO,MAAM,WAAW;;;;;;;;;;;;;;EA6BtB,CAAC"}

package/dist/InputGroup/groupStyles.js

@@ -10,6 +10,11 @@
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { radiusVars, borderVars } from "../theme/tokens.stylex.js";
+
+// A grouped control may be followed by context-layer infrastructure rather
+// than another control. Neither the inert marker nor the popover is a visual
+// group member, so skip both when finding the trailing edge.
+const IS_LAST_ITEM = ':not(:has(~ *:not([popover]):not(template)))';
 export const groupStyles = {
   inGroup: {
     kUk6DE: "x98rzlu",
@@ -18,8 +23,8 @@ export const groupStyles = {
     keTefX: "xd10s4z x1pwwqoy",
     krdFHd: "x15mokao x8eehn2",
     kVL7Gh: "xbiv7yw x1xrp5p4",
-    kfmiAY: "x1ga7v0g x11xp8u1 xpufgd0 x1ir7nn6",
-    kT0f0o: "x16uus16 x747jw7 xxd14kb x1vej5at",
+    kfmiAY: "x1ga7v0g x1tzxhge",
+    kT0f0o: "x16uus16 x1rmb4wm",
     kXnDq0: "x1rm9qnc",
     $$css: true
   }

package/dist/Layer/layerHost.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Return the corrective portal target for a layer's intended inline parent.
+ *
+ * A null result means the inline parent and all of its ancestors are safe, so
+ * the layer should stay at its JSX position. Otherwise the result is the
+ * nearest element outside every unsafe ancestor around that position.
+ *
+ * Walking up from the actual render position (rather than the trigger, or
+ * portaling to `document.body`) keeps the two things a layer inherits there:
+ *
+ * - **Theme.** Theme scopes live on DOM ancestors. Staying as close as
+ *   possible to the intended render position preserves their component rules
+ *   and custom properties; `document.body` may sit outside a nested scope.
+ * - **Tab order.** Sequential focus follows DOM order, so a host near the
+ *   trigger keeps the layer's focusables next to it. (`show()` also passes
+ *   the trigger as the popover's invoker `source`, which pins focus order to
+ *   the invoker in browsers that support it.)
+ *
+ * The outermost unsafe ancestor matters. A safe div may itself sit inside an
+ * anchor; stopping at that div would still put the layer's buttons inside the
+ * link. Walking the whole chain ensures the target is outside both.
+ */
+export declare function resolveLayerPortalTarget(inlineParent: HTMLElement | null): HTMLElement | null;
+//# sourceMappingURL=layerHost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layerHost.d.ts","sourceRoot":"","sources":["../../src/Layer/layerHost.ts"],"names":[],"mappings":"AAqGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,WAAW,GAAG,IAAI,GAC/B,WAAW,GAAG,IAAI,CAepB"}

package/dist/Layer/layerHost.js

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerHost.ts
+ * @input Uses the layer's intended inline parent element
+ * @output Exports resolveLayerPortalTarget, the corrective portal target
+ * @position Layer utility; used by useLayer to place the popover in the DOM
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/layerHost.test.ts
+ */
+
+/**
+ * Ancestors a layer must not be hosted inside.
+ *
+ * Two overlapping reasons, both verified in Chrome:
+ *
+ * 1. The HTML parser owns server markup. `<p>` and the heading-ish elements
+ *    take phrasing content only, so a block element inside one makes the
+ *    parser close the paragraph and reparent the rest — the layer's content
+ *    ends up in the page instead of the popover. A nested `<a>` triggers the
+ *    same tearing through the adoption agency algorithm.
+ * 2. Interactive ancestors capture the layer's own interactions. A card
+ *    hosted inside an `<a>` or `<button>` puts its links and buttons inside
+ *    that control: clicking one navigates the wrapping link, and every
+ *    focusable in the card joins the control's own tab stop.
+ *
+ * Inline formatting elements are on the list for a third, milder reason: a
+ * layer hosted in one inherits its typography (font-size, text-align), so a
+ * card in a 13px centered paragraph renders 13px and centered.
+ */
+const UNSAFE_HOSTS = new Set([
+// Phrasing-content-only containers
+'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'dt', 'pre', 'legend', 'data', 'dfn', 'meter', 'output', 'progress', 'option', 'optgroup',
+// Structural containers whose direct children are restricted. An inert
+// <template> marker is valid script-supporting content in these positions,
+// but the eventual div/span layer is not.
+'table', 'thead', 'tbody', 'tfoot', 'tr', 'colgroup', 'ul', 'ol', 'menu', 'dl', 'select', 'datalist', 'picture', 'hgroup', 'ruby', 'rt', 'rp',
+// Interactive containers
+'a', 'button', 'label', 'summary',
+// Inline formatting context
+'span', 'em', 'strong', 'b', 'i', 'u', 's', 'small', 'mark', 'code', 'kbd', 'samp', 'var', 'sub', 'sup', 'abbr', 'cite', 'q', 'time', 'bdi', 'bdo', 'ins', 'del']);
+
+/**
+ * Return the corrective portal target for a layer's intended inline parent.
+ *
+ * A null result means the inline parent and all of its ancestors are safe, so
+ * the layer should stay at its JSX position. Otherwise the result is the
+ * nearest element outside every unsafe ancestor around that position.
+ *
+ * Walking up from the actual render position (rather than the trigger, or
+ * portaling to `document.body`) keeps the two things a layer inherits there:
+ *
+ * - **Theme.** Theme scopes live on DOM ancestors. Staying as close as
+ *   possible to the intended render position preserves their component rules
+ *   and custom properties; `document.body` may sit outside a nested scope.
+ * - **Tab order.** Sequential focus follows DOM order, so a host near the
+ *   trigger keeps the layer's focusables next to it. (`show()` also passes
+ *   the trigger as the popover's invoker `source`, which pins focus order to
+ *   the invoker in browsers that support it.)
+ *
+ * The outermost unsafe ancestor matters. A safe div may itself sit inside an
+ * anchor; stopping at that div would still put the layer's buttons inside the
+ * link. Walking the whole chain ensures the target is outside both.
+ */
+export function resolveLayerPortalTarget(inlineParent) {
+  if (!inlineParent) {
+    return null;
+  }
+  let outermostUnsafe = null;
+  let node = inlineParent;
+  while (node) {
+    if (UNSAFE_HOSTS.has(node.tagName.toLowerCase())) {
+      outermostUnsafe = node;
+    }
+    node = node.parentElement;
+  }
+  return outermostUnsafe?.parentElement ?? null;
+}

package/dist/Layer/useLayer.d.ts

@@ -94,12 +94,11 @@ export interface ContextRenderProps {
     /**
      * HTML tag to render the popover container as.
      *
-     * Defaults to `'div'`. Pass `'span'` when the layer must render inline-safe
-     * markup — e.g. a `HoverCard` wrapping inline text inside a `<p>`. A `<span>`
-     * is phrasing content, so it stays put in the DOM tree instead of being
-     * reparented out of a paragraph by the HTML parser, which keeps server and
-     * client markup identical. The Popover API and CSS anchor positioning work
-     * the same on either tag.
+     * Defaults to `'div'`. Context layers render an inert `<template>` marker at
+     * the JSX position. The marker's parent is checked before the requested
+     * container mounts there or portals outside ancestors that cannot safely
+     * contain it. The marker remains available to detect a new parent if the
+     * render call moves. With `lazyMount`, the first check waits until `show()`.
      *
      * @default 'div'
      */
@@ -162,6 +161,15 @@ interface BaseLayerOptions {
  */
 export interface ContextLayerOptions extends BaseLayerOptions {
     mode: 'context';
+    /**
+     * Defer mounting the final layer and resolving its inline/portal position
+     * until `show()` is requested. Hiding unmounts it while the inert marker
+     * remains at the JSX position. Use this when rich content must never enter
+     * an unsafe ancestor, even briefly, and does not need to exist while closed.
+     *
+     * @default false
+     */
+    lazyMount?: boolean;
 }
 /**
  * Options for fixed mode (manual positioning)

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

@@ -1 +1 @@
-{"version":3,"file":"useLayer.d.ts","sourceRoot":"","sources":["../../src/Layer/useLayer.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAMZ,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAwCnD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAClC;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACpD;;OAEG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED;;GAEG;AACH,UAAU,gBAAgB;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,kBAAkB,KAAK,SAAS,CAAC;CACxE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,KAAK,SAAS,CAAC;CACrE;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,GAAE,cAAwB,EACnC,SAAS,GAAE,cAAyB,GACnC,MAAM,CAgBR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAAC;AAC3E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAAC"}
+{"version":3,"file":"useLayer.d.ts","sourceRoot":"","sources":["../../src/Layer/useLayer.tsx"],"names":[],"mappings":"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"}

package/dist/Layer/useLayer.js

@@ -15,10 +15,12 @@
  */
 import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import { createPortal } from 'react-dom';
 import { addAnchorName, removeAnchorName } from "./anchorName.js";
+import { resolveLayerPortalTarget } from "./layerHost.js";
 import "../theme/tokens.stylex.js";
-import { typographyVars } from "../theme/tokens.stylex.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { typeScaleVars, typographyVars } from "../theme/tokens.stylex.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const _temp = {
   keoZOQ: "x1vhfslr",
   k1K539: "xlm3tn6",
@@ -38,6 +40,8 @@ const styles = {
     ksu8eU: "xng3xce",
     kVQacm: "x1rea2x4",
     kMv6JI: "x9ynric",
+    kGuDYH: "xjm74w1",
+    kLWn49: "xw6l6zx",
     kWkggS: "xjbqb8w",
     $$css: true
   },
@@ -100,17 +104,40 @@ const styles = {
 function toCssLength(value) {
   return typeof value === 'number' ? `${value}px` : value;
 }
+function readPortalWritingContext(element, portalTarget) {
+  const view = element.ownerDocument.defaultView;
+  if (!view) {
+    return {};
+  }
+  const sourceStyle = view.getComputedStyle(element);
+  const targetStyle = view.getComputedStyle(portalTarget);
+
+  // Do not snapshot custom properties here. The portal target is the closest
+  // safe ancestor, so theme variables continue to inherit and update there.
+  // These two properties can be set on the unsafe chain itself and directly
+  // affect the logical anchor-positioning keywords used by the layer. Only
+  // override values the portal would actually lose; matching values should
+  // keep inheriting from the target so later direction changes remain live.
+  return {
+    ...(sourceStyle.direction !== targetStyle.direction && {
+      direction: sourceStyle.direction
+    }),
+    ...(sourceStyle.writingMode !== targetStyle.writingMode && {
+      writingMode: sourceStyle.writingMode
+    })
+  };
+}
 
 /**
  * Map logical placement/alignment to a CSS position-area value.
  *
  * Uses the self-* logical keyword family: the inline axis resolves against
- * the popover's own inherited direction (the layer renders inside the
- * trigger's subtree, so it inherits `direction` and mirrors in RTL with no
- * JS). The block axis is direction-neutral but must come from the same
- * keyword family — mixing physical `top` with `self-inline-*` produces an
- * invalid position-area (computes to `none`, which pins the popover to the
- * viewport corner because styles.base zeroes the UA margins).
+ * the popover's own direction (inherited inline or preserved when portaled),
+ * so it mirrors in RTL without placement-specific JS. The block axis is
+ * direction-neutral but must come from the same keyword family — mixing
+ * physical `top` with `self-inline-*` produces an invalid position-area
+ * (computes to `none`, which pins the popover to the viewport corner because
+ * styles.base zeroes the UA margins).
  *
  * Note the plain logical family (`inline-start`, no `self-`) is NOT a
  * substitute: it resolves against the containing block — the page root for
@@ -182,36 +209,101 @@ export function useLayer(options) {
     onHide,
     lightDismiss = false
   } = options;
+  const lazyMount = mode === 'context' ? options.lazyMount ?? false : false;
   const id = useId();
   const anchorId = `--astryx-layer-${id.replace(/:/g, '')}`;
   const [isOpen, setIsOpen] = useState(false);
   const popoverRef = useRef(null);
+  // The DOM element on which the current logical open state was applied.
+  // A portal target change replaces the popover element; retaining the old
+  // reference lets the ref callback recognize and reopen its replacement.
+  const openedPopoverRef = useRef(null);
   const triggerRef = useRef(null);
+  // Context layers place a persistent inert marker at their real JSX position.
+  // Its parent tells us whether the final layer can stay inline or needs a
+  // corrective portal, including after the render call moves.
+  const sentinelRef = useRef(null);
+  const contextMountRef = useRef(null);
+  const [contextMount, setContextMount] = useState(null);
+  // A show() that arrives before the final layer mounts is replayed when its
+  // popover ref attaches.
+  const pendingShowRef = useRef(false);
 
   // Ref mirrors isOpen for synchronous reads inside show/hide.
   // State drives re-renders; the ref lets the imperative calls avoid
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
+  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
+    // back to plain visibility instead of throwing.
+    if (typeof popover.showPopover === 'function') {
+      // The trigger is passed as the popover's invoker `source`: a layer
+      // hosted away from its trigger then still takes its sequential focus
+      // order (and its popover nesting) from the trigger rather than from its
+      // own DOM position. Browsers without the option ignore it.
+      popover.showPopover({
+        source: triggerRef.current ?? undefined
+      });
+    } else {
+      popover.style.display = 'block';
+    }
+    openedPopoverRef.current = popover;
+  }, []);
+  const isCurrentContextPopover = useCallback(popover => {
+    if (mode !== 'context') {
+      return true;
+    }
+    const mount = contextMountRef.current;
+    if (mount === null) {
+      return false;
+    }
+    const expectedParent = mount.portalTarget ?? sentinelRef.current?.parentElement ?? null;
+    return popover.parentElement === expectedParent;
+  }, [mode]);
+  const requestContextMount = useCallback(() => {
+    if (mode !== 'context') {
+      return;
+    }
+    const sentinel = sentinelRef.current;
+    const inlineParent = sentinel?.parentElement ?? null;
+    if (!sentinel || !inlineParent) {
+      return;
+    }
+    const portalTarget = resolveLayerPortalTarget(inlineParent);
+    const mount = {
+      portalTarget,
+      portalStyle: portalTarget ? readPortalWritingContext(sentinel, portalTarget) : {}
+    };
+    contextMountRef.current = mount;
+    setContextMount(mount);
+  }, [mode]);
+  const clearContextMount = useCallback(() => {
+    if (mode !== 'context' || !lazyMount) {
+      return;
+    }
+    contextMountRef.current = null;
+    setContextMount(null);
+  }, [mode, lazyMount]);
   const show = useCallback(() => {
-    const popover = popoverRef.current;
-    if (popover && !isOpenRef.current) {
-      // Finding infra-4: the Popover API is unsupported on Safari <17 and
-      // Firefox <125. On those browsers `showPopover` does not exist, so
-      // calling it unconditionally throws a TypeError and the layer never
-      // opens. Guard behind a feature check; when the API is missing, fall
-      // back to plain visibility (the [popover] attribute is inert there, so
-      // the element sits in normal flow) so the layer still becomes visible.
-      if (typeof popover.showPopover === 'function') {
-        popover.showPopover();
-      } else {
-        popover.style.display = 'block';
-      }
+    // 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;
+    const popover = candidate && isCurrentContextPopover(candidate) ? candidate : null;
+    if (!popover) {
+      pendingShowRef.current = true;
+      requestContextMount();
+      return;
+    }
+    if (!isOpenRef.current) {
+      showPopoverElement(popover);
       isOpenRef.current = true;
       setIsOpen(true);
       onShow?.();
     }
-  }, [onShow]);
+  }, [onShow, requestContextMount, showPopoverElement, isCurrentContextPopover]);
   const hide = useCallback(() => {
+    pendingShowRef.current = false;
     if (isOpenRef.current) {
       const el = popoverRef.current;
       // See finding infra-4 note in `show`: mirror the same guard on hide so
@@ -223,11 +315,13 @@ export function useLayer(options) {
           el.style.display = 'none';
         }
       }
+      openedPopoverRef.current = null;
       isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
     }
-  }, [onHide]);
+    clearContextMount();
+  }, [onHide, clearContextMount]);
 
   // Ref for trigger element (context mode only)
   const ref = mode === 'context' ? el => {
@@ -255,11 +349,13 @@ export function useLayer(options) {
   const handleToggle = useCallback(e => {
     const toggleEvent = e;
     if (toggleEvent.newState === 'closed' && isOpenRef.current) {
+      openedPopoverRef.current = null;
       isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
+      clearContextMount();
     }
-  }, [onHide]);
+  }, [onHide, clearContextMount]);
 
   // Ref callback for popover element — sets up the `toggle` listener.
   // Tracks the element + handler currently bound so the listener is removed
@@ -283,7 +379,24 @@ export function useLayer(options) {
   const popoverRefCallback = useCallback(el => {
     popoverRef.current = el;
     bindToggleListener(el, handleToggle);
-  }, [handleToggle, bindToggleListener]);
+    if (el && pendingShowRef.current) {
+      pendingShowRef.current = false;
+      show();
+    } else if (el && isOpenRef.current && openedPopoverRef.current !== el && isCurrentContextPopover(el)) {
+      // Changing a portal target remounts the popover. Preserve the logical
+      // open state without firing onShow again for the replacement element.
+      showPopoverElement(el);
+    }
+  }, [handleToggle, bindToggleListener, show, showPopoverElement, isCurrentContextPopover]);
+  const sentinelRefCallback = useCallback(el => {
+    sentinelRef.current = el;
+    if (el && (!lazyMount || pendingShowRef.current || isOpenRef.current)) {
+      // The render call may have moved while the hook stayed mounted.
+      // Resolve again from the newly attached marker rather than reusing a
+      // portal target from its previous JSX position.
+      requestContextMount();
+    }
+  }, [lazyMount, requestContextMount]);
 
   // Re-bind when the handler identity changes while the element stays mounted,
   // and detach on unmount.
@@ -302,6 +415,17 @@ export function useLayer(options) {
 
   // Render function for context mode
   const renderContext = useCallback((children, props) => {
+    // Keep the marker mounted after resolving the layer. Apart from giving
+    // us the real JSX parent on first show, this lets its ref report when a
+    // persistent hook's render call moves to a different host.
+    const sentinel = /*#__PURE__*/_jsx("template", {
+      ref: sentinelRefCallback
+    });
+    if (contextMount === null) {
+      return /*#__PURE__*/_jsx(_Fragment, {
+        children: sentinel
+      });
+    }
     const {
       placement = 'above',
       alignment = 'center',
@@ -332,10 +456,10 @@ export function useLayer(options) {
     const stylexResult = stylex.props(styles.base, offsetStyle, xstyle);
     const combinedClassName = extraClassName ? `${extraClassName} ${stylexResult.className ?? ''}` : stylexResult.className;
 
-    // Render as the requested tag. A `span` keeps the layer phrasing content
-    // so it is valid (and stays put on hydration) inside inline contexts like
-    // a `<p>`; `div` remains the default for block layers.
-    return /*#__PURE__*/_jsx(Container, {
+    // The marker gives us the actual JSX parent without mounting arbitrary
+    // children there. Safe positions preserve the existing DOM order and
+    // cascade; unsafe positions use the nearest corrective portal target.
+    const layer = /*#__PURE__*/_jsx(Container, {
       ref: popoverRefCallback,
       id: id,
       role: role,
@@ -345,13 +469,17 @@ export function useLayer(options) {
       style: {
         ...stylexResult.style,
         ...anchorStyle,
+        ...contextMount.portalStyle,
         ...extraStyle
       },
       onMouseEnter: onMouseEnter,
       onMouseLeave: onMouseLeave,
       children: children
     });
-  }, [anchorId, id, lightDismiss, popoverRefCallback]);
+    return /*#__PURE__*/_jsxs(_Fragment, {
+      children: [sentinel, contextMount.portalTarget ? /*#__PURE__*/createPortal(layer, contextMount.portalTarget) : layer]
+    });
+  }, [anchorId, contextMount, id, lightDismiss, popoverRefCallback, sentinelRefCallback]);
 
   // Render function for fixed mode
   const renderFixed = useCallback((children, props) => {

package/dist/NavItem/navItemStyles.stylex.d.ts

@@ -9,8 +9,13 @@
  * disabled state) so all nav-like components stay in sync — especially important
  * when TopNav items render inside MobileNav drawers alongside SideNav items.
  *
- * Individual components layer their own overrides (e.g. collapsed mode, indentation,
- * focus outlines) via stylex.props composition.
+ * Individual components layer their own overrides (e.g. collapsed mode,
+ * indentation) via stylex.props composition.
+ *
+ * The focus ring is not defined here. Compose
+ * `focusOutlineProps.focusVisible` (utils/focusOutline.stylex.ts) at the call
+ * site, on whichever element actually takes focus — in a split-action row that
+ * is the link and the toggle, not the row that contains them.
  */
 export type NavItemSize = 'sm' | 'md' | 'lg';
 import * as stylex from '@stylexjs/stylex';
@@ -63,15 +68,22 @@ export declare const navItemStyles: Readonly<{
         }>;
     }>;
     readonly selected: Readonly<{
-        readonly backgroundColor: stylex.StyleXClassNameFor<"backgroundColor", "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))">;
+        readonly backgroundColor: stylex.StyleXClassNameFor<"backgroundColor", "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))" | "Highlight">;
+        readonly color: stylex.StyleXClassNameFor<"color", "HighlightText" | null>;
         readonly fontWeight: stylex.StyleXClassNameFor<"fontWeight", "500">;
         readonly ':hover': stylex.StyleXClassNameFor<":hover", {
             readonly '@media (hover: hover)': {
-                readonly backgroundColor: stylex.StyleXVar<"light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))">;
+                readonly backgroundColor: {
+                    readonly default: stylex.StyleXVar<"light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))">;
+                    readonly '@media (forced-colors: active)': "Highlight";
+                };
             };
         }>;
         readonly ':active': stylex.StyleXClassNameFor<":active", {
-            readonly backgroundColor: stylex.StyleXVar<"light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))">;
+            readonly backgroundColor: {
+                readonly default: stylex.StyleXVar<"light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))">;
+                readonly '@media (forced-colors: active)': "Highlight";
+            };
         }>;
     }>;
     readonly disabled: Readonly<{

package/dist/NavItem/navItemStyles.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navItemStyles.stylex.d.ts","sourceRoot":"","sources":["../../src/NavItem/navItemStyles.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7C,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuExB,CAAC"}
+{"version":3,"file":"navItemStyles.stylex.d.ts","sourceRoot":"","sources":["../../src/NavItem/navItemStyles.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7C,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4FxB,CAAC"}

package/dist/NavItem/navItemStyles.stylex.js

@@ -11,8 +11,13 @@
  * disabled state) so all nav-like components stay in sync — especially important
  * when TopNav items render inside MobileNav drawers alongside SideNav items.
  *
- * Individual components layer their own overrides (e.g. collapsed mode, indentation,
- * focus outlines) via stylex.props composition.
+ * Individual components layer their own overrides (e.g. collapsed mode,
+ * indentation) via stylex.props composition.
+ *
+ * The focus ring is not defined here. Compose
+ * `focusOutlineProps.focusVisible` (utils/focusOutline.stylex.ts) at the call
+ * site, on whichever element actually takes focus — in a split-action row that
+ * is the link and the toggle, not the row that contains them.
  */
 
 import * as stylex from '@stylexjs/stylex';
@@ -63,10 +68,11 @@ export const navItemStyles = {
     $$css: true
   },
   selected: {
-    kWkggS: "x17x4s8c",
+    kWkggS: "x17x4s8c x1jzqe4",
+    kMwMTN: "x1k5gbb1",
     k63SB2: "x1e4wzip",
-    kHE3J0: "x1sua13m",
-    kSReZ0: "xjtnuge",
+    kHE3J0: "x1sua13m x1jawyga",
+    kSReZ0: "xjtnuge x1vo6n7o",
     $$css: true
   },
   disabled: {