@astryxdesign/core 0.7.2 → 0.7.3-canary.0bf23bd

package/src/Tooltip/__tests__/Tooltip.a11y.states.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tooltip.a11y.states.ts
+ * @input Tooltip's and useTooltip's representative states and the facts TOOLTIP_PATTERN reads
+ * @output TOOLTIP_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Tooltip and useTooltip under spec:AST-020 FR15)
+ */
+
+import type {TooltipStateFacts} from '@astryxdesign/a11y-spec';
+
+/**
+ * How the caller attaches the tooltip: wrapping an element, wrapping plain
+ * text, pointing `anchorRef` at its own element, or calling `useTooltip`.
+ */
+export type TooltipAttachment =
+  'wrapped-element' | 'text' | 'anchor-ref' | 'hook';
+
+export interface TooltipBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  readonly attachment: TooltipAttachment;
+  /**
+   * The trigger's visible text. A `button` trigger is also named by it; a
+   * text trigger has no role, so the lanes find it by this text.
+   */
+  readonly triggerText: string;
+  readonly triggerRole: 'button' | null;
+  /** The tooltip `content`. */
+  readonly content: string;
+  /** A visible hint the trigger is already described by, besides the tooltip. */
+  readonly hint?: string;
+  readonly facts: TooltipStateFacts;
+}
+
+const story = (id: string) => `a11y-tooltip--${id}`;
+
+/** Tooltip's and useTooltip's default hover delay. */
+const DEFAULT_DELAY: TooltipStateFacts = {showsOnHover: true, showDelayMs: 200};
+
+export const TOOLTIP_BINDING_STATES = [
+  {
+    id: 'wrapped-button',
+    summary:
+      'a Tooltip wrapping a Button, which attaches to the Button and describes it',
+    storyId: story('wrapped-button'),
+    attachment: 'wrapped-element',
+    triggerText: 'Save',
+    triggerRole: 'button',
+    content: 'Saves your changes to this draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'text-trigger',
+    summary:
+      'a Tooltip wrapping plain text, which renders its own focusable inline trigger',
+    storyId: story('text-trigger'),
+    attachment: 'text',
+    triggerText: 'Draft',
+    triggerRole: null,
+    content: 'Only you can see a draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'anchor-ref-with-hint',
+    summary:
+      'a Tooltip attached through anchorRef to a caller button that is already described by a visible hint, so the trigger is described by both',
+    storyId: story('anchor-ref-with-hint'),
+    attachment: 'anchor-ref',
+    triggerText: 'Publish',
+    triggerRole: 'button',
+    content: 'Makes this page visible to everyone',
+    hint: 'Last published yesterday',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'use-tooltip-hook',
+    summary:
+      "useTooltip on a caller button, which spreads the hook's ref and describedBy onto it and renders the tooltip",
+    storyId: story('use-tooltip-hook'),
+    attachment: 'hook',
+    triggerText: 'Archive',
+    triggerRole: 'button',
+    content: 'Moves this page out of the list',
+    facts: DEFAULT_DELAY,
+  },
+] as const satisfies ReadonlyArray<TooltipBindingState>;
+
+export const TOOLTIP_EXCLUSIONS = [
+  {
+    id: 'focus-trigger',
+    owner:
+      "the 24 core hosts that pass focusTrigger 'always' — the disabledMessage tooltips on the field and choice controls (TextInput, TextArea, NumberInput, Switch, CheckboxInput, CheckboxList, RadioList, Selector, MultiSelector, SegmentedControl, Slider, Typeahead, Tokenizer, FileInput, and the date and time inputs), the Slider value bubble and ProgressBar marks — each through its own suite (for example TextInput.test.tsx 'shows the reason tooltip on keyboard focus'); and any caller that passes 'never'",
+    reason:
+      "'always' attaches the focus listeners to a wrapper that is not itself focusable, so focusin bubbling from the control inside it shows the hint; the described element and the focused element differ, which this contract's trigger-centred rows do not model, so each host proves its own keyboard path. 'never' detaches focus showing for a trigger inside a composite widget that moves focus itself, which then owns how a keyboard user reaches the hint; no shipped composition uses it. Every state here uses the default 'auto'.",
+  },
+  {
+    id: 'touch-trigger',
+    owner:
+      'useTooltip.test.tsx and Tooltip.test.tsx (touchTrigger suites) through the shared useTouchTrigger hook',
+    reason:
+      'On a touch pointer there is no hover, so a tap opens the tooltip or leaves it to the control the tap operates; the APG defines no touch behaviour, and the Chromium lane drives a mouse and a keyboard only.',
+  },
+  {
+    id: 'controlled-and-disabled',
+    owner:
+      'Tooltip.test.tsx and useTooltip.test.tsx (isOpen, isDefaultOpen and isEnabled suites)',
+    reason:
+      'A controlled tooltip answers Escape by reporting instead of hiding, and a disabled one never shows; both hand visibility to the caller, so the hover and focus outcomes this contract reads belong to the uncontrolled, enabled tooltip every state renders.',
+  },
+  {
+    id: 'interactive-hover-content',
+    owner: 'the HoverCard binding and the overlay-dismissal family',
+    reason:
+      'Hover content a user can interact with is a non-modal dialog, not a tooltip, so HoverCard and other interactive popovers are reviewed separately; no state here places a focusable control inside a tooltip.',
+  },
+  {
+    id: 'host-compositions',
+    owner:
+      "the composing components' own contracts (Button for the IconButton label tooltip, the input status binding for useInputStatusIcon, which renders the on-field status tooltip) and their tests",
+    reason:
+      'IconButton, useInputStatusIcon and Lab InfoTip render Tooltip or useTooltip for their own purposes; this binding proves the tooltip they render, and what each host adds around it is that host.',
+  },
+  {
+    id: 'placement-and-paint',
+    owner:
+      'Tooltip.test.tsx (placement and alignment), the layer runtime anchor tests, and the repository visual gate',
+    reason:
+      'Placement, alignment, the inverted surface and the hover underline on a text trigger are layout and paint; they change no role, description, focus or dismissal outcome, so every state uses the default placement.',
+  },
+] as const;

