@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Tokenizer/Tokenizer.tsx

@@ -156,6 +156,19 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   hasEntriesOnFocus?: boolean;
   /** Max dropdown items. @default 10 */
   maxMenuItems?: number;
+  /** Fixed dropdown width in pixels. Never shrinks below the input width. */
+  menuWidth?: number;
+  /**
+   * Minimum query length before the search source is queried. Below it no
+   * search runs and the menu stays closed — useful for remote sources where
+   * one or two characters match too much to be worth fetching.
+   *
+   * With `hasCreate`, the "Create" entry rides on the search results, so it
+   * also waits for the threshold.
+   *
+   * @default 1
+   */
+  minQueryLength?: number;
   /** Text shown when no results found. @default 'No results found' */
   emptySearchResultsText?: string;
   /** Whether the input is disabled. @default false */
@@ -393,6 +406,8 @@ export function Tokenizer<T extends SearchableItem>({
   placeholder,
   hasEntriesOnFocus,
   maxMenuItems,
+  menuWidth,
+  minQueryLength,
   emptySearchResultsText,
   isDisabled = false,
   htmlName,
@@ -533,36 +548,47 @@ export function Tokenizer<T extends SearchableItem>({
     () => ({
       search: async (query: string) => {
         const results = await searchSource.search(query);
-        const filtered = results.filter(item => !selectedIds.has(item.id));
-
-        // Append a "Create: X" synthetic item when hasCreate is true,
-        // the user has typed something, and it doesn't exactly match an
-        // existing result.
-        if (hasCreate && query.trim()) {
-          const trimmed = query.trim();
-          const alreadyExists =
-            selectedIds.has(trimmed) ||
-            filtered.some(
-              item => item.label.toLowerCase() === trimmed.toLowerCase(),
-            );
-          if (!alreadyExists) {
-            const creatableItem = {
-              id: `${CREATABLE_ID_PREFIX}${trimmed}`,
-              label: `Create "${trimmed}"`,
-              auxiliaryData: {__createdValue: trimmed},
-            } as unknown as T;
-            filtered.push(creatableItem);
-          }
-        }
-
-        return filtered;
+        return results.filter(item => !selectedIds.has(item.id));
       },
       bootstrap: async () => {
         const results = await searchSource.bootstrap();
         return results.filter(item => !selectedIds.has(item.id));
       },
     }),
-    [searchSource, selectedIds, hasCreate],
+    [searchSource, selectedIds],
+  );
+
+  /**
+   * The "Create X" entry. It is derived from the typed text, not fetched for
+   * it, so it is offered through `__queryEntries` rather than appended to the
+   * search results — which is what keeps it available when the query is too
+   * short to search. `minQueryLength` is there to avoid a fetch too broad to
+   * be worth making; creating `QA` costs no fetch, and a field that can
+   * create it should not stop being able to.
+   */
+  const createEntries = useCallback(
+    (query: string, results: T[]): T[] => {
+      const trimmed = query.trim();
+      if (!hasCreate || trimmed === '') {
+        return [];
+      }
+      const alreadyExists =
+        selectedIds.has(trimmed) ||
+        results.some(
+          item => item.label.toLowerCase() === trimmed.toLowerCase(),
+        );
+      if (alreadyExists) {
+        return [];
+      }
+      return [
+        {
+          id: `${CREATABLE_ID_PREFIX}${trimmed}`,
+          label: `Create "${trimmed}"`,
+          auxiliaryData: {__createdValue: trimmed},
+        } as unknown as T,
+      ];
+    },
+    [hasCreate, selectedIds],
   );
 
   const emptySource: SearchSource<T> = useMemo(
@@ -778,6 +804,8 @@ export function Tokenizer<T extends SearchableItem>({
         placeholder={value.length === 0 ? placeholder : ''}
         hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
         maxMenuItems={maxMenuItems}
+        menuWidth={menuWidth}
+        minQueryLength={minQueryLength}
         emptySearchResultsText={emptySearchResultsText}
         isDisabled={isDisabled}
         isFocusableDisabled={showsDisabledMessage}
@@ -785,6 +813,7 @@ export function Tokenizer<T extends SearchableItem>({
         inputId={inputId}
         ariaDescribedBy={ariaDescribedBy}
         onChangeQuery={onChangeQuery}
+        __queryEntries={createEntries}
         debounceMs={debounceMs}
         onKeyDown={handleKeyDown}
         anchorRef={wrapperRef}

package/src/Toolbar/Toolbar.doc.mjs

@@ -133,6 +133,11 @@ export const docs = {
           description: 'Visual variant passed to Section.',
           default: "'transparent'",
         },
+        {
+          name: 'dividers',
+          type: "Array<'top' | 'bottom' | 'start' | 'end'>",
+          description: 'Borders/dividers rendered around the toolbar.',
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',

package/src/Tooltip/Tooltip.doc.mjs

@@ -96,6 +96,11 @@ export const docs = {
           type: 'boolean',
           description: 'Whether the tooltip should be shown on mount. Still dismissible.',
         },
+        {
+          name: 'isOpen',
+          type: 'boolean',
+          description: 'Controlled open state for the tooltip.',
+        },
       ],
     },
   ],

package/src/Tooltip/Tooltip.test.tsx

@@ -276,6 +276,38 @@ describe('Tooltip', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
     });
   });
+
+  describe('controlled', () => {
+    // Escape asks a controlled tooltip to close by calling this same handler,
+    // so a consumer who complies sees the request and then this echo. Pinning
+    // the echo here keeps the two straight.
+    it('echoes the close through onOpenChange when the consumer flips isOpen', async () => {
+      const onOpenChange = vi.fn();
+      const {rerender} = render(
+        <Tooltip content="Pinned" isOpen onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      rerender(
+        <Tooltip
+          content="Pinned"
+          isOpen={false}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+  });
   describe('touch', () => {
     // The modality is document-global; a tap in one case must not decide the
     // next one's answer.

package/src/Tooltip/Tooltip.tsx

@@ -146,6 +146,11 @@ export interface TooltipProps {
    * - `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 `onOpenChange(false)` 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;
 

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.test.tsx

@@ -860,3 +860,107 @@ describe('TopNavMegaMenu — drawer focus ring', () => {
     expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
   });
 });
+
+describe('TopNavMegaMenu pass-through props', () => {
+  it('forwards pass-through props to the trigger button', () => {
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        aria-label="Products mega menu"
+        id="mega-trigger"
+        data-source="nav"
+      />,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products mega menu'});
+    expect(trigger).toHaveAttribute('id', 'mega-trigger');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+
+  it('forwards pass-through props to the drawer trigger', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu label="Products" id="mega-drawer" data-source="nav" />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('id', 'mega-drawer');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+});
+
+describe('TopNavMegaMenu — owned handlers on the trigger', () => {
+  beforeAll(installPopoverApiMock);
+  afterAll(restorePopoverApiMock);
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("composes a caller's onClick with the trigger's own open behavior", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        onClick={handleClick}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.click(trigger);
+
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it("composes a caller's hover handlers with the trigger's hover-open behavior", async () => {
+    vi.useFakeTimers({shouldAdvanceTime: true});
+    const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+    const handleMouseEnter = vi.fn();
+    const handleMouseLeave = vi.fn();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.hover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(handleMouseEnter).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.unhover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(handleMouseLeave).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it("composes a caller's onClick with the drawer section toggle", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+          onClick={handleClick}
+        />
+      </TopNavRenderContext>,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    await user.click(trigger);
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+});

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, composeEventHandlers} 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
 // =============================================================================
@@ -335,6 +336,7 @@ export function TopNavMegaMenu({
   delay = 150,
   hideDelay = 250,
   onOpenChange,
+  ...rest
 }: TopNavMegaMenuProps) {
   const renderMode = useTopNavRenderMode();
 
@@ -349,7 +351,14 @@ export function TopNavMegaMenu({
   // Drawer mode — inline collapsible
   // =========================================================================
   if (renderMode === 'drawer') {
-    return <DrawerMegaMenu label={label} items={items} featured={featured} />;
+    return (
+      <DrawerMegaMenu
+        label={label}
+        items={items}
+        featured={featured}
+        {...rest}
+      />
+    );
   }
 
   // =========================================================================
@@ -364,6 +373,7 @@ export function TopNavMegaMenu({
       delay={delay}
       hideDelay={hideDelay}
       onOpenChange={onOpenChange}
+      {...rest}
     />
   );
 }
@@ -386,6 +396,13 @@ function DefaultMegaMenu({
   delay = 150,
   hideDelay = 250,
   onOpenChange,
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  onMouseEnter: onMouseEnterProp,
+  onMouseLeave: onMouseLeaveProp,
+  ...rest
 }: TopNavMegaMenuProps) {
   const slot = useTopNavSlot();
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
@@ -451,16 +468,29 @@ function DefaultMegaMenu({
   return (
     <>
       <button
-        ref={mergeRefs(triggerButtonRef, setTriggerEl, ref)}
+        ref={useMergedRefs(triggerButtonRef, setTriggerEl, ref)}
         type="button"
+        {...rest}
         {...popover.triggerProps}
         {...hoverTriggerProps}
+        onClick={composeEventHandlers(onClickProp, hoverTriggerProps.onClick)}
+        onMouseEnter={composeEventHandlers(
+          onMouseEnterProp,
+          hoverTriggerProps.onMouseEnter,
+        )}
+        onMouseLeave={composeEventHandlers(
+          onMouseLeaveProp,
+          hoverTriggerProps.onMouseLeave,
+        )}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
           focusOutlineProps.focusVisible(
             styles.trigger,
             popover.isOpen && styles.triggerOpen,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {label}
         <Icon
@@ -512,7 +542,13 @@ function DrawerMegaMenu({
   label,
   items,
   featured,
-}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'>) {
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  ...rest
+}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'> &
+  BaseProps<HTMLButtonElement>) {
   const [isExpanded, setIsExpanded] = useState(false);
   const menuId = `mega-menu-${label.toLowerCase().replace(/\s+/g, '-')}`;
 
@@ -521,7 +557,10 @@ function DrawerMegaMenu({
       {/* Header toggle — same pattern as TopNavMenu drawer */}
       <button
         type="button"
-        onClick={() => setIsExpanded(v => !v)}
+        {...rest}
+        onClick={composeEventHandlers(onClickProp, () =>
+          setIsExpanded(v => !v),
+        )}
         aria-expanded={isExpanded}
         aria-controls={`${menuId}-items`}
         {...mergeProps(
@@ -529,7 +568,10 @@ function DrawerMegaMenu({
           focusOutlineProps.focusVisible(
             navItemStyles.item,
             styles.drawerHeader,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {label}
         <Icon