@astryxdesign/core 0.7.1 → 0.7.2-canary.198a7e3

package/src/Tooltip/Tooltip.test.tsx

@@ -183,6 +183,37 @@ describe('Tooltip', () => {
     });
   });
 
+  describe('icon-only trigger', () => {
+    // A rendered icon is an SVGElement, and ShowPopoverOptions.source is
+    // declared as an HTMLElement. Handing the icon to showPopover throws
+    // during dictionary conversion, before the popover opens, so the hint
+    // never appeared. (#7226)
+    it('opens an icon trigger without passing an SVGElement as the source', async () => {
+      const showSpy = vi.mocked(HTMLElement.prototype.showPopover);
+      showSpy.mockClear();
+
+      render(
+        <Tooltip content="Shared memory" isDefaultOpen>
+          <svg data-testid="icon" aria-hidden="true" />
+        </Tooltip>,
+      );
+
+      await waitFor(() => {
+        expect(showSpy).toHaveBeenCalled();
+      });
+
+      const [options] = showSpy.mock.calls[0];
+      // Compared as a boolean on purpose: a plain `toBeUndefined` failure makes
+      // the diff printer walk the SVGElement, which it cannot inspect.
+      expect(options?.source === undefined).toBe(true);
+
+      // The icon is still the trigger the ARIA tooltip pattern is wired to.
+      expect(screen.getByTestId('icon').getAttribute('aria-describedby')).toBe(
+        screen.getByRole('tooltip', {hidden: true}).id,
+      );
+    });
+  });
+
   describe('WCAG 1.4.13 — content on hover or focus', () => {
     it('dismisses on Escape while visible (dismissible)', async () => {
       const onOpenChange = vi.fn();

package/src/Tooltip/useTooltip.test.tsx

@@ -147,6 +147,19 @@ describe('useTooltip — show delay', () => {
 
     expect(onShow).not.toHaveBeenCalled();
   });
+
+  it('drops a pending show when isEnabled turns false before the delay elapses', () => {
+    const onShow = vi.fn();
+    const {rerender} = render(<Harness onShow={onShow} />);
+
+    fireEvent.mouseEnter(trigger());
+    tick(100);
+    rerender(<Harness isEnabled={false} onShow={onShow} />);
+    tick(1000);
+
+    expect(onShow).not.toHaveBeenCalled();
+    expect(tooltipElement().matches(':popover-open')).toBe(false);
+  });
 });
 
 describe('useTooltip — touch suppression', () => {

package/src/Tooltip/useTooltip.tsx

@@ -352,6 +352,17 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
+  // A show scheduled while the triggers were enabled must not outlive them:
+  // disabling also detaches the leave listener that would have cancelled it,
+  // so the timer would open a tooltip that nothing ever closes. Only the
+  // pending show is dropped; a pending hide still runs.
+  useEffect(() => {
+    if (!isEnabled && showTimeoutRef.current) {
+      clearTimeout(showTimeoutRef.current);
+      showTimeoutRef.current = null;
+    }
+  }, [isEnabled]);
+
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
   // trigger onto the tooltip surface without the tooltip vanishing — required

package/src/TreeList/TreeList.spec.md

@@ -96,14 +96,15 @@ Supporting one does not justify omitting another from the durable contract.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
-| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
-| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
-| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
-| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
-| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                                                                                                                                                                                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                                                                                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                                                                                                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                                                                                                                                                                                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
+| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two.                                                                                                                                                                                                 | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
+| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.                                                                                                                                                                                                    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and a disabled Item does nothing. | Owner decision; `family:navigation-destinations`                                    | Settled intent; implementation may be staged        |
 
 ### Allowed variation
 
@@ -183,6 +184,16 @@ structure. Its current lack of a target is a reachability gap, not a decision
 that it must remain unthemeable. Header, Start content, and End content remain
 caller-owned even though TreeList positions their slot wrappers.
 
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID  | Decision                                                                                                                     | Intent or reason                                                                                                                                                                                               | Applies to                                                                             | Allowed variation                                                                                                                                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DD1 | Every Item spans the full width of the tree list at any depth; its nesting indent sits inside the row, ahead of its content. | Hover, pressed, and selected fills line up across depths, so the tree reads as one list of equal rows while labels keep their per-level alignment.                                                             | Item at every depth, at rest and through hover, pressed, selected, disabled, and focus | Themes set the indent step with `--tree-list-indent` and may restyle the row's fill, radius, and padding; row padding adds to the indent instead of replacing it. |
+| DD2 | A nested Item's indent area is part of the row's painted target: it shows the row's hover and press feedback.                | The whole painted row reads as one target, matching where a click acts (FR7), so no part of a row lights up apart from the rest.                                                                               | Nested Items that act on click                                                         | Themes may restyle the feedback through the `tree-list-item` target.                                                                                              |
+| DD3 | Guides paint above row fills, and an Item whose focus ring is showing paints above the guides.                               | Hierarchy lines stay continuous through hover and selection, and the focus indicator is never cut; on a focused row that is also filled, the ring takes precedence and the fill covers the guides at that row. | Guide and Item in `lineGuides` trees                                                   | Themes may recolor or hide guides through the `tree-list-guide` target.                                                                                           |
+
 ### Theming anatomy
 
 <!-- anatomy-theming:v1 -->
@@ -242,15 +253,16 @@ authorize or prohibit a future target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                  | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Flat, nested, described, headed, and slotted items                                     | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy`       |
-| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Five local targets and their documented states                                         | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming`       |
-| FR3                 | Source inspection plus Icon public target metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expandable rows and caller-provided slots                                              | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming`       |
-| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Item with description                                                                  | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy`       |
-| AR1                 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select                                          | `audit:TreeList/accessibility` |
-| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | One input at a time; all three together; sibling rows                                  | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`           |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and five current local targets                                       | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                                                                                                | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Flat, nested, described, headed, and slotted items                                                                                                                   | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy`       |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Five local targets and their documented states                                                                                                                       | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming`       |
+| FR3                 | Source inspection plus Icon public target metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expandable rows and caller-provided slots                                                                                                                            | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming`       |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Item with description                                                                                                                                                | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy`       |
+| AR1                 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead                                                                               | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select                                          | `audit:TreeList/accessibility` |
+| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | One input at a time; all three together; sibling rows                                                                                                                | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`           |
+| FR7                 | Focused `TreeList.test.tsx` row-click coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts.                                                 | `audit:TreeList/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and five current local targets                                                                                                                     | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming`       |
 
 Focused target-placement assertions cover all five local targets. Runtime support
 and mutation-sensitive coverage for the item styling seam may land separately,

package/src/Typeahead/BaseTypeahead.tsx

@@ -624,6 +624,32 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     sourceGenRef.current = ++searchGenRef.current;
   }
 
+  // The previous source is remembered in state, not a ref, so a render React
+  // discards cannot consume the comparison without its state updates.
+  const [sourceOfState, setSourceOfState] = useState(searchSource);
+  if (sourceOfState !== searchSource) {
+    setSourceOfState(searchSource);
+    if (isLoading) {
+      setIsLoading(false);
+      setHasSearched(false);
+    }
+    loadingRef.current = false;
+  }
+
+  // When the search source is replaced, any in-flight load from the previous
+  // source is abandoned (generation bumped above). Notify the wrapper's busy lane
+  // in an effect so external store listeners run safely after commit.
+  const isInitialMountRef = useRef(true);
+  useEffect(() => {
+    if (isInitialMountRef.current) {
+      isInitialMountRef.current = false;
+      return;
+    }
+    if (!loadingRef.current) {
+      onLoadingChangeRef.current?.(false);
+    }
+  }, [searchSource]);
+
   // Layer for dropdown
   const handleLayerShow = useCallback(() => {
     onOpenChange?.(true);

package/src/Typeahead/Typeahead.test.tsx

@@ -17,10 +17,20 @@ import {
   beforeAll,
   afterAll,
   beforeEach,
+  afterEach,
 } from 'vitest';
 import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {createRef, Profiler, type ProfilerOnRenderCallback} from 'react';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {
+  createRef,
+  Profiler,
+  startTransition,
+  StrictMode,
+  Suspense,
+  useState,
+  type ProfilerOnRenderCallback,
+} from 'react';
 import {Typeahead} from './Typeahead';
 import {readFile} from 'node:fs/promises';
 import {resolve} from 'node:path';
@@ -70,6 +80,10 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Test data
 const fruits: SearchableItem[] = [
   {id: '1', label: 'Apple'},
@@ -964,6 +978,193 @@ describe('BaseTypeahead hasEntriesOnFocus', () => {
     ).not.toBeInTheDocument();
   });
 
+  it('clears the loading state when the search source is replaced during an in-flight load', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const bootstrap = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    const initialSource: SearchSource = {search: () => [], bootstrap};
+    const replacementSource: SearchSource = {
+      search: () => [],
+      bootstrap: () => [],
+    };
+
+    const {rerender} = render(
+      <BaseTypeahead
+        searchSource={initialSource}
+        value={null}
+        onChange={() => {}}
+        hasEntriesOnFocus
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    await waitFor(() => {
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    });
+
+    rerender(
+      <BaseTypeahead
+        searchSource={replacementSource}
+        value={null}
+        onChange={() => {}}
+        hasEntriesOnFocus
+      />,
+    );
+
+    await waitFor(() => {
+      expect(
+        screen.queryByRole('status', {name: 'Loading'}),
+      ).not.toBeInTheDocument();
+    });
+
+    await act(async () => {
+      settle([]);
+      await Promise.resolve();
+    });
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+  });
+
+  it('keeps the loading state under StrictMode for a pending autofocus bootstrap', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const bootstrap = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    render(
+      <StrictMode>
+        <Typeahead
+          label="Test"
+          searchSource={{search: () => [], bootstrap}}
+          value={null}
+          onChange={() => {}}
+          hasAutoFocus
+          hasEntriesOnFocus
+        />
+      </StrictMode>,
+    );
+
+    expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+
+    await act(async () => {
+      settle([]);
+      await Promise.resolve();
+    });
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+  });
+
+  let settlePendingTransitionA: (items: SearchableItem[]) => void = () => {};
+  const stableTransitionSourceA: SearchSource = {
+    search: vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settlePendingTransitionA = resolve;
+        }),
+    ),
+    bootstrap: () => [],
+  };
+  const stableTransitionSourceB: SearchSource = {
+    search: vi.fn(async () => []),
+    bootstrap: () => [],
+  };
+
+  it('clears loading and aria-busy when source is replaced in a transition that suspends and retries', async () => {
+    let isSuspended = false;
+    let resolveSuspension: () => void = () => {};
+    let pendingSuspension: Promise<void> | null = null;
+
+    function SuspendingSibling({shouldSuspend}: {shouldSuspend: boolean}) {
+      if (shouldSuspend && isSuspended && pendingSuspension) {
+        // eslint-disable-next-line @typescript-eslint/only-throw-error
+        throw pendingSuspension;
+      }
+      return null;
+    }
+
+    let updateState!: (source: SearchSource, shouldSuspend: boolean) => void;
+
+    function TransitionContainer() {
+      const [source, setSource] = useState<SearchSource>(
+        stableTransitionSourceA,
+      );
+      const [shouldSuspend, setShouldSuspend] = useState(false);
+      updateState = (newSource, suspend) => {
+        setSource(newSource);
+        setShouldSuspend(suspend);
+      };
+
+      return (
+        <Suspense fallback={<div>Suspended...</div>}>
+          <Typeahead
+            label="Test"
+            searchSource={source}
+            value={null}
+            onChange={() => {}}
+            debounceMs={0}
+          />
+          <SuspendingSibling shouldSuspend={shouldSuspend} />
+        </Suspense>
+      );
+    }
+
+    render(<TransitionContainer />);
+    const input = screen.getByRole('combobox');
+
+    // Trigger a load so aria-busy="true" is set on the combobox
+    fireEvent.change(input, {target: {value: 'query'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-busy', 'true');
+    });
+    expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+
+    // Create the pending promise for suspension
+    isSuspended = true;
+    pendingSuspension = new Promise<void>(resolve => {
+      resolveSuspension = () => {
+        isSuspended = false;
+        resolve();
+      };
+    });
+
+    // Inside startTransition, switch from source A to source B while sibling suspends
+    act(() => {
+      startTransition(() => {
+        updateState(stableTransitionSourceB, true);
+      });
+    });
+
+    // The render suspended, so the previous committed state remains
+    expect(input).toHaveAttribute('aria-busy', 'true');
+
+    // Resolve the pending promise and let the transition commit
+    await act(async () => {
+      resolveSuspension();
+      await pendingSuspension;
+    });
+
+    // Settle the abandoned load
+    await act(async () => {
+      settlePendingTransitionA([]);
+      await Promise.resolve();
+    });
+
+    // The combobox must not keep aria-busy and the spinner must be gone
+    expect(input).not.toHaveAttribute('aria-busy');
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+  });
+
   it('shows bootstrap results on mouse click', async () => {
     render(
       <BaseTypeahead
@@ -1323,6 +1524,63 @@ describe('BaseTypeahead hasSearched reset', () => {
     // "No results found" should disappear since hasSearched is reset
     expect(screen.queryByText('No results found')).not.toBeInTheDocument();
   });
+
+  it('resets hasSearched and does not announce "No results found" when search source is replaced during a pending search', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const initialSource: SearchSource = {
+      search: vi.fn(
+        async () =>
+          new Promise<SearchableItem[]>(resolve => {
+            settle = resolve;
+          }),
+      ),
+      bootstrap: () => [],
+    };
+    const replacementSource: SearchSource = {
+      search: vi.fn(async () => []),
+      bootstrap: () => [],
+    };
+
+    const {rerender} = render(
+      <BaseTypeahead
+        searchSource={initialSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    // Type a query that starts an asynchronous search
+    fireEvent.change(input, {target: {value: 'abc'}});
+    expect(initialSource.search).toHaveBeenCalledWith('abc');
+
+    // Replace the search source while the search is still pending
+    rerender(
+      <BaseTypeahead
+        searchSource={replacementSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+
+    // Settle the abandoned search
+    await act(async () => {
+      settle([]);
+      await Promise.resolve();
+    });
+
+    await act(
+      async () =>
+        new Promise<void>(resolve => requestAnimationFrame(() => resolve())),
+    );
+    expect(
+      document.querySelector('[data-astryx-live-region="polite"]')
+        ?.textContent ?? '',
+    ).not.toContain('No results found');
+    expect(screen.queryByText('No results found')).not.toBeInTheDocument();
+  });
 });
 
 describe('BaseTypeahead popover after selection', () => {
@@ -2313,7 +2571,7 @@ describe('Typeahead consumer key handler order', () => {
       currentTarget = event.currentTarget;
       event.preventDefault();
     });
-    const {container} = render(
+    render(
       <Typeahead
         label="Fruit"
         searchSource={fruitSource}

package/src/hooks/useEntryAnimation.doc.mjs

@@ -18,12 +18,12 @@ export const docs = {
     {
       name: 'entryStyle',
       type: 'StyleXStyles | null',
-      description: 'A StyleX style object for the entry animation, or null if the element was rendered on initial page load (no animation needed).',
+      description: 'A StyleX style object for the entry animation, or null if the element was rendered on initial page load or hydrated from server HTML (no animation needed).',
     },
   ],
   usage: {
     description:
-      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
+      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Server-rendered elements hydrate without the entry style and never animate; elements mounted after hydration animate.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
       { guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
@@ -39,7 +39,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Server-rendered elements hydrate without entry style, never animate; elements mounted after hydration animate.',
   paramDescriptions: {
     preset: 'animation preset applied on mount.',
   },
@@ -48,7 +48,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Server-rendered elements hydrate without entry style, never animate; elements mounted after hydration animate.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
       { guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },