@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

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',
@@ -148,7 +158,8 @@ export const docsDense = {
       {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
       {guidance: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
-      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development. A status label is not a name.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development.'},
+      {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 for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],

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;
@@ -569,6 +649,23 @@ describe('Avatar', () => {
       render(<Avatar name="Ada Lovelace" ref={ref} data-testid="a" />);
       expect(ref.current).toBe(screen.getByTestId('a'));
     });
+
+    it('keeps its merged ref attached across unrelated rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Avatar name="Ada Lovelace" size="sm" tooltip={false} ref={ref} />,
+      );
+      const avatar = screen.getByRole('img', {name: 'Ada Lovelace'});
+      expect(ref).toHaveBeenLastCalledWith(avatar);
+      ref.mockClear();
+
+      rerender(
+        <Avatar name="Ada Lovelace" size="lg" tooltip={false} ref={ref} />,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByRole('img', {name: 'Ada Lovelace'})).toBe(avatar);
+    });
   });
 });
 

package/src/Avatar/Avatar.tsx

@@ -19,7 +19,14 @@
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
 
-import {isValidElement, useMemo, useRef, useState, type ReactNode} from 'react';
+import {
+  isValidElement,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -34,7 +41,8 @@ import {
   type AvatarStatusLabelTarget,
 } from './AvatarStatusLabelContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {themeProps} from '../utils/themeProps';
 import {firstCharacter} from '../utils/characters';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -89,6 +97,11 @@ type AvatarNumericSize =
  */
 export type AvatarSize = AvatarNamedSize | AvatarNumericSize;
 
+/**
+ * Avatar shape options
+ */
+export type AvatarShape = 'circle' | 'rounded' | 'square';
+
 /**
  * Resolves named sizes to their numeric pixel values
  */
@@ -110,6 +123,25 @@ export function resolveSize(size: AvatarSize): number {
   }
 }
 
+// Sets one local custom property rather than `borderRadius` directly, so
+// every clipping/ring surface that needs the shape's radius (the wrapper,
+// the interactive focus ring, the content div that actually clips via
+// `overflow: hidden`, and AvatarGroupOverflow's "+N" indicator) reads the
+// same value instead of each hardcoding its own borderRadius independently.
+// A theme override only has to reach this one property, not fight the
+// per-surface StyleX class order to change the shape everywhere at once.
+export const shapeStyles = stylex.create({
+  circle: {
+    '--_avatar-radius': radiusVars['--radius-full'],
+  },
+  rounded: {
+    '--_avatar-radius': radiusVars['--radius-element'],
+  },
+  square: {
+    '--_avatar-radius': radiusVars['--radius-none'],
+  },
+});
+
 /**
  * Base styles for the avatar
  * Uses a wrapper/content structure so status isn't clipped by overflow:hidden
@@ -119,10 +151,10 @@ const styles = stylex.create({
     position: 'relative',
     display: 'inline-flex',
     flexShrink: 0,
-    // The wrapper carries the avatar's box as well as its radius, so a theme
-    // rule on the `.astryx-avatar` target reaches both: the size the `size`
-    // visual prop selects on is set here, and the content below fills it.
-    borderRadius: radiusVars['--radius-full'],
+    // Reads the shape variant's `--_avatar-radius` (set by `shapeStyles`
+    // below) rather than a hardcoded value, so `shape` actually changes the
+    // wrapper's own radius instead of only the content div's clip.
+    borderRadius: 'var(--_avatar-radius)',
   },
   content: {
     display: 'flex',
@@ -130,9 +162,14 @@ const styles = stylex.create({
     justifyContent: 'center',
     width: '100%',
     height: '100%',
-    borderRadius: radiusVars['--radius-full'],
     overflow: 'hidden',
     userSelect: 'none',
+    // The content div is the one that actually clips (via overflow: hidden
+    // above), so it needs its own border-radius matching the wrapper's.
+    // It inherits `--_avatar-radius` from the wrapper, since custom
+    // properties cascade to descendants even though border-radius itself
+    // does not.
+    borderRadius: 'var(--_avatar-radius)',
   },
   image: {
     width: '100%',
@@ -159,9 +196,6 @@ const styles = stylex.create({
   status: {
     position: 'absolute',
   },
-  // Visible focus ring for the name-tooltip tab stop, matching the repo-wide
-  // focus-visible outline treatment (see Timestamp, Token, Thumbnail). Only
-  // applied when a tooltip is active so keyboard users can reveal it.
   // Reset the intrinsic styling of the interactive element (<a>/<button>) so it
   // is a transparent, correctly-sized wrapper around the avatar visuals. The
   // element carries the focus-visible accent ring for keyboard users.
@@ -179,8 +213,9 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    // Match the avatar's circular shape so the focus ring hugs it.
-    borderRadius: radiusVars['--radius-full'],
+    // Match the avatar's shape (via `--_avatar-radius`) so the focus ring
+    // hugs it, whichever shape variant is in effect.
+    borderRadius: 'var(--_avatar-radius)',
   },
 });
 
@@ -199,7 +234,7 @@ const dynamicStyles = stylex.create({
   fontSize: (size: number) => ({
     fontSize: `${size * INITIALS_FONT_SIZE_RATIO}px`,
   }),
-  statusPosition: (size: number) => ({
+  statusPositionCircle: (size: number) => ({
     bottom: size * CIRCLE_EDGE_OFFSET_RATIO,
     insetInlineEnd: size * CIRCLE_EDGE_OFFSET_RATIO,
     // `insetInlineEnd` anchors to the right edge in LTR / left in RTL, so the
@@ -209,13 +244,23 @@ const dynamicStyles = stylex.create({
       ':is([dir="rtl"] *)': 'translate(-50%, 50%)',
     },
   }),
+  statusPositionCorner: {
+    bottom: 0,
+    insetInlineEnd: 0,
+    // Same RTL mirroring as statusPositionCircle above: insetInlineEnd
+    // anchors to the right edge in LTR / left in RTL, so the outward push
+    // must flip sign too.
+    transform: {
+      default: 'translate(25%, 25%)',
+      ':is([dir="rtl"] *)': 'translate(-25%, 25%)',
+    },
+  },
 });
 
 const BORDER_WIDTH = 2;
 
 const groupStyles = stylex.create({
   ring: {
-    borderRadius: radiusVars['--radius-full'],
     borderWidth: BORDER_WIDTH,
     borderStyle: 'solid',
     borderColor: colorVars['--color-background-surface'],
@@ -268,6 +313,14 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    * @default 'md'
    */
   size?: AvatarSize;
