@arbor-education/design-system.components 0.14.0 → 0.16.0

package/dist/components/avatarGroup/AvatarGroup.stories.js

@@ -1,91 +1,714 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
 import { Avatar } from '../avatar/Avatar';
+import { Button } from '../button/Button';
 import { AvatarGroup } from './AvatarGroup';
+// ---------------------------------------------------------------------------
+// Content strings for the custom DocsPage
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    '`AvatarGroup` renders a horizontal stack of overlapping Avatar thumbnails with an optional overflow badge,',
+    'supporting both a data-driven `items` API and a composable `children` API for maximum flexibility.',
+].join(' ');
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- Showing a compact summary of participants, collaborators, or assignees on a record (e.g. teachers on a timetable slot, guardians linked to a student).',
+    '- Representing "who has access" or "who is watching" in a list view where space is limited.',
+    '- Surfacing a count of hidden members when there are more people than screen real estate allows.',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Scenario | Better alternative |',
+    '|---|---|',
+    '| You need to show full names alongside each avatar | A list of `<Avatar>` components with adjacent labels |',
+    '| You need click / interactive behaviour on each avatar | Wrap individual `<Avatar>` components in buttons |',
+    '| You only have one person to show | A single `<Avatar>` is cleaner and more semantic |',
+    '| The avatars represent non-people entities (subjects, clubs) | An icon list or tag list |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**Always supply `label`**',
+    '',
+    'Every `AvatarGroup` in production must have an `aria-label` so screen-reader users know what the group represents:',
+    '',
+    '```tsx',
+    '<AvatarGroup label="Form tutors for Year 11" items={tutors} />',
+    '```',
+    '',
+    '**Two mutually exclusive APIs**',
+    '',
+    'Choose one and stick to it — mixing both on the same component causes a TypeScript error:',
+    '',
+    '```tsx',
+    '// ✅ Items API — pass an array of AvatarGroupItem objects',
+    '<AvatarGroup items={staff} label="Staff" />',
+    '',
+    '// ✅ Children API — compose Avatar elements directly',
+    '<AvatarGroup label="Staff">',
+    '  <Avatar initials="DZ" alt="Dorothy Zbornak" />',
+    '  <Avatar initials="SP" alt="Sophia Petrillo" />',
+    '</AvatarGroup>',
+    '```',
+    '',
+    '**Group `size` wins over individual sizes**',
+    '',
+    'If you pass `size` to the group, it overrides any `size` set on individual items. This is intentional:',
+    '',
+    '```tsx',
+    '// All avatars will render at large, regardless of individual size props',
+    '<AvatarGroup size="large" items={staff} label="Staff" />',
+    '```',
+    '',
+    '**`listOrder="descending"` shows the LAST N items**',
+    '',
+    'When combined with `showMaxItems`, `ascending` shows the first N items and `descending` shows the last N.',
+    'Use `descending` for "most recent contributors" patterns where the latest entries are at the end of the array:',
+    '',
+    '```tsx',
+    '// Shows the 3 most recently active teachers (last 3 in the array)',
+    '<AvatarGroup',
+    '  items={recentTeachers}',
+    '  showMaxItems={3}',
+    '  listOrder="descending"',
+    '  label="Most recently active teachers"',
+    '/>',
+    '```',
+    '',
+    '**Custom overflow label**',
+    '',
+    'Pass a function to `overflowCountLabel` to build a fully descriptive accessible label:',
+    '',
+    '```tsx',
+    '<AvatarGroup',
+    '  items={students}',
+    '  showMaxItems={5}',
+    '  overflowCountLabel={(n) => `${n} more students not shown`}',
+    '  label="Students in tutor group 7B"',
+    '/>',
+    '```',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- The root element is a `<ul>` — each avatar is a `<li>`. Screen readers receive correct list semantics and item count.',
+    '- Supply `label` (maps to `aria-label` on the `<ul>`) so the list has a meaningful name.',
+    '- The overflow badge uses `role="status"` and an `aria-label` derived from `overflowCountLabel` (default: `"plus N more"`).',
+    '- Set `presentAllUpdatesToScreenReader` when the group updates dynamically — this adds `aria-live="polite"` and `aria-atomic="true"` to the overflow badge so changes are announced.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { AvatarGroup } from '@arbor-education/design-system.components';",
+    "import type { AvatarGroupItem, AvatarGroupListOrder } from '@arbor-education/design-system.components';",
+    '',
+    'type AvatarGroupProps = AvatarGroup.Props;',
+    '```',
+].join('\n');
+const AVATAR_GROUP_ITEM_REFERENCE = [
+    '`AvatarGroupItem` is the union type accepted by the `items` array. It supports two shapes so you can',
+    'pass either raw data objects or pre-rendered `<Avatar>` elements:',
+    '',
+    '```ts',
+    "import type { AvatarGroupItem } from '@arbor-education/design-system.components';",
+    '',
+    '// Shape 1 — plain AvatarProps object (most common, data-driven):',
+    'const item: AvatarGroupItem = { initials: "DZ", alt: "Dorothy Zbornak", size: "medium" };',
+    '',
+    '// Shape 2 — pre-rendered <Avatar> element:',
+    'const item: AvatarGroupItem = <Avatar initials="DZ" alt="Dorothy Zbornak" />;',
+    '```',
+    '',
+    'When using the `items` API, the group normalises both shapes internally so you can freely mix them:',
+    '',
+    '```tsx',
+    'const mixed: AvatarGroupItem[] = [',
+    '  { initials: "DZ", alt: "Dorothy Zbornak" },                       // plain object',
+    '  <Avatar initials="RN" alt="Rose Nylund" size="large" />,          // element',
+    '];',
+    '',
+    '<AvatarGroup items={mixed} label="Mixed item types" />',
+    '```',
+    '',
+    'Use the **items API** when avatar data comes from an API response (plain objects). Use the **children API**',
+    '(`<AvatarGroup><Avatar .../></AvatarGroup>`) when you already have `<Avatar>` instances in your render tree.',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Avatar](?path=/docs/components-avatar--docs) · [Section](?path=/docs/components-section--docs)',
+].join('\n');
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+function AvatarGroupDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "AvatarGroupItem reference" }), _jsx(Markdown, { children: AVATAR_GROUP_ITEM_REFERENCE }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/AvatarGroup',
     component: AvatarGroup,
     tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: { page: AvatarGroupDocsPage },
+    },
+    argTypes: {
+        items: {
+            description: [
+                'Data-driven API. An array of `AvatarGroupItem` values — each item is either an `AvatarProps`',
+                'plain object (`{ initials, alt, src, size, ... }`) or a pre-rendered `<Avatar>` element.',
+                'Mutually exclusive with `children`.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'readonly AvatarGroupItem[]' },
+            },
+        },
+        children: {
+            description: [
+                'Composable API. Render `<Avatar>` elements as children.',
+                'Fragments are supported — nested Avatars inside `<>...</>` are collected automatically.',
+                'Mutually exclusive with `items`.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'React.ReactNode' },
+            },
+        },
+        showMaxItems: {
+            description: [
+                'Maximum number of avatars to render.',
+                'Any additional avatars are replaced by the `+N` overflow count badge.',
+                'When omitted, all avatars are shown with no badge.',
+            ].join(' '),
+            control: { type: 'number', min: 1, max: 20, step: 1 },
+            table: {
+                type: { summary: 'number' },
+                defaultValue: { summary: 'undefined (show all)' },
+            },
+        },
+        listOrder: {
+            description: [
+                '`ascending` (default) shows the **first** N items; `descending` shows the **last** N items.',
+                'Use `descending` for "most recent contributors" patterns where the latest entries are at the end of the array.',
+            ].join(' '),
+            control: { type: 'radio' },
+            options: ['ascending', 'descending'],
+            table: {
+                type: { summary: "'ascending' | 'descending'" },
+                defaultValue: { summary: "'ascending'" },
+            },
+        },
+        label: {
+            description: [
+                'Sets `aria-label` on the root `<ul>`.',
+                '**Required in production** — without it, screen readers announce a generic unnamed list.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        overflowCountLabel: {
+            description: [
+                'Accessible label for the `+N` overflow badge.',
+                'Pass a static string or a function receiving the overflow count.',
+                'Defaults to `"plus N more"` if omitted.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'string | ((count: number) => string)' },
+                defaultValue: { summary: '"plus N more"' },
+            },
+        },
+        presentAllUpdatesToScreenReader: {
+            description: [
+                'When `true`, adds `aria-live="polite"` and `aria-atomic="true"` to the overflow badge,',
+                'so dynamic additions/removals are announced to screen-reader users.',
+                'Only enable on lists that update at runtime.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        size: {
+            description: [
+                'Group-level size override.',
+                '**This wins over any `size` set on individual Avatar items inside the group**,',
+                'ensuring visual consistency across the whole group.',
+            ].join(' '),
+            control: { type: 'select' },
+            options: ['small', 'medium', 'large', 'extra-large'],
+            table: {
+                type: { summary: "'small' | 'medium' | 'large' | 'extra-large'" },
+                defaultValue: { summary: 'undefined (each avatar uses its own size)' },
+            },
+        },
+        className: {
+            description: 'Additional CSS class names applied to the root `<ul>` element.',
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+    },
 };
 export default meta;
-const sampleSrc = (id) => `https://i.pravatar.cc/150?img=${id}`;
-export const FromProps = {
-    render: () => (_jsx(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 = {
-    name: 'Size Override',
-    render: () => (_jsx(AvatarGroup, { label: "All medium even though children are set as small", size: "medium", showMaxItems: 4, items: [
-            _jsx(Avatar, { size: "small", initials: "S1", alt: "Small 1" }, "1"),
-            _jsx(Avatar, { size: "small", initials: "S2", alt: "Small 2" }, "2"),
-            { size: 'small', initials: 'S3', alt: 'Small 3' },
-            { size: 'small', initials: 'S4', alt: 'Small 4' },
-            { size: 'small', initials: 'S5', alt: 'Small 5' },
-        ] })),
+// ---------------------------------------------------------------------------
+// Shared fixture data
+// ---------------------------------------------------------------------------
+const STAFF_ITEMS = [
+    { initials: 'DZ', alt: 'Dorothy Zbornak' },
+    { initials: 'RN', alt: 'Rose Nylund' },
+    { initials: 'BD', alt: 'Blanche Devereaux' },
+    { initials: 'SP', alt: 'Sophia Petrillo' },
+    { initials: 'MW', alt: 'Miles Webber' },
+    { initials: 'SZ', alt: 'Stan Zbornak' },
+    { initials: 'CN', alt: 'Charlie Nylund' },
+];
+const STUDENT_ITEMS = [
+    { initials: 'AT', alt: 'Aisha Thompson' },
+    { initials: 'CF', alt: 'Callum Fraser' },
+    { initials: 'FA', alt: 'Fatima Al-Rashid' },
+    { initials: 'OB', alt: 'Oliver Bennett' },
+    { initials: 'PS', alt: 'Priya Sharma' },
+    { initials: 'DM', alt: 'Declan Murphy' },
+    { initials: 'YT', alt: 'Yuki Tanaka' },
+    { initials: 'AO', alt: 'Amara Osei' },
+];
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: { ...story.parameters?.docs, description: { story: description } },
+    },
+});
+// ---------------------------------------------------------------------------
+// Template components for stateful stories
+// ---------------------------------------------------------------------------
+const LiveOverflowCounterTemplate = () => {
+    const initialItems = [
+        { initials: 'AT', alt: 'Aisha Thompson' },
+        { initials: 'CF', alt: 'Callum Fraser' },
+        { initials: 'FA', alt: 'Fatima Al-Rashid' },
+    ];
+    const extraItems = [
+        { initials: 'OB', alt: 'Oliver Bennett' },
+        { initials: 'PS', alt: 'Priya Sharma' },
+        { initials: 'DM', alt: 'Declan Murphy' },
+        { initials: 'YT', alt: 'Yuki Tanaka' },
+    ];
+    const [items, setItems] = useState(initialItems);
+    const addItem = () => {
+        const next = extraItems[items.length - initialItems.length];
+        if (next)
+            setItems(prev => [...prev, next]);
+    };
+    const removeItem = () => {
+        if (items.length > 1)
+            setItems(prev => prev.slice(0, -1));
+    };
+    return (_jsxs("div", { style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-large)',
+        }, children: [_jsx(AvatarGroup, { items: items, showMaxItems: 3, size: "medium", label: "Active session participants", overflowCountLabel: n => `${n} more participants`, presentAllUpdatesToScreenReader: true }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-medium)' }, children: [_jsx(Button, { variant: "secondary", size: "S", onClick: addItem, disabled: items.length >= initialItems.length + extraItems.length, children: "Add participant" }), _jsx(Button, { variant: "secondary", size: "S", onClick: removeItem, disabled: items.length <= 1, children: "Remove participant" })] }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: [items.length, ' ', "participant", items.length !== 1 ? 's' : '', ' ', "total \u2014 overflow badge shows", ' ', Math.max(0, items.length - 3), ' ', "hidden"] })] }));
 };
-export const ComposableChildren = {
-    name: 'Composable Children',
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        showMaxItems: 4,
+        listOrder: 'ascending',
+        label: 'Teaching staff',
+        size: 'medium',
+        presentAllUpdatesToScreenReader: false,
+    },
+    render: ({ showMaxItems, listOrder, label, size, presentAllUpdatesToScreenReader, className }) => (_jsx(AvatarGroup, { items: STAFF_ITEMS, showMaxItems: showMaxItems, listOrder: listOrder, label: label, size: size, presentAllUpdatesToScreenReader: presentAllUpdatesToScreenReader, className: className })),
+}, 'A fully interactive example — the `items` array is fixed at 7 staff members so the overflow badge is visible by default. '
+    + 'Use the **Controls** panel below to change `showMaxItems`, `size`, `listOrder`, and other props.');
+export const ItemsApi = withDescription({
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Pass `<Avatar />` nodes as `children`.',
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const students = [
+  { initials: 'AT', alt: 'Aisha Thompson' },
+  { initials: 'CF', alt: 'Callum Fraser' },
+  { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  { initials: 'OB', alt: 'Oliver Bennett' },
+  { initials: 'PS', alt: 'Priya Sharma' },
+];
+
+function TutorGroupAvatars() {
+  return (
+    <AvatarGroup
+      items={students}
+      label="Tutor group 9C"
+      size="medium"
+    />
+  );
+}
+export default TutorGroupAvatars;
+`.trim(),
             },
         },
     },
-    render: () => (_jsxs(AvatarGroup, { label: "Team (children API)", showMaxItems: 3, listOrder: "ascending", children: [_jsxs(_Fragment, { children: [_jsx(Avatar, { size: "small", initials: "A", alt: "User A" }), _jsx(Avatar, { size: "small", initials: "B", alt: "User B" })] }), _jsx(Avatar, { size: "small", initials: "C", alt: "User C" }), _jsx(Avatar, { size: "small", initials: "D", alt: "User D" }), _jsx(Avatar, { size: "small", initials: "E", alt: "User E" })] })),
-};
-export const ComposableChildrenDescending = {
-    name: 'Composed + Descending Order',
-    render: () => (_jsxs(AvatarGroup, { label: "Last three visible", size: "medium", showMaxItems: 3, listOrder: "descending", children: [_jsx(Avatar, { initials: "A", alt: "User A" }), _jsx(Avatar, { initials: "B", alt: "User B" }), _jsx(Avatar, { initials: "C", alt: "User C" }), _jsx(Avatar, { initials: "D", alt: "User D" }), _jsx(Avatar, { initials: "E", alt: "User E" })] })),
-};
-export const AscendingWithOverflow = {
-    render: () => (_jsx(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 = {
-    render: () => (_jsx(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 = {
+    render: () => (_jsx(AvatarGroup, { items: STUDENT_ITEMS.slice(0, 5), label: "Tutor group 9C", size: "medium" })),
+}, 'The **items API** is the recommended approach when avatar data arrives as a plain array (e.g. from an API response). '
+    + 'Pass an array of `AvatarGroupItem` values — each can be a plain `AvatarProps` object (`{ initials, alt, src, size, ... }`) '
+    + 'or a pre-rendered `<Avatar>` element.');
+export const ChildrenApi = withDescription({
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Custom `overflowCountLabel` values replace the full screen-reader label for the overflow badge instead of appending to the visible `+N` text.',
+            source: {
+                language: 'tsx',
+                code: `
+import { Avatar, AvatarGroup } from '@arbor-education/design-system.components';
+
+function SLTAvatars() {
+  return (
+    <AvatarGroup label="Senior leadership team" size="medium">
+      <Avatar initials="MP" alt="Margaret Pemberton" />
+      <Avatar initials="DO" alt="David Okafor" />
+      <Avatar initials="SR" alt="Siobhan Reilly" />
+      <Avatar initials="RK" alt="Raj Krishnamurthy" />
+    </AvatarGroup>
+  );
+}
+export default SLTAvatars;
+`.trim(),
             },
         },
     },
-    render: () => (_jsx(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 = {
-    name: 'Announced Overflow Updates',
+    render: () => (_jsxs(AvatarGroup, { label: "Senior leadership team", size: "medium", children: [_jsx(Avatar, { initials: "MP", alt: "Margaret Pemberton" }), _jsx(Avatar, { initials: "DO", alt: "David Okafor" }), _jsx(Avatar, { initials: "SR", alt: "Siobhan Reilly" }), _jsx(Avatar, { initials: "RK", alt: "Raj Krishnamurthy" })] })),
+}, 'The **children API** lets you compose `<Avatar>` elements directly — useful when you already have Avatar '
+    + 'components in your render tree and just want to group them. '
+    + 'Fragments are supported: Avatars inside `<>...</>` wrappers are collected automatically. '
+    + 'The `items` and `children` APIs are mutually exclusive; pick one per component instance.');
+export const AllSizes = withDescription({
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Enables polite live announcements for the built-in overflow badge. Overflow members are not rendered; only the count is shown.',
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const staff = [
+  { initials: 'DZ', alt: 'Dorothy Zbornak' },
+  { initials: 'RN', alt: 'Rose Nylund' },
+  { initials: 'BD', alt: 'Blanche Devereaux' },
+  { initials: 'SP', alt: 'Sophia Petrillo' },
+];
+
+function AllSizesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <AvatarGroup items={staff} size="small"       label="Staff — small"       showMaxItems={3} />
+      <AvatarGroup items={staff} size="medium"      label="Staff — medium"      showMaxItems={3} />
+      <AvatarGroup items={staff} size="large"       label="Staff — large"       showMaxItems={3} />
+      <AvatarGroup items={staff} size="extra-large" label="Staff — extra-large" showMaxItems={3} />
+    </div>
+  );
+}
+export default AllSizesExample;
+`.trim(),
             },
         },
     },
-    render: () => (_jsx(AvatarGroup, { label: "Live updates team", showMaxItems: 2, presentAllUpdatesToScreenReader: true, items: [
-            { initials: 'A', alt: 'User A' },
-            { initials: 'B', alt: 'User B' },
-            { initials: 'C', alt: 'User C' },
-            { initials: 'D', alt: 'User D' },
-        ] })),
-};
+    render: () => (_jsx("div", { style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-large)',
+        }, children: ['small', 'medium', 'large', 'extra-large'].map(size => (_jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-medium)',
+            }, children: [_jsx("span", { className: "ds-text", style: { width: '6rem', color: 'var(--color-grey-600)', flexShrink: 0 }, children: size }), _jsx(AvatarGroup, { items: STAFF_ITEMS.slice(0, 4), size: size, label: `Staff group — ${size}`, showMaxItems: 3 })] }, size))) })),
+}, 'All four avatar sizes — `small`, `medium`, `large`, and `extra-large` — shown side by side. '
+    + 'Use `size` on the group (not on individual items) to keep the stack visually consistent.');
+export const GroupSizeOverride = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+// Each item declares a different individual size
+const mixedItems = [
+  { initials: 'DZ', alt: 'Dorothy Zbornak', size: 'small' as const },
+  { initials: 'RN', alt: 'Rose Nylund',     size: 'extra-large' as const },
+  { initials: 'BD', alt: 'Blanche Devereaux', size: 'large' as const },
+  { initials: 'SP', alt: 'Sophia Petrillo', size: 'small' as const },
+];
+
+function GroupSizeOverrideExample() {
+  return (
+    <>
+      {/* Without group size — renders mixed, inconsistent heights */}
+      <AvatarGroup items={mixedItems} label="Mixed sizes — no override" />
+
+      {/* With group size="medium" — ALL avatars flatten to medium */}
+      <AvatarGroup items={mixedItems} size="medium" label="Group size override to medium" />
+    </>
+  );
+}
+export default GroupSizeOverrideExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => {
+        const mixedItems = [
+            { initials: 'DZ', alt: 'Dorothy Zbornak', size: 'small' },
+            { initials: 'RN', alt: 'Rose Nylund', size: 'extra-large' },
+            { initials: 'BD', alt: 'Blanche Devereaux', size: 'large' },
+            { initials: 'SP', alt: 'Sophia Petrillo', size: 'small' },
+        ];
+        return (_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsxs("div", { children: [_jsx("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: "Without group size \u2014 mixed individual sizes (small / extra-large / large / small):" }), _jsx(AvatarGroup, { items: mixedItems, label: "Mixed sizes \u2014 no group override" })] }), _jsxs("div", { children: [_jsxs("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: ["With", ' ', _jsx("code", { children: "size=\"medium\"" }), ' ', "on the group \u2014 individual sizes are overridden:"] }), _jsx(AvatarGroup, { items: mixedItems, size: "medium", label: "Mixed sizes \u2014 group override to medium" })] })] }));
+    },
+}, 'When you pass `size` to the group, it **overrides** any `size` set on individual items. '
+    + 'The top row has four items each declaring a different size — the result is visually inconsistent. '
+    + 'The bottom row adds `size="medium"` to the group and all avatars snap to the same height.');
+export const WithOverflow = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const students = [
+  { initials: 'AT', alt: 'Aisha Thompson' },
+  { initials: 'CF', alt: 'Callum Fraser' },
+  { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  { initials: 'OB', alt: 'Oliver Bennett' },
+  { initials: 'PS', alt: 'Priya Sharma' },
+  { initials: 'DM', alt: 'Declan Murphy' },
+  { initials: 'YT', alt: 'Yuki Tanaka' },
+  { initials: 'AO', alt: 'Amara Osei' },
+];
+
+function OverflowExample() {
+  return (
+    <AvatarGroup
+      items={students}
+      showMaxItems={4}
+      label="Year 8 English students"
+      size="medium"
+    />
+  );
+}
+export default OverflowExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx(AvatarGroup, { items: STUDENT_ITEMS, showMaxItems: 4, label: "Year 8 English students", size: "medium" })),
+}, '`showMaxItems` caps the rendered avatars and replaces the remainder with a `+N` overflow badge. '
+    + 'Here 8 students are in the list but only 4 are shown — the badge reads **+4**. '
+    + 'The badge carries `role="status"` and an accessible label (`"plus 4 more"` by default).');
+export const DescendingOverflow = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+// Items ordered chronologically — most recent is last in the array
+const recentContributors = [
+  { initials: 'HN', alt: 'Harriet Nwosu' },   // oldest
+  { initials: 'LM', alt: 'Leo Marchetti' },
+  { initials: 'SuP', alt: 'Sunita Patel' },
+  { initials: 'TH', alt: 'Tomás Herrera' },
+  { initials: 'IC', alt: 'Imogen Clarke' },
+  { initials: 'KA', alt: 'Kwame Asante' },     // most recent
+];
+
+function DescendingExample() {
+  return (
+    <>
+      {/* ascending — shows FIRST 3 (Harriet, Leo, Sunita) */}
+      <AvatarGroup
+        items={recentContributors}
+        showMaxItems={3}
+        listOrder="ascending"
+        label="Recent contributors — ascending"
+      />
+
+      {/* descending — shows LAST 3 (Tomás, Imogen, Kwame) */}
+      <AvatarGroup
+        items={recentContributors}
+        showMaxItems={3}
+        listOrder="descending"
+        label="Recent contributors — descending"
+      />
+    </>
+  );
+}
+export default DescendingExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => {
+        const contributors = [
+            { initials: 'HN', alt: 'Harriet Nwosu' },
+            { initials: 'LM', alt: 'Leo Marchetti' },
+            { initials: 'SuP', alt: 'Sunita Patel' },
+            { initials: 'TH', alt: 'Tomás Herrera' },
+            { initials: 'IC', alt: 'Imogen Clarke' },
+            { initials: 'KA', alt: 'Kwame Asante' },
+        ];
+        return (_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsxs("div", { children: [_jsxs("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: [_jsx("code", { children: "listOrder=\"ascending\"" }), ' ', "\u2014 shows the", ' ', _jsx("strong", { children: "first" }), ' ', "3 (Harriet, Leo, Sunita):"] }), _jsx(AvatarGroup, { items: contributors, showMaxItems: 3, listOrder: "ascending", label: "Recent contributors \u2014 ascending", size: "medium" })] }), _jsxs("div", { children: [_jsxs("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: [_jsx("code", { children: "listOrder=\"descending\"" }), ' ', "\u2014 shows the", ' ', _jsx("strong", { children: "last" }), ' ', "3 (Tom\u00E1s, Imogen, Kwame):"] }), _jsx(AvatarGroup, { items: contributors, showMaxItems: 3, listOrder: "descending", label: "Recent contributors \u2014 descending", size: "medium" })] })] }));
+    },
+}, '`listOrder` controls **which** items are shown when `showMaxItems` trims the list. '
+    + '`ascending` (default) keeps the **first** N items; `descending` keeps the **last** N items. '
+    + 'This is ideal for "most recent contributors" patterns where new entries are appended to the end of the array.');
+export const CustomOverflowLabel = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+function CustomOverflowLabelExample() {
+  return (
+    <AvatarGroup
+      items={students}
+      showMaxItems={3}
+      label="Students in tutor group 7B"
+      size="medium"
+      overflowCountLabel={(n) => \`\${n} more students not shown\`}
+    />
+  );
+}
+export default CustomOverflowLabelExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx(AvatarGroup, { items: STUDENT_ITEMS, showMaxItems: 3, label: "Students in tutor group 7B", size: "medium", overflowCountLabel: n => `${n} more students not shown` })),
+}, '`overflowCountLabel` accepts a **function** receiving the overflow count and returning an accessible label string. '
+    + 'This example produces `aria-label="5 more students not shown"` on the badge — far more descriptive than the default `"plus 5 more"`. '
+    + 'A plain `string` also works if the label does not need to reflect the count dynamically.');
+export const WithAriaLabel = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+function WithAriaLabelExample() {
+  return (
+    // Always supply label — without it, screen readers announce a nameless list
+    <AvatarGroup
+      items={formTutors}
+      label="Form tutors for Year 11"
+      size="medium"
+    />
+  );
+}
+export default WithAriaLabelExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-large)',
+        }, children: [_jsxs("div", { children: [_jsxs("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: ["With", ' ', _jsx("code", { children: "label" }), ' ', "\u2014 screen reader announces \u201CForm tutors for Year 11, list, 4 items\u201D:"] }), _jsx(AvatarGroup, { items: STAFF_ITEMS.slice(0, 4), label: "Form tutors for Year 11", size: "medium" })] }), _jsxs("div", { children: [_jsxs("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-semantic-destructive-600)' }, children: ["Without", ' ', _jsx("code", { children: "label" }), ' ', "\u2014 screen reader announces \u201Clist, 4 items\u201D (avoid in production):"] }), _jsx(AvatarGroup, { items: STAFF_ITEMS.slice(0, 4), size: "medium" })] })] })),
+}, 'The `label` prop sets `aria-label` on the root `<ul>`. '
+    + 'Without it, screen-reader users hear "list of N items" with no context about what the group represents. '
+    + '**Always provide a meaningful label in production.**');
+export const LiveOverflowCounter = withDescription({
+    render: () => _jsx(LiveOverflowCounterTemplate, {}),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Button, AvatarGroup } from '@arbor-education/design-system.components';
+
+function LiveOverflowCounterExample() {
+  const [items, setItems] = useState([
+    { initials: 'AT', alt: 'Aisha Thompson' },
+    { initials: 'CF', alt: 'Callum Fraser' },
+    { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  ]);
+
+  return (
+    <>
+      <AvatarGroup
+        items={items}
+        showMaxItems={3}
+        size="medium"
+        label="Active session participants"
+        overflowCountLabel={(n) => \`\${n} more participants\`}
+        presentAllUpdatesToScreenReader
+      />
+      <Button
+        variant="secondary"
+        size="S"
+        onClick={() => setItems(prev => [...prev, { initials: 'NP', alt: 'New Participant' }])}
+      >
+        Add participant
+      </Button>
+    </>
+  );
+}
+export default LiveOverflowCounterExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A live demo of `presentAllUpdatesToScreenReader`. '
+    + 'Use the buttons to add or remove participants — the overflow badge updates and each count change is announced '
+    + 'to screen readers via `aria-live="polite"`. '
+    + 'Only enable this on groups whose membership changes at runtime — on static groups it creates unnecessary noise.');
 //# sourceMappingURL=AvatarGroup.stories.js.map