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

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -1,10 +1,17 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Breadcrumbs} from './Breadcrumbs';
 import {BreadcrumbItem} from './BreadcrumbItem';
+import {
+  BreadcrumbMenuItem,
+  BreadcrumbMenuCheckboxItem,
+  BreadcrumbMenuRadioGroup,
+  BreadcrumbMenuRadioItem,
+} from './index';
+import type {BreadcrumbMenuOption} from './index';
 import {LinkProvider} from '../Link/LinkProvider';
 
 function CustomLink({
@@ -359,3 +366,329 @@ describe('BreadcrumbItem', () => {
     expect(current.tagName).toBe('SPAN');
   });
 });
+
+describe('BreadcrumbItem menu', () => {
+  // Mock the native Popover API — jsdom doesn't implement showPopover/
+  // hidePopover or the :popover-open match. Mirrors DropdownMenu's test setup.
+  beforeEach(() => {
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('popover-open', '');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'open'});
+      this.dispatchEvent(event);
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('popover-open');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'closed'});
+      this.dispatchEvent(event);
+    });
+    const originalMatches = HTMLElement.prototype.matches;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = function (
+      selector: string,
+    ): boolean {
+      if (selector === ':popover-open') {
+        return this.hasAttribute('popover-open');
+      }
+      return originalMatches.call(this, selector);
+    };
+  });
+
+  const items: BreadcrumbMenuOption[] = [
+    {label: 'Design', onClick: vi.fn()},
+    {label: 'Engineering', onClick: vi.fn()},
+    {type: 'divider'},
+    {label: 'Data', onClick: vi.fn()},
+  ];
+
+  it('renders as a menu trigger button with aria-haspopup="menu"', () => {
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Teams'});
+    expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('portability: a DropdownMenuOption[] renders its items on open', async () => {
+    const user = userEvent.setup();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Teams'}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    expect(menu).toHaveAttribute('aria-label', 'Teams');
+    expect(
+      screen.getByRole('menuitem', {name: 'Design', hidden: true}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('menuitem', {name: 'Engineering', hidden: true}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('menuitem', {name: 'Data', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('fires the item onClick and closes the menu on select', async () => {
+    const user = userEvent.setup();
+    const onDesign = vi.fn();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem menu={[{label: 'Design', onClick: onDesign}]}>
+          Teams
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Teams'}));
+    await user.click(
+      screen.getByRole('menuitem', {name: 'Design', hidden: true}),
+    );
+    expect(onDesign).toHaveBeenCalledTimes(1);
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+  });
+
+  it('supports the composed children form', async () => {
+    const user = userEvent.setup();
+    const onOverview = vi.fn();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={
+            <>
+              <BreadcrumbMenuItem label="Overview" onClick={onOverview} />
+              <BreadcrumbMenuItem label="Settings" />
+            </>
+          }>
+          Project
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Project'}));
+    expect(
+      screen.getByRole('menuitem', {name: 'Overview', hidden: true}),
+    ).toBeInTheDocument();
+    await user.click(
+      screen.getByRole('menuitem', {name: 'Overview', hidden: true}),
+    );
+    expect(onOverview).toHaveBeenCalledTimes(1);
+  });
+
+  it('supports a selectable checkbox item', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={
+            <BreadcrumbMenuCheckboxItem
+              label="Show archived"
+              value={false}
+              onChange={onChange}
+            />
+          }>
+          Filters
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Filters'}));
+    const checkbox = screen.getByRole('menuitemcheckbox', {
+      name: 'Show archived',
+      hidden: true,
+    });
+    expect(checkbox).toHaveAttribute('aria-checked', 'false');
+    await user.click(checkbox);
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
+  it('supports a selectable radio group', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={
+            <BreadcrumbMenuRadioGroup
+              aria-label="Sort by"
+              value="name"
+              onChange={onChange}>
+              <BreadcrumbMenuRadioItem value="name" label="Name" />
+              <BreadcrumbMenuRadioItem value="date" label="Date" />
+            </BreadcrumbMenuRadioGroup>
+          }>
+          Sort
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Sort'}));
+    const nameOption = screen.getByRole('menuitemradio', {
+      name: 'Name',
+      hidden: true,
+    });
+    expect(nameOption).toHaveAttribute('aria-checked', 'true');
+    await user.click(
+      screen.getByRole('menuitemradio', {name: 'Date', hidden: true}),
+    );
+    expect(onChange).toHaveBeenCalledWith('date');
+  });
+
+  it('opens with ArrowDown and closes with Escape, returning focus to trigger', async () => {
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Teams'});
+    trigger.focus();
+    fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => {
+      expect(menu).toContainElement(
+        document.activeElement as HTMLElement | null,
+      );
+    });
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+    await waitFor(() => {
+      expect(trigger).toHaveFocus();
+    });
+  });
+
+  it('roves focus with ArrowDown across items', async () => {
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Teams'});
+    trigger.focus();
+    fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => {
+      expect(
+        screen.getByRole('menuitem', {name: 'Design', hidden: true}),
+      ).toHaveFocus();
+    });
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Engineering', hidden: true}),
+    ).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>
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem isCurrent menu={items}>
+          Teams
+        </BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Teams'});
+    expect(trigger).toHaveAttribute('aria-current', 'page');
+    expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
+  });
+
+  it('warns and lets menu win when href is also provided', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem href="/teams" menu={items}>
+          Teams
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    // menu wins: it's a button trigger, not a link.
+    expect(screen.getByRole('button', {name: 'Teams'})).toHaveAttribute(
+      'aria-haspopup',
+      'menu',
+    );
+    expect(screen.queryByRole('link', {name: 'Teams'})).not.toBeInTheDocument();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('`menu` and `href` are mutually exclusive'),
+    );
+    warn.mockRestore();
+  });
+
+  it('keeps mid-trail separators intact around a menu crumb', () => {
+    const {container} = render(
+      <Breadcrumbs>
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    // One separator per item (first hidden via CSS); the menu crumb does not
+    // add or drop any.
+    const separators = container.querySelectorAll(
+      'ol > li > span[aria-hidden="true"]',
+    );
+    expect(separators).toHaveLength(3);
+  });
+});

package/src/Breadcrumbs/index.ts

@@ -14,3 +14,34 @@ export type {
 } from './Breadcrumbs';
 export {BreadcrumbItem} from './BreadcrumbItem';
 export type {BreadcrumbItemProps} from './BreadcrumbItem';
+
+// The breadcrumb `menu` prop reuses the DropdownMenu item API, so the item
+// components are re-exported under `Breadcrumb*` aliases for family coherence
+// and discoverability (mirroring ContextMenu). A consumer's existing
+// DropdownMenu item definitions are portable into a breadcrumb menu verbatim.
+export {
+  DropdownMenuItem as BreadcrumbMenuItem,
+  type DropdownMenuItemProps as BreadcrumbMenuItemProps,
+} from '../DropdownMenu/DropdownMenuItem';
+export {
+  DropdownMenuCheckboxItem as BreadcrumbMenuCheckboxItem,
+  type DropdownMenuCheckboxItemProps as BreadcrumbMenuCheckboxItemProps,
+} from '../DropdownMenu/DropdownMenuCheckboxItem';
+export {
+  DropdownMenuRadioGroup as BreadcrumbMenuRadioGroup,
+  type DropdownMenuRadioGroupProps as BreadcrumbMenuRadioGroupProps,
+} from '../DropdownMenu/DropdownMenuRadioGroup';
+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,
+  DropdownMenuDivider as BreadcrumbMenuDivider,
+  DropdownMenuSection as BreadcrumbMenuSection,
+} from '../DropdownMenu/DropdownMenu';

package/src/Button/Button.doc.mjs

@@ -51,6 +51,13 @@ export const docs = {
       description: 'Size variant.',
       default: "'md'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth for floating buttons (e.g. a FAB). `none` is the default flat button; `low`/`med`/`high` map to the shadow token scale. Ignored inside a ButtonGroup, where elevation is owned by the group.',
+      default: "'none'",
+    },
     {
       name: 'type',
       type: "'button' | 'submit' | 'reset'",
@@ -156,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'},
     ],
@@ -199,6 +204,7 @@ export const docsZh = {
       default: "'secondary'",
     },
     {name: 'size', type: "'sm' | 'md' | 'lg'", description: '尺寸变体。', default: "'md'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '浮动按钮（如 FAB）的静止阴影深度。`none` 为默认扁平按钮；在 ButtonGroup 内忽略。', default: "'none'"},
     {name: 'type', type: "'button' | 'submit' | 'reset'", description: 'HTML 按钮类型属性。', default: "'button'"},
     {name: 'name', type: 'string', description: '表单提交的 HTML name 属性。'},
     {name: 'value', type: 'string | number | readonly string[]', description: '表单提交的 HTML value 属性。'},
@@ -239,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'},
     ],
@@ -271,6 +275,7 @@ export const docsDense = {
     label: 'accessible label; visible text by default, aria-label when isIconOnly',
     variant: 'visual style variant',
     size: 'size variant',
+    elevation: 'resting shadow depth for floating buttons/FABs: none|low|med|high; ignored inside ButtonGroup',
     type: 'HTML button type; defaults to "button"',
     name: 'HTML name for form submission',
     displayName: 'HTML name for form submission',

package/src/Button/Button.test.tsx

@@ -445,4 +445,53 @@ describe('Button', () => {
     rerender(<Button label="Submit" isLoading />);
     expect(liveRegion).toHaveTextContent('Loading');
   });
+
+  describe('elevation', () => {
+    it('renders a distinct class for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Button label="Save" elevation={elevation} />,
+        );
+        return container.querySelector('button')!.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(<Button label="Save" />);
+      const {container: none} = render(
+        <Button label="Save" elevation="none" />,
+      );
+      expect(def.querySelector('button')!.className).toBe(
+        none.querySelector('button')!.className,
+      );
+    });
+  });
+
+  it('exposes aria-busy on the link-rendered button while loading', () => {
+    // Non-interruptible loading disables the button, which falls back to
+    // <button> rendering — so an anchor only shows loading when interruptible.
+    render(
+      <Button
+        label="Docs"
+        href="https://example.com"
+        isLoading
+        isInterruptible
+      />,
+    );
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('aria-busy', 'true');
+  });
+
+  it('does not set aria-busy on the link-rendered button when not loading', () => {
+    render(<Button label="Docs" href="https://example.com" />);
+    const link = screen.getByRole('link');
+    expect(link).not.toHaveAttribute('aria-busy');
+  });
 });

