@astryxdesign/core 0.4.7 → 0.5.0-canary.1f8525f

package/src/Tooltip/useTooltip.tsx

@@ -31,8 +31,8 @@ import {
   type LayerTouchTrigger,
 } from '../Layer/useTouchTrigger';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {themeProps} from '../utils/themeProps';
-import {isImeKeyEvent} from '../utils/ime';
 import {
   colorVars,
   radiusVars,
@@ -144,6 +144,11 @@ export interface TooltipOptions {
    * - `true`: force-show the tooltip (hover/focus hide is suppressed)
    * - `false`: force-hide the tooltip
    * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+   *
+   * A controlled tooltip still takes Escape when it is the top-most layer, and
+   * answers by calling `onHide` without hiding itself — closing is your
+   * update's decision, exactly as for a controlled Dialog. Ignore the call and
+   * the tip stays, and so does the press: nothing underneath dismisses.
    */
   isOpen?: boolean;
 
@@ -518,34 +523,52 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }
   }, [isOpen, clearTimeouts, layer]);
 
-  // Dismiss on Escape (WCAG 1.4.13 — dismissible). Uncontrolled tooltips only;
-  // a controlled tooltip's visibility is owned by the consumer. The listener is
-  // mounted for the lifetime of an uncontrolled tooltip rather than gated on
-  // `layer.isOpen` (React state, which can lag a frame behind the DOM) —
-  // `layer.hide()` self-guards and no-ops when the layer is already closed.
-  // Guarded against IME composition-cancel.
-  useEffect(() => {
-    if (isOpen !== undefined) {
-      return;
-    }
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== 'Escape') {
-        return;
+  // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
+  // stack. A visible tip is the top-most layer, so it takes the press and
+  // consumes it: Escape hides the tip and leaves the dialog underneath open.
+  // The user presses Escape again to close that. Consuming (rather than also
+  // dismissing what is beneath) keeps one rule with no per-component
+  // exceptions, and the failure mode is one extra keystroke instead of a
+  // dialog closing under someone who only wanted the tip gone.
+  //
+  // A controlled tooltip stays on the stack and takes the press like any other
+  // layer, but answers it by reporting instead of hiding: `isOpen` is the
+  // consumer's value, so only their update may change it. Same contract as a
+  // controlled Dialog.
+  useLayerDismissal({
+    // Registered for the hook's lifetime rather than gated on `layer.isOpen`:
+    // that state can lag a frame behind the DOM, so a press arriving right after
+    // the layer appears would find nothing registered. Because this layer
+    // CONSUMES the press, a stale registration would be worse than a missed one
+    // — it would silently eat Escapes meant for the dialog underneath — so
+    // presence is answered from the DOM at press time instead of from state.
+    isActive: true,
+    isPresent: () => {
+      const el =
+        typeof document === 'undefined'
+          ? null
+          : document.getElementById(layer.id);
+      if (el == null) {
+        return false;
       }
-      if (isImeKeyEvent(e)) {
-        // Ignore Escape that is committing/cancelling an IME composition;
-        // see utils/ime.ts for why.
-        return;
+      try {
+        return el.matches(':popover-open');
+      } catch {
+        // Browsers without the Popover API (and some test environments) cannot
+        // answer the selector; fall back to the hook's own state.
+        return layer.isOpen;
       }
+    },
+    onDismiss: () => {
       clearTimeouts();
       clearTapOpen();
+      if (isOpen !== undefined) {
+        onHide?.();
+        return;
+      }
       layer.hide();
-    };
-    document.addEventListener('keydown', handleKeyDown);
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [isOpen, layer, clearTimeouts, clearTapOpen]);
+    },
+  });
 
   // Render function that wraps layer.render with tooltip styling
   const renderTooltip = useCallback(

package/src/TopNav/TopNavHeading.tsx

@@ -34,7 +34,8 @@ import {Link} from '../Link';
 import {Icon} from '../Icon';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';
@@ -53,7 +54,7 @@ const styles = stylex.create({
     minHeight: spacingVars['--spacing-8'],
     paddingInlineStart: {
       default: spacingVars['--spacing-2'],
-      ':has(.astryx-navicon)': 0,
+      ':has(.astryx-nav-icon)': 0,
     },
     paddingInlineEnd: spacingVars['--spacing-2'],
     paddingBlock: 0,
@@ -189,7 +190,7 @@ const styles = stylex.create({
     minHeight: spacingVars['--spacing-8'],
     paddingInlineStart: {
       default: spacingVars['--spacing-2'],
-      ':has(.astryx-navicon)': 0,
+      ':has(.astryx-nav-icon)': 0,
     },
     paddingInlineEnd: spacingVars['--spacing-2'],
     paddingBlock: 0,
@@ -363,7 +364,7 @@ export function TopNavHeading({
   // setTriggerEl belongs on the chevron button, not this root: it is the
   // focus-restore target and a <div> cannot take focus. triggerRef stays here
   // because the panel anchors to the whole heading.
-  const setRef = mergeRefs<HTMLElement>(
+  const setRef = useMergedRefs<HTMLElement>(
     rootRef,
     ref,
     menu ? popover.triggerRef : undefined,

package/src/TopNav/TopNavMegaMenu.tsx

@@ -53,7 +53,7 @@ import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {Grid} from '../Grid/Grid';
 import {Icon} from '../Icon';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
@@ -61,6 +61,7 @@ import {useTopNavRenderMode} from './TopNavRenderContext';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles
 // =============================================================================
@@ -451,7 +452,7 @@ function DefaultMegaMenu({
   return (
     <>
       <button
-        ref={mergeRefs(triggerButtonRef, setTriggerEl, ref)}
+        ref={useMergedRefs(triggerButtonRef, setTriggerEl, ref)}
         type="button"
         {...popover.triggerProps}
         {...hoverTriggerProps}

package/src/TopNav/TopNavMenu.tsx

@@ -29,7 +29,8 @@ import {useMenuHover} from '../hooks/useMenuHover';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
 import {Icon} from '../Icon';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
@@ -361,7 +362,7 @@ export function TopNavMenu({
       popoverId: popover.id,
     });
 
-  const setTriggerRef = mergeRefs<HTMLButtonElement>(
+  const setTriggerRef = useMergedRefs<HTMLButtonElement>(
     triggerButtonRef,
     popover.triggerRef,
     setTriggerEl,
@@ -426,7 +427,7 @@ export function TopNavMenu({
 
   // Menu container carries both the hover hook's ref (for its open/close
   // focus management) and the list-focus ref (for roving tabindex/typeahead).
-  const setMenuRef = mergeRefs<HTMLDivElement>(menuRef, listRef);
+  const setMenuRef = useMergedRefs<HTMLDivElement>(menuRef, listRef);
 
   // Mobile bar: hide menus entirely
   if (renderMode === 'mobile-bar') {

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -60,6 +60,11 @@ export const docs = {
       description: 'Maximum dropdown items to display.',
       default: '10',
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -169,6 +174,11 @@ export const docsZh = {
       description: '下拉列表显示的最大项目数。',
       default: '10',
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: '下拉菜单的固定像素宽度。菜单不会小于其锚点宽度。',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -253,6 +263,7 @@ export const docsDense = {
     placeholder: 'Input placeholder.',
     hasEntriesOnFocus: 'Bootstrap results on focus.',
     maxMenuItems: 'Max dropdown items.',
+    menuWidth: 'Fixed dropdown width in pixels.',
     emptySearchResultsText: 'Text when no results.',
     isDisabled: 'Whether input disabled.',
     hasAutoFocus: 'Auto-focus on mount.',

package/src/Typeahead/BaseTypeahead.tsx

@@ -41,12 +41,13 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {getKey, mergeProps, mergeRefs} from '../utils';
+import {getKey, groupItems, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -93,6 +94,9 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   maxMenuItems?: number;
 
+  /** Fixed dropdown width in pixels. Never shrinks below the anchor width. */
+  menuWidth?: number;
+
   /**
    * Text shown when no results found.
    * @default 'No results found'
@@ -226,6 +230,18 @@ const styles = stylex.create({
   popover: {
     minWidth: 'anchor-size(width)',
   },
+  popoverCustomWidth: (width: number) => ({
+    width: `${width}px`,
+  }),
+  groupHeading: {
+    paddingInline: spacingVars['--spacing-2'],
+    paddingBlockStart: spacingVars['--spacing-2'],
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+    userSelect: 'none',
+  },
   item: {
     boxSizing: 'border-box',
     display: 'flex',
@@ -316,6 +332,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   placeholder: placeholderFromProps,
   hasEntriesOnFocus = false,
   maxMenuItems = 10,
+  menuWidth,
   emptySearchResultsText: emptySearchResultsTextFromProps,
   isDisabled = false,
   isFocusableDisabled = false,
@@ -691,6 +708,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           e.preventDefault();
           popover.hide();
           break;
+        case 'Tab':
+          // Dismiss here rather than from the blur this press produces:
+          // hiding a top-layer popover during the focusout makes Chrome
+          // abandon the in-flight focus move and drop focus to <body>, so the
+          // user's Tab appears to do nothing. Selector and MultiSelector
+          // already dismiss on this keydown.
+          popover.hide();
+          break;
         case 'Home':
           if (popover.isOpen) {
             e.preventDefault();
@@ -760,7 +785,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   return (
     <>
       <input
-        ref={mergeRefs(ref, inputRef, fallbackAnchorRef)}
+        ref={useMergedRefs(ref, inputRef, fallbackAnchorRef)}
         id={inputId}
         type="text"
         role="combobox"
@@ -835,44 +860,71 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
               {emptySearchResultsText}
             </div>
           ) : (
-            results.map((item, index) => {
-              const itemKey = getKey(item.id, index);
-              const isSelected = itemKey === selectedKey;
-              return (
-                <div
-                  key={itemKey}
-                  id={getItemId(index)}
-                  role="option"
-                  aria-selected={isSelected}
-                  tabIndex={-1}
-                  onClick={() => handleSelect(item)}
-                  onMouseEnter={() => setHighlightedIndex(index)}
-                  {...stylex.props(
-                    styles.item,
-                    itemSizeStyles[size],
-                    index === highlightedIndex && styles.itemHighlighted,
-                    isSelected && styles.itemSelected,
-                  )}>
-                  <span {...stylex.props(styles.itemContent)}>
-                    {renderItem ? (
-                      renderItem(item)
-                    ) : (
-                      <TypeaheadItem item={item} />
+            (() => {
+              let flatIndex = 0;
+              const renderOption = (item: T) => {
+                const index = flatIndex++;
+                const itemKey = getKey(item.id, index);
+                const isSelected = itemKey === selectedKey;
+                return (
+                  <div
+                    key={itemKey}
+                    id={getItemId(index)}
+                    role="option"
+                    aria-selected={isSelected}
+                    tabIndex={-1}
+                    onClick={() => handleSelect(item)}
+                    onMouseEnter={() => setHighlightedIndex(index)}
+                    {...stylex.props(
+                      styles.item,
+                      itemSizeStyles[size],
+                      index === highlightedIndex && styles.itemHighlighted,
+                      isSelected && styles.itemSelected,
+                    )}>
+                    <span {...stylex.props(styles.itemContent)}>
+                      {renderItem ? (
+                        renderItem(item)
+                      ) : (
+                        <TypeaheadItem item={item} />
+                      )}
+                    </span>
+                    {isSelected && (
+                      <Icon icon="check" size="sm" color="primary" />
                     )}
-                  </span>
-                  {isSelected && (
-                    <Icon icon="check" size="sm" color="primary" />
-                  )}
-                </div>
-              );
-            })
+                  </div>
+                );
+              };
+
+              return groupItems(results, {ungroupedFirst: true}).map(group => {
+                const options = group.items.map(renderOption);
+                if (group.heading == null) {
+                  return options;
+                }
+                return (
+                  <div
+                    key={`group-${group.heading}`}
+                    role="group"
+                    aria-label={group.heading}>
+                    <div
+                      aria-hidden="true"
+                      {...stylex.props(styles.groupHeading)}>
+                      {group.heading}
+                    </div>
+                    {options}
+                  </div>
+                );
+              });
+            })()
           )}
         </div>,
         {
           placement: 'below',
           alignment: 'start',
           offset: spacingVars['--spacing-1'],
-          xstyle: styles.popover,
+          xstyle: [
+            styles.popover,
+            menuWidth != null && styles.popoverCustomWidth(menuWidth),
+          ],
         },
       )}
     </>

package/src/Typeahead/Typeahead.doc.mjs

@@ -171,6 +171,11 @@ export const docs = {
       description:
         'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
+    {
+      name: 'startIcon',
+      type: 'IconType | ReactNode',
+      description: 'SVG icon component displayed at the start of the input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Typeahead/Typeahead.test.tsx

@@ -420,6 +420,55 @@ describe('BaseTypeahead focus-out', () => {
     });
   });
 
+  it('closes the list on the Tab keydown, before the blur it produces', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // No blur is fired here on purpose: dismissing from the blur instead lets
+    // the popover close mid-focus-move, which Chrome answers by dropping
+    // focus to <body>.
+    fireEvent.keyDown(input, {key: 'Tab'});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('Tab from the input with the list open moves focus to the next control', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+        <button type="button">Next</button>
+      </>,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    await user.keyboard('{Tab}');
+    expect(screen.getByRole('button', {name: 'Next'})).toHaveFocus();
+  });
+
   it('keeps the dropdown open when focus moves into the anchor wrapper', async () => {
     const anchor = document.createElement('div');
     document.body.appendChild(anchor);

package/src/Typeahead/Typeahead.tsx

@@ -45,13 +45,14 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
-import {getInputARIA, isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
+import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export type {
   InputStatus as TypeaheadStatus,
   InputStatusType as TypeaheadStatusType,
@@ -418,7 +419,7 @@ export function Typeahead<T extends SearchableItem>({
   const typeaheadContent = (
     <>
       <div
-        ref={mergeRefs(
+        ref={useMergedRefs(
           wrapperRef,
           disabledMessageTooltip.ref,
           inputGroup ? ref : undefined,

package/src/hooks/index.ts

@@ -56,6 +56,8 @@ export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
 
 export {useMediaQuery} from './useMediaQuery';
 
+export {useMergedRefs} from './useMergedRefs';
+
 export {useOverflow} from './useOverflow';
 export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
 

package/src/hooks/useContainerReveal.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
     {
       name: 'getContainerProps',
       type: '(options?: ContainerRevealOptions) => {className?: string; style?: CSSProperties}',
-      description: 'Spread onto the container whose hover/focus-within drives the reveal. Accepts hoverDelay (ms the pointer must dwell before the reveal starts — a hover-intent gate like Tooltip\'s and HoverCard\'s delay, so a cursor sweeping across a list leaves nothing painted behind it) and forceState ("active" | "inactive") to pin the trigger state when a caller owns it — a motion gate, a scroll, a row whose menu is open. "inactive" still yields to keyboard focus and coarse pointers.',
+      description: 'Spread onto the container whose hover/focus-within drives the reveal. Accepts hoverDelay (ms the pointer must dwell before the reveal starts: a hover-intent gate like Tooltip\'s and HoverCard\'s delay, so a cursor sweeping across a list leaves nothing painted behind it) and forceState ("active" | "inactive") to pin the trigger state when a caller owns it: a motion gate, a scroll, or a row whose menu is open. "inactive" still yields to keyboard focus and coarse pointers.',
     },
     {
       name: 'getContentRevealProps',
@@ -61,7 +61,7 @@ export const docsDense = {
     'options.isEnabled': 'when false hook is inert: no container styles, content getters return no styles, content always shown. Read every render, so it can flip after mount.',
   },
   returnDescriptions: {
-    getContainerProps: 'spread onto container whose hover/focus-within drives reveal. Accepts hoverDelay (ms dwell before reveal starts — hover-intent gate like Tooltip / HoverCard delay) + forceState ("active" | "inactive") to pin trigger state when a caller owns it. "inactive" yields to keyboard focus + coarse pointers.',
+    getContainerProps: 'spread onto container whose hover/focus-within drives reveal. Accepts hoverDelay (ms dwell before reveal starts: hover-intent gate like Tooltip / HoverCard delay) + forceState ("active" | "inactive") to pin trigger state when a caller owns it. "inactive" yields to keyboard focus + coarse pointers.',
     getContentRevealProps: 'spread onto each revealed / concealed child. Accepts isRevealInverted (conceal-on-hover), isLayoutPreserved (reserve layout box while hidden) + forceVisibility ("shown" | "hidden") to pin this element regardless of container. "hidden" yields to focus.',
   },
   usage: {

package/src/hooks/useFocusTrap.test.tsx

@@ -208,6 +208,20 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     expect(target).toHaveFocus();
     expect(screen.getByTestId('outside')).not.toHaveFocus();
   });
+
+  it('leaves Tab alone when focus is outside a trap with no tabbable controls', () => {
+    render(
+      <Trap>
+        <div role="option" tabIndex={-1} data-testid="option">
+          Option
+        </div>
+      </Trap>,
+    );
+    const outside = screen.getByTestId('outside');
+    outside.focus();
+
+    expect(fireEvent.keyDown(outside, {key: 'Tab'})).toBe(true);
+  });
 });
 
 describe('FOCUSABLE_SELECTOR href matching', () => {