@arbor-education/design-system.components 0.5.5 → 0.6.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,gDAAgD,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uEAAuE,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AACzF,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,YAAY,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,gDAAgD,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uEAAuE,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AACzF,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,gBAAgB,GACtB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,YAAY,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/index.js

@@ -32,6 +32,7 @@ export { Progress } from './components/progress/Progress';
 export { Toast } from './components/toast/Toast';
 export { DatePicker } from './components/datePicker/DatePicker';
 export { Avatar } from './components/avatar/Avatar';
+export { AvatarGroup, } from './components/avatarGroup/AvatarGroup';
 export { UserDropdown } from './components/userDropdown/UserDropdown';
 export { SearchBar } from './components/searchBar/SearchBar';
 export { ArborLogo, GovhubLogo, KeyLogo, SampeopleLogo, RobinLogo, TimetablerLogo } from './components/userDropdown/assets/logos';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,gDAAgD,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uEAAuE,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,SAAS,EAAuB,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AACzF,OAAO,EAAE,MAAM,EAAoB,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,gDAAgD,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uEAAuE,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,SAAS,EAAuB,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AACzF,OAAO,EAAE,MAAM,EAAoB,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EACL,WAAW,GAKZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbor-education/design-system.components",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "The component library for the design system (the baby)",
   "main": "dist/index.js",
   "repository": {

package/src/components/avatarGroup/AvatarGroup.stories.tsx

@@ -0,0 +1,218 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Avatar } from 'Components/avatar/Avatar';
+import { AvatarGroup } from './AvatarGroup';
+
+const meta: Meta<typeof AvatarGroup> = {
+  title: 'Components/AvatarGroup',
+  component: AvatarGroup,
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AvatarGroup>;
+
+const sampleSrc = (id: number) => `https://i.pravatar.cc/150?img=${id}`;
+
+export const FromProps: Story = {
+  render: () => (
+    <AvatarGroup
+      label="Team from props"
+      items={[
+        { src: sampleSrc(1), alt: 'Member 1' },
+        { src: sampleSrc(2), alt: 'Member 2' },
+        { initials: 'CM', alt: 'Chris Montgomery' },
+      ]}
+    />
+  ),
+};
+
+export const SizeOverridesPerAvatar: Story = {
+  name: 'Size Override',
+  render: () => (
+    <AvatarGroup
+      label="All medium even though children are set as small"
+      size="medium"
+      showMaxItems={4}
+      items={[
+        <Avatar
+          key="1"
+          size="small"
+          initials="S1"
+          alt="Small 1"
+        />,
+        <Avatar
+          key="2"
+          size="small"
+          initials="S2"
+          alt="Small 2"
+        />,
+        { size: 'small', initials: 'S3', alt: 'Small 3' },
+        { size: 'small', initials: 'S4', alt: 'Small 4' },
+        { size: 'small', initials: 'S5', alt: 'Small 5' },
+      ]}
+    />
+  ),
+};
+
+export const ComposableChildren: Story = {
+  name: 'Composable Children',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass `<Avatar />` nodes as `children`.',
+      },
+    },
+  },
+  render: () => (
+    <AvatarGroup
+      label="Team (children API)"
+      showMaxItems={3}
+      listOrder="ascending"
+    >
+      <>
+        <Avatar
+          size="small"
+          initials="A"
+          alt="User A"
+        />
+        <Avatar
+          size="small"
+          initials="B"
+          alt="User B"
+        />
+      </>
+      <Avatar
+        size="small"
+        initials="C"
+        alt="User C"
+      />
+      <Avatar
+        size="small"
+        initials="D"
+        alt="User D"
+      />
+      <Avatar
+        size="small"
+        initials="E"
+        alt="User E"
+      />
+    </AvatarGroup>
+  ),
+};
+
+export const ComposableChildrenDescending: Story = {
+  name: 'Composed + Descending Order',
+  render: () => (
+    <AvatarGroup
+      label="Last three visible"
+      size="medium"
+      showMaxItems={3}
+      listOrder="descending"
+    >
+      <Avatar
+        initials="A"
+        alt="User A"
+      />
+      <Avatar
+        initials="B"
+        alt="User B"
+      />
+      <Avatar
+        initials="C"
+        alt="User C"
+      />
+      <Avatar
+        initials="D"
+        alt="User D"
+      />
+      <Avatar
+        initials="E"
+        alt="User E"
+      />
+    </AvatarGroup>
+  ),
+};
+
+export const AscendingWithOverflow: Story = {
+  render: () => (
+    <AvatarGroup
+      label="Ascending overflow"
+      listOrder="ascending"
+      showMaxItems={3}
+      items={[
+        { initials: 'A', alt: 'User A' },
+        { initials: 'B', alt: 'User B' },
+        { initials: 'C', alt: 'User C' },
+        { initials: 'D', alt: 'User D' },
+        { initials: 'E', alt: 'User E' },
+      ]}
+    />
+  ),
+};
+
+export const DescendingWithOverflow: Story = {
+  render: () => (
+    <AvatarGroup
+      label="Descending overflow"
+      listOrder="descending"
+      showMaxItems={3}
+      items={[
+        { initials: 'A', alt: 'User A' },
+        { initials: 'B', alt: 'User B' },
+        { initials: 'C', alt: 'User C' },
+        { initials: 'D', alt: 'User D' },
+        { initials: 'E', alt: 'User E' },
+      ]}
+    />
+  ),
+};
+
+export const CustomOverflowLabel: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Custom `overflowCountLabel` values replace the full screen-reader label for the overflow badge instead of appending to the visible `+N` text.',
+      },
+    },
+  },
+  render: () => (
+    <AvatarGroup
+      label="Custom overflow copy"
+      showMaxItems={2}
+      overflowCountLabel={n => `${n} more students`}
+      items={[
+        { initials: 'J', alt: 'Jacob' },
+        { initials: 'E', alt: 'Edward' },
+        { initials: 'B', alt: 'Bella' },
+      ]}
+    />
+  ),
+};
+
+export const AnnouncedOverflowUpdates: Story = {
+  name: 'Announced Overflow Updates',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Enables polite live announcements for the built-in overflow badge. Overflow members are not rendered; only the count is shown.',
+      },
+    },
+  },
+  render: () => (
+    <AvatarGroup
+      label="Live updates team"
+      showMaxItems={2}
+      presentAllUpdatesToScreenReader
+      items={[
+        { initials: 'A', alt: 'User A' },
+        { initials: 'B', alt: 'User B' },
+        { initials: 'C', alt: 'User C' },
+        { initials: 'D', alt: 'User D' },
+      ]}
+    />
+  ),
+};

