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

package/src/components/singleUser/SingleUser.stories.tsx

@@ -1,63 +1,422 @@
 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 { SingleUser } from './SingleUser';
 
+// ---------------------------------------------------------------------------
+// Content strings for the custom DocsPage
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`SingleUser` renders a user identity pill — an avatar paired with a visible name label.',
+  'The avatar is always decorative (`aria-hidden="true"`) so the `label` prop is the sole accessible name for the element.',
+  'The component is built on top of the [`Avatar`](?path=/docs/components-avatar--docs) component and inherits its `src` and `initials` props.',
+].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',
+  '',
+  '- Displaying a named user inline — in a table cell, a row label, a card header, or a list of assignees.',
+  '- Anywhere a bare avatar would lack context — the label removes ambiguity about who the avatar represents.',
+  '- As a compact, non-interactive identity chip (e.g. "Assigned to · Sarah Okafor").',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Multiple users side by side | [`AvatarGroup`](?path=/docs/components-avatargroup--docs) |',
+  '| Avatar without a text label | [`Avatar`](?path=/docs/components-avatar--docs) directly |',
+  '| Clickable user link | Wrap `SingleUser` in an anchor or use a `Row` with `onClick` |',
+  '| User selection | A dropdown or autocomplete input |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Avatar is always decorative',
+  '',
+  'The inner `Avatar` is always rendered with `aria-hidden="true"` and `alt=""`. This means:',
+  '',
+  "- The `label` prop is the **only** accessible name — ensure it contains the user's full name.",
+  '- Screen readers announce the label text only; they will not announce initials or image alt text.',
+  '- You **cannot** override this behaviour via props — it is intentional design.',
+  '',
+  '---',
+  '',
+  '### Two className props',
+  '',
+  '`SingleUser` accepts two distinct `className` props:',
+  '',
+  '| Prop | Target element | Use case |',
+  '|---|---|---|',
+  '| `className` | Root `<span>` | Outer layout, margins, flex order |',
+  '| `avatarClassName` | Inner `<Avatar>` | Avatar-specific overrides |',
+  '',
+  '---',
+  '',
+  '### Default size is `"small"`',
+  '',
+  '> **Important:** `SingleUser` defaults to `size="small"`, not `"medium"` (which is `Avatar`\'s own default).',
+  '> Always pass `size` explicitly when a specific size is required.',
+  '',
+  '---',
+  '',
+  '### forwardRef',
+  '',
+  '`SingleUser` uses `React.forwardRef` and exposes a ref to the root `<span>` element.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { SingleUser } from '@arbor-education/design-system.components';",
+  "import type { SingleUserProps } from '@arbor-education/design-system.components';",
+  '',
+  'type SingleUserProps = {',
+  '  label: string;            // required — also the only accessible name',
+  '  className?: string;       // applied to the root <span>',
+  '  avatarClassName?: string; // applied to the inner <Avatar>',
+  "  size?: 'small' | 'medium' | 'large' | 'extra-large'; // default: 'small'",
+  '  src?: string;             // avatar image URL',
+  '  initials?: string;        // shown when src is absent or fails to load',
+  '  // ...plus remaining AvatarProps (excluding className, alt, size)',
+  '};',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Avatar](?path=/docs/components-avatar--docs) · [AvatarGroup](?path=/docs/components-avatargroup--docs) · [Row](?path=/docs/components-row--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function SingleUserDocsPage() {
+  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 SingleUser> = {
   title: 'Components/SingleUser',
   component: SingleUser,
   tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SingleUserDocsPage,
+    },
+  },
+  argTypes: {
+    label: {
+      description: [
+        'The visible name label rendered alongside the avatar.',
+        'This is also the **only** accessible name — the inner avatar is always `aria-hidden`.',
+        "Always pass the user's full name.",
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    size: {
+      description: [
+        'Controls the size of the inner avatar.',
+        "Defaults to `\"small\"` — note this differs from `Avatar`'s own default of `\"medium\"`.",
+      ].join(' '),
+      control: 'select',
+      options: ['small', 'medium', 'large', 'extra-large'],
+      table: {
+        type: { summary: "'small' | 'medium' | 'large' | 'extra-large'" },
+        defaultValue: { summary: "'small'" },
+      },
+    },
+    src: {
+      description: [
+        'URL of the avatar image.',
+        'When absent or broken, `initials` are used as a fallback.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    initials: {
+      description:
+        'One or two initials shown inside the avatar when no `src` is provided or when the image fails to load.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      description: [
+        'Additional CSS class names applied to the **root** `<span>` wrapper.',
+        'Use `avatarClassName` to target the inner avatar specifically.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    avatarClassName: {
+      description: [
+        'Additional CSS class names applied only to the **inner** `<Avatar>` element.',
+        'Useful for avatar-specific overrides without affecting the root layout.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
 };
 
 export default meta;
-
 type Story = StoryObj<typeof SingleUser>;
 
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
 const withDescription = (story: Story, description: string): Story => ({
   ...story,
   parameters: {
     ...story.parameters,
-    docs: {
-      ...story.parameters?.docs,
-      description: {
-        story: description,
-      },
-    },
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
 });
 
-const sampleSrc = 'https://i.pravatar.cc/150?img=12';
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-export const WithImage: Story = withDescription({
-  args: {
-    label: 'Jordan Matthews',
-    src: sampleSrc,
+export const Default: Story = withDescription(
+  {
+    args: {
+      label: 'Sarah Okafor',
+      initials: 'SO',
+      size: 'small',
+    },
+    render: args => <SingleUser {...args} />,
   },
-}, 'Displays `SingleUser` with an avatar image and the default small layout.');
+  'The default story is wired to the Controls panel. Adjust `label`, `initials`, `src`, and `size` to see the component update in real time.',
+);
+
+export const WithPhoto: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SingleUser } from '@arbor-education/design-system.components';
 
-export const WithInitials: Story = withDescription({
-  args: {
-    label: 'Riley Chen',
-    initials: 'RC',
+function TeacherIdentity() {
+  return (
+    <SingleUser
+      label="Miss Clara Jones"
+      src="https://i.pravatar.cc/150?img=47"
+      size="medium"
+    />
+  );
+}
+export default TeacherIdentity;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <SingleUser
+        label="Miss Clara Jones"
+        src="https://i.pravatar.cc/150?img=47"
+        size="medium"
+      />
+    ),
   },
-}, 'Uses initials when no image source is provided.');
+  'When a `src` URL is provided the avatar displays the photo. If the image fails to load, the component falls back to `initials` if supplied. The avatar is still `aria-hidden` regardless — `label` remains the only accessible name.',
+);
+
+export const AllSizes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SingleUser } from '@arbor-education/design-system.components';
 
-export const Placeholder: Story = withDescription({
-  args: {
-    label: 'Invited user',
+function SizeShowcase() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+      <SingleUser label="James Okafor" initials="JO" size="small" />
+      <SingleUser label="James Okafor" initials="JO" size="medium" />
+      <SingleUser label="James Okafor" initials="JO" size="large" />
+      <SingleUser label="James Okafor" initials="JO" size="extra-large" />
+    </div>
+  );
+}
+export default SizeShowcase;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+        <SingleUser label="James Okafor" initials="JO" size="small" />
+        <SingleUser label="James Okafor" initials="JO" size="medium" />
+        <SingleUser label="James Okafor" initials="JO" size="large" />
+        <SingleUser label="James Okafor" initials="JO" size="extra-large" />
+      </div>
+    ),
+  },
+  "All four supported sizes. `\"small\"` is the **default** — which differs from the underlying `Avatar` component's own default of `\"medium\"`. Always pass `size` explicitly when a specific size is required.",
+);
+
+export const InitialsFallback: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SingleUser } from '@arbor-education/design-system.components';
+
+function StaffList() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <SingleUser label="Dorothy Zbornak" initials="DZ" />
+      <SingleUser label="Rose Nylund" initials="RN" />
+      <SingleUser label="Blanche Devereaux" initials="BD" />
+      <SingleUser label="Sophia Petrillo" initials="SP" />
+    </div>
+  );
+}
+export default StaffList;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        <SingleUser label="Dorothy Zbornak" initials="DZ" />
+        <SingleUser label="Rose Nylund" initials="RN" />
+        <SingleUser label="Blanche Devereaux" initials="BD" />
+        <SingleUser label="Sophia Petrillo" initials="SP" />
+      </div>
+    ),
   },
