@astryxdesign/core 0.1.8 → 0.1.9

package/src/Timestamp/Timestamp.test.tsx

@@ -99,6 +99,38 @@ describe('Timestamp', () => {
     expect(el.textContent).not.toContain(':');
   });
 
+  it('renders date_weekday format with a weekday prefix', () => {
+    render(
+      <Timestamp
+        value="2026-02-19T17:00:00Z"
+        format="date_weekday"
+        data-testid="ts"
+      />,
+    );
+    const el = screen.getByTestId('ts');
+    // Includes the year and a leading weekday abbreviation, no time portion.
+    expect(el.textContent).toContain('2026');
+    expect(el.textContent).not.toContain(':');
+    // en-US short weekday for 2026-02-19 is "Thu"; assert a weekday word is
+    // present without over-fitting the exact locale punctuation.
+    expect(el.textContent).toMatch(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/);
+  });
+
+  it('renders date_long format with a full month name', () => {
+    render(
+      <Timestamp
+        value="2026-02-19T17:00:00Z"
+        format="date_long"
+        data-testid="ts"
+      />,
+    );
+    const el = screen.getByTestId('ts');
+    // Long-month shape: full month name, year, no time portion.
+    expect(el.textContent).toContain('February');
+    expect(el.textContent).toContain('2026');
+    expect(el.textContent).not.toContain(':');
+  });
+
   it('renders date_time format', () => {
     render(
       <Timestamp

package/src/Timestamp/Timestamp.tsx

@@ -21,9 +21,11 @@ import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps, mergeRefs} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {colorVars} from '../theme/tokens.stylex';
+import {SHARED_DATE_FORMAT_OPTIONS} from '../utils/plainDate';
 
 const LazyXDSTooltip = lazy(async () =>
   import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -37,6 +39,8 @@ export type TimestampFormat =
   | 'relative'
   | 'auto'
   | 'date'
+  | 'date_long'
+  | 'date_weekday'
   | 'date_time'
   | 'time'
   | 'system_date'
@@ -53,6 +57,8 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
    * - `'relative'`: "2 hours ago", "yesterday", "now"
    * - `'auto'`: Relative for recent times, `date_time` for older
    * - `'date'`: "Mar 21, 2025"
+   * - `'date_long'`: "March 21, 2025"
+   * - `'date_weekday'`: "Wed, Mar 21, 2025"
    * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
    * - `'time'`: "2:51 PM"
    * - `'system_date'`: "2025-03-21"
@@ -249,11 +255,22 @@ function formatTimestamp(
 ): string {
   switch (format) {
     case 'date':
-      return new Intl.DateTimeFormat(undefined, {
-        year: 'numeric',
-        month: 'short',
-        day: 'numeric',
-      }).format(date);
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date,
+      ).format(date);
+
+    case 'date_long':
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date_long,
+      ).format(date);
+
+    case 'date_weekday':
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date_weekday,
+      ).format(date);
 
     case 'date_time':
       return new Intl.DateTimeFormat(undefined, {
@@ -415,11 +432,14 @@ export function Timestamp({
     return () => clearInterval(timer);
   }, [isLive, isValidDate, effectiveFormat, diffSeconds]);
 
+  useDevWarning(
+    'Timestamp',
+    `could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
+    !isValidDate,
+  );
+
   // Placed after all hooks so the hook order stays stable across renders.
   if (!isValidDate) {
-    console.warn(
-      `Timestamp: could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
-    );
     return null;
   }
 

package/src/Toast/useToast.tsx

@@ -7,6 +7,7 @@ import {createRoot} from 'react-dom/client';
 import {dataAttr} from '../naming';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import {ToastViewport} from './ToastViewport';
+import {warnOnce} from '../utils/devWarning';
 import type {
   ToastOptions,
   ToastDismissFn,
@@ -17,7 +18,6 @@ import type {
 // Fallback singleton
 let fallbackContext: ToastContextValue | null = null;
 let fallbackRoot: ReturnType<typeof createRoot> | null = null;
-let fallbackWarned = false;
 
 const ROOT_THEME_ATTRS = ['data-theme', dataAttr('theme')] as const;
 
@@ -70,13 +70,12 @@ function getFallbackContext(): ToastContextValue {
     );
   }
 
-  if (!fallbackWarned) {
-    fallbackWarned = true;
-    console.warn(
-      'useToast: No LayerProvider found. Using fallback viewport. ' +
-        'Wrap your app with <LayerProvider> or <AppShell> for full control.',
-    );
-  }
+  warnOnce(
+    'toast-fallback-viewport',
+    'useToast',
+    'No LayerProvider found. Using fallback viewport. ' +
+      'Wrap your app with <LayerProvider> or <AppShell> for full control.',
+  );
 
   const container = document.createElement('div');
   container.setAttribute('data-astryx-toast-fallback', '');

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -41,7 +41,7 @@ interface ToggleButtonGroupContextValue {
   isDisabled?: boolean;
 }
 
-export const ToggleButtonGroupContext =
+const ToggleButtonGroupContext =
   createContext<ToggleButtonGroupContextValue | null>(null);
 ToggleButtonGroupContext.displayName = 'ToggleButtonGroupContext';
 

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -31,7 +31,7 @@ export const docs = {
       name: 'onChange',
       type: '(items: T[], change: TokenizerChange<T>) => void',
       description:
-        "Called when selection changes. The change argument includes the affected item and type ('add' | 'create' | 'remove' | 'reorder').",
+        "Called when selection changes. The change argument includes the affected item and type ('add' | 'create' | 'remove' | 'reorder'). Additions and removals (including Backspace on an empty input) are announced to screen readers via a polite live region.",
       required: true,
     },
     {
@@ -165,6 +165,13 @@ export const docs = {
       type: '(query: string) => void',
       description: 'Callback fired when the search query text changes.',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        'Icon to display at the start of the input, before any tokens. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly.',
+      slotElements: [{__element: 'Icon', props: {icon: 'search', size: 'sm'}}],
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
@@ -370,6 +377,12 @@ export const docsZh = {
       type: '(query: string) => void',
       description: '\u641c\u7d22\u67e5\u8be2\u6587\u672c\u53d8\u66f4\u65f6\u89e6\u53d1\u7684\u56de\u8c03\u3002',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        '\u5728\u8f93\u5165\u6846\u5f00\u5934\uff08token \u4e4b\u524d\uff09\u663e\u793a\u7684\u56fe\u6807\u3002\u63a5\u53d7\u8bed\u4e49\u56fe\u6807\u540d\u79f0\u3001SVG \u56fe\u6807\u7ec4\u4ef6\u6216\u76f4\u63a5\u4f20\u5165 ReactNode\u3002',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
@@ -460,6 +473,7 @@ export const docsDense = {
     size: 'Input+token size.',
     debounceMs: 'Search debounce delay ms. 0 for sync sources.',
     onChangeQuery: 'Fired on search query text change.',
+    startIcon: 'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',
     endContent: 'Content at input row end. For buttons, counts, controls.',
     handleRef: 'Imperative handle for focus() and blur() control.',
     xstyle: 'StyleX layout styles (margins, positioning). Must be stylex.create() value.',

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,9 @@ describe('Tokenizer', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });

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
@@ -43,6 +43,7 @@ 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,
@@ -560,6 +561,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 +591,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 +600,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

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');
+    });
+  });
 });