@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/src/Layer/useLayer.tsx

@@ -25,8 +25,10 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
+import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
-import {typographyVars} from '../theme/tokens.stylex';
+import {resolveLayerPortalTarget} from './layerHost';
+import {typeScaleVars, typographyVars} from '../theme/tokens.stylex';
 
 const styles = stylex.create({
   // Base reset for all layers
@@ -42,7 +44,12 @@ const styles = stylex.create({
     borderWidth: 0,
     borderStyle: 'none',
     overflow: 'visible',
+    // A layer is hosted wherever its trigger happens to sit, so type that is
+    // inherited rather than declared makes the same component render at a
+    // different size in different callers.
     fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-body-size'],
+    lineHeight: typeScaleVars['--text-body-leading'],
     // Override browser default [popover] background (canvas color)
     backgroundColor: 'transparent',
   },
@@ -149,12 +156,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'
    */
@@ -222,6 +228,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;
 }
 
 /**
@@ -314,16 +329,51 @@ function toCssLength(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
 
+interface ContextLayerMount {
+  /** Null means the marker's parent is safe and the layer stays inline. */
+  portalTarget: HTMLElement | null;
+  /** Logical writing context lost when moving outside an unsafe ancestor. */
+  portalStyle: React.CSSProperties;
+}
+
+function readPortalWritingContext(
+  element: HTMLElement,
+  portalTarget: HTMLElement,
+): React.CSSProperties {
+  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 as React.CSSProperties['direction'],
+    }),
+    ...(sourceStyle.writingMode !== targetStyle.writingMode && {
+      writingMode:
+        sourceStyle.writingMode as React.CSSProperties['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
@@ -406,39 +456,122 @@ export function useLayer(
   options: ContextLayerOptions | FixedLayerOptions,
 ): ContextLayerReturn | FixedLayerReturn {
   const {mode, onShow, 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<HTMLElement | null>(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<HTMLElement | null>(null);
   const triggerRef = useRef<HTMLElement | null>(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<HTMLTemplateElement | null>(null);
+  const contextMountRef = useRef<ContextLayerMount | null>(null);
+  const [contextMount, setContextMount] = useState<ContextLayerMount | null>(
+    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 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';
+  const showPopoverElement = useCallback((popover: HTMLElement) => {
+    // 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: HTMLElement): boolean => {
+      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: ContextLayerMount = {
+      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(() => {
+    // 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
@@ -450,11 +583,13 @@ export function useLayer(
           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: RefCallback<HTMLElement> | undefined =
@@ -488,12 +623,14 @@ export function useLayer(
     (e: Event) => {
       const toggleEvent = e as ToggleEvent;
       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.
@@ -531,8 +668,40 @@ export function useLayer(
     (el: HTMLElement | null) => {
       popoverRef.current = el;
       bindToggleListener(el, handleToggle);
+      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: HTMLTemplateElement | null) => {
+      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();
+      }
     },
-    [handleToggle, bindToggleListener],
+    [lazyMount, requestContextMount],
   );
 
   // Re-bind when the handler identity changes while the element stays mounted,
@@ -556,6 +725,15 @@ export function useLayer(
   // Render function for context mode
   const renderContext = useCallback(
     (children: ReactNode, props?: ContextRenderProps) => {
+      // 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 = <template ref={sentinelRefCallback} />;
+
+      if (contextMount === null) {
+        return <>{sentinel}</>;
+      }
+
       const {
         placement = 'above',
         alignment = 'center',
@@ -598,10 +776,10 @@ export function useLayer(
         ? `${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 (
+      // 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 = (
         <Container
           ref={popoverRefCallback}
           id={id}
@@ -609,14 +787,35 @@ export function useLayer(
           aria-label={ariaLabel}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
-          style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}
+          style={{
+            ...stylexResult.style,
+            ...anchorStyle,
+            ...contextMount.portalStyle,
+            ...extraStyle,
+          }}
           onMouseEnter={onMouseEnter}
           onMouseLeave={onMouseLeave}>
           {children}
         </Container>
       );
+
+      return (
+        <>
+          {sentinel}
+          {contextMount.portalTarget
+            ? createPortal(layer, contextMount.portalTarget)
+            : layer}
+        </>
+      );
     },
-    [anchorId, id, lightDismiss, popoverRefCallback],
+    [
+      anchorId,
+      contextMount,
+      id,
+      lightDismiss,
+      popoverRefCallback,
+      sentinelRefCallback,
+    ],
   );
 
   // Render function for fixed mode

package/src/MobileNav/MobileNav.doc.mjs

@@ -78,6 +78,13 @@ export const docs = {
       name: 'MobileNavToggle',
       displayName: 'Mobile Nav Toggle',
       description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+      // The toggle renders null unless AppShell mobile context reports an
+      // enabled mobile viewport — the default context outside AppShell never
+      // does, so the Properties preview was an empty stage. appShellMobile
+      // has the preview simulate that context instead (#4983).
+      playground: {
+        appShellMobile: true,
+      },
       props: [
         {
           name: 'children',

package/src/NavItem/navItemStyles.stylex.ts

@@ -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.
  */
 
 export type NavItemSize = 'sm' | 'md' | 'lg';
@@ -79,15 +84,36 @@ export const navItemStyles = stylex.create({
 
   /** Selected/active page indicator — deemphasized background, medium weight */
   selected: {
-    backgroundColor: colorVars['--color-neutral'],
+    // Forced colors flatten `--color-neutral` away, leaving the current page
+    // unmarked; Highlight/HighlightText is the platform convention, as in
+    // ToggleButton and SegmentedControlItem. No `forced-color-adjust: none`
+    // here — a nav row is not a native control, so the keywords land without
+    // it, and it would inherit into `endContent` and pin a Badge's own fill.
+    backgroundColor: {
+      default: colorVars['--color-neutral'],
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    color: {
+      default: null,
+      '@media (forced-colors: active)': 'HighlightText',
+    },
     fontWeight: fontWeightVars['--font-weight-medium'],
     ':hover': {
       '@media (hover: hover)': {
-        backgroundColor: colorVars['--color-neutral'],
+        backgroundColor: {
+          default: colorVars['--color-neutral'],
+          // Nested, not a sibling `(hover: hover) and (forced-colors:
+          // active)` block: as siblings `item`'s hover overlay ties on
+          // specificity and wins on source order, erasing the fill.
+          '@media (forced-colors: active)': 'Highlight',
+        },
       },
     },
     ':active': {
-      backgroundColor: colorVars['--color-neutral'],
+      backgroundColor: {
+        default: colorVars['--color-neutral'],
+        '@media (forced-colors: active)': 'Highlight',
+      },
     },
   },
 

package/src/RadioList/RadioListItem.tsx

@@ -51,6 +51,26 @@ const styles = stylex.create({
     opacity: 0,
     cursor: 'pointer',
     zIndex: 1,
+    minInlineSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    minBlockSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    insetBlockStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    insetInlineStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    transform: {
+      default: null,
+      '@media (pointer: coarse)': 'translate(-50%, -50%)',
+    },
   },
   inputDisabled: {
     cursor: 'not-allowed',

package/src/SideNav/SideNav.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     targets: [
       {className: 'astryx-side-nav', visualProps: ['mode']},
       {className: 'astryx-side-nav-heading'},
-      {className: 'astryx-side-nav-item', visualProps: ['size'], states: ['selected']},
+      {className: 'astryx-side-nav-item', visualProps: ['size'], states: ['selected', 'disabled']},
       {className: 'astryx-side-nav-section'},
     ],
   },
@@ -85,7 +85,7 @@ export const docs = {
     {
       name: 'footerIcons',
       type: 'ReactNode',
-      description: 'Footer icon bar.',
+      description: "Footer icon bar. The row cascades a 'sm' size to the interactive children it contains, so its icons and the built-in collapse button come out one height; pass an explicit size on a child to opt out.",
       slotElements: [
         {
           __element: 'Icon',
@@ -99,7 +99,7 @@ export const docs = {
     {
       name: 'collapsible',
       type: 'boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string }',
-      description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
+      description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel). A controlled config can also be passed to a SideNavCollapseButton rendered outside this SideNav, so both share one state.',
       default: 'false',
     },
     {
@@ -111,7 +111,7 @@ export const docs = {
     {
       name: 'handleRef',
       type: 'Ref<SideNavImperativeCollapseHandle>',
-      description: 'Imperative collapse handle for SideNavCollapseButton instances rendered outside this SideNav. Separate from `ref`, which continues to expose the root HTMLElement.',
+      description: 'Deprecated. Imperative collapse handle for SideNavCollapseButton instances rendered outside this SideNav; hand both the same controlled collapsible config instead. Separate from `ref`, which continues to expose the root HTMLElement.',
     },
     {
       name: 'xstyle',
@@ -131,6 +131,9 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],
@@ -150,6 +153,9 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],
@@ -169,6 +175,9 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],