@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Tooltip/Tooltip.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
+            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
           default: "'auto'",
         },
         {
@@ -197,7 +197,7 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
           default: "'auto'",
         },
         {
@@ -274,7 +274,7 @@ export const docsDense = {
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger tooltip.',
-        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens (info icon rendered as a button); none = never on touch.',
+        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (info icon rendered as a button); none = never on touch.',
         isEnabled: 'Enables/disables tooltip triggers.',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',

package/src/Tooltip/Tooltip.tsx

@@ -95,9 +95,10 @@ export interface TooltipProps {
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */

package/src/Tooltip/useTooltip.doc.mjs

@@ -11,8 +11,8 @@ export const docs = {
     {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
     {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
     {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
-    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
-    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},
+    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.', default: "'auto'"},
+    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},
     {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
     {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
     {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},
@@ -49,7 +49,7 @@ export const docsDense = {
     alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
-    focusTrigger: 'when focus opens tooltip; auto = naturally focusable elements only.',
+    focusTrigger: 'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
     touchTrigger: 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
     isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',

package/src/Tooltip/useTooltip.tsx

@@ -31,6 +31,7 @@ import {
   type LayerTouchTrigger,
 } from '../Layer/useTouchTrigger';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {registerLayerSurface} from '../Layer/layerSurfacePress';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -109,9 +110,10 @@ export interface TooltipOptions {
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */
@@ -264,6 +266,7 @@ function isFocusable(element: HTMLElement): boolean {
  * {tooltip.renderTooltip('Helpful tooltip text')}
  * ```
  */
+
 export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   const {
     placement = 'above',
@@ -425,9 +428,32 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     [isTouchPointerRef, layerId, scheduleHide],
   );
 
+  // Under `auto`, whether focus counts is decided when it arrives, not when
+  // the listeners attach: a roving-tabindex member that was `tabindex="-1"`
+  // then can be the tab stop now. A trigger that receives focus is focusable
+  // by definition; focus inside it counts only while the trigger is
+  // focusable too, so a plain wrapper still ignores its children's focus.
+  const isFocusForTrigger = useCallback(
+    (e: Event): boolean => {
+      if (focusTrigger === 'always') {
+        return true;
+      }
+      const triggerEl = e.currentTarget as HTMLElement | null;
+      return (
+        triggerEl != null && (e.target === triggerEl || isFocusable(triggerEl))
+      );
+    },
+    [focusTrigger],
+  );
+
+  // Whether the trigger's current focus counted when it arrived, so its blur
+  // hides the tooltip even if the trigger has since left the tab order.
+  const focusCountedRef = useRef(false);
+
   const handleFocusIn = useCallback(
     (e: Event) => {
-      if (!isEnabled) {
+      focusCountedRef.current = isFocusForTrigger(e);
+      if (!isEnabled || !focusCountedRef.current) {
         return;
       }
       // A tap focuses the trigger it activates, and `:focus-visible` does not
@@ -447,12 +473,25 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       clearTimeouts();
       showLayer();
     },
-    [isEnabled, isTouchInteraction, clearTimeouts, showLayer],
+    [
+      isEnabled,
+      isFocusForTrigger,
+      isTouchInteraction,
+      clearTimeouts,
+      showLayer,
+    ],
   );
 
-  const handleFocusOut = useCallback(() => {
-    scheduleHide();
-  }, [scheduleHide]);
+  const handleFocusOut = useCallback(
+    (e: Event) => {
+      if (!focusCountedRef.current && !isFocusForTrigger(e)) {
+        return;
+      }
+      focusCountedRef.current = false;
+      scheduleHide();
+    },
+    [isFocusForTrigger, scheduleHide],
+  );
 
   // Pressing the trigger hides its own tooltip: once the control is activated
   // the hint has served its purpose, and a tooltip lingering over a
@@ -504,12 +543,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
         el.addEventListener('pointerdown', handlePointerDown);
 
-        // Attach focus listeners based on focusTrigger option
-        const shouldAttachFocus =
-          focusTrigger === 'always' ||
-          (focusTrigger === 'auto' && isFocusable(el));
-
-        if (shouldAttachFocus) {
+        // Focus listeners unless focus never opens the tooltip; `auto` decides
+        // per event (isFocusForTrigger).
+        if (focusTrigger !== 'never') {
           el.addEventListener('focusin', handleFocusIn);
           el.addEventListener('focusout', handleFocusOut);
         }
@@ -636,7 +672,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       };
 
       return renderLayer(
-        <div {...stylex.props(styles.content)}>{children}</div>,
+        // FR11: React bubbles a press on the surface to the trigger's
+        // ancestors, portaled or not. A registered surface counts as
+        // something else in the shared interactive-ancestor walk, so a
+        // clickable container around the trigger leaves the press alone while
+        // document listeners still see it.
+        <div ref={registerLayerSurface} {...stylex.props(styles.content)}>
+          {children}
+        </div>,
         renderProps,
       );
     },

package/src/TopNav/TopNav.tsx

@@ -21,7 +21,6 @@ import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import {useTranslator} from '../i18n';
 import {TopNavSlotContext} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {useTopNavMobileContent} from './TopNavMobileContentContext';
@@ -30,6 +29,14 @@ import {MobileNav} from '../MobileNav/MobileNav';
 import {MobileNavToggle} from '../MobileNav/MobileNavToggle';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/TopNav/TopNav.generated';
+import {isRenderable} from '../utils/isRenderable';
+
+registerEnglishFallback(english);
 
 /**
  * Base TopNav styles
@@ -193,17 +200,19 @@ export function TopNav({
   ref,
   ...props
 }: TopNavProps) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const label = labelFromProps ?? t('@astryx.topNav.landmarkLabel');
   const renderMode = useTopNavRenderMode();
   const mobileContent = useTopNavMobileContent();
   const {hasAutoToggle} = useAppShellMobile();
   const resolvedStartContent = startContent ?? children;
-  const hasCenterContent = centerContent != null;
-  const hasCollapsibleContent =
-    resolvedStartContent != null || centerContent != null;
+  // The layout flags use the same test as the slots they gate.
+  const hasCenterContent = isRenderable(centerContent);
+  const hasStartContent = isRenderable(resolvedStartContent);
+  const hasMobileContent = isRenderable(mobileContent);
+  const hasCollapsibleContent = hasStartContent || hasCenterContent;
   // Show mobile toggle when there's ANY drawer content — own items OR SideNav via context
-  const hasMobileDrawerContent = hasCollapsibleContent || mobileContent != null;
+  const hasMobileDrawerContent = hasCollapsibleContent || hasMobileContent;
 
   // =========================================================================
   // Mobile bar mode — heading + endContent + toggle, hide nav items.
@@ -223,7 +232,7 @@ export function TopNav({
           style,
         )}
         {...props}>
-        {heading && (
+        {isRenderable(heading) && (
           <div {...stylex.props(styles.mobileBarHeading)}>{heading}</div>
         )}
         <div {...stylex.props(styles.mobileBarEnd)}>
@@ -240,7 +249,7 @@ export function TopNav({
   // =========================================================================
   if (renderMode === 'drawer') {
     // Only render if there are collapsible items or extra content
-    if (!hasCollapsibleContent && !mobileContent) {
+    if (!hasCollapsibleContent && !hasMobileContent) {
       return null;
     }
 
@@ -252,10 +261,10 @@ export function TopNav({
             {centerContent}
           </div>
         )}
-        {hasCollapsibleContent && mobileContent && (
+        {hasCollapsibleContent && hasMobileContent && (
           <Divider xstyle={styles.drawerDivider} />
         )}
-        {mobileContent && (
+        {hasMobileContent && (
           <div {...stylex.props(styles.drawerExtraContent)}>
             {mobileContent}
           </div>
@@ -285,8 +294,10 @@ export function TopNav({
       )}
       {...props}>
       <div {...stylex.props(styles.leftSection)}>
-        {heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
-        {resolvedStartContent && (
+        {isRenderable(heading) && (
+          <div {...stylex.props(styles.heading)}>{heading}</div>
+        )}
+        {hasStartContent && (
           <TopNavSlotContext value="start">
             <div {...stylex.props(styles.startContent)}>
               {resolvedStartContent}
@@ -304,7 +315,7 @@ export function TopNav({
           <TopNavSlotContext value="end">{endContent}</TopNavSlotContext>
         </div>
       ) : (
-        endContent && (
+        isRenderable(endContent) && (
           <div {...stylex.props(styles.endContent)}>
             <TopNavSlotContext value="end">{endContent}</TopNavSlotContext>
           </div>

package/src/TopNav/TopNavHeading.tsx

@@ -44,7 +44,14 @@ import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';
 import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';
 import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/TopNav/TopNavHeading.generated';
+import {isRenderable} from '../utils/isRenderable';
+
+registerEnglishFallback(english);
 
 // =============================================================================
 // Styles
@@ -333,7 +340,7 @@ export function TopNavHeading({
   ref,
   ...props
 }: TopNavHeadingProps) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const LinkComponent = useLinkComponent(as);
   // When the logo is wrapped in a link it needs its own accessible name (the
   // logo image itself is decorative). Prefer an explicit logoLabel, fall back
@@ -457,7 +464,7 @@ export function TopNavHeading({
     />
   );
 
-  const headerEndContentElement = headerEndContent && (
+  const headerEndContentElement = isRenderable(headerEndContent) && (
     <span {...stylex.props(styles.headerEndContent)}>{headerEndContent}</span>
   );
 
@@ -469,7 +476,7 @@ export function TopNavHeading({
       {...stylex.props(styles.popoverHeading)}
       // A close affordance, not the trigger: dismiss only.
       onClick={closeMenu}>
-      {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
+      {isRenderable(logo) && <span {...stylex.props(styles.logo)}>{logo}</span>}
       {renderTextContent(
         <Icon
           icon="chevronDown"
@@ -501,7 +508,9 @@ export function TopNavHeading({
           style,
         )}
         {...props}>
-        {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
+        {isRenderable(logo) && (
+          <span {...stylex.props(styles.logo)}>{logo}</span>
+        )}
       </Element>
     );
   }
@@ -520,7 +529,9 @@ export function TopNavHeading({
           style,
         )}
         {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>
-        {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
+        {isRenderable(logo) && (
+          <span {...stylex.props(styles.logo)}>{logo}</span>
+        )}
         {renderTextContent()}
         {headerEndContentElement}
         {chevronElement}
@@ -542,14 +553,19 @@ export function TopNavHeading({
             className,
             style,
           )}>
-          {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
+          {isRenderable(logo) && (
+            <span {...stylex.props(styles.logo)}>{logo}</span>
+          )}
           {renderTextContent(
             // Stays a <button>: this box is the popover trigger, so it carries
             // the accessible name and handlers — only the glyph moves to Icon.
             <button
               ref={setTriggerEl}
               type="button"
-              aria-label={t('@astryx.topNav.heading.openMenu')}
+              aria-label={t('@astryx.topNav.heading.openMenu', {
+                heading: heading ?? '',
+                hasHeading: heading ? 'true' : 'false',
+              })}
               onClick={e => {
                 e.stopPropagation();
                 triggerProps.onClick();
@@ -611,7 +627,7 @@ export function TopNavHeading({
             className,
             style,
           )}>
-          {logo &&
+          {isRenderable(logo) &&
             (headingHref ? (
               <LinkComponent
                 href={headingHref}
@@ -631,7 +647,10 @@ export function TopNavHeading({
               <button
                 ref={setTriggerEl}
                 type="button"
-                aria-label={t('@astryx.topNav.heading.openMenu')}
+                aria-label={t('@astryx.topNav.heading.openMenu', {
+                  heading: heading ?? '',
+                  hasHeading: heading ? 'true' : 'false',
+                })}
                 onClick={e => {
                   e.stopPropagation();
                   triggerProps.onClick();
@@ -693,7 +712,7 @@ export function TopNavHeading({
           style,
         )}
         {...props}>
-        {logo &&
+        {isRenderable(logo) &&
           (headingHref ? (
             <LinkComponent
               href={headingHref}
@@ -747,7 +766,7 @@ export function TopNavHeading({
         style,
       )}
       {...props}>
-      {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
+      {isRenderable(logo) && <span {...stylex.props(styles.logo)}>{logo}</span>}
       {renderTextContent()}
       {headerEndContentElement}
       {chevronElement}

package/src/TopNav/TopNavMegaMenu.tsx

@@ -38,6 +38,7 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {isRenderable} from '../utils/isRenderable';
 import {
   colorVars,
   spacingVars,
@@ -538,14 +539,14 @@ function DefaultMegaMenu({
           {...stylex.props(styles.panelContainer)}>
           <div {...stylex.props(styles.panelContent)}>
             {/* Menu items section */}
-            {items != null && (
+            {isRenderable(items) && (
               <Grid columns={2} gap={2} xstyle={styles.menuWrapper}>
                 {items}
               </Grid>
             )}
 
             {/* Featured section */}
-            {featured != null && (
+            {isRenderable(featured) && (
               <div {...stylex.props(styles.featured)}>{featured}</div>
             )}
           </div>
@@ -630,7 +631,7 @@ function DrawerMegaMenu({
           {items}
 
           {/* Featured card */}
-          {featured != null && (
+          {isRenderable(featured) && (
             <div {...stylex.props(styles.drawerFeatured)}>{featured}</div>
           )}
         </div>

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -26,7 +26,7 @@ import {
   typeScaleVars,
   fontWeightVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
@@ -70,6 +70,10 @@ const styles = stylex.create({
     color: colorVars['--color-text-accent'],
     textDecoration: 'none',
   },
+  // A transform needs a box: an inline span would not mirror.
+  linkArrow: {
+    display: 'inline-block',
+  },
 });
 
 // =============================================================================
@@ -175,7 +179,10 @@ export function TopNavMegaMenuFeaturedCard({
         )}
         {linkLabel && linkHref && (
           <LinkComponent href={linkHref} {...stylex.props(styles.link)}>
-            {linkLabel} →
+            {linkLabel}{' '}
+            {/* The arrow points toward the inline end, so it mirrors in RTL
+                (design:bidirectionality DR4); U+2192 is not bidi-mirrored. */}
+            <span {...stylex.props(styles.linkArrow, rtlStyles.mirror)}>→</span>
           </LinkComponent>
         )}
         {children}

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -37,6 +37,7 @@ import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {isRenderable} from '../utils/isRenderable';
 
 // =============================================================================
 // Styles
@@ -231,7 +232,9 @@ export function TopNavMegaMenuItem({
           className,
           style,
         )}>
-        {icon && <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>}
+        {isRenderable(icon) && (
+          <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>
+        )}
         <div {...stylex.props(styles.drawerItemContent)}>
           {title}
           {description && (
@@ -266,7 +269,9 @@ export function TopNavMegaMenuItem({
         className,
         style,
       )}>
-      {icon && <div {...stylex.props(styles.desktopIcon)}>{icon}</div>}
+      {isRenderable(icon) && (
+        <div {...stylex.props(styles.desktopIcon)}>{icon}</div>
+      )}
       <div {...stylex.props(styles.desktopContent)}>
         <span {...stylex.props(styles.desktopTitle)}>{title}</span>
         {description && (

package/src/TopNav/TopNavMenu.tsx

@@ -55,6 +55,7 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
+import {isRenderable} from '../utils/isRenderable';
 
 // =============================================================================
 // Styles
@@ -532,7 +533,7 @@ export function TopNavMenu({
                   interactionOverlayStyles.backgroundColor,
                   drawerStyles.item,
                 )}>
-                {item.icon && (
+                {isRenderable(item.icon) && (
                   <span {...stylex.props(drawerStyles.itemIcon)}>
                     {item.icon}
                   </span>