@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/Tokenizer/Tokenizer.test.tsx

@@ -9,11 +9,17 @@
  * SYNC: When Tokenizer.tsx changes, update tests to match
  */
 
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Tokenizer} from './Tokenizer';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {SearchSource, SearchableItem} from '../Typeahead/types';
+import {TestIcon} from '../__tests__/TestIcon';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -60,6 +66,10 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Test data
 const users: SearchableItem[] = [
   {id: '1', label: 'Alice'},
@@ -818,6 +828,51 @@ describe('Tokenizer', () => {
     });
   });
 
+  describe('startIcon', () => {
+    it('does not render a start icon when omitted', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+        />,
+      );
+      expect(document.querySelector('svg')).not.toBeInTheDocument();
+    });
+
+    it('renders a ReactNode start icon before the tokens', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[{id: '1', label: 'Alice'}]}
+          onChange={() => {}}
+          startIcon={<TestIcon data-testid="start-icon" />}
+        />,
+      );
+      const icon = screen.getByTestId('start-icon');
+      const token = screen.getByText('Alice');
+      expect(icon).toBeInTheDocument();
+      expect(
+        icon.compareDocumentPosition(token) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('renders an IconType (SVG component) start icon', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          startIcon={TestIcon}
+        />,
+      );
+      expect(document.querySelector('svg')).toBeInTheDocument();
+    });
+  });
+
   describe('disabledMessage', () => {
     const h = {hidden: true} as const;
     const isOpen = (el: Element) => el.matches(':popover-open');
@@ -921,6 +976,130 @@ describe('Tokenizer', () => {
       expect(screen.getByRole('combobox')).toBeDisabled();
     });
   });
+  describe('announcements', () => {
+    it('announces removal politely on Backspace with an empty input', async () => {
+      const onChange = vi.fn();
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[users[0], users[1]]}
+          onChange={onChange}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.keyDown(input, {key: 'Backspace'});
+      expect(onChange).toHaveBeenCalledWith([users[0]], {
+        item: users[1],
+        type: 'remove',
+      });
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Removed Bob');
+      });
+    });
+
+    it("announces removal politely when clicking a token's remove button", async () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[users[0], users[1]]}
+          onChange={() => {}}
+        />,
+      );
+      fireEvent.click(screen.getByRole('button', {name: 'Remove Alice'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Removed Alice');
+      });
+    });
+
+    it('announces addition politely when selecting a search result', async () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          hasEntriesOnFocus
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.focus(input);
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+      fireEvent.click(screen.getByText('Alice'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Added Alice');
+      });
+    });
+
+    it('announces addition politely when creating a token with hasCreate', async () => {
+      const emptySource: SearchSource = {
+        search: () => [],
+        bootstrap: () => [],
+      };
+      render(
+        <Tokenizer
+          label="Tags"
+          searchSource={emptySource}
+          value={[]}
+          onChange={() => {}}
+          hasCreate
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'new-tag'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+      fireEvent.click(screen.getByText('Create "new-tag"'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Added new-tag');
+      });
+    });
+
+    it('does not announce on mount', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[users[0]]}
+          onChange={() => {}}
+        />,
+      );
+      // The live regions are created lazily on first announce, so a mount
+      // with pre-selected tokens must not create (or speak through) one.
+      expect(politeRegion()).toBeNull();
+    });
+
+    it('does not announce add/remove while typing', async () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'Ali'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+      // BaseTypeahead announces result counts while typing (existing
+      // behavior); typing alone must not produce add/remove announcements.
+      expect(politeRegion()?.textContent ?? '').not.toMatch(/Added|Removed/);
+    });
+  });
+
   describe('form participation', () => {
     it('submits one entry per token id under htmlName', () => {
       const {container} = render(
@@ -951,7 +1130,32 @@ describe('Tokenizer', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });
+
+
+describe('Tokenizer statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/Tokenizer/Tokenizer.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Tokenizer.tsx
- * @input Uses React, BaseTypeahead, Field, Token
+ * @input Uses React, BaseTypeahead, Field, Token, useAnnounce
  * @output Exports Tokenizer multi-select typeahead component
  * @position Composed component; forwards DOM ref and exposes focus control via
  *   handleRef
@@ -37,12 +37,14 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {renderIconSlot, type IconType} from '../Icon';
 import {OverflowList} from '../OverflowList';
 import {useLayer} from '../Layer/useLayer';
 import {useTooltip} from '../Tooltip';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {
   colorVars,
   spacingVars,
@@ -110,6 +112,13 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -369,6 +378,7 @@ export function Tokenizer<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -560,6 +570,12 @@ export function Tokenizer<T extends SearchableItem>({
     [],
   );
 
+  // Announce token add/remove politely via the persistent live region.
+  // Tokens previously appeared and disappeared silently — Backspace on an
+  // empty input removes the trailing token, and the per-token remove buttons
+  // gave no audible feedback either.
+  const announce = useAnnounce();
+
   // Handle adding an item — detect creatable synthetic items
   const handleAdd = useCallback(
     (item: T | null) => {
@@ -584,6 +600,7 @@ export function Tokenizer<T extends SearchableItem>({
         const realItem = base as T;
         const newItems = [...value, realItem];
         onChange(newItems, {item: realItem, type: 'create'});
+        announce(`Added ${createdValue}`);
         return;
       }
 
@@ -592,18 +609,22 @@ export function Tokenizer<T extends SearchableItem>({
       }
       const newItems = [...value, item];
       onChange(newItems, {item, type: 'add'});
+      announce(`Added ${item.label}`);
     },
-    [value, onChange, isAtMax, selectedIds, hasCreate],
+    [value, onChange, isAtMax, selectedIds, hasCreate, announce],
   );
 
-  // Handle removing an item
+  // Handle removing an item. Single removal path: both Backspace on an empty
+  // input and the per-token remove buttons route through here, so the
+  // announcement covers both.
   const handleRemove = useCallback(
     (item: T) => {
       const newItems = value.filter(v => v.id !== item.id);
       onChange(newItems, {item, type: 'remove'});
+      announce(`Removed ${item.label}`);
       inputRef.current?.focus();
     },
-    [value, onChange],
+    [value, onChange, announce],
   );
 
   // Handle clearing all items
@@ -879,6 +900,7 @@ export function Tokenizer<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}

package/src/TopNav/TopNav.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNav} from './TopNav';
 import {TopNavRenderContext} from './TopNavRenderContext';
@@ -297,6 +297,85 @@ describe('TopNavHeading', () => {
     render(<TopNavHeading heading="Test" ref={ref} />);
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
   });
+
+  // ===========================================================================
+  // Menu popover semantics — the popup must not be announced as a modal
+  // dialog, and role="menu" must be scoped to the actual menu items so the
+  // heading button is not an invalid child of the menu.
+  // ===========================================================================
+
+  // The popover layer keeps `popover` content display:none in jsdom even
+  // when open, hiding it from role queries — so these tests assert the
+  // popup's ARIA semantics at the DOM level instead.
+  describe('menu popover semantics', () => {
+    const menuItems = (
+      <>
+        <div role="menuitem">Alpha</div>
+        <div role="menuitem">Beta</div>
+      </>
+    );
+
+    it('does not wrap the heading menu popup in a modal dialog', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+    });
+
+    it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'My App');
+      const children = Array.from(menu!.children);
+      expect(children.length).toBeGreaterThan(0);
+      for (const child of children) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+
+    it('keeps the popup heading button outside the menu and closes on click', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      const trigger = screen.getByRole('button', {name: 'Open menu'});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      // The heading replica button in the popup is a sibling of the menu,
+      // not an invalid menu child.
+      const headingButton = Array.from(
+        document.querySelectorAll('button'),
+      ).find(b => b !== trigger && b.textContent?.includes('My App'));
+      expect(headingButton).toBeDefined();
+      expect(menu!.contains(headingButton!)).toBe(false);
+      // Clicking it still closes the popup.
+      fireEvent.click(headingButton!);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+      const user = userEvent.setup();
+      render(
+        <TopNavHeading
+          heading="Product"
+          headingHref="/product"
+          menu={menuItems}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'Product');
+      for (const child of Array.from(menu!.children)) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+  });
 });
 
 describe('NavIcon', () => {
@@ -444,4 +523,49 @@ describe('TopNavItem', () => {
       expect(card).toHaveAttribute('aria-label', 'Featured');
     });
   });
+
+  describe('TopNavMegaMenuFeaturedCard image alt handling', () => {
+    it('marks the image as explicitly decorative when imageAlt is omitted', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          data-testid="featured-card"
+        />,
+      );
+      const img = screen.getByTestId('featured-card').querySelector('img');
+      expect(img).toHaveAttribute('alt', '');
+      expect(img).toHaveAttribute('role', 'presentation');
+      expect(img).toHaveAttribute('aria-hidden', 'true');
+      // The image must not be exposed to assistive technology as a nameless img.
+      expect(screen.queryByRole('img')).toBeNull();
+    });
+
+    it('exposes the image with normal img semantics when imageAlt is provided', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          imageAlt="Team collaboration"
+        />,
+      );
+      const img = screen.getByRole('img', {name: 'Team collaboration'});
+      expect(img).not.toHaveAttribute('role');
+      expect(img).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('keeps title and link semantics unchanged with a decorative image', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          linkLabel="Read the announcement"
+          linkHref="/blog/v4"
+        />,
+      );
+      expect(screen.getByText("What's new")).toBeInTheDocument();
+      const link = screen.getByRole('link', {name: /Read the announcement/});
+      expect(link).toHaveAttribute('href', '/blog/v4');
+    });
+  });
 });

package/src/TopNav/TopNavHeading.tsx

@@ -332,6 +332,10 @@ export function TopNavHeading({
 
   const popover = usePopover({
     dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
+    // The popup exposes its own role="menu" semantics; a role="dialog"
+    // aria-modal wrapper would announce "dialog, Navigation menu" around a
+    // menu (the anti-pattern removed in a478a3dcf).
+    role: 'none',
     hasCloseButton: false,
   });
 
@@ -511,13 +515,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',
@@ -575,13 +585,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',