package/src/components/avatarGroup/AvatarGroup.test.tsx

@@ -0,0 +1,298 @@
+import React from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { Avatar } from 'Components/avatar/Avatar';
+import { AvatarGroup } from './AvatarGroup';
+import { partitionAvatarGroupOverflow } from './avatarGroupOverflow';
+import { collectAvatarsFromChildren } from './collectAvatarGroupChildren';
+import type { AvatarGroupNormalizedEntry } from './useAvatarGroupItems';
+import '@testing-library/jest-dom/vitest';
+
+const fourPeople: { initials: string; alt: string }[] = [
+  { initials: 'A', alt: 'User A' },
+  { initials: 'B', alt: 'User B' },
+  { initials: 'C', alt: 'User C' },
+  { initials: 'D', alt: 'User D' },
+];
+
+describe('partitionAvatarGroupOverflow', () => {
+  const mockItems = (n: number): AvatarGroupNormalizedEntry[] =>
+    Array.from({ length: n }, (_, i) => ({
+      key: String(i),
+      avatarProps: { alt: `User ${i}` },
+    }));
+
+  test('ascending keeps head visible and counts overflow', () => {
+    const items = mockItems(4);
+    const { visibleItems, overflowCount } = partitionAvatarGroupOverflow(items, 2, 'ascending');
+    expect(visibleItems.map(x => x.key)).toEqual(['0', '1']);
+    expect(overflowCount).toBe(2);
+  });
+
+  test('descending keeps tail visible and counts overflow', () => {
+    const items = mockItems(4);
+    const { visibleItems, overflowCount } = partitionAvatarGroupOverflow(items, 2, 'descending');
+    expect(visibleItems.map(x => x.key)).toEqual(['2', '3']);
+    expect(overflowCount).toBe(2);
+  });
+
+  test('no overflow when showMaxItems omits or covers all', () => {
+    const items = mockItems(3);
+    expect(partitionAvatarGroupOverflow(items, undefined, 'ascending').overflowCount).toBe(0);
+    expect(partitionAvatarGroupOverflow(items, 10, 'ascending').overflowCount).toBe(0);
+  });
+
+  test('floors decimal values and treats negative values as show all', () => {
+    const items = mockItems(4);
+    const decimalResult = partitionAvatarGroupOverflow(items, 2.9, 'ascending');
+    const negativeResult = partitionAvatarGroupOverflow(items, -1, 'descending');
+
+    expect(decimalResult.visibleItems.map(x => x.key)).toEqual(['0', '1']);
+    expect(decimalResult.overflowCount).toBe(2);
+    expect(negativeResult.visibleItems.map(x => x.key)).toEqual(['0', '1', '2', '3']);
+    expect(negativeResult.overflowCount).toBe(0);
+  });
+});
+
+describe('AvatarGroup', () => {
+  test('renders avatar props objects', () => {
+    render(
+      <AvatarGroup
+        items={[
+          { initials: 'CM', alt: 'Chris M' },
+          { initials: 'JD', alt: 'Jay D' },
+        ]}
+      />,
+    );
+    expect(screen.getByLabelText('Chris M')).toBeInTheDocument();
+    expect(screen.getByLabelText('Jay D')).toBeInTheDocument();
+  });
+
+  test('renders pre-built Avatar elements', () => {
+    render(
+      <AvatarGroup
+        items={[
+          <Avatar
+            key="one"
+            initials="X"
+            alt="Xavier"
+          />,
+          <Avatar
+            key="two"
+            initials="Y"
+            alt="Yolanda"
+          />,
+        ]}
+      />,
+    );
+    expect(screen.getByLabelText('Xavier')).toBeInTheDocument();
+    expect(screen.getByLabelText('Yolanda')).toBeInTheDocument();
+  });
+
+  test('mixes Avatar elements and props objects', () => {
+    render(
+      <AvatarGroup
+        items={[
+          <Avatar
+            key="e"
+            initials="E"
+            alt="Element user"
+          />,
+          { initials: 'P', alt: 'Props user' },
+        ]}
+      />,
+    );
+    expect(screen.getByLabelText('Element user')).toBeInTheDocument();
+    expect(screen.getByLabelText('Props user')).toBeInTheDocument();
+  });
+
+  test('applies showMaxItems and overflow +N with default aria-label', () => {
+    render(
+      <AvatarGroup
+        items={fourPeople}
+        showMaxItems={2}
+        listOrder="ascending"
+      />,
+    );
+    expect(screen.getByText('+2')).toBeInTheDocument();
+    const overflow = screen.getByRole('status', { name: 'plus 2 more' });
+    expect(overflow).toBeInTheDocument();
+    expect(screen.getByLabelText('User A')).toBeInTheDocument();
+    expect(screen.getByLabelText('User B')).toBeInTheDocument();
+    expect(screen.queryByLabelText('User C')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('User D')).not.toBeInTheDocument();
+  });
+
+  test('descending shows last N avatars in the main list', () => {
+    const { container } = render(
+      <AvatarGroup
+        items={fourPeople}
+        showMaxItems={2}
+        listOrder="descending"
+      />,
+    );
+    const visibleLis = container.querySelectorAll('.ds-avatar-group > .ds-avatar-group__item');
+    expect(visibleLis).toHaveLength(2);
+    expect(within(visibleLis[0] as HTMLElement).getByText('C')).toBeInTheDocument();
+    expect(within(visibleLis[1] as HTMLElement).getByText('D')).toBeInTheDocument();
+
+    expect(screen.queryByLabelText('User A')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('User B')).not.toBeInTheDocument();
+  });
+
+  test('overflowCountLabel string override', () => {
+    render(
+      <AvatarGroup
+        items={fourPeople}
+        showMaxItems={2}
+        overflowCountLabel="two teammates not shown"
+      />,
+    );
+    expect(screen.getByRole('status', { name: 'two teammates not shown' })).toBeInTheDocument();
+  });
+
+  test('overflowCountLabel function override', () => {
+    render(
+      <AvatarGroup
+        items={fourPeople}
+        showMaxItems={2}
+        overflowCountLabel={n => `${n} extra`}
+      />,
+    );
+    expect(screen.getByRole('status', { name: '2 extra' })).toBeInTheDocument();
+  });
+
+  test('outer list uses aria-label from label prop', () => {
+    render(
+      <AvatarGroup
+        label="Project contributors"
+        items={[{ initials: 'Z', alt: 'Zed' }]}
+      />,
+    );
+    const list = screen.getByRole('list', { name: 'Project contributors' });
+    expect(list).toHaveAttribute('role', 'list');
+  });
+
+  test('forwards refs to the root list element', () => {
+    const ref = React.createRef<HTMLUListElement>();
+    render(
+      <AvatarGroup
+        ref={ref}
+        label="Ref team"
+        items={[{ initials: 'Z', alt: 'Zed' }]}
+      />,
+    );
+    expect(ref.current).toHaveAttribute('role', 'list');
+  });
+
+  test('AvatarGroup.OverflowCount standalone uses status semantics', () => {
+    render(
+      <AvatarGroup.OverflowCount
+        count={5}
+        overflowCountLabel="five more wolves"
+      />,
+    );
+    const overflow = screen.getByRole('status', { name: 'five more wolves' });
+    expect(overflow).toHaveTextContent('+5');
+    expect(overflow).not.toHaveAttribute('aria-live');
+    expect(overflow).not.toHaveAttribute('aria-atomic');
+  });
+
+  test('AvatarGroup.OverflowCount can announce all updates to screen readers', () => {
+    render(
+      <AvatarGroup.OverflowCount
+        count={5}
+        overflowCountLabel="five more wolves"
+        presentAllUpdatesToScreenReader
+      />,
+    );
+    const overflow = screen.getByRole('status', { name: 'five more wolves' });
+    expect(overflow).toHaveAttribute('aria-live', 'polite');
+    expect(overflow).toHaveAttribute('aria-atomic', 'true');
+  });
+
+  test('group prop plumbs live-region behaviour to the built-in overflow badge', () => {
+    render(
+      <AvatarGroup
+        items={fourPeople}
+        showMaxItems={2}
+        presentAllUpdatesToScreenReader
+      />,
+    );
+    const overflow = screen.getByRole('status', { name: 'plus 2 more' });
+    expect(overflow).toHaveAttribute('aria-live', 'polite');
+    expect(overflow).toHaveAttribute('aria-atomic', 'true');
+  });
+
+  test('size on group overrides avatar size', () => {
+    const { container } = render(
+      <AvatarGroup
+        size="large"
+        items={[
+          { initials: 'S', alt: 'Small marked', size: 'small' },
+          <Avatar
+            key="m"
+            initials="M"
+            alt="Medium marked"
+            size="medium"
+          />,
+        ]}
+      />,
+    );
+    const avatars = container.querySelectorAll('.ds-avatar--large');
+    expect(avatars).toHaveLength(2);
+  });
+
+  test('renders avatars from children with fragments and overflow', () => {
+    render(
+      <AvatarGroup
+        label="Composable team"
+        showMaxItems={2}
+        size="medium"
+      >
+        <>
+          <Avatar
+            initials="A"
+            alt="User A"
+          />
+          <Avatar
+            initials="B"
+            alt="User B"
+          />
+        </>
+        <Avatar
+          initials="C"
+          alt="User C"
+        />
+      </AvatarGroup>,
+    );
+    expect(screen.getByRole('list', { name: 'Composable team' })).toBeInTheDocument();
+    expect(screen.getByLabelText('User A')).toBeInTheDocument();
+    expect(screen.getByLabelText('User B')).toBeInTheDocument();
+    expect(screen.getByText('+1')).toBeInTheDocument();
+    expect(screen.queryByLabelText('User C')).not.toBeInTheDocument();
+  });
+});
+
+describe('collectAvatarsFromChildren', () => {
+  test('warns in development when non-Avatar React elements are passed', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const result = collectAvatarsFromChildren(
+      <>
+        <Avatar
+          initials="A"
+          alt="User A"
+        />
+        <span>Ignored child</span>
+      </>,
+    );
+
+    expect(result).toHaveLength(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      'AvatarGroup only collects `<Avatar />` children when using the children API.',
+    );
+
+    warnSpy.mockRestore();
+  });
+});

