@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/avatar/Avatar.stories.tsx

@@ -1,92 +1,537 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+
 import { Avatar } from './Avatar';
 
+// ---------------------------------------------------------------------------
+// Content strings
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Avatar` displays a visual identity for a person — a photograph, a set of initials, or a',
+  'fallback silhouette — in a consistently-sized, circular container.',
+  'It is the foundational building block for staff lists, pupil profiles, message threads,',
+  'and anywhere a face or identity marker is needed across the Arbor platform.',
+].join('\n');
+
+const PROPS_INTRO
+  = 'The preview below is wired to the **Controls** panel — adjust any prop and the canvas updates live. Try switching the `size`, clearing `src` to see initials mode, and then clearing `initials` too to see the placeholder silhouette.';
+
+const USAGE_GUIDANCE = [
+  '### Choosing a size',
+  '',
+  '| Size | CSS token | Typical context |',
+  '|---|---|---|',
+  '| `small` | `--avatar-small-size` | Dense lists, table rows, inline chips |',
+  '| `medium` | `--avatar-medium-size` | Standard list items, message previews (default) |',
+  '| `large` | `--avatar-large-size` | Cards, sidebars, expanded list items |',
+  '| `extra-large` | `--avatar-extra-large-size` | Profile headers, detail pages |',
+  '',
+  '---',
+  '',
+  '### When to use',
+  '',
+  '- To represent a teacher, pupil, guardian, or staff member visually.',
+  '- In lists, tables, message threads, profile headers, and contact cards.',
+  '- When a face or personal identifier makes a list row easier to scan.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Representing organisations, schools, or non-person entities | An icon or logo |',
+  '| Purely decorative circular shapes | A styled `<span>` or CSS directly |',
+  '| When a name alone is sufficient | Plain text — no avatar needed |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Rendering priority',
+  '',
+  '`src` always wins. If you pass both `src` and `initials`, the image is rendered and',
+  'the initials are ignored. Pass both props together if you want initials as a visual',
+  'fallback — but note there is no built-in `onError` handler. If the image URL is broken,',
+  'the browser\'s default broken-image treatment shows. Handle `onError` via `...rest`',
+  'or manage `src` state externally.',
+  '',
+  '---',
+  '',
+  '### The `alt` prop serves three purposes',
+  '',
+  '| Mode | Where `alt` goes |',
+  '|---|---|',
+  '| Image | `<img alt={alt}>` |',
+  '| Initials | `<span aria-label={alt}>` around the initials text |',
+  '| Placeholder | `<span aria-label={alt \\|\\| "User avatar"}>` around the SVG |',
+  '',
+  'When `alt` is an empty string (the default) and initials mode is active, screen readers',
+  'read the raw initials text. Always set `alt` to the person\'s full name for initials and',
+  'placeholder modes.',
+  '',
+  '---',
+  '',
+  '### Avatar is an inline element',
+  '',
+  'The root renders as a `<span>` — an inline element.',
+  'When placing Avatar next to text inside a flex container, always set `alignItems: "center"`',
+  'on the wrapper so the avatar sits correctly alongside the text baseline.',
+  '',
+  '---',
+  '',
+  '### Design tokens',
+  '',
+  'Each size has its own CSS custom properties:',
+  '',
+  '```',
+  '--avatar-small-size           --avatar-small-radius',
+  '--avatar-small-color-border   --avatar-small-color-background',
+  '',
+  '--avatar-medium-size          --avatar-medium-radius',
+  '--avatar-medium-color-border  --avatar-medium-color-background',
+  '--avatar-medium-color-text    ← text colour, only defined for medium',
+  '',
+  '--avatar-large-size           --avatar-large-radius',
+  '--avatar-large-color-border   --avatar-large-color-background',
+  '',
+  '--avatar-extra-large-size     --avatar-extra-large-radius',
+  '--avatar-extra-large-color-border  --avatar-extra-large-color-background',
+  '```',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Avatar } from '@arbor-education/design-system.components';",
+  '',
+  'type AvatarProps = Avatar.Props;',
+  "type AvatarSize  = Avatar.Size; // 'small' | 'medium' | 'large' | 'extra-large'",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[AvatarGroup](?path=/docs/components-avatargroup--docs) · [SingleUser](?path=/docs/components-singleuser--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function AvatarDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
 const meta: Meta<typeof Avatar> = {
   title: 'Components/Avatar',
   component: Avatar,
   tags: ['autodocs'],
   parameters: {
-    docs: {
-      description: {
-        component:
-          'Renders a user avatar as a `<span>`',
-      },
-    },
+    layout: 'padded',
+    docs: { page: AvatarDocsPage },
   },
   argTypes: {
     size: {
-      control: 'select',
+      description: [
+        'Controls the diameter of the avatar.',
+        'Use `small` for dense lists, `medium` (default) for standard contexts,',
+        '`large` for cards and sidebars, and `extra-large` for profile headers.',
+        'Note: the correct value is `"extra-large"` — not `"xl"`.',
+      ].join(' '),
+      control: { type: 'select' },
       options: ['small', 'medium', 'large', 'extra-large'],
+      table: {
+        type: { summary: "'small' | 'medium' | 'large' | 'extra-large'" },
+        defaultValue: { summary: "'medium'" },
+      },
+    },
+    src: {
+      description: [
+        'URL of the person\'s photograph.',
+        'When provided, the image is rendered and `initials` is ignored entirely.',
+        'There is no built-in `onError` fallback — handle broken images externally via `...rest` or by managing `src` state.',
+      ].join(' '),
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    alt: {
+      description: [
+        'Accessible label for the avatar.',
+        'In image mode it becomes the `<img alt>` attribute.',
+        'In initials mode it becomes `aria-label` on the initials span.',
+        'In placeholder mode it becomes `aria-label` on the SVG wrapper (defaulting to `"User avatar"` when empty).',
+        'Always set this to the person\'s full name.',
+      ].join(' '),
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "''" },
+      },
+    },
+    initials: {
+      description: [
+        'Short string (typically 1–2 characters) shown when no `src` is provided.',
+        'Rendered on a coloured circular background.',
+        'Silently ignored when `src` is present.',
+      ].join(' '),
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      description: [
+        'Additional CSS class names applied to the root `<span>` element,',
+        'alongside the built-in `ds-avatar` and `ds-avatar--{size}` classes.',
+      ].join(' '),
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
 };
 
-type Story = StoryObj<typeof Avatar>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
 
-export const Default: Story = {
-  args: {
-    size: 'medium',
-    src: 'https://i.pravatar.cc/150?img=1',
-    alt: 'User avatar',
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
-};
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-export const WithInitials: Story = {
-  args: {
-    size: 'medium',
-    initials: 'CM',
-    alt: 'Christine Montgomery',
+export const Default: Story = withDescription(
+  {
+    args: {
+      size: 'medium',
+      src: 'https://i.pravatar.cc/150?img=1',
+      alt: 'Amara Osei-Bonsu',
+    },
+    render: args => <Avatar {...args} />,
   },
-};
+  'The default story is wired to the Controls panel. Clear `src` to switch to initials mode, then clear `initials` to see the placeholder silhouette. Toggle `size` to compare the four diameter options.',
+);
 
-export const Placeholder: Story = {
-  args: {
-    size: 'medium',
-    alt: 'User avatar',
+export const WithInitials: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+function WithInitialsExample() {
+  return (
+    <Avatar
+      size="medium"
+      initials="JB"
+      alt="Jacob Black"
+    />
+  );
+}
+export default WithInitialsExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => <Avatar size="medium" initials="JB" alt="Jacob Black" />,
   },
-};
+  'When no photo is available, pass `initials` (typically the person\'s first and last initial). The component renders them on a coloured circular background. Screen readers announce the full name from the `alt` prop rather than spelling out the raw letters.',
+);
 
-export const Small: Story = {
-  args: {
-    size: 'small',
-    src: 'https://i.pravatar.cc/150?img=2',
-    alt: 'User avatar',
+export const Placeholder: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+function PlaceholderExample() {
+  return (
+    <Avatar
+      size="medium"
+      alt="Unknown staff member"
+    />
+  );
+}
+export default PlaceholderExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => <Avatar size="medium" alt="Unknown staff member" />,
   },
-};
+  'When neither `src` nor `initials` is provided, a generic person-silhouette SVG renders. The `alt` prop becomes the `aria-label`; if `alt` is also empty it defaults to `"User avatar"`. Use this for anonymous or as-yet-unknown users.',
+);
 
-export const Medium: Story = {
-  args: {
-    size: 'medium',
-    src: 'https://i.pravatar.cc/150?img=3',
-    alt: 'User avatar',
+export const AllRenderingModes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+function AllRenderingModesExample() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+      <Avatar size="medium" src="https://i.pravatar.cc/150?img=5" alt="Sarah Thompson" />
+      <Avatar size="medium" initials="MP" alt="Mrs Patel" />
+      <Avatar size="medium" alt="Unknown user" />
+    </div>
+  );
+}
+export default AllRenderingModesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+        <Avatar size="medium" src="https://i.pravatar.cc/150?img=5" alt="Sarah Thompson" />
+        <Avatar size="medium" initials="MP" alt="Mrs Patel" />
+        <Avatar size="medium" alt="Unknown user" />
+      </div>
+    ),
   },