package/src/Button/Button.tsx

@@ -20,7 +20,7 @@
 
 import {useRef, useTransition, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
-import type {SizeValue} from '../utils/types';
+import type {Elevation, SizeValue} from '../utils/types';
 import * as stylex from '@stylexjs/stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {
@@ -33,6 +33,7 @@ import {
   easeVars,
   fontWeightVars,
   typeScaleVars,
+  shadowVars,
 } from '../theme/tokens.stylex';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -160,6 +161,18 @@ const iconSizeStyles = stylex.create({
   lg: {width: 20, height: 20, fontSize: 20},
 });
 
+/**
+ * Resting elevation for floating buttons (e.g. a FAB). `none` is the default
+ * flat button; `low`/`med`/`high` map to the shadow token scale. 'none' stays
+ * a literal so it never conflicts with a variant's background layering.
+ */
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {boxShadow: shadowVars['--shadow-low']},
+  med: {boxShadow: shadowVars['--shadow-med']},
+  high: {boxShadow: shadowVars['--shadow-high']},
+});
+
 /**
  * Variant styles using backgroundImage for layered colors
  * Pseudo-classes are nested within properties per StyleX recommendation
@@ -307,6 +320,12 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
    * @default 'md'
    */
   size?: ButtonSize;
+  /**
+   * Resting elevation — the shadow depth the button sits at. Use for floating
+   * buttons (FABs) that hover above content. `none` is the default flat button.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Whether the button is disabled.
    * @default false
@@ -430,8 +449,8 @@ const loadingStyles = stylex.create({
   spinnerOverlay: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     bottom: 0,
     display: 'grid',
     placeItems: 'center',
@@ -578,6 +597,7 @@ export function Button({
   icon,
   isIconOnly = false,
   width,
+  elevation = 'none',
   children,
   endContent,
   tooltip,
@@ -691,6 +711,9 @@ export function Button({
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.onSolidHorizontal
         : groupStyles.onSolidVertical),
+    // Standalone floating buttons only — a grouped button's elevation is owned
+    // by the ButtonGroup so the shared surface lifts as one unit.
+    !buttonGroup && elevationStyles[elevation],
     width != null && dynamicStyles.width(width),
     xstyle,
   );
@@ -786,6 +809,7 @@ export function Button({
         {...ariaLabelProp}
         {...describedByProp}
         {...edgeCompAttr}
+        aria-busy={isLoadingState || undefined}
         onClick={handleClick}>
         {buttonContent}
       </LinkComponent>

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -29,6 +29,7 @@ export const docs = {
         {name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},
         {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},
         {name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},
+        {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth for the whole group. The connected buttons share one surface, so the shadow lifts them as a unit. Use for a group that floats above content.', default: "'none'"},
         {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
         {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
         {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
@@ -66,6 +67,7 @@ export const docsZh = {
         orientation: '按钮组的布局方向。',
         size: '组内按钮的默认尺寸。单个按钮可覆盖。',
         isDisabled: '组内所有按钮是否禁用。',
+        elevation: '整个组的静止阴影深度。连接的按钮共享一个表面，阴影将它们作为整体抬起。',
         ref: '转发到根元素的引用。',
         xstyle: 'StyleX 样式，用于布局自定义。必须是 stylex.create() 的值。',
         'data-testid': '自动化测试的选择器。',
@@ -116,6 +118,7 @@ export const docsDense = {
         orientation: 'layout direction',
         size: 'default btn size; individual btns override',
         isDisabled: 'all btns disabled',
+        elevation: 'resting shadow depth for whole group: none|low|med|high',
         xstyle: 'StyleX layout styles; must be stylex.create() value',
         'data-testid': 'test selector',
       },

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -572,4 +572,41 @@ describe('ButtonGroup', () => {
       expect(hasRoundedTrailingCorners(save)).toBe(false);
     });
   });
+
+  describe('elevation', () => {
+    it('renders a distinct class on the group for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <ButtonGroup label="Actions" elevation={elevation}>
+            <Button label="One" />
+            <Button label="Two" />
+          </ButtonGroup>,
+        );
+        return container.querySelector('[role="group"]')!.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(
+        <ButtonGroup label="Actions">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+      const {container: none} = render(
+        <ButtonGroup label="Actions" elevation="none">
+          <Button label="One" />
+        </ButtonGroup>,
+      );
+      expect(def.querySelector('[role="group"]')!.className).toBe(
+        none.querySelector('[role="group"]')!.className,
+      );
+    });
+  });
 });