@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Timestamp/Timestamp.tsx

@@ -20,7 +20,7 @@ import {lazy, Suspense, useEffect, useRef, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useTranslator} from '../i18n';
 import {useLocale} from '../i18n/useLocale';
@@ -33,6 +33,7 @@ import type {
   TimestampTooltipLine,
 } from './tooltipEntries';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // Load the overlay lazily so a card-less Timestamp — the default — never
 // bundles HoverCard or the copy affordance's Icon/IconButton. Mirrors the code
 // split the read-only Tooltip path used before it.
@@ -422,6 +423,7 @@ export function Timestamp({
   const t = useTranslator();
   const locale = useLocale();
   const timeRef = useRef<HTMLTimeElement>(null);
+  const mergedTimeRef = useMergedRefs(ref, timeRef);
   const [now, setNow] = useState(() => new Date());
 
   const date = parseValue(value);
@@ -526,7 +528,7 @@ export function Timestamp({
       xstyle={xstyle}
       {...timestampProps}>
       <time
-        ref={mergeRefs(ref, timeRef)}
+        ref={mergedTimeRef}
         dateTime={isoString}
         // `ariaLabelText` is '' only for an invalid date, which bails out
         // before rendering — but keep the guard local: an empty aria-label

package/src/Toast/Toast.doc.mjs

@@ -60,6 +60,12 @@ export const docs = {
       type: '(reason: "auto" | "manual") => void',
       description: 'Callback fired when the toast is removed.',
     },
+    {
+      name: 'onDismiss',
+      type: '(reason: "auto" | "manual") => void',
+      description: 'Callback fired when the toast is dismissed.',
+      required: true,
+    },
   ],  theming: {
     targets: [
       {className: 'astryx-toast', visualProps: ['type']},

package/src/Toast/ToastViewport.tsx

@@ -58,7 +58,6 @@ const styles = stylex.create({
     pointerEvents: 'auto',
     display: 'grid',
     gridTemplateRows: '1fr',
-    paddingBlockEnd: spacingVars['--spacing-3'],
     transitionProperty: 'grid-template-rows, padding',
     transitionDuration: {
       default: durationVars['--duration-fast'],
@@ -70,6 +69,18 @@ const styles = stylex.create({
       paddingBlockEnd: 0,
     },
   },
+  // The inter-toast gap is padding on each toast rather than `gap` on the
+  // viewport so it can animate alongside gridTemplateRows on entry and exit.
+  // That makes it the toast's own trailing space, so the toast at the visual
+  // bottom of the stack has to give it up — otherwise it stacks on top of the
+  // viewport's own padding. Which child that is flips with the flex direction
+  // the position sets.
+  toastWrapperGap: {
+    paddingBlockEnd: {default: spacingVars['--spacing-3'], ':last-child': 0},
+  },
+  toastWrapperGapReversed: {
+    paddingBlockEnd: {default: spacingVars['--spacing-3'], ':first-child': 0},
+  },
   toastWrapperExiting: {
     gridTemplateRows: '0fr',
     paddingBlockEnd: 0,
@@ -417,6 +428,10 @@ export function ToastViewport({
         : position === 'bottomStart'
           ? styles.bottomStart
           : styles.bottomEnd;
+  const isReversed = position === 'topEnd' || position === 'topStart';
+  const gapStyle = isReversed
+    ? styles.toastWrapperGapReversed
+    : styles.toastWrapperGap;
 
   return (
     <ToastContext value={contextValue}>
@@ -444,6 +459,7 @@ export function ToastViewport({
               data-toast-id={entry.id}
               {...stylex.props(
                 styles.toastWrapper,
+                gapStyle,
                 isExiting && styles.toastWrapperExiting,
               )}
               onTransitionEnd={

package/src/Token/TokenLink.tsx

@@ -27,10 +27,10 @@
 
 import type {ReactNode, CSSProperties, Ref, HTMLAttributes} from 'react';
 import {useRef} from 'react';
-import {mergeRefs} from '../utils';
 import {useClickableContainer} from '../hooks/useClickableContainer';
 import type {LinkComponentType} from '../Link/types';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
   /** Ref forwarded to the container element. */
   ref?: Ref<HTMLElement>;
@@ -86,7 +86,7 @@ export function TokenLink({
 
   return (
     <span
-      ref={mergeRefs(ref, containerRef)}
+      ref={useMergedRefs(ref, containerRef)}
       onClick={isDisabled ? undefined : onClick}
       onMouseUp={isDisabled ? undefined : onMouseUp}
       {...containerProps}>

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -135,6 +135,11 @@ export const docs = {
       description: 'Maximum number of 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',
@@ -201,6 +206,22 @@ 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: 'tokenOverflowBehavior',
+      type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
+      description: 'Controls how tokens overflow when the container is too narrow.',
+      default: "'none'",
+    },
+    {
+      name: 'onFocus',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus enters the tokenizer input.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus leaves the tokenizer input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -368,6 +389,11 @@ export const docsZh = {
       description: '\u4e0b\u62c9\u5217\u8868\u663e\u793a\u7684\u6700\u5927\u9879\u76ee\u6570\u3002',
       default: '10',
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: '下拉菜单的固定像素宽度。菜单不会小于其锚点宽度。',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -490,6 +516,7 @@ export const docsDense = {
     labelTooltip: 'Tooltip on label.',
     hasEntriesOnFocus: 'Show bootstrap results on focus before typing.',
     maxMenuItems: 'Max dropdown items to display.',
+    menuWidth: 'Fixed dropdown width in pixels.',
     emptySearchResultsText: 'Text when search returns no results.',
     hasAutoFocus: 'Auto-focus input on mount.',
     size: 'Input+token size.',

package/src/Tokenizer/Tokenizer.tsx

@@ -156,6 +156,8 @@ 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;
   /** Text shown when no results found. @default 'No results found' */
   emptySearchResultsText?: string;
   /** Whether the input is disabled. @default false */
@@ -393,6 +395,7 @@ export function Tokenizer<T extends SearchableItem>({
   placeholder,
   hasEntriesOnFocus,
   maxMenuItems,
+  menuWidth,
   emptySearchResultsText,
   isDisabled = false,
   htmlName,
@@ -778,6 +781,7 @@ export function Tokenizer<T extends SearchableItem>({
         placeholder={value.length === 0 ? placeholder : ''}
         hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
         maxMenuItems={maxMenuItems}
+        menuWidth={menuWidth}
         emptySearchResultsText={emptySearchResultsText}
         isDisabled={isDisabled}
         isFocusableDisabled={showsDisabledMessage}

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.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.',