-};
+  'All three rendering modes side by side at the same size: **image** (left), **initials** (centre), **placeholder** (right). All three share the same container size and shape — only the inner content differs.',
+);
+
+export const AllSizes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
 
-export const Large: Story = {
-  args: {
-    size: 'large',
-    src: 'https://i.pravatar.cc/150?img=4',
-    alt: 'User avatar',
+function AllSizesExample() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '1rem', padding: '1rem' }}>
+      <Avatar size="small"       src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+      <Avatar size="medium"      src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+      <Avatar size="large"       src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+      <Avatar size="extra-large" src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+    </div>
+  );
+}
+export default AllSizesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '1rem', padding: '1rem' }}>
+        <Avatar size="small" src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+        <Avatar size="medium" src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+        <Avatar size="large" src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+        <Avatar size="extra-large" src="https://i.pravatar.cc/150?img=10" alt="Amara Osei-Bonsu" />
+      </div>
+    ),
   },
-};
+  'All four sizes — `small`, `medium`, `large`, and `extra-large` — shown together. Note the correct prop value is `"extra-large"`, not `"xl"`.',
+);
 
-export const ExtraLarge: Story = {
-  args: {
-    size: 'extra-large',
-    src: 'https://i.pravatar.cc/150?img=5',
-    alt: 'User avatar',
+export const ImageTakesPriorityOverInitials: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+function ImagePriorityExample() {
+  // Passing both src and initials is safe — src always wins.
+  // If the image later becomes unavailable, initials act as a visual fallback.
+  return (
+    <Avatar
+      size="large"
+      src="https://i.pravatar.cc/150?img=3"
+      initials="SD"
+      alt="Mr Davies"
+    />
+  );
+}
+export default ImagePriorityExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Avatar
+        size="large"
+        src="https://i.pravatar.cc/150?img=3"
+        initials="SD"
+        alt="Mr Davies"
+      />
+    ),
   },
