@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -48,9 +48,10 @@ export const docs = {
     },
     {
       name: 'size',
-      type: 'AvatarSize',
+      type:
+        "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180",
       description:
-        "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
+        "Size applied to all avatars: named sizes are 'xsm' (20px), 'sm' (24px), 'md' (36px), 'lg' (48px), and 'xl' (128px); numeric sizes must be one of the pixel values listed in the type. The group's size always overrides each child Avatar's size, including when the group uses its default size.",
       default: "'md'",
     },
     {

package/src/AvatarGroup/AvatarGroupOverflow.test.tsx

@@ -21,6 +21,29 @@ describe('AvatarGroupOverflow', () => {
     expect(overflow).toHaveTextContent('+5');
   });
 
+  it('exposes the static overflow as a named image', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByRole('img', {name: '5 more'});
+    expect(overflow).toHaveAttribute('role', 'img');
+  });
+
+  it('keeps a caller-supplied role on the static overflow', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} role="note" />
+      </AvatarGroup>,
+    );
+
+    expect(screen.getByLabelText('5 more')).toHaveAttribute('role', 'note');
+  });
+
   it('reflects the group size on the overflow chip', () => {
     render(
       <AvatarGroup size="lg">
@@ -66,7 +89,7 @@ describe('AvatarGroupOverflow', () => {
       </AvatarGroup>,
     );
 
-    const overflow = screen.getByLabelText('3 more');
+    const overflow = screen.getByRole('button', {name: '3 more'});
     expect(overflow.tagName).toBe('BUTTON');
   });
 

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -208,6 +208,8 @@ export function AvatarGroupOverflow({
   return (
     <span
       ref={ref}
+      // Before the caller's props so a caller-supplied role still wins.
+      role="img"
       {...rest}
       aria-label={label}
       {...mergeProps(

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -56,6 +56,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
+  DropdownMenuRootOpenContext,
   type DropdownMenuContextValue,
   type DropdownMenuSize,
 } from '../DropdownMenu/DropdownMenuContext';
@@ -673,7 +674,9 @@ function BreadcrumbMenuTrigger({
             stylex.props(menuStyles.menu),
           )}>
           <DropdownMenuContext value={contextValue}>
-            {menuContent}
+            <DropdownMenuRootOpenContext value={popover.isOpen}>
+              {menuContent}
+            </DropdownMenuRootOpenContext>
           </DropdownMenuContext>
         </div>,
         {

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -7,12 +7,13 @@ import {Breadcrumbs} from './Breadcrumbs';
 import {BreadcrumbItem} from './BreadcrumbItem';
 import {
   BreadcrumbMenuItem,
+  BreadcrumbMenuDivider,
   BreadcrumbMenuGroup,
   BreadcrumbMenuCheckboxItem,
   BreadcrumbMenuRadioGroup,
   BreadcrumbMenuRadioItem,
 } from './index';
-import type {BreadcrumbMenuOption} from './index';
+import type {BreadcrumbMenuDividerProps, BreadcrumbMenuOption} from './index';
 import {LinkProvider} from '../Link/LinkProvider';
 
 function CustomLink({
@@ -771,6 +772,34 @@ describe('BreadcrumbItem menu', () => {
     expect(separators).toHaveLength(3);
   });
 
+  it('renders the separator and props types through the BreadcrumbMenuDivider aliases', async () => {
+    const user = userEvent.setup();
+    const dividerProps: BreadcrumbMenuDividerProps = {
+      'data-testid': 'breadcrumb-menu-divider',
+    };
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={
+            <>
+              <BreadcrumbMenuItem label="Overview" />
+              <BreadcrumbMenuDivider {...dividerProps} />
+              <BreadcrumbMenuItem label="Settings" />
+            </>
+          }>
+          Project
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Project'}));
+
+    expect(screen.getByTestId('breadcrumb-menu-divider')).toHaveAttribute(
+      'role',
+      'separator',
+    );
+  });
+
   it('carries the group semantics through the BreadcrumbMenuGroup alias', async () => {
     // The alias must bring the semantics, not just the component: a group
     // that renders but is not named leaves a screen reader with a run of

package/src/Card/Card.doc.mjs

@@ -83,7 +83,7 @@ export const docs = {
       code: `
 import {Card} from '@astryxdesign/core/Card';
 import {Grid} from '@astryxdesign/core/Grid';
-import {VStack} from '@astryxdesign/core/Layout';
+import {VStack} from '@astryxdesign/core/VStack';
 import {Heading} from '@astryxdesign/core/Heading';
 import {Text} from '@astryxdesign/core/Text';
 

package/src/Chat/ChatLayoutScrollButton.test.tsx

@@ -70,6 +70,19 @@ describe('ChatLayoutScrollButton', () => {
     ).toHaveFocus();
   });
 
+  it('makes the pill inert whenever the visible state turns off', () => {
+    const {container, rerender} = render(
+      <ChatLayoutScrollButton isVisible onClick={() => {}} />,
+    );
+    const pill = container.querySelector('.astryx-chat-layout-scroll-button');
+
+    expect(pill).not.toHaveAttribute('inert');
+
+    rerender(<ChatLayoutScrollButton isVisible={false} onClick={() => {}} />);
+
+    expect(pill).toHaveAttribute('inert');
+  });
+
   it('is not keyboard reachable while hidden', async () => {
     const user = userEvent.setup();
     render(

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -86,8 +86,9 @@ const styles = stylex.create({
     opacity: 0,
     pointerEvents: 'none',
     // The hidden pill paints nothing, so focus landing on it would have no
-    // visible indicator (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events`
-    // leave the button in sequential focus navigation; `visibility` removes it.
+    // visible indicator (WCAG 2.2 SC 2.4.7). `visibility` removes it from
+    // sequential navigation after the fade; `inert` immediately prevents new
+    // focus and makes an already-focused descendant relinquish focus.
     visibility: 'hidden',
     maxWidth: sizeVars['--size-element-md'],
   },
@@ -151,6 +152,7 @@ export function ChatLayoutScrollButton({
       {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
       {...rest}>
       <div
+        inert={!isVisible}
         {...mergeProps(
           themeProps('chat-layout-scroll-button'),
           stylex.props(

package/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts

@@ -44,6 +44,7 @@ const STORY_ID = 'core-chatlayout--scroll-affordance-states';
  * a stable handle for it.
  */
 const PILL = '.astryx-chat-layout-scroll-button';
+const AFFORDANCE = `${PILL} button`;
 
 /** One observed tab stop, identified structurally rather than by its text. */
 type FocusStop = {
@@ -126,7 +127,11 @@ test.afterAll(async () => {
 
 async function openStory(
   page: Page,
-  {theme = 'neutral', colorMode = 'light'} = {},
+  {
+    theme = 'neutral',
+    colorMode = 'light',
+    holdMotion = true,
+  }: {theme?: string; colorMode?: string; holdMotion?: boolean} = {},
 ): Promise<Locator> {
   page.on('pageerror', error => pageErrors.push(String(error)));
   browserVersion = page.context().browser()?.version() ?? 'unknown';
@@ -136,7 +141,9 @@ async function openStory(
   );
   const root = page.locator('.astryx-chat-layout');
   await root.waitFor({state: 'visible'});
-  await holdMotionStill(page);
+  if (holdMotion) {
+    await holdMotionStill(page);
+  }
   await page.evaluate(async () => document.fonts.ready);
   return root;
 }
@@ -169,21 +176,25 @@ async function pillVisibility(page: Page): Promise<string> {
 }
 
 /**
- * Can the affordance take focus at all? This is the mechanism under test:
- * `visibility: hidden` removes an element from sequential focus navigation AND
- * refuses programmatic focus, which `opacity: 0` does neither of. A CSS locator
- * is used rather than a role query because a hidden button is not in the
- * accessibility tree and a role query would not resolve it.
+ * Can the affordance take new focus at all? This is one half of the mechanism
+ * under test: `inert` refuses programmatic focus immediately, while delayed
+ * `visibility: hidden` removes the control from sequential navigation after the
+ * fade. A CSS locator is used rather than a role query because a hidden button
+ * is not in the accessibility tree and a role query would not resolve it.
  */
-async function affordanceAcceptsFocus(page: Page): Promise<boolean> {
-  return page
-    .locator('.astryx-chat-layout-scroll-button button')
-    .evaluate(element => {
-      // preventScroll: focusing must not move the scroll position, or the
-      // probe would change the very state the next assertion reads.
-      (element as HTMLElement).focus({preventScroll: true});
-      return document.activeElement === element;
-    });
+async function affordanceAcceptsFocus(
+  page: Page,
+  resetFocus: Locator,
+): Promise<boolean> {
+  // Start outside the affordance so this probe proves a NEW focus transfer;
+  // equality alone would also be true when a button stayed active as it hid.
+  await resetFocus.focus();
+  return page.locator(AFFORDANCE).evaluate(element => {
+    // preventScroll: focusing must not move the scroll position, or the
+    // probe would change the very state the next assertion reads.
+    (element as HTMLElement).focus({preventScroll: true});
+    return document.activeElement === element;
+  });
 }
 
 /**
@@ -340,6 +351,36 @@ async function capture(
   return receipt;
 }
 
+test('the hiding affordance releases focus before its fade finishes', async ({
+  page,
+}) => {
+  const root = await openStory(page, {holdMotion: false});
+  const pill = page.locator(PILL);
+  const affordance = page.locator(AFFORDANCE);
+
+  await scrollToTop(root);
+  await expect(pill).toHaveCSS('visibility', 'visible');
+  await affordance.focus();
+  await expect(affordance).toBeFocused();
+
+  await page.keyboard.press('Enter');
+  await expect
+    .poll(
+      async () =>
+        affordance.evaluate(element => document.activeElement === element),
+      {timeout: 5000},
+    )
+    .toBe(false);
+
+  // `visibility` flips only after the fade. Focus leaving while it is still
+  // visible proves the immediate `inert` state rather than the delayed CSS.
+  await expect(pill).toHaveCSS('visibility', 'visible');
+  await expect
+    .poll(async () => distanceFromBottom(root), {timeout: 5000})
+    .toBeLessThan(2);
+  await expect(pill).toHaveCSS('visibility', 'hidden');
+});
+
 test('the scroll affordance is keyboard reachable exactly while it is visible', async ({
   page,
 }) => {
@@ -367,7 +408,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
   expect(await distanceFromBottom(root)).toBeLessThan(2);
   await expect(pill).toHaveCSS('visibility', 'hidden');
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'a control that paints nothing must refuse focus (WCAG 2.2 SC 2.4.7)',
   ).toBe(false);
   const restFrame = await capture(page, 'rest-hidden', {
@@ -384,7 +425,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
   await expect(pill).toHaveCSS('visibility', 'visible');
   expect(await distanceFromBottom(root)).toBeGreaterThan(100);
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'the visible affordance must keep its keyboard access',
   ).toBe(true);
   await expect(
@@ -415,8 +456,12 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
     .poll(async () => distanceFromBottom(root), {timeout: 5000})
     .toBeLessThan(2);
   await expect(pill).toHaveCSS('visibility', 'hidden');
+  await expect(
+    page.locator(AFFORDANCE),
+    'the affordance must relinquish focus when it hides',
+  ).not.toBeFocused();
   expect(
-    await affordanceAcceptsFocus(page),
+    await affordanceAcceptsFocus(page, before),
     'after returning to the bottom the affordance must refuse focus again',
   ).toBe(false);
   const returnedFrame = await capture(page, 'returned-hidden', {

package/src/Chat/__tests__/ChatMessageMetadata.a11y.chromium.spec.ts

@@ -395,7 +395,9 @@ test('captures narrow touch reflow in both modes', async ({browser}) => {
   try {
     const page = await context.newPage();
     const scenario = CASES.find(item => item.name === 'narrow-overflow');
-    if (!scenario) {throw new Error('Narrow metadata fixture is missing');}
+    if (!scenario) {
+      throw new Error('Narrow metadata fixture is missing');
+    }
     const failures: string[] = [];
     for (const mode of ['light', 'dark'] as const) {
       failures.push(

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -209,6 +209,40 @@ describe('CheckboxInput', () => {
     );
   });
 
+  it('preserves a caller-provided id on the input and its label', () => {
+    render(
+      <CheckboxInput
+        id="accept-terms"
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAttribute('id', 'accept-terms');
+    expect(screen.getByText('Accept terms').closest('label')).toHaveAttribute(
+      'for',
+      'accept-terms',
+    );
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
+  it('generates an id the label resolves when the caller passes an empty id', () => {
+    render(
+      <CheckboxInput
+        id=""
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox.id).not.toBe('');
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
   it('forwards arbitrary data-* attributes to the input', () => {
     render(
       <CheckboxInput

package/src/CheckboxInput/CheckboxInput.tsx

@@ -311,6 +311,7 @@ const dynamicWidthStyles = stylex.create({
  * ```
  */
 export function CheckboxInput({
+  id: idProp,
   label,
   isLabelHidden = false,
   description,
@@ -340,7 +341,8 @@ export function CheckboxInput({
   // The row is the pressable: the overlay's pressed arm reads the row's
   // scope marker, the way the indicator's hover tint does.
   const pressable = usePressFeedback();
-  const id = useId();
+  const generatedId = useId();
+  const id = idProp || generatedId;
   const descriptionID = useId();
   const statusMessageID = useId();
   // Announce the effective required state (form default included) while the

package/src/CheckboxList/CheckboxList.fr10.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it} from 'vitest';
-import {screen} from '@testing-library/react';
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
 import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
 import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
 import {CheckboxList, type CheckboxListProps} from './CheckboxList';
@@ -22,3 +22,30 @@ describeFieldInputParts('CheckboxList', {
   getControl: () => screen.getByRole('group'),
   inGroup: false,
 });
+
+describe('CheckboxList FR10 details', () => {
+  it("names the group by its label and then a caller's aria-labelledby", () => {
+    render(
+      <>
+        <span id="caller-name">Billing</span>
+        <CheckboxList
+          label="Preferences"
+          value={[]}
+          onChange={() => {}}
+          aria-labelledby="caller-name">
+          <CheckboxListItem label="A" value="a" />
+        </CheckboxList>
+      </>,
+    );
+    const group = screen.getByRole('group');
+    const ids = group.getAttribute('aria-labelledby')?.split(' ');
+    expect(ids).toHaveLength(2);
+    expect(document.getElementById(ids?.[0] ?? '')?.textContent).toContain(
+      'Preferences',
+    );
+    expect(ids?.[1]).toBe('caller-name');
+    expect(screen.getByRole('group', {name: 'Preferences Billing'})).toBe(
+      group,
+    );
+  });
+});

package/src/CheckboxList/CheckboxList.test.tsx

@@ -59,6 +59,28 @@ beforeEach(() => {
 });
 
 describe('CheckboxList', () => {
+  it('forwards CheckboxListItem align to its Item row unchanged', () => {
+    render(
+      <CheckboxList label="Toppings" value={[]} onChange={() => {}}>
+        <CheckboxListItem label="Cheese" value="cheese" data-testid="cheese" />
+        <CheckboxListItem
+          label="Olives"
+          value="olives"
+          align="first-line"
+          data-testid="olives"
+        />
+      </CheckboxList>,
+    );
+    expect(screen.getByTestId('cheese')).toHaveAttribute(
+      'data-align',
+      'center',
+    );
+    expect(screen.getByTestId('olives')).toHaveAttribute(
+      'data-align',
+      'first-line',
+    );
+  });
+
   it('renders with label', () => {
     render(
       <CheckboxList label="Preferences" value={[]} onChange={() => {}}>

package/src/CheckboxList/CheckboxList.tsx

@@ -38,6 +38,7 @@ import {useTooltip} from '../Tooltip';
 import * as stylex from '@stylexjs/stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {joinAriaIDs} from '../utils/inputAria';
 import {
   CheckboxListContext,
   type CheckboxListContextValue,
@@ -170,6 +171,7 @@ export function CheckboxList({
   controlXstyle,
   controlClassName,
   controlStyle,
+  'aria-labelledby': ariaLabelledByProp,
   'aria-describedby': ariaDescribedByProp,
   ...restProps
 }: CheckboxListProps) {
@@ -290,7 +292,8 @@ export function CheckboxList({
             controlStyle,
           )}
           role="group"
-          aria-labelledby={labelID}
+          // A caller aria-labelledby names the group together with its label.
+          aria-labelledby={joinAriaIDs(labelID, ariaLabelledByProp)}
           aria-describedby={
             [
               ariaDescribedByProp,

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -55,6 +55,13 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a checkbox) level with the first line of a wrapped label. See Item.align.',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -130,6 +137,13 @@ export const docsZh = {
       type: 'ReactNode',
       description: '在标签区域后渲染的内容。',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        '起始和结束内容相对于标签的垂直对齐方式，原样传递给 Item。`first-line` 让小标记（复选框）与换行标签的第一行保持水平。参见 Item.align。',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -165,6 +179,8 @@ export const docsDense = {
   description:
     'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value.',
   propDescriptions: {
+    align:
+      "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",
     label:
       'Primary label. String or ReactNode; nested controls keep their behavior. A ReactNode names the checkbox from its visible text.',
     'aria-label':

package/src/CheckboxList/CheckboxListItem.tsx

@@ -29,6 +29,7 @@ import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
 import {useTranslator} from '../i18n';
 import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
+import type {ItemAlign} from '../Item';
 
 // =============================================================================
 // Styles
@@ -45,6 +46,13 @@ const styles = stylex.create({
 // =============================================================================
 
 export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
+  /**
+   * Vertical alignment of the start and end content against the label,
+   * forwarded to Item. Use `first-line` to keep the checkbox level with the
+   * first line of a wrapped label.
+   * @default 'center'
+   */
+  align?: ItemAlign;
   /**
    * Primary text label for the item.
    *
@@ -192,6 +200,7 @@ export function CheckboxListItem({
   className,
   style,
   onClick: onClickProp,
+  align,
   ...restProps
 }: CheckboxListItemProps) {
   const t = useTranslator();
@@ -297,6 +306,7 @@ export function CheckboxListItem({
       label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label}
       description={description}
       endContent={endContent}
+      align={align}
       isDisabled={effectiveDisabled}
       // Delegate row clicks to the checkbox instead of wiring onClick (which
       // would add an invisible row button = a second tab stop). The checkbox

package/src/Code/Code.doc.mjs

@@ -4,6 +4,7 @@
 export const docs = {
   name: 'Code',
   displayName: 'Code',
+  keywords: ['inlinecode', 'monospace'],
   group: 'Code',
   category: 'Content',
   description:

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -87,6 +87,8 @@ export const docs = {
     'modal',
     'dialog',
     'navigation',
+    'commandmenu',
+    'cmdk',
   ],
   description:
     'Root component. Manages open state, search, keyboard navigation, and composition slots.',

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -8,12 +8,19 @@
  */
 
 import {createRef} from 'react';
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {CommandPaletteInput} from './CommandPaletteInput';
 import {CommandPaletteContext} from './CommandPaletteContext';
 import {Dialog} from '../Dialog';
 import type {CommandPaletteContextValue} from './CommandPaletteContext';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
+
+beforeEach(() => {
+  __resetInteractionModalityForTest();
+});
 
 function makeContext(
   overrides: Partial<CommandPaletteContextValue> = {},
@@ -279,6 +286,45 @@ describe('CommandPaletteInput', () => {
     },
   );
 
+  it('draws the shared ring only when keyboard navigation acquired focus', () => {
+    render(<CommandPaletteInput hasAutoFocus={false} />);
+    const input = screen.getByRole('searchbox');
+    const ringClasses = stylex
+      .props(focusOutlineStyles.focusVisible)
+      .className!.split(' ');
+    const isRinged = () =>
+      ringClasses.every(className => input.classList.contains(className));
+
+    fireEvent.pointerDown(input);
+    fireEvent.focus(input);
+    expect(isRinged()).toBe(false);
+
+    fireEvent.blur(input);
+    fireEvent.keyDown(input, {key: 'Tab'});
+    fireEvent.focus(input);
+    expect(isRinged()).toBe(true);
+  });
+
+  it('preserves caller focus and blur handlers while tracking modality', () => {
+    const onFocus = vi.fn();
+    const onBlur = vi.fn();
+    render(
+      <CommandPaletteInput
+        hasAutoFocus={false}
+        onFocus={onFocus}
+        onBlur={onBlur}
+      />,
+    );
+    const input = screen.getByRole('searchbox');
+
+    fireEvent.keyDown(input, {key: 'Tab'});
+    fireEvent.focus(input);
+    fireEvent.blur(input);
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onBlur).toHaveBeenCalledTimes(1);
+  });
+
   it('does not schedule focus when hasAutoFocus is false', async () => {
     const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
     render(<CommandPaletteInput hasAutoFocus={false} />);
@@ -481,8 +527,11 @@ describe('CommandPaletteInput popup context', () => {
       </CommandPaletteContext>,
     );
 
-    await vi.waitFor(() => {
-      expect(screen.getByRole('combobox')).toHaveFocus();
+    await act(async () => {
+      await new Promise<void>(resolve =>
+        requestAnimationFrame(() => resolve()),
+      );
     });
+    expect(screen.getByRole('combobox')).toHaveFocus();
   });
 });