package/src/Tooltip/__tests__/Tooltip.a11y.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Tooltip.a11y.test.tsx
+ * @input TOOLTIP_PATTERN bound to Tooltip's and useTooltip's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Tooltip and useTooltip (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLTIP_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderTooltipState} from './Tooltip.a11y.renders';
+import {
+  TOOLTIP_BINDING_STATES,
+  TOOLTIP_EXCLUSIONS,
+  type TooltipBindingState,
+} from './Tooltip.a11y.states';
+
+function triggerFor(state: TooltipBindingState): HTMLElement {
+  return state.triggerRole == null
+    ? screen.getByText(state.triggerText, {exact: true})
+    : screen.getByRole(state.triggerRole, {name: state.triggerText});
+}
+
+function relatedFor(): Readonly<Record<string, Element>> {
+  return {
+    // The tooltip stays in the page while hidden; it is found with hidden
+    // elements included so the DOM rows can read it before it shows.
+    tooltip: screen.getByRole('tooltip', {hidden: true}),
+    before: screen.getByRole('button', {name: 'Before the trigger'}),
+    after: screen.getByRole('button', {name: 'After the trigger'}),
+  };
+}
+
+async function checkState(state: TooltipBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLTIP_PATTERN,
+    binding: 'Tooltip',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderTooltipState(state));
+      return createJsdomHarness({
+        subject: triggerFor(state),
+        related: relatedFor(),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Tooltip — tooltip pattern, jsdom lane', () => {
+  it.each(
+    TOOLTIP_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLTIP_PATTERN,
+      binding: 'Tooltip',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderTooltipState(state));
+      },
+      subject: () => triggerFor(state),
+      related: () => relatedFor(),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TOOLTIP_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLTIP_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('tooltip binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLTIP_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps focus-trigger opt-outs, touch, controlled visibility, interactive hover content, host compositions and paint explicit', () => {
+    expect(TOOLTIP_EXCLUSIONS.map(row => row.id)).toEqual([
+      'focus-trigger',
+      'touch-trigger',
+      'controlled-and-disabled',
+      'interactive-hover-content',
+      'host-compositions',
+      'placement-and-paint',
+    ]);
+    for (const exclusion of TOOLTIP_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the trigger, one tooltip and both page buttons for every state', () => {
+    for (const state of TOOLTIP_BINDING_STATES) {
+      render(renderTooltipState(state));
+      expect(triggerFor(state), state.id).toBeTruthy();
+      expect(
+        screen.getAllByRole('tooltip', {hidden: true}),
+        state.id,
+      ).toHaveLength(1);
+      expect(Object.keys(relatedFor())).toEqual(['tooltip', 'before', 'after']);
+      cleanup();
+    }
+  });
+});

