@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -226,3 +226,128 @@ describe('AvatarGroupOverflow — hardening', () => {
     expect(screen.getByLabelText('4912 more')).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

@@ -165,6 +165,7 @@ export function AvatarGroupOverflow({
         onClick={onClick}
         {...rest}
         aria-label={label}
+        data-avatar-item=""
         {...mergeProps(
           themeProps('avatar-group-overflow'),
           stylex.props(

package/src/Banner/Banner.doc.mjs

@@ -81,6 +81,13 @@ export const docs = {
         'Container type: card has border-radius; section is full-width with no border-radius for page-level use.',
       default: "'card'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. Use for a floating banner that hovers above content; `none` is the default inline banner. A `card`-container banner rounds its shadow to match.',
+      default: "'none'",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -157,6 +164,7 @@ export const docsZh = {
     {name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用；无论是否提供此回调，横幅都会自动隐藏。'},
     {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
     {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
     {name: 'defaultIsExpanded', type: 'boolean', description: '内容区域（children）是否初始展开。仅在提供 children 时相关。', default: 'false'},
     {
@@ -230,6 +238,7 @@ export const docsDense = {
     onDismiss: 'dismiss callback; banner self-hides regardless',
     endContent: 'end-aligned action in header, typically button/link',
     container: 'card=border-radius; section=full-width no radius for page-level',
+    elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
     children: 'content in card-bg area below colored header',
     xstyle: 'StyleX layout customization via stylex.create()',
   },

package/src/Banner/Banner.test.tsx

@@ -368,4 +368,34 @@ describe('Banner', () => {
     );
     expect(screen.getByTestId('custom-chevron')).toBeInTheDocument();
   });
+
+  describe('elevation', () => {
+    it('renders a distinct root class for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Banner status="info" title="Heads up" elevation={elevation} />,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <Banner status="info" title="Heads up" />,
+      );
+      const {container: none} = render(
+        <Banner status="info" title="Heads up" elevation="none" />,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });

package/src/Banner/Banner.tsx

@@ -46,8 +46,10 @@ import {
   borderVars,
   durationVars,
   easeVars,
+  shadowVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import type {Elevation} from '../utils/types';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -157,6 +159,13 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
    * @default 'card'
    */
   container?: BannerContainer;
+  /**
+   * Resting elevation — the shadow depth the banner sits at. Use for a
+   * floating banner that hovers above content. `none` is the default inline
+   * banner.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Whether the content area (children) starts expanded.
    * Only relevant when children are provided.
@@ -215,6 +224,11 @@ const styles = stylex.create({
     flexDirection: 'column',
     fontFamily: 'inherit',
   },
+  // When elevated, a card-container banner rounds its root so the shadow
+  // follows the same silhouette as the header/content border-radius.
+  rootElevatedCard: {
+    borderRadius: radiusVars['--radius-container'],
+  },
   // Header area — colored status background with icon, title, description, actions
   // This is the primary theme target ('banner')
   header: {
@@ -280,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: {
@@ -323,6 +337,18 @@ const statusStyles = stylex.create({
   },
 });
 
+// Resting elevation for the banner. Applied to the root so the shadow wraps
+// the whole banner (header + optional content). 'none' is the default and
+// leaves the layout-only root untouched. For the `card` container the root is
+// rounded (rootElevatedCard) so the shadow follows the card silhouette; the
+// full-width `section` container stays square.
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {boxShadow: shadowVars['--shadow-low']},
+  med: {boxShadow: shadowVars['--shadow-med']},
+  high: {boxShadow: shadowVars['--shadow-high']},
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -381,6 +407,7 @@ export function Banner({
   onDismiss,
   endContent,
   container = 'card',
+  elevation = 'none',
   defaultIsExpanded = false,
   children,
   xstyle,
@@ -429,7 +456,16 @@ export function Banner({
     <div
       ref={ref}
       role={role}
-      {...mergeProps(stylex.props(styles.root, xstyle), className, style)}
+      {...mergeProps(
+        stylex.props(
+          styles.root,
+          elevationStyles[elevation],
+          isCard && elevation !== 'none' && styles.rootElevatedCard,
+          xstyle,
+        ),
+        className,
+        style,
+      )}
       {...rest}>
       {/* Header: colored status background — primary theme target ('banner') */}
       <div
@@ -474,8 +510,16 @@ export function Banner({
               <Button
                 variant="ghost"
                 size="sm"
-                label={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
-                tooltip={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
+                label={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
+                tooltip={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
                 icon={
                   <span
                     {...stylex.props(

package/src/Breadcrumbs/BreadcrumbItem.doc.mjs

@@ -45,6 +45,18 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'menu',
+      type: 'DropdownMenuOption[] | ReactNode',
+      description:
+        'Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.',
+    },
+    {
+      name: 'menuSize',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        "Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').",
+    },
     {
       name: 'as',
       type: 'LinkComponentType',
@@ -86,6 +98,18 @@ export const docsZh = {
       type: 'ReactNode',
       description: '在项目标签前渲染的图标。',
     },
+    {
+      name: 'menu',
+      type: 'DropdownMenuOption[] | ReactNode',
+      description:
+        '激活项目时打开的菜单，使用与 DropdownMenu/MoreMenu/ContextMenu 相同的项目 API（DropdownMenuOption[] 数组或组合的 DropdownMenuItem 子元素）。渲染为带 chevron 和 aria-haspopup="menu" 的链接样式触发器。优先于 href/onClick。',
+    },
+    {
+      name: 'menuSize',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        "传递给菜单项的尺寸。默认根据面包屑变体推断（'supporting' → 'sm'，否则 'md'）。",
+    },
     {
       name: 'as',
       type: 'LinkComponentType',
@@ -105,6 +129,8 @@ export const docsDense = {
     onClick: 'click handler',
     isCurrent: 'marks current page w/ aria-current="page"',
     startIcon: 'icon before label',
+    menu: 'DropdownMenuOption[] | children; opens a menu trigger (aria-haspopup="menu"); reuses the DropdownMenu item API',
+    menuSize: "menu item size; defaults from variant (supporting→sm, else md)",
     as: 'custom link component; overrides LinkProvider default',
   },
 };