@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -45,6 +45,13 @@ export const docs = {
       description: 'Whether the thumbnail is disabled.',
       default: 'false',
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. `none` (the default) keeps the existing hover-only shadow; set a level to raise the tile at rest.',
+      default: "'none'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -101,6 +108,7 @@ export const docsZh = {
     onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',
     isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',
     isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',
+    elevation: '\u9759\u6B62\u9634\u5F71\u6DF1\u5EA6\uFF1Anone\uFF08\u9ED8\u8BA4\uFF0C\u4FDD\u7559\u4EC5\u60AC\u505C\u9634\u5F71\uFF09| low | med | high\u3002',
     xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',
     className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
     style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
@@ -141,6 +149,7 @@ export const docsDense = {
     onClick: '(e) => void. Adds button semantics + hover shadow.',
     isLoading: 'Skeleton (no src) or upload overlay (with src). Default: false.',
     isDisabled: 'Disabled state. Default: false.',
+    elevation: 'Resting shadow depth: none (keeps hover-only shadow) | low | med | high.',
     xstyle: 'stylex.create() for layout.',
     className: 'CSS class. Prefer xstyle.',
     style: 'Inline styles. Prefer xstyle.',

package/src/Thumbnail/Thumbnail.test.tsx

@@ -21,16 +21,19 @@ describe('Thumbnail', () => {
   });
 
   it('shows skeleton when isLoading with no src', () => {
-    const {container} = render(
-      <Thumbnail isLoading data-testid="thumb" />,
-    );
+    const {container} = render(<Thumbnail isLoading data-testid="thumb" />);
     expect(container.querySelector('.astryx-skeleton')).toBeInTheDocument();
     expect(screen.queryByRole('img')).toBeNull();
   });
 
   it('shows image with upload overlay when isLoading with src', () => {
     render(
-      <Thumbnail src="/local.jpg" alt="Uploading" isLoading data-testid="thumb" />,
+      <Thumbnail
+        src="/local.jpg"
+        alt="Uploading"
+        isLoading
+        data-testid="thumb"
+      />,
     );
     const img = screen.getByRole('img');
     expect(img).toHaveAttribute('src', '/local.jpg');
@@ -75,7 +78,6 @@ describe('Thumbnail', () => {
     ).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
@@ -117,9 +119,7 @@ describe('Thumbnail', () => {
 
   it('is not interactive when isLoading', () => {
     const onClick = vi.fn();
-    render(
-      <Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />,
-    );
+    render(<Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />);
     expect(screen.queryByRole('button')).toBeNull();
   });
 
@@ -128,4 +128,34 @@ describe('Thumbnail', () => {
     render(<Thumbnail ref={ref} data-testid="thumb" />);
     expect(ref).toHaveBeenCalled();
   });
+
+  describe('elevation', () => {
+    // The elevation class lives on the image container (the shadow surface),
+    // which is the root's first element child.
+    const imageContainerClass = (
+      elevation: 'none' | 'low' | 'med' | 'high',
+    ) => {
+      const {container} = render(
+        <Thumbnail src="/x.png" alt="x" elevation={elevation} />,
+      );
+      return container.firstElementChild!.firstElementChild!.className;
+    };
+
+    it('renders a distinct class for each elevation level', () => {
+      const classes = new Set([
+        imageContainerClass('none'),
+        imageContainerClass('low'),
+        imageContainerClass('med'),
+        imageContainerClass('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(<Thumbnail src="/x.png" alt="x" />);
+      expect(def.firstElementChild!.firstElementChild!.className).toBe(
+        imageContainerClass('none'),
+      );
+    });
+  });
 });

package/src/Thumbnail/Thumbnail.tsx

@@ -38,6 +38,7 @@ import {Tooltip} from '../Tooltip/Tooltip';
 import {MediaTheme} from '../theme/MediaTheme';
 import {useImageMode} from '../hooks/useImageMode';
 import type {BaseProps} from '../BaseProps';
+import type {Elevation} from '../utils/types';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -90,6 +91,12 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Resting elevation — the shadow depth the tile sits at. `none` (the default)
+   * keeps the existing hover-only shadow; a set level raises the tile at rest.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Test ID for testing frameworks.
    */
@@ -116,6 +123,10 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-element'],
     overflow: 'hidden',
     backgroundColor: colorVars['--color-neutral'],
+    // Resting elevation is set via --_thumbnail-elevation (see elevationStyles).
+    // Routing it through a var lets the interactive hover bump (below) override
+    // just the resting value without clobbering the elevation prop.
+    boxShadow: 'var(--_thumbnail-elevation, none)',
   },
   image: {
     width: '100%',
@@ -144,7 +155,10 @@ const styles = stylex.create({
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
     boxShadow: {
-      default: 'none',
+      // Rest at the elevation prop's level (default none); bump to med on hover
+      // as before. Reading the var here keeps a set elevation visible at rest
+      // instead of being reset to flat.
+      default: 'var(--_thumbnail-elevation, none)',
       ':hover': {
         '@media (hover: hover)': shadowVars['--shadow-med'],
       },
@@ -201,6 +215,17 @@ const styles = stylex.create({
   },
 });
 
+// Resting elevation → shadow token. Sets --_thumbnail-elevation (read by the
+// image container and the interactive hover style) rather than box-shadow
+// directly, so a set resting elevation survives the interactive hover bump.
+// 'none' is the default — the existing hover-only shadow is unchanged.
+const elevationStyles = stylex.create({
+  none: {'--_thumbnail-elevation': 'none'},
+  low: {'--_thumbnail-elevation': shadowVars['--shadow-low']},
+  med: {'--_thumbnail-elevation': shadowVars['--shadow-med']},
+  high: {'--_thumbnail-elevation': shadowVars['--shadow-high']},
+});
+
 // =============================================================================
 // Placeholder icon — a simple image silhouette
 // =============================================================================
@@ -246,6 +271,7 @@ export function Thumbnail({
   onClick,
   isLoading = false,
   isDisabled = false,
+  elevation = 'none',
   xstyle,
   className,
   style,
@@ -311,6 +337,7 @@ export function Thumbnail({
       <div
         {...stylex.props(
           styles.imageContainer,
+          elevationStyles[elevation],
           isInteractive && styles.interactive,
         )}>
         {isInteractive ? (

package/src/TimeInput/TimeInput.test.tsx

@@ -9,12 +9,24 @@
  * SYNC: When TimeInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TimeInput} from './TimeInput';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import type {ISOTimeString} from '../utils';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+function assertiveRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 describe('TimeInput', () => {
   it('renders with label', () => {
@@ -352,6 +364,69 @@ describe('TimeInput', () => {
       // duplicated.
       expect(container.querySelectorAll('svg')).toHaveLength(1);
     });
+
+    // The grouped status node exists only for aria-describedby; announcing
+    // happens through the persistent useAnnounce regions because a live
+    // region mounted together with its content is not reliably announced.
+    it('keeps the grouped status node role-free while announcing via the persistent region', async () => {
+      render(
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            status={{type: 'error', message: 'Start time is required'}}
+          />
+        </InputGroup>,
+      );
+
+      const input = screen.getByRole('textbox', {
+        name: 'Schedule Start time',
+      });
+      const describedByIDs =
+        input.getAttribute('aria-describedby')?.split(' ') ?? [];
+      const statusNode = describedByIDs
+        .map(id => document.getElementById(id))
+        .find(el => el?.textContent === 'Start time is required');
+      expect(statusNode).toBeTruthy();
+      expect(statusNode).not.toHaveAttribute('role');
+      expect(statusNode).not.toHaveAttribute('aria-live');
+
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('Start time is required');
+      });
+    });
+
+    // Regression: a grouped status message appearing after mount (the common
+    // validation flow) must land in the persistent announce region.
+    it('announces a grouped status message that appears after mount', async () => {
+      const grouped = (status?: {
+        type: 'error' | 'warning';
+        message: string;
+      }) => (
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            status={status}
+          />
+        </InputGroup>
+      );
+      const {rerender} = render(grouped());
+      expect(politeRegion()).toBeNull();
+
+      rerender(grouped({type: 'warning', message: 'Schedule is unusual'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Schedule is unusual');
+      });
+      // Non-error statuses stay on the polite channel.
+      expect(assertiveRegion()).toHaveTextContent('');
+    });
   });
 
   describe('disabledMessage', () => {

package/src/TimeInput/TimeInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TimeInput.tsx
- * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, InputGroupContext
+ * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, InputGroupContext, useAnnounce
  * @output Exports TimeInput component, TimeInputProps
  * @position Core implementation; consumed by index.ts, tested by TimeInput.test.tsx
  *
@@ -20,6 +20,7 @@ import {
   useId,
   useState,
   useCallback,
+  useEffect,
   useRef,
   useMemo,
   useOptimistic,
@@ -64,6 +65,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
@@ -369,6 +371,21 @@ export function TimeInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // In grouped mode the status message renders as a visually-hidden node that
+  // exists only for aria-describedby. Announce it through the persistent
+  // useAnnounce live regions instead of role/aria-live on that node — a live
+  // region mounted together with its content is not reliably announced.
+  // Ungrouped mode delegates to Field -> FieldStatus, which announces itself.
+  const announce = useAnnounce();
+  useEffect(() => {
+    if (inputGroup && status?.message) {
+      announce(
+        status.message,
+        status.type === 'error' ? 'assertive' : 'polite',
+      );
+    }
+  }, [announce, inputGroup, status?.message, status?.type]);
+
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the input container (which already exists) and
   // the input stays perceivable via aria-disabled instead of the disabled
@@ -611,11 +628,7 @@ export function TimeInput({
         </VisuallyHidden>
       )}
       {inputGroup && status?.message && (
-        <VisuallyHidden
-          as="div"
-          id={statusMessageID}
-          role={status.type === 'error' ? 'alert' : 'status'}
-          aria-live={status.type === 'error' ? 'assertive' : 'polite'}>
+        <VisuallyHidden as="div" id={statusMessageID}>
           {status.message}
         </VisuallyHidden>
       )}

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,
     },
     {

package/src/Tokenizer/Tokenizer.test.tsx

@@ -9,12 +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';
 
+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 +65,10 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Test data
 const users: SearchableItem[] = [
   {id: '1', label: 'Alice'},
@@ -921,6 +930,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 +1084,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/Toolbar/Toolbar.tsx

@@ -239,6 +239,7 @@ export function Toolbar({
   const hasCenterContent = centerContent != null;
   const hasStartContent = startContent != null;
   const hasEndContent = endContent != null;
+  const hasBottomDivider = dividers?.includes('bottom') ?? false;
 
   const gapVar = spacingVars[spacingStepToVar[gap]] as string;
 
@@ -316,9 +317,15 @@ export function Toolbar({
               orientation === 'vertical' && styles.vertical,
               sizeStyles.base,
               dynamicStyles.gap(gapVar),
-              dynamicStyles.tabIndicatorBottom(
-                `calc(-1 * (${blockPaddingVarForSize[size]}${dividers?.includes('bottom') ? ' + 1px' : ''}))`,
-              ),
+              // Only drop the tab indicator through the toolbar's block padding
+              // onto the rail when a bottom divider is actually present.
+              // Without a divider, leave `--_tab-indicator-bottom` unset so a
+              // nested TabList's indicator keeps its own default (hugging the
+              // tab) instead of floating down into the toolbar's padding.
+              hasBottomDivider &&
+                dynamicStyles.tabIndicatorBottom(
+                  `calc(-1 * (${blockPaddingVarForSize[size]} + 1px))`,
+                ),
             ),
           )}
           {...props}>