@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -4,7 +4,8 @@ import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {AvatarGroup} from './AvatarGroup';
 import {AvatarGroupOverflow} from './AvatarGroupOverflow';
-import {Avatar} from '../Avatar';
+import {Avatar, AvatarStatusDot} from '../Avatar';
+import {InternationalizationProvider} from '../i18n';
 
 describe('AvatarGroup', () => {
   it('renders all avatar children', () => {
@@ -21,6 +22,21 @@ describe('AvatarGroup', () => {
     expect(screen.getByLabelText('Charlie')).toBeInTheDocument();
   });
 
+  it('composes a labelled status into a grouped avatar accessible name (WCAG 4.1.2)', () => {
+    render(
+      <AvatarGroup>
+        <Avatar
+          name="Alice"
+          status={<AvatarStatusDot variant="success" label="Online" />}
+        />
+        <Avatar name="Bob" />
+      </AvatarGroup>,
+    );
+
+    expect(screen.getByLabelText('Alice, Online')).toBeInTheDocument();
+    expect(screen.getByLabelText('Bob')).toBeInTheDocument();
+  });
+
   it('renders with role="group" and default aria-label', () => {
     render(
       <AvatarGroup>
@@ -223,6 +239,150 @@ describe('AvatarGroupOverflow — hardening', () => {
     );
 
     expect(screen.getByText('+4912')).toBeInTheDocument();
-    expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+    // The aria-label routes through the catalog's `{count, number}` ICU
+    // argument, so the en locale adds a grouping separator.
+    expect(screen.getByLabelText('4,912 more')).toBeInTheDocument();
+  });
+
+  it('localizes the overflow label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.avatarGroup.overflow': '{count, number} de plus'},
+        }}>
+        <AvatarGroup>
+          <Avatar name="Alice" />
+          <AvatarGroupOverflow count={3} />
+        </AvatarGroup>
+      </InternationalizationProvider>,
+    );
+
+    expect(screen.getByLabelText('3 de plus')).toBeInTheDocument();
+  });
+});
+
+describe('AvatarGroup — roving focus + keyboard hint', () => {
+  it('is a single tab stop over interactive avatars (one tabindex=0, rest -1)', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" href="/alice" />
+        <Avatar name="Bob" href="/bob" />
+        <Avatar name="Charlie" href="/charlie" />
+      </AvatarGroup>,
+    );
+
+    const alice = screen.getByRole('link', {name: 'Alice'});
+    const bob = screen.getByRole('link', {name: 'Bob'});
+    const charlie = screen.getByRole('link', {name: 'Charlie'});
+
+    expect(alice).toHaveAttribute('tabindex', '0');
+    expect(bob).toHaveAttribute('tabindex', '-1');
+    expect(charlie).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('roves focus with ArrowRight/ArrowLeft across interactive avatars', async () => {
+    const user = userEvent.setup();
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" href="/alice" />
+        <Avatar name="Bob" onClick={() => {}} />
+        <Avatar name="Charlie" href="/charlie" />
+      </AvatarGroup>,
+    );
+
+    const alice = screen.getByRole('link', {name: 'Alice'});
+    const bob = screen.getByRole('button', {name: 'Bob'});
+    const charlie = screen.getByRole('link', {name: 'Charlie'});
+
+    alice.focus();
+    expect(alice).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(bob).toHaveFocus();
+    expect(bob).toHaveAttribute('tabindex', '0');
+    expect(alice).toHaveAttribute('tabindex', '-1');
+
+    await user.keyboard('{ArrowRight}');
+    expect(charlie).toHaveFocus();
+
+    await user.keyboard('{ArrowLeft}');
+    expect(bob).toHaveFocus();
+  });
+
+  it('includes the overflow button as the last roving item', async () => {
+    const user = userEvent.setup();
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" href="/alice" />
+        <AvatarGroupOverflow count={3} onClick={() => {}} />
+      </AvatarGroup>,
+    );
+
+    const alice = screen.getByRole('link', {name: 'Alice'});
+    const overflow = screen.getByRole('button', {name: '3 more'});
+    expect(overflow).toHaveAttribute('data-avatar-item');
+
+    alice.focus();
+    await user.keyboard('{ArrowRight}');
+    expect(overflow).toHaveFocus();
+  });
+
+  it('does NOT rove over a non-avatar button in a status slot', async () => {
+    const user = userEvent.setup();
+    render(
+      <AvatarGroup>
+        <Avatar
+          name="Alice"
+          href="/alice"
+          status={<button type="button">badge</button>}
+        />
+        <Avatar name="Bob" href="/bob" />
+      </AvatarGroup>,
+    );
+
+    const alice = screen.getByRole('link', {name: 'Alice'});
+    const bob = screen.getByRole('link', {name: 'Bob'});
+    const statusButton = screen.getByRole('button', {name: 'badge'});
+
+    // The status button carries no data-avatar-item marker.
+    expect(statusButton).not.toHaveAttribute('data-avatar-item');
+
+    alice.focus();
+    await user.keyboard('{ArrowRight}');
+    // Arrow moves to the next avatar, skipping the nested status button.
+    expect(bob).toHaveFocus();
+    expect(statusButton).not.toHaveFocus();
+  });
+
+  it('attaches an aria-describedby keyboard hint when interactive children exist', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" href="/alice" />
+        <Avatar name="Bob" href="/bob" />
+      </AvatarGroup>,
+    );
+
+    const group = screen.getByRole('group');
+    const describedBy = group.getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+    const hint = document.getElementById(describedBy!);
+    expect(hint).not.toBeNull();
+    expect(hint).toHaveTextContent('Use arrow keys to move between avatars');
+  });
+
+  it('a purely static group has no tab stop and no keyboard hint', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" data-testid="alice" />
+        <Avatar name="Bob" data-testid="bob" />
+      </AvatarGroup>,
+    );
+
+    const group = screen.getByRole('group');
+    expect(group).not.toHaveAttribute('aria-describedby');
+    // Static avatars are not focusable — no roving tabindex stamped.
+    expect(screen.getByTestId('alice')).not.toHaveAttribute('tabindex');
+    expect(screen.getByTestId('bob')).not.toHaveAttribute('tabindex');
   });
 });