package/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TooltipHoverBridge.a11y.chromium.spec.ts
+ * @input The `Core/Tooltip` Default story in a built Storybook and real mouse
+ *   input.
+ * @output Real-engine proof that a pointer moving from the trigger onto the
+ *   tooltip in one step keeps the tooltip open (WCAG 2.2 1.4.13 Content on
+ *   Hover or Focus, hoverable), and that leaving the tooltip still hides it.
+ * @position Run with `pnpm test:a11y-contract`. The defect lives in the order
+ *   the engine dispatches mouseout and mouseleave on one pointer step, which
+ *   only a real engine produces.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'core-tooltip--default';
+
+async function openTooltip(page: Page) {
+  await page.setViewportSize({width: 900, height: 600});
+  await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+  await holdMotionStill(page);
+  const trigger = page.getByRole('button', {name: 'Hover me'});
+  await trigger.hover();
+  const tooltip = page.getByRole('tooltip');
+  await expect(tooltip).toBeVisible();
+  const t = await trigger.boundingBox();
+  const s = await tooltip.boundingBox();
+  if (t == null || s == null) {
+    throw new Error('the trigger or the tooltip has no layout box');
+  }
+  return {tooltip, s};
+}
+
+test('a one-step move from the trigger onto the tooltip keeps it open', async ({
+  page,
+}) => {
+  const {tooltip, s} = await openTooltip(page);
+
+  // One mousemove event straight onto the tooltip, as a quick hand makes.
+  await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+  // Well past the 100ms hover bridge.
+  await page.waitForTimeout(400);
+
+  await expect(tooltip).toBeVisible();
+});
+
+test('leaving the tooltip for the page still hides it', async ({page}) => {
+  const {tooltip, s} = await openTooltip(page);
+
+  await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+  await page.waitForTimeout(200);
+  await page.mouse.move(5, 5);
+
+  await expect(tooltip).toBeHidden();
+});

package/src/Tooltip/useTooltip.test.tsx

@@ -214,6 +214,29 @@ describe('useTooltip — hide delay', () => {
     expect(onHide).toHaveBeenCalledTimes(1);
   });
 
+  it('stays open when the pointer crosses onto the tooltip in one step', () => {
+    const onHide = vi.fn();
+    showTooltip(onHide);
+    const surface = tooltipElement();
+
+    // A one-step crossing dispatches in browser order: the trigger's mouseout
+    // (React derives the surface's onMouseEnter from it), then the trigger's
+    // native mouseleave, both pointing at the surface. fireEvent.mouseLeave
+    // would add a mouseout after the leave, so the leave is dispatched raw.
+    fireEvent.mouseOut(trigger(), {relatedTarget: surface});
+    act(() => {
+      trigger().dispatchEvent(
+        new MouseEvent('mouseleave', {relatedTarget: surface}),
+      );
+    });
+    tick(500);
+    expect(onHide).not.toHaveBeenCalled();
+
+    fireEvent.mouseOut(surface, {relatedTarget: document.body});
+    tick(100);
+    expect(onHide).toHaveBeenCalledTimes(1);
+  });
+
   it('uses an explicit hideDelay instead of the hover bridge', () => {
     const onHide = vi.fn();
     showTooltip(onHide, {hideDelay: 500});

package/src/Tooltip/useTooltip.tsx

@@ -397,15 +397,28 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     scheduleShow();
   }, [isTouchPointerRef, scheduleShow]);
 
-  const handleMouseLeave = useCallback(() => {
-    // On touch the synthesized mouseleave arrives with the next tap elsewhere,
-    // which the outside-tap dismissal already handles — and handling it here
-    // too would close the tooltip behind the tap-open bookkeeping's back.
-    if (isTouchPointerRef.current) {
-      return;
-    }
-    scheduleHide();
-  }, [isTouchPointerRef, scheduleHide]);
+  const handleMouseLeave = useCallback(
+    (event: Event) => {
+      // On touch the synthesized mouseleave arrives with the next tap elsewhere,
+      // which the outside-tap dismissal already handles — and handling it here
+      // too would close the tooltip behind the tap-open bookkeeping's back.
+      if (isTouchPointerRef.current) {
+        return;
+      }
+      // Leaving straight onto the tooltip: the surface's onMouseEnter already
+      // ran, because React dispatches it from the mouseout that precedes this
+      // mouseleave, so a hide scheduled now would never be cancelled. The
+      // surface's own mouse leave schedules the hide instead.
+      const next = (event as MouseEvent).relatedTarget as Node | null;
+      const surface =
+        next == null ? null : next.ownerDocument?.getElementById(layerId);
+      if (surface != null && surface.contains(next)) {
+        return;
+      }
+      scheduleHide();
+    },
+    [isTouchPointerRef, layerId, scheduleHide],
+  );
 
   const handleFocusIn = useCallback(
     (e: Event) => {

package/src/TopNav/TopNav.tsx

@@ -94,10 +94,18 @@ const styles = stylex.create({
     padding: spacingVars['--spacing-2'],
     boxSizing: 'border-box',
   },
+  // The heading gives up space first so the end content and toggle stay in view
+  mobileBarHeading: {
+    display: 'flex',
+    alignItems: 'center',
+    flex: '0 1 auto',
+    minWidth: 0,
+  },
   mobileBarEnd: {
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-1'],
+    flexShrink: 0,
     marginInlineStart: 'auto',
   },
   // Drawer mode — vertical list of nav items
@@ -215,7 +223,9 @@ export function TopNav({
           style,
         )}
         {...props}>
-        {heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
+        {heading && (
+          <div {...stylex.props(styles.mobileBarHeading)}>{heading}</div>
+        )}
         <div {...stylex.props(styles.mobileBarEnd)}>
           {endContent}
           {hasMobileDrawerContent && hasAutoToggle && <MobileNavToggle />}

package/src/TopNav/TopNavHeading.tsx

@@ -52,6 +52,7 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
     minHeight: spacingVars['--spacing-8'],
+    minWidth: 0,
     paddingInlineStart: {
       default: spacingVars['--spacing-2'],
       ':has(.astryx-nav-icon)': 0,

package/src/TopNav/__tests__/TopNavMobileLongHeading.a11y.chromium.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TopNavMobileLongHeading.a11y.chromium.spec.ts
+ * @input The `Core/AppShell` Long Heading On Mobile story in a built Storybook
+ *   at a 320px phone viewport.
+ * @output Real-engine proof that a long TopNav heading gives way on a narrow
+ *   screen: the menu toggle stays inside the compact bar, and the drawer's
+ *   close button stays inside the drawer.
+ * @position Run with `pnpm test:a11y-contract`. jsdom has no layout, so where
+ *   the toggle lands is only observable here.
+ */
+
+import {expect, test, type Locator} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'core-appshell--long-heading-on-mobile';
+
+async function boxOf(locator: Locator) {
+  const box = await locator.boundingBox();
+  if (box == null) {
+    throw new Error('the element has no layout box');
+  }
+  return box;
+}
+
+test('a long heading keeps the menu toggle and the drawer close button on screen', async ({
+  page,
+}) => {
+  await page.setViewportSize({width: 320, height: 568});
+  await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+
+  const bar = page.getByRole('navigation', {name: 'Main navigation'});
+  const toggle = page.getByRole('button', {name: 'Open navigation'});
+  await expect(toggle).toBeVisible();
+
+  const barBox = await boxOf(bar);
+  const toggleBox = await boxOf(toggle);
+  expect(toggleBox.x).toBeGreaterThanOrEqual(barBox.x);
+  expect(toggleBox.x + toggleBox.width).toBeLessThanOrEqual(
+    barBox.x + barBox.width,
+  );
+
+  await toggle.click();
+
+  const drawer = page.getByRole('dialog', {name: 'Navigation'});
+  const close = drawer.getByRole('button', {name: 'Close navigation'});
+  await expect(close).toBeVisible();
+
+  // The drawer slides in from the inline end; measure once it has settled.
+  await expect(close).toBeInViewport({ratio: 1});
+  const drawerBox = await boxOf(drawer);
+  const closeBox = await boxOf(close);
+  expect(closeBox.x).toBeGreaterThanOrEqual(drawerBox.x);
+  expect(closeBox.x + closeBox.width).toBeLessThanOrEqual(
+    drawerBox.x + drawerBox.width,
+  );
+});

package/src/Typeahead/Typeahead.test.tsx

@@ -1637,6 +1637,95 @@ describe('Typeahead edit mode', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  it('empties the input when cleared while editing the selected value (#7038)', async () => {
+    const onChangeQuery = vi.fn();
+    function Controlled() {
+      const [value, setValue] = useState<SearchableItem | null>(fruits[0]);
+      return (
+        <Typeahead
+          label="Fruit"
+          searchSource={fruitSource}
+          value={value}
+          onChange={setValue}
+          onChangeQuery={onChangeQuery}
+          hasClear
+        />
+      );
+    }
+    render(<Controlled />);
+    const input = screen.getByRole<HTMLInputElement>('combobox');
+
+    // Enter edit mode: the token gives way to the label as editable text
+    fireEvent.click(screen.getByText(fruits[0].label).closest('div')!);
+    await waitFor(() => expect(input.value).toBe(fruits[0].label));
+
+    fireEvent.click(screen.getByRole('button', {name: 'Clear selection'}));
+
+    // The value and the visible text agree: nothing selected, nothing typed
+    await waitFor(() => expect(input.value).toBe(''));
+    expect(onChangeQuery).toHaveBeenLastCalledWith('');
+    expect(input).toHaveFocus();
+  });
+
+  // Escape and blur restore the token but leave the edit-mode label in the
+  // base's query, so a clear from the restored token faces the same stale text.
+  it.each([
+    [
+      'Escape',
+      (input: HTMLElement) => fireEvent.keyDown(input, {key: 'Escape'}),
+    ],
+    ['blur', (input: HTMLElement) => fireEvent.blur(input)],
+  ])(
+    'empties the input when cleared after %s restored the token (#7038)',
+    async (_name, leaveEditMode) => {
+      const onChangeQuery = vi.fn();
+      function Controlled() {
+        const [value, setValue] = useState<SearchableItem | null>(fruits[0]);
+        return (
+          <Typeahead
+            label="Fruit"
+            searchSource={fruitSource}
+            value={value}
+            onChange={setValue}
+            onChangeQuery={onChangeQuery}
+            hasClear
+          />
+        );
+      }
+      render(<Controlled />);
+      const input = screen.getByRole<HTMLInputElement>('combobox');
+
+      fireEvent.click(screen.getByText(fruits[0].label).closest('div')!);
+      await waitFor(() => expect(input.value).toBe(fruits[0].label));
+
+      leaveEditMode(input);
+      await screen.findByRole('button', {name: 'Clear selection'});
+
+      fireEvent.click(screen.getByRole('button', {name: 'Clear selection'}));
+
+      await waitFor(() => expect(input.value).toBe(''));
+      expect(onChangeQuery).toHaveBeenLastCalledWith('');
+    },
+  );
+
+  it('does not report a query change when cleared outside edit mode', () => {
+    const onChangeQuery = vi.fn();
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={vi.fn()}
+        onChangeQuery={onChangeQuery}
+        hasClear
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', {name: 'Clear selection'}));
+
+    expect(onChangeQuery).not.toHaveBeenCalled();
+  });
+
   it('restores token on blur without action', async () => {
     const onChange = vi.fn();
     render(

package/src/Typeahead/Typeahead.tsx

@@ -519,12 +519,25 @@ export function Typeahead<T extends SearchableItem>({
     [onChange],
   );
 
-  // Handle clear (explicit X button on token)
+  // Handle clear (explicit X button on token). Edit mode copied the label into
+  // the base's query, and the base only resets that query on a selection, so
+  // clearing the value has to empty it the way entering edit mode filled it
+  // (#7038): a native set plus a synthetic input event, which reaches the
+  // base's own change handler and its onChangeQuery.
   const handleClear = useCallback(() => {
+    const input = inputRef.current;
+    if (input && input.value !== '') {
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value',
+      )?.set;
+      nativeInputValueSetter?.call(input, '');
+      input.dispatchEvent(new Event('input', {bubbles: true}));
+    }
     setIsEditing(false);
     setEditingValue(null);
     onChange(null);
-    inputRef.current?.focus();
+    input?.focus();
   }, [onChange]);
 
   // Handle Escape during edit mode — restore token