@astryxdesign/core 0.7.4-canary.faa934f → 0.7.4

package/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts

@@ -0,0 +1,461 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetNativeModal.a11y.browser.spec.ts
+ * @input The `Core/BottomSheetSwitcher` stories in a built Storybook, and
+ *   real Chromium/WebKit wheel, keyboard, and pointer input.
+ * @output Browser evidence for a flow whose every sheet owns a native modal
+ *   dialog: the flow's one page scroll lock (the shared hook, as Dialog)
+ *   holding while two sheet dialogs are open through a handoff and under a
+ *   Core Dialog opened from a step, never released between steps nor when
+ *   that Dialog closes, and the page's offset restored after the exit; Tab landing inside the entering sheet's dialog
+ *   as soon as both dialogs are open and on Tab stops for as long as the
+ *   retained dialog is open beneath it (its fade included), never the page
+ *   once the handoff is done, by the browser's own containment, with the
+ *   retained dialog carrying `inert` and `aria-hidden` on every step it is
+ *   open; Escape and
+ *   the backdrop dismissing by purpose with focus returned to the opener;
+ *   and one steady scrim through a handoff.
+ * @position Cross-browser proof; jsdom presents no dialog and contains no
+ *   focus, so BottomSheetSwitcher.test.tsx can only assert the calls. WebKit
+ *   here is desktop WebKit under Playwright, not iOS Safari.
+ */
+
+import {expect, test, type Page} 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();
+});
+
+test.use({viewport: {width: 390, height: 844}, hasTouch: true});
+
+const OPENER = 'Set up notifications';
+
+/**
+ * Open a switcher story with the flow closed and the page made scrollable:
+ * a tall spacer below the story, scrolled part way down, so a lock that
+ * fails would show as a change in `scrollY`.
+ */
+async function mountScrollable(page: Page, story = 'hug-content') {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-bottomsheetswitcher--${story}&viewMode=story`,
+  );
+  // The story's play function opens the flow; start from closed.
+  await expect(page.locator('dialog[open]')).toHaveCount(1);
+  await page.keyboard.press('Escape');
+  await expect(page.locator('dialog[open]')).toHaveCount(0);
+  await page.evaluate(() => {
+    const spacer = document.createElement('div');
+    spacer.id = 'spacer';
+    spacer.style.height = '3000px';
+    document.body.appendChild(spacer);
+    const counter = window as {__scrollEvents?: number};
+    counter.__scrollEvents = 0;
+    window.addEventListener('scroll', () => {
+      counter.__scrollEvents = (counter.__scrollEvents ?? 0) + 1;
+    });
+    window.scrollTo(0, 300);
+  });
+  expect(await page.evaluate(() => window.scrollY)).toBe(300);
+}
+
+/**
+ * The shared lock's pin on <body>, and the page's offset as the lock sees
+ * it: while pinned, `scrollY` reads 0 and the saved offset is `top`; after
+ * release, `scrollY` is the restored offset. `scrollEvents` counts window
+ * scroll events since `resetScrollCounter`: a lock released and re-acquired
+ * between steps restores the offset and pins again, which fires one.
+ */
+async function lockState(page: Page): Promise<{
+  position: string;
+  top: string;
+  scrollY: number;
+  scrollEvents: number;
+}> {
+  return page.evaluate(() => ({
+    position: document.body.style.position,
+    top: document.body.style.top,
+    scrollY: window.scrollY,
+    scrollEvents: (window as {__scrollEvents?: number}).__scrollEvents ?? 0,
+  }));
+}
+
+/**
+ * Zero the counter once the events already owed have arrived: the spacer
+ * scroll in `mountScrollable` and the lock's own pin (300 → 0) each fire one
+ * window `scroll` event, and WebKit delivers them late on a cold run.
+ */
+async function resetScrollCounter(page: Page) {
+  await page
+    .waitForFunction(
+      () => ((window as {__scrollEvents?: number}).__scrollEvents ?? 0) >= 2,
+      undefined,
+      {timeout: 3000},
+    )
+    .catch(() => {});
+  await page.evaluate(() => {
+    (window as {__scrollEvents?: number}).__scrollEvents = 0;
+  });
+}
+
+async function wheelDown(page: Page) {
+  // Over the top of the viewport: the backdrop when a modal sheet is open,
+  // the page otherwise.
+  await page.mouse.move(195, 80);
+  await page.mouse.wheel(0, 400);
+  await page.waitForTimeout(250);
+}
+
+/** A finger drag over the backdrop; Chromium only (CDP), WebKit has no API. */
+async function touchScrollDown(page: Page, browserName: string) {
+  if (browserName !== 'chromium') {
+    return;
+  }
+  const session = await page.context().newCDPSession(page);
+  await session.send('Input.synthesizeScrollGesture', {
+    x: 195,
+    y: 120,
+    yDistance: -300,
+    gestureSourceType: 'touch',
+    speed: 800,
+  });
+  await session.detach();
+  await page.waitForTimeout(250);
+}
+
+/**
+ * Open the flow from its opener without scrolling the page: a pointer click
+ * would first scroll the opener into view, and the lock tests need the page
+ * to stay where it was scrolled. The opener is focused first, as a real
+ * activation would leave it, so focus return has somewhere to go.
+ */
+async function openFlow(page: Page) {
+  await page.evaluate(name => {
+    const opener = Array.from(document.querySelectorAll('button')).find(
+      button => button.textContent?.trim() === name,
+    );
+    opener?.focus({preventScroll: true});
+    opener?.click();
+  }, OPENER);
+  await expect(page.getByRole('dialog', {name: OPENER})).toBeVisible();
+  await page.waitForTimeout(500);
+}
+
+test('the flow holds one page scroll lock through a handoff and under a Core Dialog opened from a step, never released between steps, and restores the offset after the exit', async ({
+  page,
+  browserName,
+}) => {
+  await mountScrollable(page, 'dialog-from-step');
+  await openFlow(page);
+  let state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.top).toBe('-300px');
+  await resetScrollCounter(page);
+
+  await page.getByRole('button', {name: 'Continue', exact: true}).click();
+  await expect(page.locator('dialog[open]')).toHaveCount(2);
+  state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.top).toBe('-300px');
+  // Wheel and finger over the backdrop with both dialogs open: the pinned
+  // page does not move.
+  await wheelDown(page);
+  await touchScrollDown(page, browserName);
+  state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.top).toBe('-300px');
+  expect(state.scrollY).toBe(0);
+  await expect(page.locator('dialog[open]')).toHaveCount(1, {timeout: 3000});
+  // One lock for the flow: the handoff released nothing, so the page never
+  // scrolled back and forth between steps.
+  state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.scrollEvents).toBe(0);
+
+  // A Core Dialog opened from the step, as a builder would, takes the same
+  // shared lock a second time; closing it must give back only its own hold,
+  // leaving the flow's pin in place with the saved offset untouched.
+  await page.getByRole('button', {name: 'Reset', exact: true}).click();
+  const resetDialog = page.getByRole('dialog', {name: 'Reset frequency?'});
+  await expect(resetDialog).toBeVisible();
+  await wheelDown(page);
+  state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.top).toBe('-300px');
+  expect(state.scrollY).toBe(0);
+  await page.getByRole('button', {name: 'Keep', exact: true}).click();
+  await expect(resetDialog).toBeHidden();
+  await page.waitForTimeout(400);
+  state = await lockState(page);
+  expect(state.position).toBe('fixed');
+  expect(state.top).toBe('-300px');
+  expect(state.scrollY).toBe(0);
+  expect(state.scrollEvents).toBe(0);
+  await wheelDown(page);
+  expect(await page.evaluate(() => window.scrollY)).toBe(0);
+  // The Dialog returned focus into the step, so Escape closes the flow.
+  await expect(page.locator('dialog[open]')).toHaveCount(1);
+
+  await page.keyboard.press('Escape');
+  await expect(page.locator('dialog[open]')).toHaveCount(0, {timeout: 3000});
+  state = await lockState(page);
+  expect(state.position).toBe('');
+  expect(state.top).toBe('');
+  expect(state.scrollY).toBe(300);
+  // The page scrolls again.
+  await wheelDown(page);
+  expect(await page.evaluate(() => window.scrollY)).toBeGreaterThan(300);
+});
+
+/**
+ * One synchronous read per step: how many sheet dialogs are open, where focus
+ * is (and whether it moved since the last read and sits outside any inert
+ * subtree), and whether the retained dialog (by accessible name) still
+ * carries `inert` and `aria-hidden`. Read together so a close between two
+ * reads cannot make a stale attribute look like a regression, or hide one.
+ */
+async function handoffStep(
+  page: Page,
+  retainedName: string,
+): Promise<{
+  openCount: number;
+  /** Page-clock ms since the second dialog opened; -1 before that. */
+  sinceBothOpen: number;
+  where: string;
+  moved: boolean;
+  insideInert: boolean;
+  retained: {open: boolean; inert: boolean; ariaHidden: string | null} | null;
+}> {
+  return page.evaluate(name => {
+    const openDialogs = Array.from(document.querySelectorAll('dialog[open]'));
+    const clock = window as {__bothOpenAt?: number};
+    const sinceBothOpen =
+      clock.__bothOpenAt == null
+        ? -1
+        : Math.round(performance.now() - clock.__bothOpenAt);
+    const active = document.activeElement;
+    const tracker = window as {__lastActive?: Element | null};
+    const moved = active !== tracker.__lastActive;
+    tracker.__lastActive = active;
+    const insideInert = active?.closest('[inert]') != null;
+    const activeDialog = active?.closest('dialog') ?? null;
+    const where =
+      active == null || active === document.body
+        ? 'body'
+        : activeDialog == null
+          ? 'page'
+          : (activeDialog.getAttribute('aria-label') ?? '?');
+    const retainedDialog = Array.from(document.querySelectorAll('dialog')).find(
+      dialog => dialog.getAttribute('aria-label') === name,
+    );
+    return {
+      openCount: openDialogs.length,
+      sinceBothOpen,
+      where,
+      moved,
+      insideInert,
+      retained:
+        retainedDialog == null
+          ? null
+          : {
+              open: retainedDialog.hasAttribute('open'),
+              inert: retainedDialog.hasAttribute('inert'),
+              ariaHidden: retainedDialog.getAttribute('aria-hidden'),
+            },
+    };
+  }, retainedName);
+}
+
+test('focus is inside the entering sheet as soon as both dialogs are open, and Tab reaches stops inside it for as long as the retained dialog is open, which stays inert and hidden through its fade, and inside the flow after the handoff', async ({
+  page,
+}) => {
+  await mountScrollable(page);
+  await openFlow(page);
+  // Stamp the page clock the moment the second dialog opens, so the late
+  // window below is measured from the handoff itself, not from when the
+  // test runner got around to reading it on a slow run.
+  await page.evaluate(() => {
+    const clock = window as {__bothOpenAt?: number};
+    clock.__bothOpenAt = undefined;
+    const observer = new MutationObserver(() => {
+      if (
+        clock.__bothOpenAt == null &&
+        document.querySelectorAll('dialog[open]').length >= 2
+      ) {
+        clock.__bothOpenAt = performance.now();
+        observer.disconnect();
+      }
+    });
+    observer.observe(document.body, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['open'],
+    });
+  });
+  await page.getByRole('button', {name: 'Continue', exact: true}).click();
+  // Both dialogs are open for the handoff's ~650ms: the retained one holds
+  // still, then fades from ~345ms, then closes. Step with Tab until it has
+  // closed, reading open count, focus, and the retained dialog's attributes
+  // in one evaluate per step: focus must land in the entering sheet's dialog
+  // ("Notification frequency"), never in the retained one ("Set up
+  // notifications") or the page, and the retained dialog must carry `inert`
+  // and `aria-hidden` on every step it is still open, the fade included.
+  await expect(page.locator('dialog[open]')).toHaveCount(2);
+  // The entering sheet takes focus with its presentation, before any Tab:
+  // the moment both dialogs are open, focus is inside "Notification
+  // frequency" and outside every inert subtree. An entering sheet made
+  // inert while it enters would leave focus on <body> for its first ~300ms.
+  const atOpen = await handoffStep(page, OPENER);
+  expect(atOpen.openCount).toBe(2);
+  expect(atOpen.where, 'focus as soon as both dialogs are open').toBe(
+    'Notification frequency',
+  );
+  expect(atOpen.insideInert, 'focus inside an inert subtree at open').toBe(
+    false,
+  );
+  expect(atOpen.sinceBothOpen).toBeGreaterThanOrEqual(0);
+  let midHandoffPresses = 0;
+  let lateHandoffPresses = 0;
+  let midHandoffStopsInside = 0;
+  let lateHandoffStopsInside = 0;
+  for (let index = 0; index < 40; index += 1) {
+    await page.keyboard.press('Tab');
+    const step = await handoffStep(page, OPENER);
+    if (step.openCount < 2 || step.retained?.open !== true) {
+      break;
+    }
+    midHandoffPresses += 1;
+    // "Late" is inside the retained dialog's fade (from ~345ms after both
+    // opened), on the page's own clock.
+    const isLate = step.sinceBothOpen > 400;
+    if (isLate) {
+      lateHandoffPresses += 1;
+    }
+    const label = `mid-handoff, Tab ${index + 1} at ${step.sinceBothOpen}ms`;
+    expect(step.where, label).not.toBe('page');
+    expect(step.where, label).not.toBe(OPENER);
+    expect(['Notification frequency', 'body'], label).toContain(step.where);
+    // A stop inside the entering sheet is a Tab that moved focus onto a
+    // focusable element there, outside any inert subtree; focus merely left
+    // where the presentation put it, inside a dialog that went inert, is not.
+    expect(step.insideInert, `${label}: focus inside an inert subtree`).toBe(
+      false,
+    );
+    if (step.where === 'Notification frequency' && step.moved) {
+      midHandoffStopsInside += 1;
+      if (isLate) {
+        lateHandoffStopsInside += 1;
+      }
+    }
+    expect(step.retained.inert, `${label}: retained dialog inert`).toBe(true);
+    expect(step.retained.ariaHidden, `${label}: retained aria-hidden`).toBe(
+      'true',
+    );
+    await page.waitForTimeout(40);
+  }
+  // Presses landed both before and during the retained dialog's fade, else
+  // the test proved nothing about the handoff; and at least one of them
+  // stopped inside the entering sheet, else an entering sheet that can never
+  // take focus (every stop on the browser-UI `body` stop) would pass.
+  expect(midHandoffPresses).toBeGreaterThan(2);
+  expect(lateHandoffPresses).toBeGreaterThan(0);
+  expect(midHandoffStopsInside).toBeGreaterThan(0);
+  // ...and at least one of those stops landed inside the retained dialog's
+  // fade (from ~345ms), so an entering sheet that went inert only while the
+  // retained one fades would not pass.
+  expect(lateHandoffStopsInside).toBeGreaterThan(0);
+
+  await expect(page.locator('dialog[open]')).toHaveCount(1, {timeout: 3000});
+  let stopsInside = 0;
+  for (let index = 0; index < 8; index += 1) {
+    await page.keyboard.press('Tab');
+    const step = await handoffStep(page, OPENER);
+    expect(step.where, `after the handoff, Tab ${index + 1}`).not.toBe('page');
+    expect(['Notification frequency', 'body']).toContain(step.where);
+    expect(step.insideInert, `after the handoff, Tab ${index + 1}`).toBe(false);
+    if (step.where === 'Notification frequency' && step.moved) {
+      stopsInside += 1;
+    }
+  }
+  expect(stopsInside).toBeGreaterThan(0);
+});
+
+test('Escape and a backdrop tap dismiss an info flow and return focus to the opener', async ({
+  page,
+}) => {
+  await mountScrollable(page);
+  const opener = page.getByRole('button', {name: OPENER});
+  await openFlow(page);
+  await page.getByRole('button', {name: 'Continue', exact: true}).click();
+  await page.waitForTimeout(900);
+
+  await page.keyboard.press('Escape');
+  await expect(page.locator('dialog[open]')).toHaveCount(0, {timeout: 3000});
+  await expect(opener).toBeFocused();
+
+  await openFlow(page);
+  await page.mouse.click(195, 60);
+  await expect(page.locator('dialog[open]')).toHaveCount(0, {timeout: 3000});
+  await expect(opener).toBeFocused();
+});
+
+test('one steady scrim through a handoff: no dip and no double dim', async ({
+  page,
+}) => {
+  await mountScrollable(page);
+  await openFlow(page);
+  const samples = await page.evaluate(
+    async () =>
+      new Promise<number[]>(resolve => {
+        const dims: number[] = [];
+        const start = performance.now();
+        const tick = () => {
+          let combined = 1;
+          for (const dialog of document.querySelectorAll('dialog[open]')) {
+            if (!dialog.matches(':modal')) {
+              continue;
+            }
+            const style = getComputedStyle(dialog, '::backdrop');
+            const match = /rgba?\(([^)]+)\)/.exec(style.backgroundColor);
+            const parts = match
+              ? match[1].split(/[,/]\s*|\s+/).filter(Boolean)
+              : [];
+            const alpha = parts.length === 4 ? Number(parts[3]) : 1;
+            combined *= 1 - alpha * Number(style.opacity);
+          }
+          dims.push(Number((1 - combined).toFixed(3)));
+          if (performance.now() - start < 1100) {
+            requestAnimationFrame(tick);
+          } else {
+            resolve(dims);
+          }
+        };
+        Array.from(
+          document.querySelectorAll<HTMLButtonElement>(
+            'dialog[open]:not([inert]) button',
+          ),
+        )
+          .find(button => button.textContent?.trim() === 'Continue')
+          ?.click();
+        requestAnimationFrame(tick);
+      }),
+  );
+  expect(samples.length).toBeGreaterThan(20);
+  const steady = samples[0];
+  expect(steady).toBeGreaterThan(0.3);
+  for (const dim of samples) {
+    expect(dim).toBeGreaterThanOrEqual(steady * 0.9);
+    expect(dim).toBeLessThanOrEqual(steady * 1.05);
+  }
+});

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -225,7 +225,10 @@ export const docs = {
       {className: 'astryx-command-palette-group'},
       {className: 'astryx-command-palette-group-heading'},
       {className: 'astryx-command-palette-input'},
-      {className: 'astryx-command-palette-item'},
+      {
+        className: 'astryx-command-palette-item',
+        states: ['highlighted', 'selected', 'disabled'],
+      },
       {className: 'astryx-command-palette-list'},
     ],
   },

package/src/CommandPalette/CommandPalette.test.tsx

@@ -729,7 +729,7 @@ describe('CommandPalette', () => {
       });
     });
 
-    it('does not announce on initial open (bootstrap)', async () => {
+    it('announces no result count on initial open (bootstrap)', async () => {
       render(
         <CommandPalette
           isOpen={true}
@@ -742,7 +742,9 @@ describe('CommandPalette', () => {
       await act(async () => {
         await new Promise(resolve => setTimeout(resolve, 50));
       });
-      expect(politeRegion()?.textContent ?? '').toBe('');
+      // The bootstrap's busy start may say "Loading" (spec:AST-086 FR3, FR8);
+      // its results are never counted aloud.
+      expect(['', 'Loading']).toContain(politeRegion()?.textContent ?? '');
     });
   });
 });

package/src/CommandPalette/CommandPalette.tsx

@@ -318,11 +318,11 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const searchVersionRef = useRef(0);
   const emptyStateRef = useRef<HTMLDivElement>(null);
 
-  // Announce search status to screen readers through the shared polite live
+  // Announce search results to screen readers through the shared polite live
   // region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
-  // The busy spinner and the empty states are otherwise purely visual, so a
-  // screen-reader user typing a query would hear nothing when loading starts
-  // or results disappear.
+  // The empty states are otherwise purely visual, so a screen-reader user
+  // typing a query would hear nothing when results disappear. The busy start
+  // is announced by CommandPaletteInput.
   const announce = useAnnounce();
 
   const value = controlledValue ?? internalValue;
@@ -407,13 +407,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       startTransition(async () => {
         const isBootstrap = query === '';
 
-        // Loading started for a user query: tell screen-reader users the
-        // spinner appeared. The polite region coalesces rapid updates, so for
-        // fast sources the result-count announcement below simply replaces
-        // this instead of stacking one "Loading" per keystroke.
-        if (!isBootstrap) {
-          announce(t('@astryx.commandPalette.loading'));
-        }
+        // The busy start ("Loading") is announced by CommandPaletteInput,
+        // from a region inside the palette's dialog (spec:AST-086 FR8, FR3).
 
         // Client-filter previous results for instant narrowing while fetch is in flight
         if (!isBootstrap && searchResults.length > 0) {

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -377,7 +377,9 @@ describe('CommandPaletteInput popup context', () => {
       </CommandPaletteContext>,
     );
 
-    const spinner = screen.getByRole('status');
+    // The Spinner is decorative (spec:AST-086 FR8), so find it by its class.
+    const spinner = document.querySelector('.astryx-spinner') as HTMLElement;
+    expect(spinner).toHaveAttribute('aria-hidden', 'true');
     const trailingContent = screen.getByTestId('trailing-content');
     expect(trailingContent.parentElement?.firstElementChild).toContainElement(
       spinner,

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -36,6 +36,7 @@ import {
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 const styles = stylex.create({
   wrapper: {
     display: 'flex',
@@ -190,6 +191,14 @@ export function CommandPaletteInput({
   const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
   const dialogContext = useDialogContext();
   const inputRef = useRef<HTMLInputElement>(null);
+  // The search Spinner is decorative; the input announces each busy start,
+  // including the load on opening or clearing the query. Inside the palette's
+  // native modal it does so from a region in the dialog (spec:AST-086 FR8, FR3).
+  useBusyAnnouncement(
+    ctx?.isBusy === true,
+    t('@astryx.commandPalette.loading'),
+    inputRef,
+  );
   const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);
 
   // Text-entry controls match :focus-visible after pointer focus in Chromium.
@@ -335,7 +344,7 @@ export function CommandPaletteInput({
         <span {...stylex.props(styles.end)}>
           {ctx?.isBusy && (
             <span {...stylex.props(styles.icon, styles.spinner)}>
-              <Spinner size="sm" />
+              <Spinner size="sm" aria-hidden="true" />
             </span>
           )}
           {hasEndContent && endContent}

package/src/CommandPalette/CommandPaletteItem.doc.mjs

@@ -21,7 +21,12 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use non-interactive child content such as icons, descriptions, and shortcut hints; activate the option itself instead of nesting buttons or links.',
+          'Inside CommandPalette, each item is an option in the listbox popup of the WAI-ARIA combobox pattern: keyboard focus stays in the query field, arrow keys move the highlight through aria-activedescendant, and Enter selects the highlighted item.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest buttons, links, or other interactive controls inside an item. Option semantics make descendants presentational, so use non-interactive content such as icons, descriptions, and shortcut hints, and activate the option itself.',
       },
       {
         guidance: false,
@@ -45,7 +50,12 @@ export const docs = {
     ],
   },
   theming: {
-    targets: [{className: 'astryx-command-palette-item'}],
+    targets: [
+      {
+        className: 'astryx-command-palette-item',
+        states: ['highlighted', 'selected', 'disabled'],
+      },
+    ],
   },
   props: [
     {
@@ -79,7 +89,7 @@ export const docs = {
       name: 'isSelected',
       type: 'boolean',
       description:
-        'Whether this item represents the selected value in picker mode.',
+        'Whether this item represents the selected value in picker mode. Derived from the CommandPalette value when omitted inside CommandPalette.',
       default: 'false',
     },
     {
@@ -117,7 +127,8 @@ export const docsZh = {
       '通过指针激活此条目后调用。CommandPalette 中的键盘选择通过根组件的 onValueChange 报告。',
     isHighlighted:
       '此条目是否为当前键盘结果。在 CommandPalette 内省略时从上下文派生。',
-    isSelected: '此条目是否代表选择器模式中的已选值。',
+    isSelected:
+      '此条目是否代表选择器模式中的已选值。在 CommandPalette 内省略时从面板的值派生。',
     isDisabled: '条目是否不可用并禁止指针激活。',
     xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
   },
@@ -135,7 +146,8 @@ export const docsDense = {
     onSelect:
       'called after pointer activation; palette keyboard selection uses root onValueChange',
     isHighlighted: 'active keyboard result; derived from context when omitted',
-    isSelected: 'selected value in picker mode',
+    isSelected:
+      'selected value in picker mode; derived from palette value when omitted',
     isDisabled: 'unavailable; suppresses pointer activation',
     xstyle: 'StyleX layout styles; must be stylex.create() value',
   },