package/src/components/avatarGroup/AvatarGroup.tsx

@@ -0,0 +1,127 @@
+import classNames from 'classnames';
+import { Avatar, type AvatarSize } from 'Components/avatar/Avatar';
+import React from 'react';
+import { partitionAvatarGroupOverflow, type AvatarGroupListOrder } from './avatarGroupOverflow';
+import { collectAvatarsFromChildren } from './collectAvatarGroupChildren';
+import { useAvatarGroupItems, type AvatarGroupItem } from './useAvatarGroupItems';
+
+export type { AvatarGroupItem, AvatarGroupListOrder };
+
+export type AvatarGroupOverflowCountProps = {
+  count: number;
+  overflowCountLabel?: string | ((count: number) => string);
+  className?: string;
+  presentAllUpdatesToScreenReader?: boolean;
+};
+
+function resolveOverflowAriaLabel(
+  count: number,
+  overflowCountLabel?: string | ((c: number) => string),
+): string {
+  if (typeof overflowCountLabel === 'function') {
+    return overflowCountLabel(count);
+  }
+  if (typeof overflowCountLabel === 'string') {
+    return overflowCountLabel;
+  }
+  return `plus ${count} more`;
+}
+
+function AvatarGroupOverflowCount({
+  count,
+  overflowCountLabel,
+  className,
+  presentAllUpdatesToScreenReader = false,
+}: AvatarGroupOverflowCountProps) {
+  return (
+    <span
+      role="status"
+      className={classNames('ds-avatar-group__overflow-count', className)}
+      aria-label={resolveOverflowAriaLabel(count, overflowCountLabel)}
+      aria-live={presentAllUpdatesToScreenReader ? 'polite' : undefined}
+      aria-atomic={presentAllUpdatesToScreenReader ? 'true' : undefined}
+    >
+      +
+      {count}
+    </span>
+  );
+}
+
+type AvatarGroupSharedProps = {
+  showMaxItems?: number;
+  listOrder?: AvatarGroupListOrder;
+  label?: string;
+  overflowCountLabel?: string | ((count: number) => string);
+  presentAllUpdatesToScreenReader?: boolean;
+  size?: AvatarSize;
+  className?: string;
+};
+
+export type AvatarGroupProps = AvatarGroupSharedProps
+  & (
+    | { items: readonly AvatarGroupItem[]; children?: undefined }
+    | { children: React.ReactNode; items?: undefined }
+  )
+  & Omit<React.HTMLAttributes<HTMLUListElement>, 'children'>;
+
+const AvatarGroupRoot = React.forwardRef<HTMLUListElement, AvatarGroupProps>(({
+  items,
+  children,
+  size: groupSize,
+  showMaxItems,
+  listOrder = 'ascending',
+  label,
+  overflowCountLabel,
+  presentAllUpdatesToScreenReader = false,
+  className,
+  ...rest
+}: AvatarGroupProps, ref) => {
+  const sourceItems = React.useMemo(() => {
+    if (children != null) {
+      return collectAvatarsFromChildren(children);
+    }
+    return items ?? [];
+  }, [children, items]);
+
+  const normalized = useAvatarGroupItems(sourceItems, groupSize);
+  const { visibleItems, overflowCount } = React.useMemo(
+    () => partitionAvatarGroupOverflow(normalized, showMaxItems, listOrder),
+    [normalized, showMaxItems, listOrder],
+  );
+
+  return (
+    <ul
+      ref={ref}
+      role="list"
+      className={classNames('ds-avatar-group', className)}
+      aria-label={label}
+      {...rest}
+    >
+      {visibleItems.map(entry => (
+        <li
+          key={entry.key}
+          className="ds-avatar-group__item"
+        >
+          <Avatar {...entry.avatarProps} />
+        </li>
+      ))}
+      {overflowCount > 0
+        ? (
+            <li className="ds-avatar-group__overflow">
+              <AvatarGroupOverflowCount
+                count={overflowCount}
+                overflowCountLabel={overflowCountLabel}
+                presentAllUpdatesToScreenReader={presentAllUpdatesToScreenReader}
+              />
+            </li>
+          )
+        : null}
+    </ul>
+  );
+});
+
+AvatarGroupRoot.displayName = 'AvatarGroup';
+
+export const AvatarGroup = Object.assign(AvatarGroupRoot, {
+  OverflowCount: AvatarGroupOverflowCount,
+});