@astryxdesign/core 0.1.9 → 0.2.0-canary.0e01213

package/src/CommandPalette/CommandPalette.test.tsx

@@ -8,10 +8,11 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, waitFor, fireEvent} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';
 import {CommandPalette} from './CommandPalette';
 import {createStaticSource} from '@astryxdesign/core/Typeahead';
 import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 const simpleSource = createStaticSource([
   {id: 'home', label: 'Home'},
@@ -35,6 +36,9 @@ beforeEach(() => {
   HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
     this.removeAttribute('open');
   });
+  // The live regions are module-level singletons; reset them so
+  // announcements from one test don't leak into the next.
+  __resetLiveRegionsForTest();
 });
 
 describe('CommandPalette', () => {
@@ -269,4 +273,94 @@ describe('CommandPalette', () => {
       expect(screen.getByText('No results')).toBeInTheDocument(),
     );
   });
+
+  describe('screen reader announcements', () => {
+    const politeRegion = () =>
+      document.querySelector('[data-astryx-live-region="polite"]');
+
+    it('announces the result count politely after typing a query', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // "e" matches both Home and Settings.
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'e'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('2 results');
+      });
+    });
+
+    it('announces the singular form when one item matches', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // "set" matches only Settings. Anchored so it cannot pass on "1 results".
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'set'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent(/^1 result$/);
+      });
+    });
+
+    it('announces the empty state with the query when nothing matches', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('No results for zzz');
+      });
+    });
+
+    it('announces loading politely while a search is in flight', async () => {
+      // A source whose searches never resolve, so the palette stays busy and
+      // only the loading announcement can reach the live region.
+      const source: SearchSource = {
+        bootstrap: () => [],
+        async search(): Promise<SearchableItem[]> {
+          return new Promise<SearchableItem[]>(() => {});
+        },
+      };
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={source}
+        />,
+      );
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'z'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Loading');
+      });
+    });
+
+    it('does not announce on initial open (bootstrap)', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // Flush effects and any pending live-region rAF writes.
+      await act(async () => {
+        await new Promise(resolve => setTimeout(resolve, 50));
+      });
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
+  });
 });

package/src/CommandPalette/CommandPalette.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -36,6 +36,7 @@ import {CommandPaletteInput} from './CommandPaletteInput';
 import {CommandPaletteFooter} from './CommandPaletteFooter';
 import {CommandPaletteEmpty} from './CommandPaletteEmpty';
 import type {BaseProps} from '../BaseProps';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useTranslator} from '../i18n';
 
 export interface CommandPaletteProps<
@@ -291,6 +292,13 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const isBusy = isPending;
   const searchVersionRef = useRef(0);
 
+  // Announce search status 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.
+  const announce = useAnnounce();
+
   const value = controlledValue ?? internalValue;
 
   const setValue = useCallback(
@@ -318,8 +326,12 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       setInternalValue('');
     }
     searchSource.cancel?.();
+    // Clear any lingering result / loading announcement when the palette
+    // closes so stale status text does not linger in the a11y tree
+    // (matching Selector's onHide).
+    announce('');
     onOpenChange(false);
-  }, [onOpenChange, searchSource, controlledValue]);
+  }, [onOpenChange, searchSource, controlledValue, announce]);
 
   const selectItem = useCallback(
     (itemValue: string) => {
@@ -355,6 +367,14 @@ 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'));
+        }
+
         // Client-filter previous results for instant narrowing while fetch is in flight
         if (!isBootstrap && searchResults.length > 0) {
           const lower = query.toLowerCase().trim();
@@ -377,6 +397,23 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
           setOptimisticResults(items);
           setSearchResults(items);
 
+          // Announce the outcome from the search commit (not a reactive
+          // effect), matching Selector / BaseTypeahead: exactly one
+          // announcement per committed query, and the version check above
+          // already discards stale keystrokes. Bootstrap stays silent — the
+          // same role PowerSearch's mount guard plays — so opening the
+          // palette announces nothing; clearing the query only clears any
+          // lingering status text.
+          if (isBootstrap) {
+            announce('');
+          } else if (items.length === 0) {
+            announce(t('@astryx.commandPalette.noResultsFor', {query}));
+          } else {
+            announce(
+              t('@astryx.commandPalette.resultCount', {count: items.length}),
+            );
+          }
+
           // When opening with a preselected value, highlight it once
           // bootstrap results arrive. No value → highlight stays at -1
           // and ArrowDown naturally moves to the first item.
@@ -396,6 +433,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       value,
       combobox,
       setOptimisticResults,
+      announce,
+      t,
     ],
   );
 

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -43,7 +43,7 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left' as const,
+    textAlign: 'start' as const,
     outline: 'none',
     userSelect: 'none',
   },

package/src/ContextMenu/ContextMenu.test.tsx

@@ -136,6 +136,21 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
   });
 
+  it('closes the menu when Tab is pressed inside it (APG menu pattern)', () => {
+    render(
+      <ContextMenu items={[{label: 'Item 1'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+  });
+
   it('ignores Escape during IME composition', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -552,7 +567,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={() => {}}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>
@@ -587,7 +602,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={onSort}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>
@@ -803,4 +818,46 @@ describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)
       screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
     ).toHaveFocus();
   });
+
+  it('renders a submenu from a nested items array and keyboard-reaches an item after it', () => {
+    // Same inline-flyout scoping the DropdownMenu fix covers: the submenu's
+    // items must not pollute the ContextMenu's roving order, and an item after
+    // the submenu row must stay keyboard-reachable.
+    const onDelete = vi.fn();
+    render(
+      <ContextMenu
+        items={[
+          {label: 'Cut', onClick: () => {}},
+          {
+            label: 'Move to',
+            items: [
+              {label: 'Folder A', onClick: () => {}},
+              {label: 'Folder B', onClick: () => {}},
+            ],
+          },
+          {type: 'divider'},
+          {label: 'Delete', onClick: onDelete},
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    // Two role="menu" exist (the context menu + the inline submenu flyout);
+    // the context menu is the first in DOM order.
+    const menu = screen.getAllByRole('menu', {hidden: true})[0];
+    // The submenu trigger renders as a menuitem with aria-haspopup.
+    const submenuTrigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    expect(submenuTrigger).toHaveAttribute('aria-haspopup', 'menu');
+    // Cut → Move to → Delete, one step per press (submenu items not swept in).
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(submenuTrigger).toHaveFocus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveFocus();
+  });
 });

package/src/ContextMenu/ContextMenu.tsx

@@ -49,6 +49,7 @@ import {
 import {
   MENU_ITEM_ROLES,
   MENU_ITEM_SELECTOR,
+  MENU_BOUNDARY_SELECTOR,
 } from '../DropdownMenu/menuItemRoles';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
@@ -268,22 +269,18 @@ export function ContextMenu({
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
+    ownsEvent,
+    getItems: getMenuItems,
   } = useListFocus<HTMLDivElement>({
     itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
     wrap: false,
     onEscape: closeMenu,
   });
 
-  // First-character typeahead over the enabled menu items (menus-11).
-  const getMenuItems = useCallback(
-    (): HTMLElement[] =>
-      listRef.current
-        ? Array.from(
-            listRef.current.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-          )
-        : [],
-    [listRef],
-  );
+  // First-character typeahead over the enabled menu items (menus-11). Reuses
+  // the hook's scoped item collection so an inline submenu flyout's items
+  // aren't swept in.
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -340,6 +337,11 @@ export function ContextMenu({
 
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // A submenu flyout renders inline inside this menu; its key events bubble
+      // up here. Let that level own them — only handle events from this level.
+      if (!ownsEvent(e)) {
+        return;
+      }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
@@ -351,13 +353,22 @@ export function ContextMenu({
         }
         return;
       }
+      // APG menu pattern: Tab closes the menu. Menu items are tabIndex={-1}
+      // so Tab would otherwise leak focus into the page while the menu stayed
+      // open (menus-5). Do NOT preventDefault — closing restores focus to the
+      // previously focused element, and the browser's default Tab then
+      // continues from there to the next element.
+      if (e.key === 'Tab') {
+        closeMenu();
+        return;
+      }
       if (typeahead.onKeyDown(e)) {
         e.preventDefault();
         return;
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, typeahead],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   // Place the zero-size cursor anchor at a point in the trigger's local

package/src/ContextMenu/index.ts

@@ -35,3 +35,8 @@ export {
   DropdownMenuRadioItem as ContextMenuRadioItem,
   type DropdownMenuRadioItemProps as ContextMenuRadioItemProps,
 } from '../DropdownMenu/DropdownMenuRadioItem';
+// Submenus work inside a ContextMenu too (nested flyout of items).
+export {
+  DropdownMenuSubMenu as ContextMenuSubMenu,
+  type DropdownMenuSubMenuProps as ContextMenuSubMenuProps,
+} from '../DropdownMenu/DropdownMenuSubMenu';

package/src/DateInput/DateInput.doc.mjs

@@ -115,6 +115,13 @@ export const docs = {
       description:
         'Status indicator object for error, warning, or success states with a message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -142,6 +149,12 @@ export const docs = {
         "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
       default: "'date_long'",
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -152,6 +165,8 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-date-input', visualProps: ['size', 'status']},
+      {className: 'astryx-date-input-toggle-icon', states: ['state']},
+      {className: 'astryx-date-input-clear-icon'},
     ],
   },
   usage: {
@@ -384,6 +399,13 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '错误、警告或成功状态的状态指示对象，附带消息。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -415,6 +437,8 @@ export const docsZh = {
         className: 'astryx-date-input',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-date-input-toggle-icon', states: ['state']},
+      {className: 'astryx-date-input-clear-icon'},
     ],
   },
 };
@@ -492,6 +516,7 @@ export const docsDense = {
     placeholder: 'placeholder text in input',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'tooltip text via info icon at label end',
     hasClear: 'Shows clear button when date is set. Clears value on click.',
     numberOfMonths: 'months shown simultaneously in calendar popover',