@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/Table/plugins/sortable/useTableSortableState.tsx

@@ -168,14 +168,18 @@ function defaultCompare<T extends Record<string, unknown>>(
   const aVal = a[sortKey];
   const bVal = b[sortKey];
 
-  // null/undefined sort to the end
-  if (aVal == null && bVal == null) {
+  // null/undefined/NaN sort to the end. NaN must not reach the numeric fast
+  // path: a NaN comparator result reads as "equal" to Array.sort, which makes
+  // the comparator inconsistent and corrupts the order of the other rows.
+  const aMissing = aVal == null || (typeof aVal === 'number' && Number.isNaN(aVal));
+  const bMissing = bVal == null || (typeof bVal === 'number' && Number.isNaN(bVal));
+  if (aMissing && bMissing) {
     return 0;
   }
-  if (aVal == null) {
+  if (aMissing) {
     return 1;
   }
-  if (bVal == null) {
+  if (bMissing) {
     return -1;
   }
 

package/src/TextArea/TextArea.test.tsx

@@ -13,7 +13,7 @@ import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -193,7 +193,7 @@ describe('TextArea', () => {
         label="Description"
         value=""
         onChange={() => {}}
-        startIcon={MagnifyingGlassIcon}
+        startIcon={TestIcon}
       />,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();
@@ -577,7 +577,7 @@ describe('TextArea', () => {
           label="Notes"
           value=""
           onChange={() => {}}
-          startIcon={<MagnifyingGlassIcon />}
+          startIcon={<TestIcon />}
         />,
       );
 

package/src/TextInput/TextInput.test.tsx

@@ -12,7 +12,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {TextInput} from './TextInput';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -163,7 +163,7 @@ describe('TextInput', () => {
         label="Search"
         value=""
         onChange={() => {}}
-        startIcon={MagnifyingGlassIcon}
+        startIcon={TestIcon}
       />,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();
@@ -482,7 +482,7 @@ describe('TextInput', () => {
           label="Search"
           value=""
           onChange={() => {}}
-          startIcon={<MagnifyingGlassIcon />}
+          startIcon={<TestIcon />}
         />,
       );
 

package/src/Thumbnail/Thumbnail.test.tsx

@@ -37,11 +37,45 @@ describe('Thumbnail', () => {
     expect(screen.getByRole('status')).toBeInTheDocument();
   });
 
-  it('uses label as accessible name on root', () => {
+  it('exposes the label as an accessible name via a valid group role', () => {
     render(<Thumbnail label="photo.png" data-testid="thumb" />);
-    expect(screen.getByTestId('thumb')).toHaveAttribute('aria-label', 'photo.png');
+    // The accessible name must be carried by a valid named role (group),
+    // not by a bare aria-label on a generic div (aria-prohibited-attr).
+    const group = screen.getByRole('group', {name: 'photo.png'});
+    expect(group).toBe(screen.getByTestId('thumb'));
   });
 
+  it('does not put aria-label on a generic (roleless) element', () => {
+    render(<Thumbnail label="photo.png" data-testid="thumb" />);
+    const thumb = screen.getByTestId('thumb');
+    // The labeled element must declare a role so the name is legitimate.
+    expect(thumb).toHaveAttribute('role', 'group');
+  });
+
+  it('keeps interactive children accessible while exposing the group name', () => {
+    const onRemove = vi.fn();
+    render(
+      <Thumbnail
+        src="/img.jpg"
+        alt="Clickable"
+        label="file.png"
+        onClick={vi.fn()}
+        onRemove={onRemove}
+      />,
+    );
+    // A group role (unlike img) must not hide descendant controls.
+    expect(
+      screen.getByRole('group', {name: 'file.png — Clickable'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Open file.png — Clickable'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Remove file.png — Clickable'}),
+    ).toBeInTheDocument();
+  });
+
+
   it('label is shown via tooltip, not as inline text', () => {
     render(<Thumbnail label="photo.png" data-testid="thumb" />);
     // Label should exist in DOM (tooltip) but not as a direct child text node

package/src/Thumbnail/Thumbnail.tsx

@@ -58,8 +58,9 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
   alt?: string;
   /**
    * Accessible label for the thumbnail (e.g. file name).
-   * Not rendered visually — shown in a tooltip on hover and used
-   * as accessible name for the remove button.
+   * Not rendered visually — shown in a tooltip on hover, exposed as the
+   * accessible name of the thumbnail group, and used as the accessible
+   * name for the remove button.
    */
   label?: string;
   /**
@@ -296,6 +297,7 @@ export function Thumbnail({
     <div
       ref={ref}
       data-testid={testId}
+      role="group"
       aria-label={accessibleName}
       {...mergeProps(
         themeProps('thumbnail'),

package/src/TimeInput/TimeInput.test.tsx

@@ -160,6 +160,43 @@ describe('TimeInput', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  it('sets aria-invalid="true" when typed input is out of range', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '25:99'}});
+
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('does not set aria-invalid when typed input is a valid time', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '3:45 pm'}});
+
+    expect(input).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('announces an alert message when typed input is invalid', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '25:99'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Invalid time');
+  });
+
+  it('does not announce an alert message when input is valid', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '3:45 pm'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('');
+    expect(screen.queryByText('Invalid time')).not.toBeInTheDocument();
+  });
+
   it('calls onChange on blur when input is valid', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/TimeInput/TimeInput.tsx

@@ -635,7 +635,9 @@ export function TimeInput({
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
         aria-required={isRequired === true ? 'true' : undefined}
-        aria-invalid={status?.type === 'error' ? 'true' : undefined}
+        aria-invalid={
+          status?.type === 'error' || !isInputValid ? 'true' : undefined
+        }
         aria-busy={isBusy || undefined}
         aria-labelledby={ariaLabelledBy}
         {...stylex.props(
@@ -644,6 +646,14 @@ export function TimeInput({
           !isInputValid && styles.inputInvalid,
         )}
       />
+      {/*
+          Live region announcing invalid typed input to assistive technology.
+          The value silently reverts on blur, so without this a screen-reader
+          user would get no feedback that their entry was rejected (WCAG 3.3.1).
+        */}
+      <VisuallyHidden as="div" role="alert" aria-live="assertive">
+        {!isInputValid ? 'Invalid time' : ''}
+      </VisuallyHidden>
       {isBusy && <Spinner size="sm" />}
       {hasClear && value && !isDisabled && (
         <button

package/src/Timestamp/Timestamp.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-timestamp', visualProps: ['type', 'color']},
+      {className: 'astryx-timestamp', visualProps: ['type', 'color', 'format']},
     ],
   },
   usage: {

package/src/Toast/Toast.tsx

@@ -121,8 +121,14 @@ export function Toast({
   // Will be initialized by startTimer when actually used
   const startTimeRef = useRef<number | null>(null);
 
+  // Read onDismiss through a ref: the viewport re-creates it on every render
+  // (another toast arriving/exiting), and a startTimer that depends on it
+  // would restart — and un-pause — this toast's timer on unrelated renders.
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
   const startTimer = useCallback(() => {
-    if (!isAutoHide) {
+    if (!isAutoHide || isPausedRef.current) {
       return;
     }
     if (timerRef.current) {
@@ -130,9 +136,9 @@ export function Toast({
     }
     startTimeRef.current = Date.now();
     timerRef.current = setTimeout(() => {
-      onDismiss('auto');
+      onDismissRef.current('auto');
     }, remainingRef.current);
-  }, [isAutoHide, onDismiss]);
+  }, [isAutoHide]);
 
   const pauseTimer = useCallback(() => {
     if (!isAutoHide || isPausedRef.current) {
@@ -165,6 +171,8 @@ export function Toast({
         clearTimeout(timerRef.current);
       }
     };
+    // startTimer's identity is stable per isAutoHide, so this runs on mount
+    // and on a genuine duration change — not on unrelated viewport renders.
   }, [autoHideDuration, startTimer]);
 
   // Pause the auto-hide timer while the window is not focused, so a toast

package/src/Toast/ToastViewport.test.tsx

@@ -212,3 +212,67 @@ describe('ToastViewport region ARIA', () => {
     expect(region).not.toHaveAttribute('aria-modal');
   });
 });
+
+describe('toast timer lifecycle (#3589)', () => {
+  it('fires onHide exactly once when dismissed twice during the exit window', () => {
+    const onHide = vi.fn();
+    renderViewport(
+      <ShowToastButton options={{body: 'Once', onHide}} triggerLabel="Show" />,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    // The toast stays mounted during its exit transition; a second click
+    // lands on the same still-mounted button.
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    expect(onHide).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a window-blur pause alive when another toast arrives', () => {
+    vi.useFakeTimers();
+    try {
+      const onHide = vi.fn();
+      renderViewport(
+        <>
+          <ShowToastButton
+            options={{body: 'Paused', autoHideDuration: 3000, onHide}}
+            triggerLabel="Show A"
+          />
+          <ShowToastButton options={INFO_B} triggerLabel="Show B" />
+        </>,
+      );
+      act(() => {
+        fireEvent.click(screen.getByText('Show A'));
+      });
+      act(() => {
+        fireEvent.blur(window);
+      });
+      // A second toast arriving re-renders the viewport; the paused timer
+      // must not silently restart.
+      act(() => {
+        fireEvent.click(screen.getByText('Show B'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(60_000);
+      });
+      expect(onHide).not.toHaveBeenCalled();
+      // Focus returns: the remaining time resumes and completes normally.
+      act(() => {
+        fireEvent.focus(window);
+      });
+      act(() => {
+        vi.advanceTimersByTime(60_000);
+      });
+      expect(onHide).toHaveBeenCalledTimes(1);
+      expect(onHide).toHaveBeenCalledWith('auto');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/Toast/ToastViewport.tsx

@@ -114,6 +114,9 @@ export function ToastViewport({
 
   // Show the popover on mount so it enters the top layer.
   const viewportRef = useRef<HTMLDivElement>(null);
+  // Toast ids whose exit has begun — guards onHide from double-firing (see
+  // removeToast). Mirrors exitingIds state, readable synchronously.
+  const exitingIdsRef = useRef<Set<string>>(new Set());
   // The element that was focused before the user jumped into the viewport
   // (via F6). Used to restore focus once all toasts are dismissed so focus
   // never falls to <body>.
@@ -171,6 +174,14 @@ export function ToastViewport({
   }, []);
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
+    // An exiting toast stays in toastsRef until its exit transition ends, so
+    // a second dismissal inside that window (double-click, auto-timer plus
+    // manual dismiss()) would re-fire onHide. Track exiting ids in a ref —
+    // the exitingIds state dedupe below runs too late to protect onHide.
+    if (exitingIdsRef.current.has(id)) {
+      return;
+    }
+    exitingIdsRef.current.add(id);
     const entry = toastsRef.current.find(t => t.id === id);
     if (entry) {
       entry.options.onHide?.(reason);
@@ -210,6 +221,7 @@ export function ToastViewport({
   }, []);
 
   const handleExited = useCallback((id: string) => {
+    exitingIdsRef.current.delete(id);
     setExitingIds(prev => {
       if (!prev.has(id)) {
         return prev;

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-toggle-button-group'},
+      {className: 'astryx-toggle-button', states: ['isPressed']},
     ],
   },
   description: 'A button that toggles between pressed and unpressed states. Thin wrapper over Button with controlled toggle pattern, icon swap, and font weight emphasis.',

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -189,7 +189,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
     ],
   },
   usage: {
@@ -390,7 +390,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
     ],
   },
   usage: {

package/src/TopNav/TopNav.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-top-nav', states: ['mode']},
-      {className: 'astryx-top-nav-item', states: ['mode']},
+      {className: 'astryx-top-nav-item', states: ['mode', 'selected']},
       {className: 'astryx-top-nav-heading'},
       {className: 'astryx-top-nav-mega-menu', states: ['mode']},
       {className: 'astryx-top-nav-mega-menu-item', states: ['mode']},

package/src/TreeList/TreeList.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
-      {className: 'astryx-tree-list-item', states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
     ],
   },
   components: [
@@ -89,7 +89,7 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
-      {className: 'astryx-tree-list-item', states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
     ],
   },
   components: [

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -8,6 +8,16 @@ export const docs = {
   displayName: 'Base Typeahead',
   isHiddenFromOverview: true,
   description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+  usage: {
+    description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly, since BaseTypeahead renders no visual chrome of its own.' },
+      { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
+      { guidance: false, description: 'Expect a wrapper div, border, or token rendering. BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.' },
+    ],
+  },
   props: [
     {
       name: 'searchSource',
@@ -226,6 +236,15 @@ export const docsDense = {
   isHiddenFromOverview: true,
   displayName: 'Base Typeahead',
   description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by Typeahead+Tokenizer.',
+  usage: {
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they add the wrapper, border, and token rendering BaseTypeahead omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly; BaseTypeahead renders no chrome.' },
+      { guidance: true, description: 'Pass anchorRef to your wrapper so the dropdown positions against your input chrome, not the bare input.' },
+      { guidance: false, description: 'Expect wrapper, border, or token rendering. Engine only; chrome is the caller\'s job.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer suffice; extra work only pays off for custom compositions.' },
+    ],
+  },
   propDescriptions: {
     searchSource: 'Data source w/ search+bootstrap methods.',
     value: 'Currently selected item.',

package/src/Typeahead/BaseTypeahead.tsx

@@ -410,7 +410,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   const performSearch = useCallback(
     async (searchQuery: string) => {
       searchSource.cancel?.();
-      const gen = searchGenRef.current;
+      // Claim a new generation so overlapping searches can't race: an
+      // in-flight response for an older query fails the gen check below
+      // instead of overwriting the newer results.
+      const gen = ++searchGenRef.current;
       setIsLoading(true);
       setHasSearched(true);
       try {
@@ -451,7 +454,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
-    const gen = searchGenRef.current;
+    const gen = ++searchGenRef.current;
     setIsLoading(true);
     try {
       const bootstrapResults = await searchSource.bootstrap();

package/src/Typeahead/Typeahead.doc.mjs

@@ -168,7 +168,7 @@ export const docs = {
   components: [{name: 'BaseTypeahead'}, {name: 'TypeaheadItem'}],
   theming: {
     targets: [
-      {className: 'astryx-typeahead', visualProps: ['status']},
+      {className: 'astryx-typeahead', visualProps: ['status', 'size']},
       {className: 'astryx-typeahead-dropdown'},
       {className: 'astryx-typeahead-item'},
     ],

package/src/Typeahead/Typeahead.test.tsx

@@ -18,7 +18,7 @@ import {
   afterAll,
   beforeEach,
 } from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Typeahead} from './Typeahead';
 import {BaseTypeahead} from './BaseTypeahead';
@@ -314,6 +314,50 @@ describe('BaseTypeahead focus-out', () => {
 });
 
 describe('Typeahead', () => {
+  describe('out-of-order async results', () => {
+    it('discards a stale response that resolves after a newer query', async () => {
+      const resolvers = new Map<string, (items: SearchableItem[]) => void>();
+      const rawSource: SearchSource = {
+        search: async (query: string) =>
+          new Promise<SearchableItem[]>(resolve => {
+            resolvers.set(query, resolve);
+          }),
+        bootstrap: () => [],
+      };
+
+      render(
+        <Typeahead
+          label="Fruit"
+          searchSource={rawSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'a'}});
+      fireEvent.change(input, {target: {value: 'ap'}});
+
+      // The newer query resolves first…
+      await act(async () => {
+        resolvers.get('ap')!([{id: 'apple', label: 'Apple'}]);
+      });
+      expect(screen.getByText('Apple')).toBeInTheDocument();
+
+      // …then the abandoned query's slow response arrives and must be
+      // discarded rather than overwriting the current results.
+      await act(async () => {
+        resolvers.get('a')!([
+          {id: 'avocado', label: 'Avocado'},
+          {id: 'apricot', label: 'Apricot'},
+        ]);
+      });
+      expect(screen.getByText('Apple')).toBeInTheDocument();
+      expect(screen.queryByText('Avocado')).not.toBeInTheDocument();
+    });
+  });
+
   it('renders with label', () => {
     render(
       <Typeahead

package/src/__tests__/TestIcon.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TestIcon.tsx
+ * @input Standard SVG props
+ * @output A minimal SVG React component for tests
+ * @position Test fixture; a stand-in external SVG icon for Icon component-mode tests
+ *
+ * A trivial SVG component used by tests that need to pass a custom SVG icon to
+ * `Icon` (component mode) or component `*Icon` props. It forwards all standard
+ * SVG props and its ref so tests exercising prop/ref forwarding behave the same
+ * as a real third-party icon component.
+ */
+
+import React, {type SVGProps} from 'react';
+
+export function TestIcon({
+  ref,
+  ...props
+}: SVGProps<SVGSVGElement> & {ref?: React.Ref<SVGSVGElement>}) {
+  return (
+    <svg ref={ref} viewBox="0 0 24 24" {...props}>
+      <path d="M4 4h16v16H4z" />
+    </svg>
+  );
+}