@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Timestamp/Timestamp.test.tsx

@@ -33,6 +33,31 @@ describe('Timestamp', () => {
     expect(screen.getByText('2 hours ago')).toBeInTheDocument();
   });
 
+  it('does not round a tier up past its own boundary', () => {
+    // Just under each threshold the count must stay within the tier, e.g.
+    // 59.98 minutes is "59 minutes ago", never "60 minutes ago".
+    const {rerender} = render(
+      <Timestamp value={Date.now() / 1000 - 3599} format="relative" />,
+    );
+    expect(screen.getByText('59 minutes ago')).toBeInTheDocument();
+
+    rerender(
+      <Timestamp value={Date.now() / 1000 - 86399} format="relative" />,
+    );
+    expect(screen.getByText('23 hours ago')).toBeInTheDocument();
+
+    rerender(
+      <Timestamp value={Date.now() / 1000 - 2591999} format="relative" />,
+    );
+    expect(screen.getByText('29 days ago')).toBeInTheDocument();
+
+    // Same guarantee on the future side.
+    rerender(
+      <Timestamp value={Date.now() / 1000 + 3599} format="relative" />,
+    );
+    expect(screen.getByText('in 59 minutes')).toBeInTheDocument();
+  });
+
   it('renders "now" for very recent times', () => {
     const fiveSecondsAgo = Date.now() / 1000 - 5;
     render(<Timestamp value={fiveSecondsAgo} format="relative" />);
@@ -290,4 +315,31 @@ describe('Timestamp', () => {
     const el = screen.getByRole('time');
     expect(el.textContent).not.toContain('ago');
   });
+
+  // --- Invalid values ---
+
+  it('renders nothing instead of crashing on an unparseable string value', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const {container} = render(
+        <Timestamp value="not-a-date" data-testid="ts" />,
+      );
+      expect(container).toBeEmptyDOMElement();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('could not parse value'),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('renders nothing instead of crashing on a NaN value', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const {container} = render(<Timestamp value={NaN} data-testid="ts" />);
+      expect(container).toBeEmptyDOMElement();
+    } finally {
+      warn.mockRestore();
+    }
+  });
 });

package/src/Timestamp/Timestamp.tsx

@@ -180,22 +180,22 @@ function getRelativeTimeString(date: Date, now: Date): string {
       return 'in a few seconds';
     }
     if (absDiff < HOUR) {
-      const mins = Math.round(absDiff / MINUTE);
+      const mins = Math.floor(absDiff / MINUTE);
       return `in ${mins} ${mins === 1 ? 'minute' : 'minutes'}`;
     }
     if (absDiff < DAY) {
-      const hours = Math.round(absDiff / HOUR);
+      const hours = Math.floor(absDiff / HOUR);
       return `in ${hours} ${hours === 1 ? 'hour' : 'hours'}`;
     }
     if (absDiff < MONTH) {
-      const days = Math.round(absDiff / DAY);
+      const days = Math.floor(absDiff / DAY);
       return `in ${days} ${days === 1 ? 'day' : 'days'}`;
     }
     if (absDiff < YEAR) {
-      const months = Math.round(absDiff / MONTH);
+      const months = Math.floor(absDiff / MONTH);
       return `in ${months} ${months === 1 ? 'month' : 'months'}`;
     }
-    const years = Math.round(absDiff / YEAR);
+    const years = Math.floor(absDiff / YEAR);
     return `in ${years} ${years === 1 ? 'year' : 'years'}`;
   }
 
@@ -203,25 +203,25 @@ function getRelativeTimeString(date: Date, now: Date): string {
     return `${diffSeconds} seconds ago`;
   }
   if (diffSeconds < HOUR) {
-    const mins = Math.round(diffSeconds / MINUTE);
+    const mins = Math.floor(diffSeconds / MINUTE);
     return `${mins} ${mins === 1 ? 'minute' : 'minutes'} ago`;
   }
   if (diffSeconds < DAY) {
-    const hours = Math.round(diffSeconds / HOUR);
+    const hours = Math.floor(diffSeconds / HOUR);
     return `${hours} ${hours === 1 ? 'hour' : 'hours'} ago`;
   }
   if (diffSeconds < 2 * DAY) {
     return 'yesterday';
   }
   if (diffSeconds < MONTH) {
-    const days = Math.round(diffSeconds / DAY);
+    const days = Math.floor(diffSeconds / DAY);
     return `${days} days ago`;
   }
   if (diffSeconds < YEAR) {
-    const months = Math.round(diffSeconds / MONTH);
+    const months = Math.floor(diffSeconds / MONTH);
     return `${months} ${months === 1 ? 'month' : 'months'} ago`;
   }
