@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

package/src/Table/useTableGroupedRows.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableGroupedRows',
   description:
-    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\'s data rows while keeping the header visible. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass all three to Table (data, plugins, and idKey respectively).',
+    "Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group's data rows while keeping the header visible. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass them to Table as data, plugins, and idKey respectively.",
   props: [
     {
       name: 'data',
@@ -58,13 +58,14 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass them to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
   propDescriptions: {
     data: 'The flat data to group.',
-    groupBy: 'Derive a row\'s group key. Same key = same section.',
+    groupBy: "Derive a row's group key. Same key = same section.",
     collapsedGroups: 'Set of currently-collapsed group keys.',
     onToggleGroup: 'Called with the group key when a header is toggled.',
-    renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",
+    renderGroupHeader:
+      "Custom header content (right of chevron). Default '<key> (<count>)'.",
     getRowKey: 'Stable key for a real row; positional fallback when omitted.',
     groupOrder: 'Pin these group keys first; others keep first-seen order.',
   },

package/src/Table/useTablePagination.doc.mjs

@@ -72,6 +72,12 @@ export const docs = {
       description: 'Horizontal alignment of the pagination controls.',
       default: "'center'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: "Accessible name for the pagination nav landmark. With position='both' the two navs get distinct names — the label suffixed as '(top)' and '(bottom)' — so same-type landmarks stay unique (axe landmark-unique).",
+      default: "'Table pagination'",
+    },
   ],
 };
 
@@ -129,5 +135,6 @@ export const docsDense = {
     pageSize: 'Items per page. Default 10.',
     variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
     position: "Render position: 'below'|'above'|'both'|'none'.",
+    label: "Accessible name for the nav landmark; position='both' emits '<label> (top)' / '<label> (bottom)'.",
   },
 };

package/src/Table/useTableRowStatus.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableRowStatus',
   description:
-    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. Memoize getStatus with useCallback for a stable plugin identity.',
+    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. The column header is visually blank but carries a screen-reader-only localized name ("Row status", i18n key @astryx.table.rowStatus.columnHeader). Memoize getStatus with useCallback for a stable plugin identity.',
   props: [
     {
       name: 'getStatus',

package/src/Table/useTableSelection.doc.mjs

@@ -61,6 +61,13 @@ export const docs = {
       description:
         'Derives a human-readable identity for a row; the row checkbox\'s hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.',
     },
+    {
+      name: 'hasRowHighlight',
+      type: 'boolean',
+      description:
+        'Paints checked rows with the accent wash. Set false when the surrounding UI already uses row background to mean something else (a row open in a detail panel, say) — the wash is an inline style, so it cannot be overridden from userland. Only the background is dropped: aria-selected is still set on checked rows either way.',
+      default: 'true',
+    },
   ],
   examples: [
     {
@@ -82,6 +89,21 @@ const selectionPlugin = useTableSelection({
   idKey="id"
   plugins={{selection: selectionPlugin}}
 />;
+`,
+    },
+    {
+      label: 'Opt out of the checked-row wash',
+      code: `
+// This table already uses row background to mean "open in the detail
+// panel". Turning the selection wash off keeps that meaning unambiguous;
+// the checkbox and aria-selected still carry the selection.
+const selectionPlugin = useTableSelection({
+  getIsItemSelected: item => selectedIds.has(item.id),
+  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
+  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
+  getIsAllSelected: () => selectedIds.size === users.length,
+  hasRowHighlight: false,
+});
 `,
     },
   ],
@@ -142,6 +164,13 @@ export const docsZh = {
       description:
         '为行派生人类可读的标识；行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`，让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',
     },
+    {
+      name: 'hasRowHighlight',
+      type: 'boolean',
+      description:
+        '为选中的行绘制强调色背景。当周围的界面已用行背景表达其他含义（例如该行已在详情面板中打开）时设为 false —— 该背景是内联样式，无法从业务代码覆盖。仅去掉背景：无论如何选中的行仍会设置 aria-selected。',
+      default: 'true',
+    },
   ],
 };
 
@@ -164,5 +193,7 @@ export const docsDense = {
       'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
     getRowLabel:
       'Derives row identity for the checkbox\'s hidden label: `Select ${getRowLabel(item)}`. Falls back to "Select row" when omitted.',
+    hasRowHighlight:
+      'false => skip the accent wash on checked rows (inline style, not overridable from userland). aria-selected is unaffected. Defaults to true.',
   },
 };

package/src/Text/Text.test.tsx

@@ -6,7 +6,7 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {Text} from './Text';
 import type {TextType} from './Text';
 import type {TextColor} from '../theme/types';
@@ -23,6 +23,28 @@ describe('Text', () => {
       expect(screen.getByText('Hello World')).toBeInTheDocument();
     });
 
+    it('keeps a forwarded ref attached across rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Text ref={ref} type="body">
+          Before
+        </Text>,
+      );
+
+      const element = screen.getByText('Before');
+      expect(ref).toHaveBeenLastCalledWith(element);
+      ref.mockClear();
+
+      rerender(
+        <Text ref={ref} type="body">
+          After
+        </Text>,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByText('After')).toBe(element);
+    });
+
     it('renders as span by default', () => {
       render(<Text type="body">Text</Text>);
       const element = screen.getByText('Text');

package/src/Text/Text.tsx

@@ -48,7 +48,8 @@ import {
 } from './text.stylex';
 import {useTruncation} from './useTruncation';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -271,13 +272,16 @@ export function Text({
   // Ref for the text element (used as tooltip anchor)
   const textRef = useRef<HTMLElement>(null);
 
+  // Keep the merged ref stable across rerenders.
+  const mergedRef = useMergedRefs(ref, truncation.ref, textRef);
+
   // Build inline style for -webkit-line-clamp (dynamic value)
   const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;
 
   return (
     <>
       <Component
-        ref={mergeRefs(ref, truncation.ref, textRef)}
+        ref={mergedRef}
         {...mergeProps(
           themeProps('text', {type, size, color: resolvedColor}),
           stylex.props(

package/src/TextArea/TextArea.tsx

@@ -46,7 +46,7 @@ import {
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
@@ -58,6 +58,7 @@ import {themeProps} from '../utils/themeProps';
 import {characterCount} from '../utils/characters';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
@@ -580,7 +581,7 @@ export function TextArea({
         )}
         <textarea
           {...rest}
-          ref={mergeRefs(ref, textareaRef)}
+          ref={useMergedRefs(ref, textareaRef)}
           id={id}
           name={isDisabled ? undefined : htmlName}
           value={optimisticValue}

package/src/TextInput/TextInput.doc.mjs

@@ -71,6 +71,16 @@ export const docs = {
         'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
       default: 'false',
     },
+    {
+      name: 'onEnter',
+      type: '() => void',
+      description: 'Callback fired when the user presses the Enter key.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: KeyboardEvent<HTMLInputElement>) => void',
+      description: 'Callback fired on keydown events on the input.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/TextInput/TextInput.tsx

@@ -97,7 +97,7 @@ export type {
   InputStatus as TextInputStatus,
   InputStatusType as TextInputStatusType,
 } from '../Field';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -108,6 +108,7 @@ import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export type TextInputType = 'text' | 'password' | 'email';
 
 export interface TextInputProps extends Omit<
@@ -421,7 +422,7 @@ export function TextInput({
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
         {...rest}
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         id={id}
         name={isDisabled ? undefined : htmlName}
         type={type}

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       {className: 'astryx-thumbnail'},
     ],
     vars: [
-      {name: '--_thumbnail-hit-inset', description: 'Outset of the remove button\u2019s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
+      {name: '--_thumbnail-hit-inset', description: 'Outset of the remove button\'s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
     ],
   },
   usage: {

package/src/TimeInput/TimeInput.tsx

@@ -58,7 +58,6 @@ import {
   isImeKeyEvent,
   isTimeInRange,
   mergeProps,
-  mergeRefs,
   getInputARIA,
 } from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -74,6 +73,7 @@ import {useTooltip} from '../Tooltip';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   icon: {
     display: 'flex',
@@ -648,7 +648,7 @@ export function TimeInput({
         </VisuallyHidden>
       )}
       <input
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         id={id}
         type="text"
         value={displayValue}

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/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

@@ -201,6 +201,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',

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/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/Typeahead/BaseTypeahead.tsx

@@ -41,12 +41,13 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {getKey, mergeProps, mergeRefs} from '../utils';
+import {getKey, 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
 // =============================================================================
@@ -760,7 +761,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"

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