-};
+  'Both `src` and `initials` are passed here, but the photo always wins — initials are silently ignored when `src` is present. Passing both is a safe, intentional pattern for graceful degradation (though note there is no built-in `onError` handler for broken image URLs).',
+);
+
+export const SmallInListContext: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+const staffMembers = [
+  { src: 'https://i.pravatar.cc/150?img=20', initials: 'AO', name: 'Amara Osei-Bonsu', role: 'Head of Year 9' },
+  { src: 'https://i.pravatar.cc/150?img=21', initials: 'SD', name: 'Mr Davies',         role: 'Mathematics' },
+  { src: undefined,                           initials: 'NP', name: 'Mrs Patel',          role: 'Cover Supervisor' },
+  { src: undefined,                           initials: undefined, name: 'Supply Teacher', role: 'Not yet confirmed' },
+];
 
-export const AllSizes: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
-      <Avatar size="small" src="https://i.pravatar.cc/150?img=6" alt="Small avatar" />
-      <Avatar size="medium" src="https://i.pravatar.cc/150?img=7" alt="Medium avatar" />
-      <Avatar size="large" src="https://i.pravatar.cc/150?img=8" alt="Large avatar" />
-      <Avatar size="extra-large" src="https://i.pravatar.cc/150?img=9" alt="Extra large avatar" />
+function StaffListExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+      {staffMembers.map(({ src, initials, name, role }) => (
+        <div key={name} style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+          <Avatar size="small" src={src} initials={initials} alt={name} />
+          <span className="ds-text"><strong>{name}</strong> — {role}</span>
+        </div>
+      ))}
     </div>
-  ),
-};
+  );
+}
+export default StaffListExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => {
+      const staffMembers = [
+        { src: 'https://i.pravatar.cc/150?img=20', initials: 'AO', name: 'Amara Osei-Bonsu', role: 'Head of Year 9' },
+        { src: 'https://i.pravatar.cc/150?img=21', initials: 'SD', name: 'Mr Davies', role: 'Mathematics' },
+        { src: undefined, initials: 'NP', name: 'Mrs Patel', role: 'Cover Supervisor' },
+        { src: undefined, initials: undefined, name: 'Supply Teacher', role: 'Not yet confirmed' },
+      ];
+      return (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+          {staffMembers.map(({ src, initials, name, role }) => (
+            <div key={name} style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+              <Avatar size="small" src={src} initials={initials} alt={name} />
+              <span className="ds-text">
+                <strong>{name}</strong>
+                {' '}
+                —
+                {' '}
+                {role}
+              </span>
+            </div>
+          ))}
+        </div>
+      );
+    },
+  },
+  'A realistic staff list showing all three rendering modes at `small` size. The first two rows have photos, the third has initials only, and the fourth shows the placeholder silhouette. Note `alignItems: "center"` on each row — required because Avatar is an inline `<span>` element.',
+);
 
-export default meta;
+export const ExtraLargeProfile: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar } from '@arbor-education/design-system.components';
+
+function ProfileHeaderExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '0.75rem' }}>
+      <Avatar
+        size="extra-large"
+        src="https://i.pravatar.cc/150?img=47"
+        alt="Jacob Black"
+      />
+      <div style={{ textAlign: 'center' }}>
+        <p className="ds-text"><strong>Jacob Black</strong></p>
+        <p className="ds-text">Year 10 · Form 10B</p>
+      </div>
+    </div>
+  );
+}
+export default ProfileHeaderExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '0.75rem' }}>
+        <Avatar
+          size="extra-large"
+          src="https://i.pravatar.cc/150?img=47"
+          alt="Jacob Black"
+        />
+        <div style={{ textAlign: 'center' }}>
+          <p className="ds-text"><strong>Jacob Black</strong></p>
+          <p className="ds-text">Year 10 · Form 10B</p>
+        </div>
+      </div>
+    ),
+  },
+  'The `extra-large` size (6rem / 96px) is designed for profile headers where the person\'s identity is the focal point of the view. Pair it with the person\'s full name and a short contextual label beneath.',
+);