@astryxdesign/core 0.7.1 → 0.7.2-canary.151434a

package/src/TabList/TabMenu.tsx

@@ -37,7 +37,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useTabListContext} from './TabListContext';
 import type {TabListSize} from './TabListContext';
 import {tabScope} from './tab.markers.stylex';
-import {mergeProps} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -51,9 +51,9 @@ export interface TabMenuOption {
   icon?: ReactNode | IconType;
 }
 
-export interface TabMenuProps extends Pick<
+export interface TabMenuProps extends Omit<
   BaseProps<HTMLButtonElement>,
-  'xstyle' | 'className' | 'style'
+  'role' | 'tabIndex' | 'aria-haspopup' | 'aria-expanded' | 'aria-controls'
 > {
   ref?: React.Ref<HTMLButtonElement>;
   /**
@@ -263,6 +263,8 @@ export function TabMenu({
   xstyle,
   className,
   style,
+  onClick,
+  ...rest
 }: TabMenuProps) {
   const tabListCtx = useTabListContext();
   const menuId = useId();
@@ -346,6 +348,7 @@ export function TabMenu({
   return (
     <>
       <button
+        {...rest}
         ref={setButtonRef}
         type="button"
         aria-haspopup="menu"
@@ -353,7 +356,7 @@ export function TabMenu({
         aria-controls={menuId}
         data-tab-menu=""
         tabIndex={hasSelectedOption ? 0 : -1}
-        onClick={handleToggle}
+        onClick={composeEventHandlers(handleToggle, onClick)}
         {...mergeProps(
           themeProps('tab-menu'),
           focusOutlineProps.focusVisible(

package/src/Text/useTruncation.test.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTruncation.test.tsx
+ * Tests for useTruncation
+ */
+
+import {render, screen, waitFor} from '@testing-library/react';
+import {afterEach, describe, it, expect, vi} from 'vitest';
+import {useTruncation} from './useTruncation';
+
+function Probe({text}: {text: string}) {
+  const truncation = useTruncation({maxLines: 1});
+  return (
+    <>
+      <span ref={truncation.ref}>{text}</span>
+      <output data-testid="full-text">{truncation.fullText}</output>
+    </>
+  );
+}
+
+// A status line at a fixed width never resizes when its message changes, so
+// the tooltip text must follow the content, not only the element's size.
+describe('useTruncation', () => {
+  it('re-measures when the text changes without a resize', async () => {
+    const {rerender} = render(<Probe text="planning the first step" />);
+    expect(screen.getByTestId('full-text')).toHaveTextContent(
+      'planning the first step',
+    );
+
+    rerender(<Probe text="writing the second step" />);
+
+    await waitFor(() =>
+      expect(screen.getByTestId('full-text')).toHaveTextContent(
+        'writing the second step',
+      ),
+    );
+  });
+
+  describe('content observation', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('shares one observer across every truncating instance', () => {
+      const NativeMutationObserver = globalThis.MutationObserver;
+      let created = 0;
+      vi.stubGlobal(
+        'MutationObserver',
+        class extends NativeMutationObserver {
+          constructor(callback: MutationCallback) {
+            super(callback);
+            created += 1;
+          }
+        },
+      );
+
+      render(
+        <>
+          {Array.from({length: 50}, (_, index) => (
+            <Probe key={index} text={`cell ${index}`} />
+          ))}
+        </>,
+      );
+
+      expect(created).toBe(1);
+    });
+  });
+});

package/src/Text/useTruncation.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTruncation.ts
- * @input Uses React hooks, sharedResizeObserver
+ * @input Uses React hooks, sharedResizeObserver, sharedMutationObserver
  * @output Exports useTruncation hook for detecting text overflow
  * @position Hook; consumed by Text.tsx, Heading.tsx
  *
@@ -14,6 +14,7 @@
 
 import {useCallback, useRef, useState, type RefCallback} from 'react';
 import {observeResize} from '../utils/sharedResizeObserver';
+import {observeContent} from '../utils/sharedMutationObserver';
 
 export interface UseTruncationOptions {
   /**
@@ -43,10 +44,12 @@ export interface UseTruncationReturn {
 /**
  * Hook for detecting text overflow/truncation.
  *
- * Uses a shared ResizeObserver singleton (via observeResize)
- * for efficient detection when content or container changes. A single
- * ResizeObserver instance is shared across all mounted useTruncation hooks,
- * so even hundreds of table cells only create one observer.
+ * Uses a shared ResizeObserver singleton (via observeResize) for size
+ * changes and a shared MutationObserver singleton (via observeContent) for
+ * content changes, so even hundreds of table cells create one observer of
+ * each kind. Observing content matters because an element whose text changes
+ * without resizing (a fixed-width status line) must still be re-measured for
+ * the tooltip text and the truncated state to follow the current content.
  *
  * - Single-line: compares scrollWidth > offsetWidth
  * - Multi-line: uses Range.getBoundingClientRect() to measure actual content
@@ -71,6 +74,7 @@ export function useTruncation(
   const [fullText, setFullText] = useState('');
   const elementRef = useRef<HTMLElement | null>(null);
   const unobserveRef = useRef<(() => void) | null>(null);
+  const unobserveContentRef = useRef<(() => void) | null>(null);
 
   const checkTruncation = useCallback(
     (element: HTMLElement) => {
@@ -113,6 +117,8 @@ export function useTruncation(
       // by element leaves any other observer of the same node untouched.
       unobserveRef.current?.();
       unobserveRef.current = null;
+      unobserveContentRef.current?.();
+      unobserveContentRef.current = null;
 
       elementRef.current = element;
 
@@ -127,6 +133,11 @@ export function useTruncation(
         } else {
           checkTruncation(element);
         }
+        // New text in a box that keeps its size fires no resize, so the
+        // captured text and truncated state would otherwise stay stale.
+        unobserveContentRef.current = observeContent(element, () => {
+          checkTruncation(element);
+        });
       } else {
         setIsTruncated(false);
         setFullText('');

package/src/Tokenizer/Tokenizer.test.tsx

@@ -20,7 +20,7 @@ import {
   afterEach,
 } from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
-import {createRef, Profiler} from 'react';
+import {createRef, Profiler, useState} from 'react';
 import userEvent from '@testing-library/user-event';
 import {Tokenizer} from './Tokenizer';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -1790,6 +1790,59 @@ describe('Tokenizer end-lane reserve', () => {
     expect(renderedTokens).toEqual([]);
   });
 
+  it('clears the busy spinner when a token is added while a bootstrap load is in flight', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const bootstrap = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    const source: SearchSource = {search: () => [], bootstrap};
+
+    function Harness() {
+      const [value, setValue] = useState<SearchableItem[]>([]);
+      return (
+        <>
+          <Tokenizer
+            label="Items"
+            searchSource={source}
+            value={value}
+            onChange={setValue}
+            hasEntriesOnFocus
+          />
+          <button type="button" onClick={() => setValue([users[0]])}>
+            Add Token
+          </button>
+        </>
+      );
+    }
+
+    render(<Harness />);
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    await waitFor(() => {
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole('button', {name: 'Add Token'}));
+
+    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('shares one observer across every field on the page', () => {
     // Browsers batch per observer instance, so one observer per lane meant N
     // callback dispatches a frame for N fields.

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);