+  /**
+   * Shape variant of the avatar.
+   * - 'circle': Full circle (default)
+   * - 'rounded': Rounded square
+   * - 'square': Sharp square
+   * @default 'circle'
+   */
+  shape?: AvatarShape;
   /**
    * The primary image source for the avatar.
    */
@@ -471,6 +524,7 @@ export function Avatar({
   fallbackSrc,
   name,
   size = 'md',
+  shape = 'circle',
   src,
   status,
   tooltip = true,
@@ -530,6 +584,7 @@ export function Avatar({
     : undefined;
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
+  const resolvedShape = avatarGroup?.shape ?? shape;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
 
   // Resolve the tooltip content:
@@ -608,47 +663,62 @@ export function Avatar({
     label: undefined,
     update: null,
   });
-  // A fresh callback ref every render, so React reattaches it on every commit
-  // and the name is recomposed after React has written this render's props.
+  const {
+    'aria-hidden': consumerAriaHidden,
+    'aria-label': consumerAriaLabel,
+    role: consumerRole,
+  } = props;
+  // Recompose the name after React has written any relevant prop changes.
   // `update` covers the other direction: a label that changes while the avatar
   // itself does not re-render.
-  const nameRef = (element: HTMLElement | null) => {
-    if (element == null) {
-      return;
-    }
-    const target = statusLabelRef.current;
-    target.update = () => {
-      const composed = composeAccessibleName(
-        t,
-        nameLabel,
-        meaningful(target.label) ?? getStatusLabel(status),
-      );
-      // A consumer's own ARIA wins here exactly as it does in render, where
-      // the derived props spread before `{...props}`.
-      if (props['aria-label'] == null) {
-        setAttributeOrRemove(element, 'aria-label', composed);
+  const nameRef = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null) {
+        return;
       }
-      // An `<a>`/`<button>` root carries its own role and must not be hidden,
-      // so only the name transfers there.
-      if (!isInteractive) {
-        if (props.role == null) {
-          element.setAttribute('role', composed ? 'img' : 'presentation');
+      const target = statusLabelRef.current;
+      target.update = () => {
+        const composed = composeAccessibleName(
+          t,
+          nameLabel,
+          meaningful(target.label) ?? getStatusLabel(status),
+        );
+        // A consumer's own ARIA wins here exactly as it does in render, where
+        // the derived props spread before `{...props}`.
+        if (consumerAriaLabel == null) {
+          setAttributeOrRemove(element, 'aria-label', composed);
         }
-        if (props['aria-hidden'] == null) {
-          setAttributeOrRemove(
-            element,
-            'aria-hidden',
-            composed ? undefined : 'true',
-          );
+        // An `<a>`/`<button>` root carries its own role and must not be hidden,
+        // so only the name transfers there.
+        if (!isInteractive) {
+          if (consumerRole == null) {
+            element.setAttribute('role', composed ? 'img' : 'presentation');
+          }
+          if (consumerAriaHidden == null) {
+            setAttributeOrRemove(
+              element,
+              'aria-hidden',
+              composed ? undefined : 'true',
+            );
+          }
         }
-      }
-    };
-    target.update();
-    return () => {
-      target.update = null;
-    };
-  };
-  const rootRef = mergeRefs(
+      };
+      target.update();
+      return () => {
+        target.update = null;
+      };
+    },
+    [
+      consumerAriaHidden,
+      consumerAriaLabel,
+      consumerRole,
+      isInteractive,
+      nameLabel,
+      status,
+      t,
+    ],
+  );
+  const rootRef = useMergedRefs(
     ref,
     showTooltip ? tooltipHook.ref : undefined,
     nameRef,
@@ -700,7 +770,9 @@ export function Avatar({
         <div
           {...stylex.props(
             styles.status,
-            dynamicStyles.statusPosition(numericSize),
+            resolvedShape === 'circle'
+              ? dynamicStyles.statusPositionCircle(numericSize)
+              : dynamicStyles.statusPositionCorner,
           )}>
           {status}
         </div>
@@ -713,7 +785,7 @@ export function Avatar({
   // tooltip tab-stop focus ring all live here so the interactive
   // `<a>`/`<button>` and the static `<div>` carry the exact same box.
   const rootStylexProps = mergeProps(
-    themeProps('avatar', {size: resolvedSize}),
+    themeProps('avatar', {size: resolvedSize, shape: resolvedShape}),
     focusOutlineProps.focusVisible(
       styles.wrapper,
       dynamicStyles.size(numericSize),
@@ -721,6 +793,7 @@ export function Avatar({
       avatarGroup && groupStyles.ring,
       avatarGroup && groupStyles.overlap,
       avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),
+      shapeStyles[resolvedShape],
       xstyle,
     ),
     className,

package/src/Avatar/index.ts

@@ -5,7 +5,7 @@
 /**
  * @file index.ts
  * @input Imports Avatar component and types from Avatar.tsx, AvatarStatusDot from AvatarStatusDot.tsx
- * @output Exports Avatar, AvatarProps, AvatarSize, AvatarStatusDot, AvatarStatusDotProps, AvatarStatusDotVariant
+ * @output Exports Avatar, AvatarProps, AvatarSize, AvatarShape, resolveSize, AvatarStatusDot, AvatarStatusDotProps, AvatarStatusDotVariant
  * @position Component entry point; re-exported by /packages/core/src/index.ts
  *
  * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs
@@ -38,7 +38,7 @@ export interface AvatarStatusDotVariantMap {
 }
 
 export {Avatar, resolveSize} from './Avatar';
-export type {AvatarProps, AvatarSize} from './Avatar';
+export type {AvatarProps, AvatarSize, AvatarShape} from './Avatar';
 export {AvatarStatusDot} from './AvatarStatusDot';
 export type {
   AvatarStatusDotProps,

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -25,8 +25,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-avatar-group', visualProps: ['size']},
-      {className: 'astryx-avatar-group-overflow', visualProps: ['size']},
+      {className: 'astryx-avatar-group', visualProps: ['size', 'shape']},
+      {className: 'astryx-avatar-group-overflow', visualProps: ['size', 'shape']},
     ],
   },
   description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.',
@@ -52,6 +52,12 @@ export const docs = {
         "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
       default: "'md'",
     },
+    {
+      name: 'shape',
+      type: "'circle' | 'rounded' | 'square'",
+      description: "Shape applied to all avatars via context, overriding each avatar's own shape prop. Also applied to AvatarGroupOverflow's \"+N\" indicator.",
+      default: "'circle'",
+    },
     {
       name: 'ref',
       type: 'React.Ref<HTMLDivElement>',

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -118,6 +118,30 @@ describe('AvatarGroupOverflow', () => {
     expect(overflow).toHaveAttribute('data-size', 'lg');
   });
 
+  it('applies the group shape to the overflow chip, matching its avatars', () => {
+    render(
+      <AvatarGroup shape="square">
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByLabelText('5 more');
+    expect(overflow).toHaveAttribute('data-shape', 'square');
+  });
+
+  it('defaults the overflow chip to circle shape with no explicit AvatarGroup shape', () => {
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByLabelText('5 more');
+    expect(overflow).toHaveAttribute('data-shape', 'circle');
+  });
+
   it('renders as button when onClick is provided', () => {
     render(
       <AvatarGroup>

package/src/AvatarGroup/AvatarGroup.tsx

@@ -26,9 +26,9 @@
 
 import {useId, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
-import {resolveSize, type AvatarSize} from '../Avatar';
+import {resolveSize, type AvatarShape, type AvatarSize} from '../Avatar';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {AvatarGroupContext} from './AvatarGroupContext';
 import {themeProps} from '../utils/themeProps';
@@ -37,6 +37,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {VisuallyHidden} from '../VisuallyHidden';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const OVERLAP_RATIO = 0.25;
 
 export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
@@ -54,6 +55,13 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
    * @default 'md'
    */
   size?: AvatarSize;
+  /**
+   * Shape applied to all avatars via context, overriding each avatar's own
+   * `shape` prop so a group stays visually uniform. Also applied to the
+   * `AvatarGroupOverflow` "+N" indicator, so it matches the group.
+   * @default 'circle'
+   */
+  shape?: AvatarShape;
   /**
    * Test ID for integration testing.
    */
@@ -88,6 +96,7 @@ const styles = stylex.create({
 export function AvatarGroup({
   children,
   size = 'md',
+  shape = 'circle',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   'aria-describedby': ariaDescribedByFromProps,
@@ -105,8 +114,8 @@ export function AvatarGroup({
   const overlap = Math.round(numericSize * OVERLAP_RATIO);
 
   const contextValue = useMemo(
-    () => ({size, overlap, numericSize}),
-    [size, overlap, numericSize],
+    () => ({size, shape, overlap, numericSize}),
+    [size, shape, overlap, numericSize],
   );
 
   // The keyboard hint and roving tab stop only make sense once the group has
@@ -143,7 +152,7 @@ export function AvatarGroup({
     <AvatarGroupContext value={contextValue}>
       <div
         {...props}
-        ref={mergeRefs(ref, listRef)}
+        ref={useMergedRefs(ref, listRef)}
         role="group"
         aria-label={ariaLabel}
         aria-describedby={describedBy}
@@ -151,7 +160,7 @@ export function AvatarGroup({
         onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
         onFocus={composeEventHandlers(onFocus, handleFocus)}
         {...mergeProps(
-          themeProps('avatar-group', {size}),
+          themeProps('avatar-group', {size, shape}),
           stylex.props(styles.root, xstyle),
           className,
           style,

package/src/AvatarGroup/AvatarGroupContext.ts

@@ -9,16 +9,18 @@
  */
 
 import {createContext, use} from 'react';
-import type {AvatarSize} from '../Avatar';
+import type {AvatarShape, AvatarSize} from '../Avatar';
 
 export interface AvatarGroupContextValue {
   size: AvatarSize;
+  shape: AvatarShape;
   overlap: number;
   numericSize: number;
 }
 
-export const AvatarGroupContext =
-  createContext<AvatarGroupContextValue | null>(null);
+export const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(
+  null,
+);
 AvatarGroupContext.displayName = 'AvatarGroupContext';
 
 export function useAvatarGroup(): AvatarGroupContextValue | null {