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

package/src/components/section/Section.stories.tsx

@@ -1,90 +1,743 @@
-import type { Meta } from '@storybook/react-vite';
-import { Section } from './Section';
+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 { fn } from 'storybook/test';
+
 import { Row } from 'Components/row/Row';
+import { Section } from './Section';
+
+// ---------------------------------------------------------------------------
+// Content strings for the custom DocsPage
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Section` is a structural layout component that wraps a labelled content region.',
+  'It renders a semantic `<section>` element with an optional title heading, an optional action button,',
+  'and optional collapse/expand behaviour.',
+  'Sections can be nested to create hierarchical content structures — nested sections automatically',
+  'lose their horizontal padding to maintain visual rhythm.',
+].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',
+  '',
+  '- Grouping related content within a page or panel under a descriptive heading (e.g. "Personal Details", "Contact Information").',
+  '- Providing a collapsible region where space is at a premium and the content can reasonably be hidden by default.',
+  '- Pairing with an action button in the heading to give quick access to a related action (e.g. "Edit", "Add").',
+  '- Nesting sections to model a parent/child hierarchy — e.g. a "Student Profile" section containing "Personal Details" and "Academic" sub-sections.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Full-page layout regions | Native `<main>`, `<aside>`, or `<article>` elements |',
+  '| Overlay or modal content | [`Modal`](?path=/docs/components-modals-modal--docs) or [`Slideover`](?path=/docs/components-slideover--docs) |',
+  '| Tabbed content panels | A tab component with panel regions |',
+  '| Purely decorative grouping with no heading | A plain `<div>` — `Section` always renders a heading element |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### `collapsed` is initial state only',
+  '',
+  'The `collapsed` prop sets the **initial** collapsed state — the component becomes self-managed (uncontrolled) after mount.',
+  '`Section` owns the expanded/collapsed state internally via `useState(initialCollapsed)`.',
+  'You cannot control the expanded state from outside after the component has mounted.',
+  'If you need fully controlled behaviour, you will need a custom implementation.',
+  '',
+  '---',
+  '',
+  '### `headingLevel` defaults to `1` — use with care',
+  '',
+  '`headingLevel` defaults to `1`, which renders an `<h1>`. Most pages should have only one `<h1>`.',
+  'Always set an explicit `headingLevel` appropriate to the heading hierarchy of the page.',
+  'Use `2` for top-level sections on a page that already has an `<h1>`, and `3` or `4` for nested sub-sections.',
+  '',
+  '---',
+  '',
+  '### Button props must all be provided together',
+  '',
+  'The action button only renders when `buttonText` is provided.',
+  'When adding a button, always supply all four props together: `buttonText`, `buttonOnClick`, `buttonVariant`, and `buttonSize`.',
+  'If any are omitted, the `Button` component falls back to its own defaults, which may produce unexpected visual results.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The `<section>` renders with a hardcoded `aria-label="section"` to give it an implicit `role="region"`. This label is not configurable.',
+  '- When `collapsible` is `true`, a `<button>` with `aria-expanded` is rendered in the heading — this is the accessible toggle.',
+  '- The heading element gains `tabIndex={0}` and responds to **Enter** and **Space** when collapsible.',
+  '- Title icons should always include `titleIconScreenReaderText` unless they are purely decorative and the title fully describes the section.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Section } from '@arbor-education/design-system.components';",
+  '',
+  'type SectionProps = Section.Props;',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Row](?path=/docs/components-row--docs) · [Card](?path=/docs/components-card--docs) · [Heading](?path=/docs/components-heading--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function SectionDocsPage() {
+  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 Section> = {
   title: 'Components/Section',
   component: Section,
-  globals: {
-    backgrounds: { value: 'dark' },
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SectionDocsPage,
+    },
+  },
+  argTypes: {
+    title: {
+      description: 'Heading text rendered at the top of the section.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    headingLevel: {
+      description: [
+        'The HTML heading level rendered for the section title.',
+        'Defaults to `1` (an `<h1>`) — always set this explicitly to match the page heading hierarchy.',
+        'Use `2` for top-level sections, `3` or `4` for nested sub-sections.',
+      ].join(' '),
+      control: 'select',
+      options: [1, 2, 3, 4],
+      table: {
+        type: { summary: '1 | 2 | 3 | 4' },
+        defaultValue: { summary: '1' },
+      },
+    },
+    titleIconName: {
+      description: [
+        'Icon rendered immediately after the title text.',
+        'Pass `titleIconScreenReaderText` if the icon carries semantic meaning.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'IconName' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    titleIconColor: {
+      description: 'CSS colour value applied to the title icon (e.g. `var(--color-brand-600)` or a hex string).',
+      control: 'color',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    titleIconScreenReaderText: {
+      description: [
+        'Accessible label for the title icon.',
+        'Omit only when the icon is purely decorative and the title already conveys full meaning.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    collapsible: {
+      description: [
+        'When `true`, the section heading becomes a toggle.',
+        'A chevron button with `aria-expanded` is rendered and the section contents can be shown or hidden.',
+        'Keyboard users can toggle with **Enter** or **Space**.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    collapsed: {
+      description: [
+        '**Initial** collapsed state when `collapsible` is `true`.',
+        'This prop sets the state at mount — the component is uncontrolled after that.',
+        'Changing this prop after mount has no effect.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    buttonText: {
+      description: [
+        'Label for the action button rendered in the section heading.',
+        'Must be paired with `buttonOnClick`, `buttonVariant`, and `buttonSize`.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    buttonOnClick: {
+      description: 'Click handler for the heading action button.',
+      action: 'buttonOnClick',
+      control: false,
+      table: {
+        type: { summary: 'MouseEventHandler<HTMLButtonElement>' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    buttonVariant: {
+      description: 'Visual variant for the heading action button. Always supply when `buttonText` is set.',
+      control: 'select',
+      options: ['primary', 'secondary', 'tertiary', 'primary-destructive', 'secondary-destructive', 'tertiary-destructive', 'ghost'],
+      table: {
+        type: { summary: "'primary' | 'secondary' | 'tertiary' | 'primary-destructive' | 'secondary-destructive' | 'tertiary-destructive' | 'ghost'" },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    buttonSize: {
+      description: "Size of the heading action button. Always supply when `buttonText` is set. Use `'S'` to keep it visually lightweight alongside the title.",
+      control: 'select',
+      options: ['S', 'M', 'L'],
+      table: {
+        type: { summary: "'S' | 'M' | 'L'" },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      description: 'Additional CSS class names applied to the root `<section>` element.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    children: {
+      description: [
+        'Content rendered inside the section body.',
+        'Typically `Row` components, nested `Section` components, or any React node.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
   },
 };
 
-export const Default = {
-  args: {
-    title: 'titleValue',
-    children: [<p key={1}>Sunt consectetur esse labore dolor consequat tempor dolor incididunt. Ullamco veniam ex enim consequat esse. Qui aute consequat dolore dolore ipsum commodo magna minim consectetur deserunt veniam in ipsum. Aute veniam do mollit cupidatat laboris. Laborum nisi est qui et eiusmod. Enim aliqua quis officia ut eiusmod quis dolore id commodo ipsum cillum sunt adipisicing laboris. Et non est sunt cillum ipsum.</p>],
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
-};
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-export const NestedSections = {
-  args: {
-    title: 'Parent Section',
-    collapsible: true,
-    children: [
-      <Section key={1} title="Sub-section 1" collapsible>
-        <p>Eu nisi dolore qui irure irure nulla aliqua commodo non sint dolor consectetur. Ullamco dolore ut exercitation ad cupidatat ipsum. Nisi proident esse nisi ullamco irure incididunt eiusmod fugiat est culpa Lorem. Dolor esse ut minim magna. In qui fugiat non nulla eu mollit enim excepteur consequat qui consequat occaecat aliquip adipisicing. Eu est nisi irure laboris culpa amet consectetur irure quis duis.</p>
-      </Section>,
-      <Section key={2} title="Sub-section 2" collapsible>
-        <p>Eu nisi dolore qui irure irure nulla aliqua commodo non sint dolor consectetur. Ullamco dolore ut exercitation ad cupidatat ipsum. Nisi proident esse nisi ullamco irure incididunt eiusmod fugiat est culpa Lorem. Dolor esse ut minim magna. In qui fugiat non nulla eu mollit enim excepteur consequat qui consequat occaecat aliquip adipisicing. Eu est nisi irure laboris culpa amet consectetur irure quis duis.</p>
-      </Section>,
-    ],
+export const Default: Story = withDescription(
+  {
+    args: {
+      title: 'Student Details',
+      headingLevel: 2,
+      children: (
+        <p>
+          Section content goes here. Add
+          <code>Row</code>
+          {' '}
+          components, nested
+          <code>Section</code>
+          {' '}
+          components, or any content relevant to the section topic.
+        </p>
+      ),
+    },
+    render: args => <Section {...args} />,
   },
-};
+  'The default story is wired to the Controls panel. Toggle `collapsible` to add expand/collapse behaviour, or add `buttonText` (with the three companion props) to surface an action in the heading.',
+);
+
+export const WithHeadingLevel: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
 
-export const WithRows = {
-  args: {
-    title: 'Student Details',
-    children: [
-      <Row key={1} label="First Name" value="Jacob" />,
-      <Row key={2} label="Last Name" value="Black" />,
-      <Row key={3} label="Year Group" value="Year 10" note="2024/2025" />,
-      <Row key={4} label="Form Group" value="10A" />,
-    ],
+function SectionHierarchyExample() {
+  return (
+    <Section title="Student Profile" headingLevel={2}>
+      <p>Top-level section — headingLevel 2.</p>
+      <Section title="Personal Details" headingLevel={3}>
+        <p>Sub-section — headingLevel 3.</p>
+        <Section title="Emergency Contacts" headingLevel={4}>
+          <p>Deeper sub-section — headingLevel 4.</p>
+        </Section>
+      </Section>
+    </Section>
+  );
+}
+export default SectionHierarchyExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section title="Student Profile" headingLevel={2}>
+        <p>
+          Top-level section —
+          <code>
+            headingLevel=
+            {2}
+          </code>
+          .
+        </p>
+        <Section title="Personal Details" headingLevel={3}>
+          <p>
+            Sub-section —
+            <code>
+              headingLevel=
+              {3}
+            </code>
+            .
+          </p>
+          <Section title="Emergency Contacts" headingLevel={4}>
+            <p>
+              Deeper sub-section —
+              <code>
+                headingLevel=
+                {4}
+              </code>
+              .
+            </p>
+          </Section>
+        </Section>
+      </Section>
+    ),
   },
-};
+  'Set `headingLevel` to match the correct position in the page heading hierarchy. The default is `1` — always override it to avoid multiple `<h1>` elements on the page.',
+);
+
+export const WithTitleIcon: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
 
-export const WithClickableRows = {
-  args: {
-    title: 'Quick Links',
-    buttonText: 'Edit',
-    children: [
-      <Row key={1} label="Attendance" value="96%" note="Above target" onClick={() => { console.log('click!'); }} />,
-      <Row key={2} label="Behaviour" value="3 positive points" onClick={() => { console.log('click!'); }} />,
-      <Row key={3} label="Assessment" value="On track" note="Last updated 2 days ago" onClick={() => { console.log('click!'); }} />,
-    ],
+function SENSectionWithIcon() {
+  return (
+    <Section
+      title="SEN Information"
+      headingLevel={2}
+      titleIconName="circle-alert"
+      titleIconColor="var(--color-semantic-warning-600)"
+      titleIconScreenReaderText="Special educational needs flag"
+    >
+      <p>Section content here.</p>
+    </Section>
+  );
+}
+export default SENSectionWithIcon;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="SEN Information"
+        headingLevel={2}
+        titleIconName="circle-alert"
+        titleIconColor="var(--color-semantic-warning-600)"
+        titleIconScreenReaderText="Special educational needs flag"
+      >
+        <p>
+          An icon after the title provides an at-a-glance visual cue. Pass
+          <code>titleIconScreenReaderText</code>
+          {' '}
+          so the icon is announced to screen readers.
+        </p>
+      </Section>
+    ),
   },
-};
+  'Add `titleIconName` to render an icon after the section title. Pair it with `titleIconColor` for semantic colour and `titleIconScreenReaderText` for accessibility.',
+);
 
-export const CollapsibleWithRows = {
-  args: {
-    title: 'Contact Information',
-    collapsible: true,
-    children: [
-      <Row key={1} label="Email" value="jacob.black@forks.edu" />,
-      <Row key={2} label="Phone" value="01onal 555 0123" />,
-      <Row key={3} label="Address" value="La Push, Washington" note="Primary" />,
-    ],
+export const WithActionButton: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
+
+function PersonalDetailsSection() {
+  return (
+    <Section
+      title="Personal Details"
+      headingLevel={2}
+      buttonText="Edit"
+      buttonOnClick={() => openEditModal()}
+      buttonVariant="secondary"
+      buttonSize="S"
+    >
+      <p>Section content here.</p>
+    </Section>
+  );
+}
+export default PersonalDetailsSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="Personal Details"
+        headingLevel={2}
+        buttonText="Edit"
+        buttonOnClick={fn()}
+        buttonVariant="secondary"
+        buttonSize="S"
+      >
+        <p>
+          The action button appears in the heading row. Always provide all four button props together:
+          <code>buttonText</code>
+          ,
+          <code>buttonOnClick</code>
+          ,
+          <code>buttonVariant</code>
+          , and
+          <code>buttonSize</code>
+          .
+        </p>
+      </Section>
+    ),
   },
-};
+  'Provide all four button props together to render an action button in the section heading. Use `buttonSize="S"` to keep it visually lightweight alongside the title.',
+);
 
-export const NestedSectionsWithRows = {
-  args: {
-    title: 'Student Profile',
-    collapsible: true,
-    children: [
-      <Section key={1} title="Personal Details" collapsible>
-        <Row label="First Name" value="Jacob" />
-        <Row label="Last Name" value="Black" />
-        <Row label="Date of Birth" value="14/01/1990" note="Age 36" />
-      </Section>,
-      <Section key={2} title="Academic" collapsible>
-        <Row label="Year Group" value="Year 10" note="2024/2025" />
-        <Row label="Form Group" value="10A" />
-        <Row label="Attendance" value="96%" note="Above target" onClick={() => { console.log('click!'); }} />
-      </Section>,
-    ],
+export const Collapsible: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
+
+function CollapsibleSection() {
+  return (
+    <Section
+      title="Additional Notes"
+      headingLevel={2}
+      collapsible
+    >
+      <p>This section starts expanded. Click the heading or the chevron to collapse it.</p>
+    </Section>
+  );
+}
+export default CollapsibleSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="Additional Notes"
+        headingLevel={2}
+        collapsible
+      >
+        <p>
+          This section starts
+          <strong>expanded</strong>
+          . Click the heading or the chevron to collapse it. The state is managed internally — no external state management is required.
+        </p>
+      </Section>
+    ),
   },
-};
+  'Set `collapsible` to add expand/collapse behaviour. The section starts expanded by default. Click the heading or the chevron icon to toggle — keyboard users can press **Enter** or **Space**.',
+);
 
-export default meta;
+export const CollapsibleInitiallyCollapsed: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
+
+function CollapsedByDefaultSection() {
+  return (
+    <Section
+      title="Medical Information"
+      headingLevel={2}
+      collapsible
+      collapsed
+    >
+      <p>Sensitive content that is hidden by default.</p>
+    </Section>
+  );
+}
+export default CollapsedByDefaultSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="Medical Information"
+        headingLevel={2}
+        collapsible
+        collapsed
+      >
+        <p>
+          This content was hidden when the section mounted. The
+          <code>collapsed</code>
+          {' '}
+          prop only sets the initial state — the section is self-managed after that.
+        </p>
+      </Section>
+    ),
+  },
+  'Pass `collapsed` alongside `collapsible` to start in the collapsed state. The `collapsed` prop is **initial state only** — the component owns the toggle state after mount and changing the prop later has no effect.',
+);
+
+export const CollapsibleWithActionButton: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
+
+function ContactSection() {
+  return (
+    <Section
+      title="Contact Information"
+      headingLevel={2}
+      collapsible
+      buttonText="Add contact"
+      buttonOnClick={() => openAddContactModal()}
+      buttonVariant="secondary"
+      buttonSize="S"
+    >
+      <p>Contact details here.</p>
+    </Section>
+  );
+}
+export default ContactSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="Contact Information"
+        headingLevel={2}
+        collapsible
+        buttonText="Add contact"
+        buttonOnClick={fn()}
+        buttonVariant="secondary"
+        buttonSize="S"
+      >
+        <p>
+          A section can be both collapsible
+          <em>and</em>
+          {' '}
+          have an action button. The chevron and the button both appear in the heading row.
+        </p>
+      </Section>
+    ),
+  },
+  'A section can combine `collapsible` with an action button. Both the chevron toggle and the action button appear in the heading row — useful when the content can be hidden but the action remains permanently accessible.',
+);
+
+export const WithRows: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section, Row } from '@arbor-education/design-system.components';
+
+function PupilDetailSection() {
+  return (
+    <Section
+      title="Personal Details"
+      headingLevel={2}
+      buttonText="Edit"
+      buttonOnClick={() => openEditModal()}
+      buttonVariant="secondary"
+      buttonSize="S"
+    >
+      <Row label="Full name" value="Amara Osei-Bonsu" />
+      <Row label="Date of birth" value="14 March 2009" note="Age 16" />
+      <Row label="Year group" value="Year 10" />
+      <Row label="Form" value="10JH" />
+      <Row label="UPN" value="A823456789012" />
+    </Section>
+  );
+}
+export default PupilDetailSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section
+        title="Personal Details"
+        headingLevel={2}
+        buttonText="Edit"
+        buttonOnClick={fn()}
+        buttonVariant="secondary"
+        buttonSize="S"
+      >
+        <Row label="Full name" value="Amara Osei-Bonsu" />
+        <Row label="Date of birth" value="14 March 2009" note="Age 16" />
+        <Row label="Year group" value="Year 10" />
+        <Row label="Form" value="10JH" />
+        <Row label="UPN" value="A823456789012" />
+      </Section>
+    ),
+  },
+  'The most common real-world usage — `Row` components inside a `Section`. Static and clickable rows can be freely mixed. The section heading can carry an action button for record-level operations like "Edit".',
+);
+
+export const NestedCollapsibleSections: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section, Row } from '@arbor-education/design-system.components';
+
+function PupilProfilePanel() {
+  return (
+    <Section title="Student Profile" headingLevel={2} collapsible>
+      <Section title="Personal Details" headingLevel={3} collapsible>
+        <Row label="Full name" value="Amara Osei-Bonsu" />
+        <Row label="Date of birth" value="14 March 2009" note="Age 16" />
+        <Row label="Admission number" value="001847" />
+      </Section>
+      <Section title="Academic" headingLevel={3} collapsible>
+        <Row label="Year group" value="Year 10" />
+        <Row label="Form" value="10JH" />
+        <Row
+          label="Attendance (YTD)"
+          value="88.3%"
+          note="Below 90% threshold"
+          onClick={() => navigateToAttendance()}
+        />
+      </Section>
+      <Section title="Contact Information" headingLevel={3} collapsible collapsed>
+        <Row label="Email" value="guardian@example.com" note="Primary contact" />
+        <Row label="Phone" value="07700 900123" />
+      </Section>
+    </Section>
+  );
+}
+export default PupilProfilePanel;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section title="Student Profile" headingLevel={2} collapsible>
+        <Section title="Personal Details" headingLevel={3} collapsible>
+          <Row label="Full name" value="Amara Osei-Bonsu" />
+          <Row label="Date of birth" value="14 March 2009" note="Age 16" />
+          <Row label="Admission number" value="001847" />
+        </Section>
+        <Section title="Academic" headingLevel={3} collapsible>
+          <Row label="Year group" value="Year 10" />
+          <Row label="Form" value="10JH" />
+          <Row
+            label="Attendance (YTD)"
+            value="88.3%"
+            note="Below 90% threshold"
+            onClick={fn()}
+          />
+        </Section>
+        <Section title="Contact Information" headingLevel={3} collapsible collapsed>
+          <Row label="Email" value="guardian@example.com" note="Primary contact" />
+          <Row label="Phone" value="07700 900123" />
+        </Section>
+      </Section>
+    ),
+  },
+  'Nested sections are a common pattern for hierarchical detail panels. Nested sections automatically lose their horizontal padding to maintain visual rhythm. Each section manages its own collapsed state independently.',
+);