package/src/AvatarGroup/AvatarGroup.tsx

@@ -11,6 +11,12 @@
  * one AvatarGroupOverflow). The group provides overlap styling via
  * context — no child introspection needed.
  *
+ * When the group contains interactive avatars (rendered as links/buttons) or an
+ * interactive AvatarGroupOverflow, it becomes a single Tab stop with roving
+ * arrow-key focus (via useListFocus with hasRovingTabIndex) and exposes a
+ * screen-reader keyboard hint via aria-describedby. A purely static facepile
+ * gets neither — it stays a plain non-focusable group.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AvatarGroup/AvatarGroup.doc.mjs (props table, features)
  * - /packages/core/src/AvatarGroup/index.ts (exports if types change)
@@ -18,14 +24,18 @@
  * - /packages/cli/templates/blocks/components/AvatarGroup/ (showcase blocks)
  */
 
-import {useMemo, type ReactNode} from 'react';
+import {useId, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import {resolveSize, type AvatarSize} from '../Avatar';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
+import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {AvatarGroupContext} from './AvatarGroupContext';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {useListFocus} from '../hooks/useListFocus';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 const OVERLAP_RATIO = 0.25;
 
@@ -78,6 +88,9 @@ export function AvatarGroup({
   size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
+  'aria-describedby': ariaDescribedByFromProps,
+  onKeyDown,
+  onFocus,
   xstyle,
   className,
   style,
@@ -94,14 +107,51 @@ export function AvatarGroup({
     [size, overlap, numericSize],
   );
 
+  // The keyboard hint and roving tab stop only make sense once the group has
+  // interactive children. Detect their presence (and the writing direction for
+  // RTL-correct arrow navigation) from the rendered DOM after commit, matching
+  // how the codebase reads direction elsewhere (`getComputedStyle(el).direction`).
+  const [hasInteractiveItems, setHasInteractiveItems] = useState(false);
+  const [isRtl, setIsRtl] = useState(false);
+
+  // Single tab stop + roving arrow focus over the group's interactive items.
+  // `itemSelector` targets the shared `[data-avatar-item]` marker stamped on
+  // interactive avatars (their rendered <a>/<button>) and on the overflow
+  // button — NOT a tag/role selector — so roving never catches a nested button
+  // inside a custom status/badge slot (O5).
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: '[data-avatar-item]',
+    orientation: 'horizontal',
+    hasRovingTabIndex: true,
+    isRtl,
+  });
+
+  useIsomorphicLayoutEffect(() => {
+    const root = listRef.current;
+    if (!root) {
+      return;
+    }
+    setHasInteractiveItems(root.querySelector('[data-avatar-item]') != null);
+    setIsRtl(getComputedStyle(root).direction === 'rtl');
+  });
+
+  const hintId = useId();
+  const describedBy =
+    [ariaDescribedByFromProps, hasInteractiveItems ? hintId : null]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
   return (
     <AvatarGroupContext value={contextValue}>
       <div
         {...props}
-        ref={ref}
+        ref={mergeRefs(ref, listRef)}
         role="group"
         aria-label={ariaLabel}
+        aria-describedby={describedBy}
         data-testid={testId}
+        onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
+        onFocus={composeEventHandlers(onFocus, handleFocus)}
         {...mergeProps(
           themeProps('avatar-group', {size}),
           stylex.props(styles.root, xstyle),
@@ -109,6 +159,11 @@ export function AvatarGroup({
           style,
         )}>
         {children}
+        {hasInteractiveItems && (
+          <VisuallyHidden id={hintId}>
+            {t('@astryx.avatarGroup.keyboardHint')}
+          </VisuallyHidden>
+        )}
       </div>
     </AvatarGroupContext>
   );

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -3,7 +3,7 @@
 
 /**
  * @file AvatarGroupOverflow.tsx
- * @input Uses React, StyleX, AvatarGroupContext
+ * @input Uses React, StyleX, AvatarGroupContext, i18n (useTranslator)
  * @output Exports AvatarGroupOverflow for overflow indicator
  * @position Slot component used inside AvatarGroup
  *
@@ -26,6 +26,7 @@ import {mergeProps} from '../utils';
 import {useAvatarGroup} from './AvatarGroupContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const BORDER_WIDTH = 2;
 const OVERFLOW_FONT_RATIO = 0.35;
@@ -150,11 +151,12 @@ export function AvatarGroupOverflow({
   style,
   ...rest
 }: AvatarGroupOverflowProps): ReactNode {
+  const t = useTranslator();
   const group = useAvatarGroup();
   const numericSize = group?.numericSize ?? 36;
   const overlap = group?.overlap ?? 0;
 
-  const label = `${count} more`;
+  const label = t('@astryx.avatarGroup.overflow', {count});
   const content = children ?? `+${count}`;
 
   if (onClick) {
@@ -165,6 +167,7 @@ export function AvatarGroupOverflow({
         onClick={onClick}
         {...rest}
         aria-label={label}
+        data-avatar-item=""
         {...mergeProps(
           themeProps('avatar-group-overflow'),
           stylex.props(

package/src/Banner/Banner.tsx

@@ -294,14 +294,14 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-background-card'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-4'],
-    borderLeftWidth: borderVars['--border-width'],
-    borderRightWidth: borderVars['--border-width'],
+    borderInlineStartWidth: borderVars['--border-width'],
+    borderInlineEndWidth: borderVars['--border-width'],
     borderBottomWidth: borderVars['--border-width'],
-    borderLeftStyle: 'solid',
-    borderRightStyle: 'solid',
+    borderInlineStartStyle: 'solid',
+    borderInlineEndStyle: 'solid',
     borderBottomStyle: 'solid',
-    borderLeftColor: colorVars['--color-border'],
-    borderRightColor: colorVars['--color-border'],
+    borderInlineStartColor: colorVars['--color-border'],
+    borderInlineEndColor: colorVars['--color-border'],
     borderBottomColor: colorVars['--color-border'],
   },
   contentAreaCard: {

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -59,6 +59,7 @@ import {
 import {
   MENU_ITEM_ROLES,
   MENU_ITEM_SELECTOR,
+  MENU_BOUNDARY_SELECTOR,
 } from '../DropdownMenu/menuItemRoles';
 import type {DropdownMenuOption} from '../DropdownMenu/DropdownMenu';
 
@@ -515,21 +516,15 @@ function BreadcrumbMenuTrigger({
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
+    ownsEvent,
+    getItems: getMenuItems,
   } = useListFocus<HTMLDivElement>({
     itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
     wrap: false,
     onEscape: closeMenu,
   });
 
-  const getMenuItems = useCallback(
-    (): HTMLElement[] =>
-      listRef.current
-        ? Array.from(
-            listRef.current.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-          )
-        : [],
-    [listRef],
-  );
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -542,6 +537,11 @@ function BreadcrumbMenuTrigger({
 
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // A submenu flyout renders inline inside this menu; its key events bubble
+      // up here. Let that level own them — only handle events from this level.
+      if (!ownsEvent(e)) {
+        return;
+      }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
@@ -564,7 +564,7 @@ function BreadcrumbMenuTrigger({
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, closeMenu, typeahead],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   const openAndFocus = useCallback(() => {

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -519,7 +519,7 @@ describe('BreadcrumbItem menu', () => {
         <BreadcrumbItem
           menu={
             <BreadcrumbMenuRadioGroup
-              aria-label="Sort by"
+              label="Sort by"
               value="name"
               onChange={onChange}>
               <BreadcrumbMenuRadioItem value="name" label="Name" />
@@ -589,6 +589,57 @@ describe('BreadcrumbItem menu', () => {
     ).toHaveFocus();
   });
 
+  it('renders a submenu from a nested items array and keyboard-reaches an item after it', async () => {
+    // Breadcrumb menus reuse the DropdownMenu item pipeline, so a nested
+    // `items` array becomes a submenu. The inline flyout must not pollute the
+    // breadcrumb menu's roving order — an item after the submenu row stays
+    // keyboard-reachable.
+    const onDelete = vi.fn();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={[
+            {label: 'Rename', onClick: vi.fn()},
+            {
+              label: 'Move to',
+              items: [
+                {label: 'Folder A', onClick: vi.fn()},
+                {label: 'Folder B', onClick: vi.fn()},
+              ],
+            },
+            {type: 'divider'},
+            {label: 'Delete', onClick: onDelete},
+          ]}>
+          Teams
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Teams'});
+    trigger.focus();
+    fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+    // Two role="menu" exist (the breadcrumb menu + the inline submenu flyout);
+    // the breadcrumb menu is the first in DOM order.
+    const menu = screen.getAllByRole('menu', {hidden: true})[0];
+    const submenuTrigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    expect(submenuTrigger).toHaveAttribute('aria-haspopup', 'menu');
+    await waitFor(() => {
+      expect(
+        screen.getByRole('menuitem', {name: 'Rename', hidden: true}),
+      ).toHaveFocus();
+    });
+    // Rename → Move to → Delete, one step per press.
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(submenuTrigger).toHaveFocus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveFocus();
+  });
+
   it('allows menu together with isCurrent (both aria-current and aria-haspopup)', () => {
     render(
       <Breadcrumbs>

package/src/Breadcrumbs/index.ts

@@ -35,6 +35,10 @@ export {
   DropdownMenuRadioItem as BreadcrumbMenuRadioItem,
   type DropdownMenuRadioItemProps as BreadcrumbMenuRadioItemProps,
 } from '../DropdownMenu/DropdownMenuRadioItem';
+export {
+  DropdownMenuSubMenu as BreadcrumbMenuSubMenu,
+  type DropdownMenuSubMenuProps as BreadcrumbMenuSubMenuProps,
+} from '../DropdownMenu/DropdownMenuSubMenu';
 export type {
   DropdownMenuOption as BreadcrumbMenuOption,
   DropdownMenuItemData as BreadcrumbMenuItemData,

package/src/Button/Button.doc.mjs

@@ -163,8 +163,6 @@ export const docs = {
     ],
     vars: [
       {name: '--_button-radius', description: 'Border radius', default: 'var(--radius-element)', private: true},
-      {name: '--button-press-scale', description: 'Active press transform', default: 'scale(0.98)'},
-      {name: '--button-disabled-opacity', description: 'Opacity when disabled', default: '0.5'},
       {name: '--button-focus-offset', description: 'Focus ring outline offset', default: '3px'},
       {name: '--button-icon-only-aspect', description: 'Aspect ratio for icon-only buttons', default: '1 / 1'},
     ],
@@ -247,8 +245,6 @@ export const docsZh = {
     ],
     vars: [
       {name: '--_button-radius', description: '圆角半径', default: 'var(--radius-element)', private: true},
-      {name: '--button-press-scale', description: '按下时的变换', default: 'scale(0.98)'},
-      {name: '--button-disabled-opacity', description: '禁用时的不透明度', default: '0.5'},
       {name: '--button-focus-offset', description: '焦点环轮廓偏移', default: '3px'},
       {name: '--button-icon-only-aspect', description: '纯图标按钮的宽高比', default: '1 / 1'},
     ],

package/src/Button/Button.test.tsx

@@ -14,6 +14,7 @@ import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import {Badge} from '../Badge/Badge';
+import {InternationalizationProvider} from '../i18n';
 
 describe('Button', () => {
   it('renders label as visible text', () => {
@@ -446,6 +447,21 @@ describe('Button', () => {
     expect(liveRegion).toHaveTextContent('Loading');
   });
 
+  it('localizes the loading announcement through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.button.loading': 'Chargement'}}}>
+        <Button label="Submit" isLoading />
+      </InternationalizationProvider>,
+    );
+    const button = screen.getByRole('button');
+    // The Spinner also has role="status", so grab the live region explicitly.
+    const regions = button.querySelectorAll('[role="status"]');
+    const liveRegion = regions[regions.length - 1];
+    expect(liveRegion).toHaveTextContent('Chargement');
+  });
+
   describe('elevation', () => {
     it('renders a distinct class for each elevation level', () => {
       const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {

package/src/Button/Button.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Button.tsx
- * @input Uses React, ButtonHTMLAttributes, ReactNode
+ * @input Uses React, ButtonHTMLAttributes, ReactNode, i18n (useTranslator)
  * @output Exports Button component, ButtonProps, ButtonVariant types
  * @position Core implementation; consumed by index.ts, tested by Button.test.tsx
  *
@@ -45,6 +45,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 /**
  * Base button styles
@@ -449,8 +450,8 @@ const loadingStyles = stylex.create({
   spinnerOverlay: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     bottom: 0,
     display: 'grid',
     placeItems: 'center',
@@ -611,6 +612,7 @@ export function Button({
   ref,
   ...props
 }: ButtonProps): ReactNode {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
 
@@ -760,7 +762,7 @@ export function Button({
       </span>
       {/* Live region for loading state announcements */}
       <VisuallyHidden role="status" aria-live="polite">
-        {isLoadingState ? 'Loading' : ''}
+        {isLoadingState ? t('@astryx.button.loading') : ''}
       </VisuallyHidden>
     </>
   );