@astryxdesign/core 0.5.0 → 0.5.1-canary.70169cd

package/src/AlertDialog/AlertDialog.test.tsx

@@ -9,12 +9,65 @@
  * SYNC: When AlertDialog.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {AlertDialog} from './AlertDialog';
 import {useImperativeAlertDialog} from './useImperativeAlertDialog';
 
+function stubAlertDialogMedia({
+  smallScreen,
+  coarsePointer,
+  noHover,
+  reduceMotion = false,
+}: {
+  smallScreen: boolean;
+  coarsePointer: boolean;
+  noHover: boolean;
+  reduceMotion?: boolean;
+}): void {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => {
+      let matches = false;
+      if (query.includes('max-width: 640px')) {
+        matches = smallScreen;
+      } else if (query.includes('pointer: coarse')) {
+        matches = coarsePointer;
+      } else if (query.includes('pointer: fine')) {
+        matches = !coarsePointer;
+      } else if (query.includes('hover: none')) {
+        matches = noHover;
+      } else if (query.includes('hover: hover')) {
+        matches = !noHover;
+      } else if (query.includes('prefers-reduced-motion: reduce')) {
+        matches = reduceMotion;
+      } else if (query.includes('prefers-reduced-motion: no-preference')) {
+        matches = !reduceMotion;
+      } else if (query.includes('prefers-reduced-motion')) {
+        matches = reduceMotion;
+      }
+
+      return {
+        matches,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      };
+    }),
+  );
+}
+
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
     this: HTMLDialogElement,
@@ -26,6 +79,10 @@ beforeEach(() => {
   });
 });
 
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
 describe('AlertDialog', () => {
   const defaultProps = {
     isOpen: true,
@@ -109,6 +166,158 @@ describe('AlertDialog', () => {
     expect(screen.getByRole('alertdialog')).toBeInTheDocument();
   });
 
+  describe('responsive actions', () => {
+    const longCancelLabel = 'Keep this workspace and all of its dashboards';
+    const longActionLabel =
+      'Permanently delete this workspace and all dashboards';
+
+    it('preserves the preferred width and horizontal order above the small breakpoint', () => {
+      stubAlertDialogMedia({
+        smallScreen: false,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(<AlertDialog {...defaultProps} />);
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(dialog.getAttribute('style')).toContain(
+        '--x-maxWidth: min(100%, calc(100dvw - var(--spacing-4) - var(--spacing-4)))',
+      );
+      expect(buttons.map(button => button.textContent)).toEqual([
+        'Cancel',
+        'Delete',
+      ]);
+      expect(getComputedStyle(footerStack).flexWrap).toBe('wrap');
+    });
+
+    it('keeps long action buttons within the wide horizontal footer without changing Button sizing', () => {
+      stubAlertDialogMedia({
+        smallScreen: false,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(buttons.map(button => button.textContent)).toEqual([
+        longCancelLabel,
+        longActionLabel,
+      ]);
+      expect(getComputedStyle(footerStack).flexWrap).toBe('wrap');
+      for (const button of buttons) {
+        const computed = getComputedStyle(button);
+        expect(computed.whiteSpace).toBe('nowrap');
+        expect(computed.height).toBe('var(--size-element-md)');
+        expect(computed.maxWidth).toBe('100%');
+      }
+    });
+
+    it('stacks long destructive action labels above cancel on a narrow fine-pointer screen', () => {
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(buttons.map(button => button.textContent)).toEqual([
+        longActionLabel,
+        longCancelLabel,
+      ]);
+      expect(getComputedStyle(footerStack).flexDirection).toBe('column');
+      for (const button of buttons) {
+        const computed = getComputedStyle(button);
+        expect(computed.whiteSpace).toBe('nowrap');
+        expect(computed.width).toBe('100%');
+        expect(computed.maxWidth).toBe('100%');
+      }
+    });
+
+    it('uses the same stacked layout on a mobile touch screen', () => {
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: true,
+        noHover: true,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel="Keep this workspace"
+          actionLabel="Permanently delete workspace"
+        />,
+      );
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(buttons.map(button => button.textContent)).toEqual([
+        'Permanently delete workspace',
+        'Keep this workspace',
+      ]);
+      expect(getComputedStyle(buttons[0]).whiteSpace).toBe('nowrap');
+      expect(getComputedStyle(buttons[0]).width).toBe('100%');
+      expect(getComputedStyle(buttons[1]).whiteSpace).toBe('nowrap');
+      expect(getComputedStyle(buttons[1]).width).toBe('100%');
+    });
+
+    it('keeps narrow visual, DOM, and tab order aligned while autofocus stays on cancel', async () => {
+      const user = userEvent.setup();
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      const action = screen.getByRole('button', {name: longActionLabel});
+      const cancel = screen.getByRole('button', {name: longCancelLabel});
+      expect(
+        action.compareDocumentPosition(cancel) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(cancel).toHaveAttribute('data-autofocus');
+      action.focus();
+      await user.tab();
+      expect(cancel).toHaveFocus();
+    });
+  });
+
   it('defaults cancel label to Cancel', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();

package/src/AlertDialog/AlertDialog.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file AlertDialog.tsx
- * @input Uses React, Dialog, Layout, Heading, Text, Button
+ * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button
  * @output Exports AlertDialog component, AlertDialogProps type
  * @position Core implementation; consumed by index.ts, tested by AlertDialog.test.tsx
  *
@@ -17,11 +17,12 @@
  */
 
 import React, {useId, useCallback} from 'react';
+import * as stylex from '@stylexjs/stylex';
 import {Dialog} from '../Dialog';
 import {Layout} from '../Layout/Layout';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {LayoutFooter} from '../Layout/LayoutFooter';
-import {HStack} from '../Stack';
+import {Stack} from '../Stack';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
 import {Button, type ButtonVariant} from '../Button';
@@ -29,6 +30,19 @@ import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {useMediaQuery} from '../hooks';
+
+const SMALL_SCREEN_QUERY = '(max-width: 640px)';
+
+const styles = stylex.create({
+  action: {
+    maxWidth: '100%',
+    minWidth: 0,
+  },
+  stackedAction: {
+    width: '100%',
+  },
+});
 
 export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
   ref?: React.Ref<HTMLDialogElement>;
@@ -147,11 +161,44 @@ export function AlertDialog({
   const cancelLabel = cancelLabelFromProps ?? t('@astryx.alertDialog.cancel');
   const titleId = useId();
   const descriptionId = useId();
+  // Width stays delegated to Dialog: this query exists only so AlertDialog can
+  // keep narrow visual, DOM, and tab order aligned for its destructive/cancel
+  // semantics without coupling action order to pointer or hover capability.
+  const isSmallScreen = useMediaQuery(SMALL_SCREEN_QUERY);
 
   const handleCancel = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);
 
+  const buttonActionStyle = [
+    styles.action,
+    isSmallScreen && styles.stackedAction,
+  ];
+  const cancelButton = (
+    <Button
+      key="cancel"
+      variant="ghost"
+      label={cancelLabel}
+      onClick={handleCancel}
+      xstyle={buttonActionStyle}
+      // Dialog focuses [data-autofocus] itself after showModal(), because
+      // React's autoFocus runs during commit while the dialog is invisible.
+      // Cancel is least destructive, so it remains the autofocus target even
+      // when small-screen visual order places the destructive action above it.
+      data-autofocus
+    />
+  );
+  const actionButton = (
+    <Button
+      key="action"
+      variant={actionVariant}
+      label={actionLabel}
+      onClick={onAction}
+      isLoading={isActionLoading}
+      xstyle={buttonActionStyle}
+    />
+  );
+
   return (
     <Dialog
       {...rest}
@@ -185,24 +232,19 @@ export function AlertDialog({
         }
         footer={
           <LayoutFooter>
-            <HStack gap={2} hAlign="end">
-              <Button
-                variant="ghost"
-                label={cancelLabel}
-                onClick={handleCancel}
-                // Dialog focuses [data-autofocus] itself after showModal(),
-                // because React's autoFocus runs during commit while the
-                // dialog is still invisible. Cancel is the least destructive
-                // choice, so it is the one that should be preselected.
-                data-autofocus
-              />
-              <Button
-                variant={actionVariant}
-                label={actionLabel}
-                onClick={onAction}
-                isLoading={isActionLoading}
-              />
-            </HStack>
+            {/* Generic Dialog footers should wrap, but their consumers own
+                action semantics and order. AlertDialog keeps this
+                destructive-above-Cancel narrow order because confirmation
+                actions have component-specific meaning here. */}
+            <Stack
+              direction={isSmallScreen ? 'vertical' : 'horizontal'}
+              gap={2}
+              hAlign={isSmallScreen ? 'stretch' : 'end'}
+              wrap={isSmallScreen ? 'nowrap' : 'wrap'}>
+              {isSmallScreen
+                ? [actionButton, cancelButton]
+                : [cancelButton, actionButton]}
+            </Stack>
           </LayoutFooter>
         }
       />

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
-      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule; component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`); with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -84,7 +84,7 @@ export const docsZh = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
-      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule; component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`); with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -135,7 +135,7 @@ export const docsDense = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
-      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule; component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`); with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},

package/src/AspectRatio/AspectRatio.tsx

@@ -53,14 +53,14 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
    *   `astryx-base` cascade layer, and unlayered CSS wins over layered
    *   rules regardless of specificity.
    *
+   * A responsive ratio is set in CSS, not on the component. For example, a 3:1
+   * hero can become 3:2 when its container narrows by targeting the element's
+   * class from a container query:
+   * `@container gallery (max-width: 720px) { .gallery-hero { aspect-ratio: 3 / 2; } }`.
+   *
    * @example
    * ```
-   * // 3:1 hero that becomes 3:2 when its container stacks
-   * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
-   *
-   * // CSS: @container gallery (max-width: 720px) {
-   * //   .gallery-hero { aspect-ratio: 3 / 2; }
-   * // }
+   * <AspectRatio ratio={3 / 1} className="gallery-hero">...</AspectRatio>
    * ```
    */
   ratio: number;

package/src/Avatar/Avatar.doc.mjs

@@ -19,7 +19,7 @@ export const docs = {
       {guidance: true, description: 'Give every interactive avatar (href or onClick) a name or alt. It is the control\'s accessible name, and it warns in development when it is missing.'},
       {guidance: false, description: 'Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.'},
       {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team. Use an image or icon instead.'},
-      {guidance: false, description: 'Force a square or custom shape. Avatars are always circular to stay consistent across the system.'},
+      {guidance: false, description: 'Use xstyle or className to override shape. Use the shape prop instead so themes can control it globally.'},
     ],
     anatomy: [
       {name: 'Photo', required: false, description: 'The profile image, loaded from the src URL. Shown when available.'},
@@ -30,13 +30,17 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-avatar', visualProps: ['size']},
+      {className: 'astryx-avatar', visualProps: ['size', 'shape']},
       {className: 'astryx-avatar-fallback', visualProps: ['size']},
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
       {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
     vars: [
       {name: '--_avatar-group-overlap', description: 'Negative inline offset applied to every avatar after the first when avatars are stacked in an AvatarGroup. Set from the group size; a more negative value tightens the stack.', default: 'set at runtime from the group avatar size (px)', private: true},
+      {name: '--_avatar-radius', description: 'Border radius of the avatar wrapper, content, focus ring, and the AvatarGroupOverflow "+N" chip. Set per shape variant by shapeStyles.', default: 'var(--radius-full)', private: true},
+    ],
+    derived: [
+      {property: 'borderRadius', vars: ['--_avatar-radius']},
     ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
@@ -67,6 +71,12 @@ export const docs = {
       description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored.",
       default: "'md'",
     },
+    {
+      name: 'shape',
+      type: "'circle' | 'rounded' | 'square'",
+      description: "Shape variant of the avatar. 'circle' (default) stays fully round. 'rounded' uses the element radius token so it matches UI corner rounding and can be set globally via theme. 'square' has no radius. Status dot positioning adapts automatically: 4-o'clock on circle, bottom-right corner on rounded/square.",
+      default: "'circle'",
+    },
     {
       name: 'status',
       type: 'ReactNode',

package/src/Avatar/Avatar.test.tsx

@@ -6,6 +6,7 @@ import {act, render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Avatar} from './Avatar';
 import {AvatarStatusDot} from './AvatarStatusDot';
+import {AvatarGroup} from '../AvatarGroup';
 
 describe('Avatar', () => {
   it('exposes role="img" with the name as accessible name', () => {
@@ -416,6 +417,85 @@ describe('Avatar', () => {
     expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
   });
 
+  it('renders without error for all shape variants', () => {
+    const shapes = ['circle', 'rounded', 'square'] as const;
+    for (const shape of shapes) {
+      const {unmount} = render(
+        <Avatar
+          name="Ana Thomas"
+          shape={shape}
+          data-testid={`avatar-${shape}`}
+        />,
+      );
+      expect(screen.getByTestId(`avatar-${shape}`)).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it('defaults to circle shape (no shape prop)', () => {
+    render(<Avatar name="Lee" data-testid="avatar-default" />);
+    // Should still render with role="img" using the name as the accessible label.
+    expect(screen.getByRole('img', {name: 'Lee'})).toBeInTheDocument();
+  });
+
+  it('renders status dot for all shape variants', () => {
+    const shapes = ['circle', 'rounded', 'square'] as const;
+    const StatusDot = () => <span data-testid="status-dot" />;
+    for (const shape of shapes) {
+      const {unmount} = render(
+        <Avatar
+          name="Ana"
+          shape={shape}
+          status={<StatusDot />}
+          data-testid={`avatar-${shape}-status`}
+        />,
+      );
+      expect(screen.getByTestId('status-dot')).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it('applies shapeStyles to wrapper when rendered inside AvatarGroup', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" shape="rounded" data-testid="group-avatar" />
+      </AvatarGroup>,
+    );
+    expect(screen.getByTestId('group-avatar')).toBeInTheDocument();
+  });
+
+  it("an AvatarGroup's shape overrides an individual Avatar's own shape prop, matching how size already works", () => {
+    render(
+      <AvatarGroup shape="square">
+        <Avatar name="Alice" shape="rounded" data-testid="group-avatar" />
+      </AvatarGroup>,
+    );
+    expect(screen.getByTestId('group-avatar')).toHaveAttribute(
+      'data-shape',
+      'square',
+    );
+  });
+
+  it("an Avatar's own shape prop applies outside any AvatarGroup", () => {
+    render(<Avatar name="Ana" shape="rounded" data-testid="solo-avatar" />);
+    expect(screen.getByTestId('solo-avatar')).toHaveAttribute(
+      'data-shape',
+      'rounded',
+    );
+  });
+
+  it('defaults to circle shape inside an AvatarGroup with no explicit shape', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" shape="square" data-testid="group-avatar" />
+      </AvatarGroup>,
+    );
+    expect(screen.getByTestId('group-avatar')).toHaveAttribute(
+      'data-shape',
+      'circle',
+    );
+  });
+
   // --- Name tooltip (tooltip?: string | boolean) ---
   describe('name tooltip', () => {
     const originalShowPopover = HTMLElement.prototype.showPopover;