@astryxdesign/core 0.3.0 → 0.4.0

package/src/TopNav/TopNavMegaMenu.tsx

@@ -12,6 +12,13 @@
  * eliminating z-index stacking. CSS anchor positioning places the panel below
  * the nav wrapper.
  *
+ * The default (desktop) trigger opens on hover and click. Hover opens are
+ * transient; click/keyboard opens are pinned. A click shortly after hover-open
+ * confirms and pins the panel instead of closing it. The panel remains an auto
+ * popover for native dismissal and sibling exclusivity; `popoverTarget`
+ * registers the trigger as its native invoker so the guard runs before any
+ * dismiss.
+ *
  * Supports three render modes via TopNavRenderContext:
  * - 'default': desktop popover mega menu (hover/click triggered)
  * - 'mobile-bar': returns null (hidden in compact mobile bar)
@@ -44,13 +51,14 @@ import {
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {Grid} from '../Grid/Grid';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles
@@ -79,14 +87,6 @@ const styles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
     border: 'none',
     fontFamily: 'inherit',
   },
@@ -97,6 +97,14 @@ const styles = stylex.create({
   chevron: {
     display: 'inline-flex',
     alignItems: 'center',
+    // The registry chevron is a 1em SVG, so it has always rendered at the
+    // trigger's own font size (--text-label-size). Icon's size box would repin
+    // it to a fixed rem (the nearest, sm, is 1rem = 16px vs the 14px here), so
+    // hold it on the inherited em: same pixels, and still tracks the type
+    // scale when a theme changes the label size.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -131,7 +139,10 @@ const styles = stylex.create({
   // own content, keeping the surface radius/shadow static at the edges.
   // Internal scroll is a stopgap until the mobile bottom-sheet lands.
   panelViewportFit: {
-    display: 'flex',
+    display: {
+      default: 'none',
+      ':popover-open': 'flex',
+    },
     flexDirection: 'column',
     maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
   },
@@ -197,6 +208,11 @@ const styles = stylex.create({
   },
   drawerChevron: {
     display: 'inline-flex',
+    // Same em pin as styles.chevron above — the drawer header inherits
+    // --text-label-size from navItemStyles.item.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -354,6 +370,8 @@ TopNavMegaMenu.displayName = 'TopNavMegaMenu';
 // DefaultMegaMenu — desktop popover mode
 // =============================================================================
 
+const CLICK_GUARD_MS = 500;
+
 function DefaultMegaMenu({
   ref,
   label,
@@ -364,30 +382,39 @@ function DefaultMegaMenu({
   onOpenChange,
 }: TopNavMegaMenuProps) {
   const slot = useTopNavSlot();
-  const chevronDownIcon = useIcon('chevronDown');
   const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
-  const clickLockedRef = useRef(false);
+  const hoverOpenedAtRef = useRef(0);
+  const stickyRef = useRef(false);
 
   const handlePopoverShow = useCallback(() => {
     onOpenChange?.(true);
   }, [onOpenChange]);
 
   const handlePopoverHide = useCallback(() => {
+    hoverOpenedAtRef.current = 0;
+    stickyRef.current = false;
     onOpenChange?.(false);
   }, [onOpenChange]);
 
   const popover = usePopover({
     // role: 'none' — the panel exposes its own role="group" labeled by
-    // `label`. Focus stays on the trigger while the panel is open, so a
-    // role="dialog" aria-modal="true" wrapper would announce an unnamed
-    // modal dialog around a grid of links.
+    // `label`. Pointer/hover opens keep focus on the trigger; keyboard and
+    // assistive-tech opens move focus into the panel (a labeled group you exit
+    // with Escape or by tabbing out). Either way role="dialog"
+    // aria-modal="true" would be wrong: it announces an unnamed modal dialog
+    // around a grid of links (and, when focus stays on the trigger, marks the
+    // focused control inert).
     role: 'none',
     // hasSurface: false — mega menu provides its own surface (panelContainer)
     // with border-top and custom overflow. Animation is applied via the
     // render() call's xstyle prop (panelAnimation), not the hook options.
     hasSurface: false,
+    // Keep native outside-click/Escape dismissal and sibling exclusivity.
+    // The trigger's popoverTarget association prevents its activation from
+    // being treated as an ordinary outside interaction.
+    hasLightDismiss: true,
     onShow: handlePopoverShow,
     onHide: handlePopoverHide,
   });
@@ -417,40 +444,75 @@ function DefaultMegaMenu({
   const scheduleShow = useCallback(() => {
     clearTimeouts();
     showTimeoutRef.current = setTimeout(() => {
+      hoverOpenedAtRef.current = Date.now();
       popover.show({skipAutoFocus: true});
     }, delay);
-  }, [clearTimeouts, popover, delay]);
+  }, [clearTimeouts, delay, popover]);
 
   const scheduleHide = useCallback(() => {
     clearTimeouts();
     hideTimeoutRef.current = setTimeout(() => {
       popover.hide();
     }, hideDelay);
-  }, [clearTimeouts, popover, hideDelay]);
+  }, [clearTimeouts, hideDelay, popover]);
+
+  const focusFirstPanelItem = useCallback(() => {
+    popover.contentRef.current
+      ?.querySelector<HTMLElement>(
+        'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      )
+      ?.focus();
+  }, [popover.contentRef]);
 
-  const handleMouseEnter = useCallback(() => {
-    if (!clickLockedRef.current) {
+  const handleTriggerMouseEnter = useCallback(() => {
+    clearTimeouts();
+    if (!popover.isOpen) {
       scheduleShow();
     }
-  }, [scheduleShow]);
+  }, [clearTimeouts, popover.isOpen, scheduleShow]);
+
+  const handlePanelMouseEnter = useCallback(() => {
+    clearTimeouts();
+  }, [clearTimeouts]);
 
   const handleMouseLeave = useCallback(() => {
-    if (!clickLockedRef.current) {
+    if (!stickyRef.current) {
       scheduleHide();
     }
   }, [scheduleHide]);
 
-  const handleClick = useCallback(() => {
-    clearTimeouts();
-    if (popover.isOpen) {
-      clickLockedRef.current = false;
-      popover.hide();
-      triggerButtonRef.current?.focus();
-    } else {
-      clickLockedRef.current = true;
-      popover.show();
-    }
-  }, [popover, clearTimeouts]);
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      // Cancel the native invoker toggle so this guard is the single source of
+      // truth for trigger activation. popoverTarget still establishes the
+      // invoker relationship used by native light-dismiss and stacking.
+      event.preventDefault();
+      clearTimeouts();
+
+      if (event.detail === 0) {
+        stickyRef.current = true;
+        hoverOpenedAtRef.current = 0;
+        if (popover.isOpen) {
+          focusFirstPanelItem();
+        } else {
+          popover.show();
+        }
+      } else if (!popover.isOpen) {
+        stickyRef.current = true;
+        popover.show({skipAutoFocus: true});
+      } else if (Date.now() - hoverOpenedAtRef.current < CLICK_GUARD_MS) {
+        // A click that naturally follows a hover-open confirms the open state
+        // instead of toggling the panel shut. From here it behaves like any
+        // other click-open and stays pinned until explicit dismissal.
+        stickyRef.current = true;
+        hoverOpenedAtRef.current = 0;
+      } else {
+        popover.hide();
+        triggerButtonRef.current?.focus();
+      }
+    },
+    [clearTimeouts, focusFirstPanelItem, popover],
+  );
 
   useEffect(() => {
     return () => {
@@ -464,21 +526,25 @@ function DefaultMegaMenu({
         ref={mergeRefs(triggerButtonRef, ref)}
         type="button"
         {...popover.triggerProps}
+        // Native invoker prevents trigger light-dismiss.
+        popoverTarget={popover.id}
         onClick={handleClick}
-        onMouseEnter={handleMouseEnter}
+        onMouseEnter={handleTriggerMouseEnter}
         onMouseLeave={handleMouseLeave}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
-          stylex.props(styles.trigger, popover.isOpen && styles.triggerOpen),
+          focusOutlineProps.focusVisible(
+            styles.trigger,
+            popover.isOpen && styles.triggerOpen,
+          ),
         )}>
         {label}
-        <span
-          {...stylex.props(
-            styles.chevron,
-            popover.isOpen && styles.chevronOpen,
-          )}>
-          {chevronDownIcon}
-        </span>
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="inherit"
+          xstyle={[styles.chevron, popover.isOpen && styles.chevronOpen]}
+        />
       </button>
       {popover.render(
         <div
@@ -487,17 +553,15 @@ function DefaultMegaMenu({
           // for action menus; link mega menus are the documented anti-case).
           role="group"
           aria-label={label}
-          onMouseEnter={handleMouseEnter}
+          onMouseEnter={handlePanelMouseEnter}
           onMouseLeave={handleMouseLeave}
           {...stylex.props(styles.panelContainer)}>
           <div {...stylex.props(styles.panelContent)}>
             {/* Menu items section */}
             {items != null && (
-              <div {...stylex.props(styles.menuWrapper)}>
-                <Grid columns={2} gap={2}>
-                  {items}
-                </Grid>
-              </div>
+              <Grid columns={2} gap={2} xstyle={styles.menuWrapper}>
+                {items}
+              </Grid>
             )}
 
             {/* Featured section */}
@@ -526,7 +590,6 @@ function DrawerMegaMenu({
   featured,
 }: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'>) {
   const [isExpanded, setIsExpanded] = useState(false);
-  const chevronDownIcon = useIcon('chevronDown');
   const menuId = `mega-menu-${label.toLowerCase().replace(/\s+/g, '-')}`;
 
   return (
@@ -542,13 +605,15 @@ function DrawerMegaMenu({
           stylex.props(navItemStyles.item, styles.drawerHeader),
         )}>
         {label}
-        <span
-          {...stylex.props(
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="inherit"
+          xstyle={[
             styles.drawerChevron,
             isExpanded && styles.drawerChevronExpanded,
-          )}>
-          {chevronDownIcon}
-        </span>
+          ]}
+        />
       </button>
 
       {/* Animated expand/collapse container */}

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -34,6 +34,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles
@@ -61,14 +62,6 @@ const styles = stylex.create({
       ':active': colorVars['--color-overlay-pressed'],
     },
     border: 'none',
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
     color: 'inherit',
     fontFamily: 'inherit',
     textAlign: 'start',
@@ -249,7 +242,7 @@ export function TopNavMegaMenuItem({
       tabIndex={tabIndex}
       {...mergeProps(
         themeProps('top-nav-mega-menu-item'),
-        stylex.props(styles.desktop),
+        focusOutlineProps.focusVisible(styles.desktop),
       )}>
       {icon && <div {...stylex.props(styles.desktopIcon)}>{icon}</div>}
       <div {...stylex.props(styles.desktopContent)}>

package/src/TopNav/TopNavMenu.tsx

@@ -28,7 +28,7 @@ import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
@@ -37,6 +37,7 @@ import {useTopNavRenderMode} from './TopNavRenderContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {
   colorVars,
   spacingVars,
@@ -74,14 +75,6 @@ const styles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
     border: 'none',
     fontFamily: 'inherit',
   },
@@ -92,6 +85,14 @@ const styles = stylex.create({
   chevron: {
     display: 'inline-flex',
     alignItems: 'center',
+    // The registry chevron is a 1em SVG, so it has always rendered at the
+    // trigger's own font size (--text-label-size). Icon's size box would repin
+    // it to a fixed rem (the nearest, sm, is 1rem = 16px vs the 14px here), so
+    // hold it on the inherited em: same pixels, and still tracks the type
+    // scale when a theme changes the label size.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -106,9 +107,6 @@ const styles = stylex.create({
     minWidth: 280,
     padding: spacingVars['--spacing-1'],
   },
-  menuOffset: {
-    marginBlockStart: spacingVars['--spacing-1'],
-  },
   menuItem: {
     display: 'flex',
     alignItems: 'center',
@@ -128,14 +126,6 @@ const styles = stylex.create({
       },
     },
     border: 'none',
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   menuItemIcon: {
     display: 'flex',
@@ -179,6 +169,11 @@ const drawerStyles = stylex.create({
   },
   chevron: {
     display: 'inline-flex',
+    // Same em pin as styles.chevron above — the drawer header inherits
+    // --text-label-size from navItemStyles.item.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -332,7 +327,6 @@ export function TopNavMenu({
   hideDelay = 200,
 }: TopNavMenuProps) {
   const renderMode = useTopNavRenderMode();
-  const chevronDownIcon = useIcon('chevronDown');
   const {closeMobileNav} = useAppShellMobile();
   const LinkComponent = useLinkComponent();
   const [drawerExpanded, setDrawerExpanded] = useState(false);
@@ -346,7 +340,6 @@ export function TopNavMenu({
     // wrapper would announce an unnamed dialog around the menu and make the
     // trigger claim aria-haspopup="dialog" for menu content (see TabMenu).
     role: 'none',
-    xstyle: styles.menuOffset,
   });
 
   const {triggerProps, contentProps, menuRef, setTriggerEl} =
@@ -441,13 +434,15 @@ export function TopNavMenu({
           aria-controls={`${menuId}-items`}
           {...stylex.props(navItemStyles.item, drawerStyles.header)}>
           {label}
-          <span
-            {...stylex.props(
+          <Icon
+            icon="chevronDown"
+            size="sm"
+            color="inherit"
+            xstyle={[
               drawerStyles.chevron,
               drawerExpanded && drawerStyles.chevronExpanded,
-            )}>
-            {chevronDownIcon}
-          </span>
+            ]}
+          />
         </button>
         <div
           id={`${menuId}-items`}
@@ -496,16 +491,18 @@ export function TopNavMenu({
         {...triggerProps}
         {...mergeProps(
           themeProps('top-nav-menu'),
-          stylex.props(styles.trigger, popover.isOpen && styles.triggerOpen),
+          focusOutlineProps.focusVisible(
+            styles.trigger,
+            popover.isOpen && styles.triggerOpen,
+          ),
         )}>
         {label}
-        <span
-          {...stylex.props(
-            styles.chevron,
-            popover.isOpen && styles.chevronOpen,
-          )}>
-          {chevronDownIcon}
-        </span>
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="inherit"
+          xstyle={[styles.chevron, popover.isOpen && styles.chevronOpen]}
+        />
       </button>
       {popover.render(
         <div
@@ -530,7 +527,7 @@ export function TopNavMenu({
                 tabIndex={-1}
                 href={item.href}
                 onClick={item.onClick}
-                {...stylex.props(styles.menuItem)}>
+                {...focusOutlineProps.focusVisible(styles.menuItem)}>
                 <div {...stylex.props(styles.menuItemIcon)}>{item.icon}</div>
                 <div {...stylex.props(styles.menuItemContent)}>
                   <span {...stylex.props(styles.menuItemTitle)}>
@@ -549,7 +546,7 @@ export function TopNavMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.menuOffset,
+          offset: spacingVars['--spacing-1'],
         },
       )}
     </>

package/src/TreeList/TreeList.doc.mjs

@@ -32,6 +32,7 @@ export const docs = {
     ],
     vars: [
       {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
+      {name: '--tree-list-row-gap', description: 'Vertical gap between adjacent rows. Default `2px` (var(--spacing-0-5)) gives a subtle separation; set it on the `tree-list` target to widen or close the gap. The connector guides span the gap automatically (the line stays continuous) and do not overhang the last row, so no guide-height tuning is needed.', default: 'var(--spacing-0-5)'},
     ],
   },
   components: [
@@ -82,6 +83,7 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
       {guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
+      {guidance: true, description: 'Leaf rows reserve space for a chevron column whenever the tree has any expandable item to line up under; only a fully flat tree (no expandable items at all) renders its rows flush. Rely on this rather than nudging indentation with custom CSS.'},
       {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
       {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
     ],
@@ -109,6 +111,7 @@ export const docsZh = {
     ],
     vars: [
       {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。', default: 'var(--spacing-4)'},
+      {name: '--tree-list-row-gap', description: '相邻行之间的垂直间距。默认 `2px`（var(--spacing-0-5)）提供细微的分隔；在 `tree-list` 目标上设置以加宽或关闭间距。连接引导线会自动跨越该间距（线保持连续）且不会超出最后一行，因此无需调整引导线高度。', default: 'var(--spacing-0-5)'},
     ],
   },
   components: [
@@ -159,6 +162,7 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
       {guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
+      {guidance: true, description: 'Leaf rows reserve space for a chevron column whenever the tree has any expandable item to line up under; only a fully flat tree (no expandable items at all) renders its rows flush. Rely on this rather than nudging indentation with custom CSS.'},
       {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
       {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
     ],
@@ -175,6 +179,7 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
       {guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
+      {guidance: true, description: 'Leaf rows reserve space for a chevron column whenever the tree has any expandable item to line up under; only a fully flat tree (no expandable items at all) renders its rows flush. Rely on this rather than nudging indentation with custom CSS.'},
       {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
       {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
     ],