-}, 'Shows the placeholder avatar treatment when neither image nor initials are supplied.');
+  'When no `src` is provided, the avatar falls back to `initials`. One or two characters are recommended for legibility across all sizes.',
+);
 
-export const MediumAvatar: Story = withDescription({
-  name: 'Size override (medium)',
-  args: {
-    label: 'Taylor Brooks',
-    initials: 'TB',
-    size: 'medium',
+export const TwoClassNameProps: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SingleUser } from '@arbor-education/design-system.components';
+
+function AssignedUser() {
+  return (
+    <SingleUser
+      label="Amara Osei-Bonsu"
+      initials="AO"
+      className="my-root-override"
+      avatarClassName="my-avatar-override"
+    />
+  );
+}
+export default AssignedUser;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <SingleUser
+        label="Amara Osei-Bonsu"
+        initials="AO"
+        className="my-root-override"
+        avatarClassName="my-avatar-override"
+      />
+    ),
   },
-}, 'Demonstrates overriding the default avatar size within the SingleUser pill.');
+  '`SingleUser` exposes two separate `className` props: `className` targets the **root `<span>`** and `avatarClassName` targets only the **inner `<Avatar>`**. Use them independently to avoid unintended style bleed.',
+);
 
-export const LongLabel: Story = withDescription({
-  args: {
-    label: 'Dr. Alexandrina Constantinopolous-Worthington',
-    initials: 'AC',
+export const LongLabel: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SingleUser } from '@arbor-education/design-system.components';
+
+function LongNameExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <SingleUser label="Mrs Jacqueline Abernathy-Thornton" initials="JA" />
+      <SingleUser label="Mr Bartholomew Featherington-Smythe" initials="BF" size="medium" />
+    </div>
+  );
+}
+export default LongNameExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        <SingleUser label="Mrs Jacqueline Abernathy-Thornton" initials="JA" />
+        <SingleUser label="Mr Bartholomew Featherington-Smythe" initials="BF" size="medium" />
+      </div>
+    ),
   },
-}, 'Exercises the component with a longer label so text wrapping and spacing can be reviewed.');
+  'Long display names flow naturally — the label has no enforced max-width and extends the pill as needed. Apply a width constraint via `className` if truncation is required.',
+);