-  const years = Math.round(diffSeconds / YEAR);
+  const years = Math.floor(diffSeconds / YEAR);
   return `${years} ${years === 1 ? 'year' : 'years'} ago`;
 }
 
@@ -360,7 +360,12 @@ export function Timestamp({
   const [now, setNow] = useState(() => new Date());
 
   const date = parseValue(value);
-  const isoString = date.toISOString();
+  // An unparseable value (a malformed date string, or a NaN timestamp from
+  // missing data) yields an Invalid Date, and formatting one throws "Invalid
+  // time value" — crashing the whole tree. Compute nothing from it here and
+  // bail out below (after the hooks) instead.
+  const isValidDate = !Number.isNaN(date.getTime());
+  const isoString = isValidDate ? date.toISOString() : '';
 
   // Determine effective format
   const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
@@ -372,19 +377,20 @@ export function Timestamp({
       : format;
 
   // Format the display text
-  const displayText =
-    effectiveFormat === 'relative'
+  const displayText = !isValidDate
+    ? ''
+    : effectiveFormat === 'relative'
       ? getRelativeTimeString(date, now)
       : isAbsoluteFormat(effectiveFormat)
         ? formatTimestamp(date, effectiveFormat, isTimezoneShown)
         : '';
 
   // Full absolute text for tooltip and aria-label
-  const fullAbsoluteText = getFullAbsoluteString(date);
+  const fullAbsoluteText = isValidDate ? getFullAbsoluteString(date) : '';
 
   // Live updates
   useEffect(() => {
-    if (!isLive || effectiveFormat !== 'relative') {
+    if (!isLive || !isValidDate || effectiveFormat !== 'relative') {
       return;
     }
 
@@ -394,7 +400,15 @@ export function Timestamp({
     }, interval);
 
     return () => clearInterval(timer);
-  }, [isLive, effectiveFormat, diffSeconds]);
+  }, [isLive, isValidDate, effectiveFormat, diffSeconds]);
+
+  // Placed after all hooks so the hook order stays stable across renders.
+  if (!isValidDate) {
+    console.warn(
+      `Timestamp: could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
+    );
+    return null;
+  }
 
   const showTooltip = hasTooltip && effectiveFormat === 'relative';
 

package/src/Toast/Toast.tsx

@@ -121,8 +121,14 @@ export function Toast({
   // Will be initialized by startTimer when actually used
   const startTimeRef = useRef<number | null>(null);
 
+  // Read onDismiss through a ref: the viewport re-creates it on every render
+  // (another toast arriving/exiting), and a startTimer that depends on it
+  // would restart — and un-pause — this toast's timer on unrelated renders.
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
   const startTimer = useCallback(() => {
-    if (!isAutoHide) {
+    if (!isAutoHide || isPausedRef.current) {
       return;
     }
     if (timerRef.current) {
@@ -130,9 +136,9 @@ export function Toast({
     }
     startTimeRef.current = Date.now();
     timerRef.current = setTimeout(() => {
-      onDismiss('auto');
+      onDismissRef.current('auto');
     }, remainingRef.current);
-  }, [isAutoHide, onDismiss]);
+  }, [isAutoHide]);
 
   const pauseTimer = useCallback(() => {
     if (!isAutoHide || isPausedRef.current) {
@@ -165,6 +171,8 @@ export function Toast({
         clearTimeout(timerRef.current);
       }
     };
+    // startTimer's identity is stable per isAutoHide, so this runs on mount
+    // and on a genuine duration change — not on unrelated viewport renders.
   }, [autoHideDuration, startTimer]);
 
   // Pause the auto-hide timer while the window is not focused, so a toast

package/src/Toast/ToastViewport.test.tsx

@@ -212,3 +212,67 @@ describe('ToastViewport region ARIA', () => {
     expect(region).not.toHaveAttribute('aria-modal');
   });
 });
+
+describe('toast timer lifecycle (#3589)', () => {
+  it('fires onHide exactly once when dismissed twice during the exit window', () => {
+    const onHide = vi.fn();
+    renderViewport(
+      <ShowToastButton options={{body: 'Once', onHide}} triggerLabel="Show" />,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    // The toast stays mounted during its exit transition; a second click
+    // lands on the same still-mounted button.
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    expect(onHide).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a window-blur pause alive when another toast arrives', () => {
+    vi.useFakeTimers();
+    try {
+      const onHide = vi.fn();
+      renderViewport(
+        <>
+          <ShowToastButton
+            options={{body: 'Paused', autoHideDuration: 3000, onHide}}
+            triggerLabel="Show A"
+          />
+          <ShowToastButton options={INFO_B} triggerLabel="Show B" />
+        </>,
+      );
+      act(() => {
+        fireEvent.click(screen.getByText('Show A'));
+      });
+      act(() => {
+        fireEvent.blur(window);
+      });
+      // A second toast arriving re-renders the viewport; the paused timer
+      // must not silently restart.
+      act(() => {
+        fireEvent.click(screen.getByText('Show B'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(60_000);
+      });
+      expect(onHide).not.toHaveBeenCalled();
+      // Focus returns: the remaining time resumes and completes normally.
+      act(() => {
+        fireEvent.focus(window);
+      });
+      act(() => {
+        vi.advanceTimersByTime(60_000);
+      });
+      expect(onHide).toHaveBeenCalledTimes(1);
+      expect(onHide).toHaveBeenCalledWith('auto');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/Toast/ToastViewport.tsx

@@ -114,6 +114,9 @@ export function ToastViewport({
 
   // Show the popover on mount so it enters the top layer.
   const viewportRef = useRef<HTMLDivElement>(null);
+  // Toast ids whose exit has begun — guards onHide from double-firing (see
+  // removeToast). Mirrors exitingIds state, readable synchronously.
+  const exitingIdsRef = useRef<Set<string>>(new Set());
   // The element that was focused before the user jumped into the viewport
   // (via F6). Used to restore focus once all toasts are dismissed so focus
   // never falls to <body>.
@@ -171,6 +174,14 @@ export function ToastViewport({
   }, []);
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
+    // An exiting toast stays in toastsRef until its exit transition ends, so
+    // a second dismissal inside that window (double-click, auto-timer plus
+    // manual dismiss()) would re-fire onHide. Track exiting ids in a ref —
+    // the exitingIds state dedupe below runs too late to protect onHide.
+    if (exitingIdsRef.current.has(id)) {
+      return;
+    }
+    exitingIdsRef.current.add(id);
     const entry = toastsRef.current.find(t => t.id === id);
     if (entry) {
       entry.options.onHide?.(reason);
@@ -210,6 +221,7 @@ export function ToastViewport({
   }, []);
 
   const handleExited = useCallback((id: string) => {
+    exitingIdsRef.current.delete(id);
     setExitingIds(prev => {
       if (!prev.has(id)) {
         return prev;

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-toggle-button-group'},
+      {className: 'astryx-toggle-button', states: ['isPressed']},
     ],
   },
   description: 'A button that toggles between pressed and unpressed states. Thin wrapper over Button with controlled toggle pattern, icon swap, and font weight emphasis.',

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -70,11 +70,17 @@ export const docs = {
       description: 'Disables the input and all token interactions.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for form submissions. Renders one hidden input per selected item id.',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -183,7 +189,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
     ],
   },
   usage: {
@@ -277,11 +283,16 @@ export const docsZh = {
       description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description: '用于表单提交的 HTML name 属性。为每个已选项目的 id 渲染一个隐藏输入。',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -379,7 +390,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
     ],
   },
   usage: {
@@ -435,6 +446,7 @@ export const docsDense = {
     renderToken: 'Custom token render. Default renders Token w/ label+onRemove.',
     renderItem: 'Custom dropdown item render. Default renders TypeaheadItem.',
     isDisabled: 'Disables input+all token interactions.',
+    htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',

package/src/Tokenizer/Tokenizer.test.tsx

@@ -867,4 +867,37 @@ describe('Tokenizer', () => {
       expect(screen.getByRole('combobox')).toBeDisabled();
     });
   });
+  describe('form participation', () => {
+    it('submits one entry per token id under htmlName', () => {
+      const {container} = render(
+        <form>
+          <Tokenizer
+            label="Users"
+            htmlName="users"
+            searchSource={userSource}
+            value={[users[0], users[1]]}
+            onChange={() => {}}
+          />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.getAll('users')).toEqual([users[0].id, users[1].id]);
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <Tokenizer
+            label="Users"
+            htmlName="users"
+            searchSource={userSource}
+            value={[users[0]]}
+            onChange={() => {}}
+            isDisabled
+          />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+  });
 });

package/src/Tokenizer/Tokenizer.tsx

@@ -128,6 +128,12 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   searchSource: SearchSource<T>;
   /** Currently selected items. */
   value: T[];
+
+  /**
+   * The HTML name attribute for form submissions. When set, hidden inputs
+   * carry one entry per selected item's id under this name.
+   */
+  htmlName?: string;
   /** Callback when selection changes. Includes change metadata. */
   onChange: (items: T[], change: TokenizerChange<T>) => void;
   /** Render function for dropdown items. Default: TypeaheadItem. */
@@ -377,6 +383,7 @@ export function Tokenizer<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  htmlName,
   disabledMessage,
   hasClear = false,
   endContent,
@@ -760,6 +767,18 @@ export function Tokenizer<T extends SearchableItem>({
               : undefined
         }
       />
+      {htmlName != null &&
+        value.map(item => (
+          <input
+            key={item.id}
+            type="hidden"
+            name={htmlName}
+            value={item.id}
+            // Disabled native controls are excluded from form submission;
+            // mirror that for the hidden carriers.
+            disabled={isDisabled}
+          />
+        ))}
       {(endContent || (hasClear && value.length > 0 && !isDisabled)) && (
         <div {...stylex.props(styles.endSection, endSectionSizeStyles[size])}>
           {endContent}

package/src/Toolbar/Toolbar.test.tsx

@@ -168,7 +168,7 @@ describe('Toolbar', () => {
 
   it('passes variant to Section', () => {
     const {container} = render(<Toolbar label="Actions" variant="muted" />);
-    // Section renders with xds-section class containing the variant
+    // Section renders with astryx-section class containing the variant
     const sectionInner = container.querySelector('.astryx-section');
     expect(sectionInner).toBeInTheDocument();
     expect(sectionInner?.className).toContain('muted');

package/src/TopNav/TopNav.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-top-nav', states: ['mode']},
-      {className: 'astryx-top-nav-item', states: ['mode']},
+      {className: 'astryx-top-nav-item', states: ['mode', 'selected']},
       {className: 'astryx-top-nav-heading'},
       {className: 'astryx-top-nav-mega-menu', states: ['mode']},
       {className: 'astryx-top-nav-mega-menu-item', states: ['mode']},

package/src/TopNav/TopNav.test.tsx

@@ -16,6 +16,7 @@ import {TopNav} from './TopNav';
 import {TopNavHeading} from './TopNavHeading';
 import {NavIcon} from '../NavIcon';
 import {TopNavItem} from './TopNavItem';
+import {TopNavMegaMenuFeaturedCard} from './TopNavMegaMenuFeaturedCard';
 import {LinkProvider} from '../Link/LinkProvider';
 
 function CustomLink({
@@ -398,4 +399,21 @@ describe('TopNavItem', () => {
     expect(link).toHaveAttribute('data-custom-link');
     expect(link).not.toHaveAttribute('data-another-link');
   });
+
+  describe('TopNavMegaMenuFeaturedCard rest forwarding', () => {
+    it('forwards data-testid, id, and aria-* to the root element', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          description="Details"
+          data-testid="featured-card"
+          id="card-1"
+          aria-label="Featured"
+        />,
+      );
+      const card = screen.getByTestId('featured-card');
+      expect(card).toHaveAttribute('id', 'card-1');
+      expect(card).toHaveAttribute('aria-label', 'Featured');
+    });
+  });
 });

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -132,6 +132,10 @@ export function TopNavMegaMenuFeaturedCard({
   linkLabel,
   linkHref,
   children,
+  xstyle,
+  className,
+  style,
+  ...rest
 }: TopNavMegaMenuFeaturedCardProps) {
   const LinkComponent = useLinkComponent();
   return (
@@ -139,8 +143,11 @@ export function TopNavMegaMenuFeaturedCard({
       ref={ref}
       {...mergeProps(
         themeProps('top-nav-mega-menu-featured-card'),
-        stylex.props(styles.root),
-      )}>
+        stylex.props(styles.root, xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       {image && (
         <img src={image} alt={imageAlt ?? ''} {...stylex.props(styles.image)} />
       )}

package/src/TreeList/TreeList.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
-      {className: 'astryx-tree-list-item', states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
     ],
   },
   components: [
@@ -89,7 +89,7 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
-      {className: 'astryx-tree-list-item', states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
     ],
   },
   components: [

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -8,6 +8,16 @@ export const docs = {
   displayName: 'Base Typeahead',
   isHiddenFromOverview: true,
   description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+  usage: {
+    description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly, since BaseTypeahead renders no visual chrome of its own.' },
+      { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
+      { guidance: false, description: 'Expect a wrapper div, border, or token rendering. BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.' },
+    ],
+  },
   props: [
     {
       name: 'searchSource',
@@ -226,6 +236,15 @@ export const docsDense = {
   isHiddenFromOverview: true,
   displayName: 'Base Typeahead',
   description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by Typeahead+Tokenizer.',
+  usage: {
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they add the wrapper, border, and token rendering BaseTypeahead omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly; BaseTypeahead renders no chrome.' },
+      { guidance: true, description: 'Pass anchorRef to your wrapper so the dropdown positions against your input chrome, not the bare input.' },
+      { guidance: false, description: 'Expect wrapper, border, or token rendering. Engine only; chrome is the caller\'s job.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer suffice; extra work only pays off for custom compositions.' },
+    ],
+  },
   propDescriptions: {
     searchSource: 'Data source w/ search+bootstrap methods.',
     value: 'Currently selected item.',

package/src/Typeahead/BaseTypeahead.tsx

@@ -410,7 +410,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   const performSearch = useCallback(
     async (searchQuery: string) => {
       searchSource.cancel?.();
-      const gen = searchGenRef.current;
+      // Claim a new generation so overlapping searches can't race: an
+      // in-flight response for an older query fails the gen check below
+      // instead of overwriting the newer results.
+      const gen = ++searchGenRef.current;
       setIsLoading(true);
       setHasSearched(true);
       try {
@@ -451,7 +454,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
-    const gen = searchGenRef.current;
+    const gen = ++searchGenRef.current;
     setIsLoading(true);
     try {
       const bootstrapResults = await searchSource.bootstrap();

package/src/Typeahead/Typeahead.doc.mjs

@@ -75,7 +75,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'maxMenuItems',
@@ -168,7 +168,7 @@ export const docs = {
   components: [{name: 'BaseTypeahead'}, {name: 'TypeaheadItem'}],
   theming: {
     targets: [
-      {className: 'astryx-typeahead', visualProps: ['status']},
+      {className: 'astryx-typeahead', visualProps: ['status', 'size']},
       {className: 'astryx-typeahead-dropdown'},
       {className: 'astryx-typeahead-item'},
     ],
@@ -287,6 +287,11 @@ export const docsDense = {
         description:
           'Add a search delay for remote data sources to avoid excessive network requests.',
       },
+      {
+        guidance: true,
+        description:
+          'Use inside InputGroup when the typeahead needs a single-line prefix or suffix addon.',
+      },
       {
         guidance: false,
         description: