@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Timestamp/Timestamp.doc.mjs

@@ -26,9 +26,9 @@ export const docs = {
     },
     {
       name: 'format',
-      type: "'relative' | 'auto' | 'date' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
+      type: "'relative' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
       description:
-        "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
+        "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
       default: "'auto'",
     },
     {
@@ -110,7 +110,7 @@ export const docs = {
 export const docsZh = {
   propDescriptions: {
     value: '\u8981\u663e\u793a\u7684\u65e5\u671f/\u65f6\u95f4\u3002\u63a5\u53d7 Unix \u65f6\u95f4\u6233\uff08\u79d2\uff09\u6216 ISO 8601 \u5b57\u7b26\u4e32\u3002',
-    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
+    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'date_long' \u663e\u793a\u957f\u6708\u4efd\u65e5\u671f\uff0c'date_weekday' \u663e\u793a\u661f\u671f+\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
     autoThreshold: "auto \u683c\u5f0f\u4ece\u76f8\u5bf9\u65f6\u95f4\u5207\u6362\u5230 date_time \u7684\u9608\u503c\u79d2\u6570\u3002",
     hasTooltip: '\u60ac\u505c\u65f6\u662f\u5426\u663e\u793a\u5305\u542b\u5b8c\u6574\u65e5\u671f/\u65f6\u95f4\u7684\u5de5\u5177\u63d0\u793a\uff08\u76f8\u5bf9\u65f6\u95f4\u6a21\u5f0f\uff09\u3002',
     isTimezoneShown: '\u662f\u5426\u9644\u52a0\u65f6\u533a\u7f29\u5199\u3002',
@@ -157,7 +157,7 @@ export const docsDense = {
   },
   propDescriptions: {
     value: 'date/time as unix seconds or ISO string',
-    format: "display mode: 'relative', 'auto', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
+    format: "display mode: 'relative', 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
     autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
     hasTooltip: 'show full time tooltip on hover (relative mode)',
     isTimezoneShown: 'append timezone abbreviation',

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/Token/Token.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Token} from './Token';
+import type {TokenColor} from './Token';
 
 describe('Token', () => {
   it('renders with label', () => {
@@ -51,6 +52,23 @@ describe('Token', () => {
     }
   });
 
+  it('reflects a custom (theme-augmented) color as a class and data attribute', () => {
+    // Themes extend TokenColorMap via module augmentation and supply the
+    // styling through generated theme CSS; the runtime just forwards the
+    // value as the stable class + data-color reflection so the theme
+    // selector can match. Cast simulates a consumer-augmented color.
+    render(
+      <Token
+        label="Brand"
+        color={'brand' as TokenColor}
+        data-testid="token-custom"
+      />,
+    );
+    const token = screen.getByTestId('token-custom');
+    expect(token).toHaveClass('astryx-token', 'brand');
+    expect(token).toHaveAttribute('data-color', 'brand');
+  });
+
   it('renders as a span with invisible button when onClick is provided', () => {
     const handleClick = vi.fn();
     render(
@@ -135,10 +153,7 @@ describe('Token', () => {
 
   it('renders endContent', () => {
     render(
-      <Token
-        label="Token"
-        endContent={<span data-testid="end">End</span>}
-      />,
+      <Token label="Token" endContent={<span data-testid="end">End</span>} />,
     );
     expect(screen.getByTestId('end')).toBeInTheDocument();
     expect(screen.getByText('End')).toBeInTheDocument();
@@ -241,12 +256,7 @@ describe('Token accessibility', () => {
 
   it('disables both buttons when isDisabled is true', () => {
     render(
-      <Token
-        label="Token"
-        onClick={() => {}}
-        onRemove={() => {}}
-        isDisabled
-      />,
+      <Token label="Token" onClick={() => {}} onRemove={() => {}} isDisabled />,
     );
     const buttons = screen.getAllByRole('button');
     for (const button of buttons) {
@@ -355,11 +365,7 @@ describe('Token focus outline', () => {
   it('invisible button does not show its own focus outline', async () => {
     const user = userEvent.setup();
     render(
-      <Token
-        label="Focusable"
-        onClick={() => {}}
-        data-testid="focus-token"
-      />,
+      <Token label="Focusable" onClick={() => {}} data-testid="focus-token" />,
     );
     const button = screen.getByRole('button', {name: 'Focusable'});
     await user.tab();

package/src/Token/Token.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Token.tsx
  * @input Uses React, ReactNode, StyleXStyles
- * @output Exports Token component, TokenProps, TokenColor types
+ * @output Exports Token component, TokenProps, TokenColor, TokenColorMap types
  * @position Core implementation; consumed by index.ts, tested by Token.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -41,20 +41,37 @@ import {useTranslator} from '../i18n';
 // =============================================================================
 
 /**
- * Available color variants for the token.
+ * Extensible color map for Token.
+ *
+ * Theme packages can add custom colors via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Token' {
+ *   interface TokenColorMap {
+ *     brand: true;
+ *   }
+ * }
+ * ```
+ */
+export interface TokenColorMap {
+  default: true;
+  red: true;
+  orange: true;
+  yellow: true;
+  green: true;
+  teal: true;
+  cyan: true;
+  blue: true;
+  purple: true;
+  pink: true;
+  gray: true;
+}
+
+/**
+ * Token color type derived from TokenColorMap.
+ * Extensible via module augmentation of TokenColorMap.
  */
-export type TokenColor =
-  | 'default'
-  | 'red'
-  | 'orange'
-  | 'yellow'
-  | 'green'
-  | 'teal'
-  | 'cyan'
-  | 'blue'
-  | 'purple'
-  | 'pink'
-  | 'gray';
+export type TokenColor = keyof TokenColorMap;
 
 export type TokenSize = 'sm' | 'md' | 'lg';
 

package/src/Token/index.ts

@@ -12,4 +12,4 @@
  */
 
 export {Token} from './Token';
-export type {TokenProps, TokenColor, TokenSize} from './Token';
+export type {TokenProps, TokenColor, TokenColorMap, TokenSize} from './Token';

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,
     },
     {
@@ -88,6 +88,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      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.',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -165,6 +172,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',
@@ -178,7 +192,14 @@ export const docs = {
     {
       name: 'handleRef',
       type: 'React.Ref<TokenizerHandle>',
-      description: 'Imperative handle for focus() and blur() control.',
+      description:
+        'Imperative handle exposing focusInput(), focusFirstToken(), focusLastToken(), clearInput(), and selectAll().',
+    },
+    {
+      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',
@@ -300,6 +321,13 @@ export const docsZh = {
       description:
         '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -370,6 +398,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',
@@ -448,6 +482,7 @@ export const docsDense = {
     isDisabled: 'Disables input+all token interactions.',
     htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',
     isRequired: 'Marks field required.',
@@ -460,6 +495,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,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',
+    );
+  });
+});