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

package/src/components/modal/Modal.stories.tsx

@@ -1,37 +1,974 @@
-import type { Meta } from '@storybook/react-vite';
-import { fn } from 'storybook/test';
-import { Modal, type ModalProps } from './Modal';
-import { Button } from 'Components/button/Button';
 import { useState } from 'react';
+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 { Modal } from './Modal';
+import { Button } from 'Components/button/Button';
+import { FormField } from 'Components/formField/FormField';
+import { Dropdown } from 'Components/dropdown/Dropdown';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Modal is a focused, interruptive dialog that blocks all background interaction until the user',
+  'takes an explicit action or dismisses it.',
+  '',
+  '> **Tip:** For programmatic modal control — opening modals from event handlers, PubSub events,',
+  '> or outside the React tree — use [`ModalManager`](?path=/docs/components-modals-modalmanager--docs)',
+  '> with `ModalUtils.addModal()` instead of wiring `open` state manually.',
+  '',
+  '> **Built on [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog).**',
+  '> Modal renders via a portal. The overlay registers itself as a `PopupParentContext`, so any',
+  '> floating elements (Dropdown, Tooltip) inside the modal automatically portal into the overlay.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- The user must make a decision or complete a short task before continuing (e.g. a delete',
+  '  confirmation, a quick-add form)',
+  '- You need to fully interrupt the flow to prevent data loss or an irreversible action',
+  '- The content is self-contained and does not require the user to reference the underlying page',
+  '- Multi-step flows where each step is short and sequential',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| User needs to reference the background page while editing | [Slideover](?path=/docs/components-modals-slideover--docs) |',
+  '| Non-blocking contextual info anchored to a trigger | [Dropdown](?path=/docs/components-dropdown--docs) |',
+  '| Brief status feedback that auto-dismisses | [Toast](?path=/docs/components-toast--docs) |',
+  '| Content too complex for a dialog | A dedicated page or Slideover |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`closeHandler` gates everything.** With no `closeHandler`:',
+  '- The X close button is **not rendered** (even if `hideCloseButton` is `false`)',
+  '- Pressing **Escape** does nothing',
+  '- Clicking the overlay does nothing (overlay clicks never dismiss — intentional)',
+  '',
+  'A modal without `closeHandler` can only be closed by action buttons you render inside it. Use',
+  'this pattern for destructive confirmations where an accidental dismiss would be dangerous.',
+  '',
+  '**`hideCloseButton` vs no `closeHandler`:**',
+  '',
+  '| Scenario | `closeHandler` | `hideCloseButton` | Result |',
+  '|---|---|---|---|',
+  '| Standard dismissible modal | provided | `false` | X button shown; Escape works |',
+  '| Escape only, no visible X | provided | `true` | X button hidden; Escape still works |',
+  '| Forced decision (no escape route) | omitted | n/a | No X, no Escape, no overlay dismiss |',
+  '',
+  '**`title` prop shortcut.** Passing `title="My Title"` auto-renders `Modal.Header` + `Modal.Title`.',
+  'Do **not** also render a manual `<Modal.Header>` — you will get a double header.',
+  '',
+  '**Width is consumer-controlled.** There is no `size` prop. Pass `className` to control width.',
+  'Standard modals: 480–600 px; delete confirmations: 400–480 px.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The dialog root receives `role="dialog"` and `aria-modal="true"` (Radix UI)',
+  '- `Modal.Title` renders an `<h2>` and is linked to the dialog via `aria-labelledby`',
+  '- Focus is **trapped** inside the modal — Tab and Shift+Tab cycle only within the modal',
+  '- Focus returns to the trigger element when the modal closes',
+  '- Always provide `Modal.Title` (or the `title` prop) — a dialog without a label breaks screen',
+  '  reader announcement',
+  '',
+  '---',
+  '',
+  '### Sub-component props',
+  '',
+  '| Sub-component | Props | Description |',
+  '|---|---|---|',
+  '| `Modal.Header` | `className?`, `children?` | Flex row header bar — put `Modal.Title` here |',
+  '| `Modal.Body` | `className?`, `children?` | Scrollable content area with grey background |',
+  '| `Modal.Footer` | `className?`, `children?` | Flex row footer — put action `Button`s here |',
+  '| `Modal.Title` | `className?`, `children?`, all `DialogTitleProps` | `<h2>` dialog title — required for accessibility |',
+  '| `Modal.CloseButton` | all `ButtonProps` | Reads `closeHandler` from context — renders `null` if no `closeHandler` |',
+  '',
+  '---',
+  '',
+  '### Design tokens used',
+  '',
+  '| Token | Usage |',
+  '|---|---|',
+  '| `--modal-overlay-color-background` | Overlay backdrop colour |',
+  '| `--modal-color-background` | Dialog box background |',
+  '| `--modal-radius` | Dialog border radius |',
+  '| `--modal-header-color-background` | Header section background |',
+  '| `--modal-header-spacing-padding` | Header padding |',
+  '| `--modal-footer-color-background` | Footer section background |',
+  '| `--modal-footer-spacing-padding` | Footer padding |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Slideover](?path=/docs/components-modals-slideover--docs) · [Dropdown](?path=/docs/components-dropdown--docs) · [Toast](?path=/docs/components-toast--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
 
-const meta: Meta<typeof Modal> = {
+function ModalDocsPage() {
+  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 = {
   title: 'Components/Modals/Modal',
   component: Modal,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: ModalDocsPage,
+    },
+  },
   tags: ['autodocs'],
+  argTypes: {
+    open: {
+      control: 'boolean',
+      description:
+        'Controls whether the modal is visible. Pair with `closeHandler` for a fully controlled component.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    closeHandler: {
+      control: false,
+      description: [
+        'Callback fired when the modal requests to close (Escape key or X button).',
+        '**Omitting this prop disables all dismiss mechanisms** — no X button, no Escape key.',
+      ].join(' '),
+      table: {
+        type: { summary: '() => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    hideCloseButton: {
+      control: 'boolean',
+      description:
+        'Hides the X close button while keeping Escape-key dismiss active (requires `closeHandler`).',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    title: {
+      control: 'text',
+      description: [
+        'Shortcut that auto-renders `Modal.Header` + `Modal.Title`.',
+        'Do **not** combine with a manual `<Modal.Header>` — you will get a double header.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      control: 'text',
+      description:
+        'CSS class applied to the dialog element. Use this to control modal width — there is no `size` prop.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    overlayClassName: {
+      control: 'text',
+      description: 'CSS class applied to the overlay / backdrop element.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    portalTarget: {
+      control: false,
+      description:
+        'DOM element into which the modal portal mounts. Defaults to `PopupParentContext` value (`div#ds-popup-parent` in body).',
+      table: {
+        type: { summary: 'HTMLElement | null' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+} satisfies Meta<typeof Modal>;
+
+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,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Add Assessment Period
+      </Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Add Assessment Period">
+        <Modal.Body>
+          <p>
+            Create a new assessment period for the current academic year. Assessment periods define
+            the date ranges used when recording and reporting pupil attainment data.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Add Assessment Period
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const NoCloseHandlerTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Open Session Timeout Warning
+      </Button>
+      <Modal open={open} title="Your session is about to expire">
+        <Modal.Body>
+          <p>
+            For security reasons, your session will expire in 2 minutes due to inactivity. Choose an
+            option below to continue — you cannot dismiss this dialog by pressing Escape or clicking
+            outside it.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Log out now
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Stay logged in
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const HideCloseButtonTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Review Data Export
+      </Button>
+      <Modal
+        open={open}
+        closeHandler={() => setOpen(false)}
+        hideCloseButton
+        title="Export Pupil Data"
+      >
+        <Modal.Body>
+          <p>
+            You are about to export sensitive pupil data. Please review the export settings before
+            proceeding. Press
+            {' '}
+            <strong>Escape</strong>
+            {' '}
+            or select an action button to close this
+            dialog — the X button is intentionally hidden for this flow.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Export Data
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const ManualHeaderCompositionTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Edit Year Group Settings
+      </Button>
+      {/* hideCloseButton suppresses the auto top-right X so the manual one in the header is the only dismiss button */}
+      <Modal open={open} closeHandler={() => setOpen(false)} hideCloseButton>
+        <Modal.Header>
+          <div
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 'var(--spacing-xsmall)',
+              flex: 1,
+            }}
+          >
+            <Modal.Title>Year Group Settings</Modal.Title>
+            <p style={{ color: 'var(--color-grey-600)', margin: 0, fontSize: 'var(--font-size-2-13)' }}>
+              Year 9 · Autumn Term 2024
+            </p>
+          </div>
+          <Modal.CloseButton />
+        </Modal.Header>
+        <Modal.Body>
+          <p>
+            Adjust the settings for this year group. Changes will apply to all classes within Year 9
+            for the current term.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Save Settings
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const LongScrollingContentTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        View Attendance Policy
+      </Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Attendance Policy">
+        <Modal.Body>
+          {Array.from({ length: 12 }).map((_, i) => (
+            <p key={i} style={{ marginBottom: 'var(--spacing-large)' }}>
+              Section
+              {' '}
+              {i + 1}
+              : Attendance records must be completed by 9:30 am each school day.
+              Persistent absence is defined as missing 10% or more of sessions. Parents and carers
+              must be notified when a pupil&apos;s attendance falls below 90%. Schools are required
+              to keep accurate records for inspection and reporting purposes.
+            </p>
+          ))}
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Close
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Acknowledge Policy
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const WithFormContentTemplate = () => {
+  const [open, setOpen] = useState(false);
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [yearGroup, setYearGroup] = useState('');
+
+  const handleSave = () => {
+    setOpen(false);
+    setFirstName('');
+    setLastName('');
+    setYearGroup('');
+  };
+
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Add New Pupil
+      </Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Add New Pupil">
+        <Modal.Body>
+          <p style={{ marginBottom: 'var(--spacing-large)' }}>
+            Enter the pupil&apos;s details below. Tab through fields to navigate — focus is trapped
+            within this dialog.
+          </p>
+          <FormField
+            label="First name"
+            id="pupil-first-name"
+            inputType="text"
+            inputProps={{
+              value: firstName,
+              onChange: e => setFirstName(e.target.value),
+              placeholder: 'e.g. Emily',
+            }}
+          />
+          <FormField
+            label="Last name"
+            id="pupil-last-name"
+            inputType="text"
+            inputProps={{
+              value: lastName,
+              onChange: e => setLastName(e.target.value),
+              placeholder: 'e.g. Clarke',
+            }}
+          />
+          <FormField
+            label="Year group"
+            id="pupil-year-group"
+            inputType="text"
+            inputProps={{
+              value: yearGroup,
+              onChange: e => setYearGroup(e.target.value),
+              placeholder: 'e.g. Year 7',
+            }}
+          />
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={handleSave}>
+            Add Pupil
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const DeleteConfirmationTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="secondary-destructive" onClick={() => setOpen(true)}>
+        Remove Pupil
+      </Button>
+      {/* No closeHandler — the user must explicitly choose Cancel or Remove */}
+      <Modal open={open} title="Remove Emily Clarke?">
+        <Modal.Body>
+          <p style={{ marginBottom: 'var(--spacing-small)' }}>
+            You are about to permanently remove
+            {' '}
+            <strong>Emily Clarke (Year 9)</strong>
+            {' '}
+            from the
+            register. This action cannot be undone.
+          </p>
+          <p>
+            All associated assessment records, attendance data, and report history will be archived
+            and will no longer appear in active reports.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary-destructive" onClick={() => setOpen(false)}>
+            Remove Pupil
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
 };
 
-export const Default = {
-  args: {
-    open: false,
-    closeHandler: fn(),
-    title: 'Modal Title',
+const WithDropdownInsideModalTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Assign Class Teacher
+      </Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Assign Class Teacher">
+        <Modal.Body>
+          <p style={{ marginBottom: 'var(--spacing-large)' }}>
+            Select a teacher to assign as the lead for this class. The dropdown portals into the
+            modal overlay automatically — no additional configuration required.
+          </p>
+          <Dropdown>
+            <Dropdown.Trigger>
+              <Button variant="dropdown">Select a teacher</Button>
+            </Dropdown.Trigger>
+            <Dropdown.Content>
+              <Dropdown.Item onSelect={() => {}}>Ms A. Johnson — English</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Mr B. Patel — Mathematics</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Mrs C. Williams — Science</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Mr D. Thompson — History</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Ms E. Okonkwo — Art</Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Assign Teacher
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+function AddAssessmentPeriodModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Add Assessment Period
+      </Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Add Assessment Period">
+        <Modal.Body>
+          <p>
+            Create a new assessment period for the current academic year.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Add Assessment Period</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default AddAssessmentPeriodModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <DefaultTemplate />,
   },
-  render: (args: ModalProps) => {
-    const [showModal, setShowModal] = useState(args.open);
-    return (
-      <>
-        <Button type="primary" onClick={() => setShowModal(true)}>Open Modal</Button>
-        <Modal {...args} open={showModal} closeHandler={() => setShowModal(false)}>
-          <Modal.Body>Cheddar and Pickle were Norwich terriers who lived next door. Cheddar, the older, was cautious and methodical; Pickle, the younger, was bold and impulsive. One morning, Pickle spotted a squirrel in the garden and gave chase, while Cheddar watched from the porch. When Pickle got stuck under the neighbor’s fence, Cheddar squeezed through a gap and nudged him free. From then on, they worked as a team: Pickle scouted, and Cheddar planned. They became inseparable, exploring the neighborhood together and always looking out for each other.</Modal.Body>
-          <Modal.Footer>
-            <Button variant="tertiary" onClick={() => setShowModal(false)}>Close</Button>
-            <Button variant="primary" onClick={() => setShowModal(false)}>Primary Action</Button>
-          </Modal.Footer>
-        </Modal>
-      </>
+  'The standard controlled modal pattern. A trigger button opens the modal; `closeHandler` enables the X button and Escape key. The `title` prop auto-renders `Modal.Header` + `Modal.Title` with no manual composition needed.',
+);
 
-    );
+export const NoCloseHandler: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+// No closeHandler — no X button, no Escape key, no overlay dismiss.
+// The user MUST choose an action button.
+function SessionTimeoutModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Open Session Timeout Warning
+      </Button>
+      <Modal open={open} title="Your session is about to expire">
+        <Modal.Body>
+          <p>
+            For security reasons, your session will expire in 2 minutes.
+            Choose an option below to continue.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Log out now</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Stay logged in</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default SessionTimeoutModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <NoCloseHandlerTemplate />,
   },
-};
+  [
+    '**No `closeHandler` provided.** The X button is not rendered, Escape does nothing, and clicking',
+    'the overlay does nothing. The user must select one of the action buttons. Use this pattern for',
+    'flows where an accidental dismiss would be confusing or dangerous — session timeouts, required',
+    'acknowledgements, and critical confirmations.',
+  ].join(' '),
+);
 
-export default meta;
+export const HideCloseButton: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+function ExportModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>Review Data Export</Button>
+      <Modal
+        open={open}
+        closeHandler={() => setOpen(false)}
+        hideCloseButton
+        title="Export Pupil Data"
+      >
+        <Modal.Body>
+          <p>Review the export settings below. Press Escape to cancel.</p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Export Data</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default ExportModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <HideCloseButtonTemplate />,
+  },
+  [
+    '`hideCloseButton` removes the top-right X button while keeping the Escape key active (because',
+    '`closeHandler` is still provided). Use this for flows that want a cleaner look without a visible',
+    'close affordance — the user can still press Escape to dismiss.',
+  ].join(' '),
+);
+
+export const ManualHeaderComposition: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+function YearGroupSettingsModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>Edit Year Group Settings</Button>
+      {/* hideCloseButton suppresses the auto top-right X; the manual CloseButton in the header takes its place */}
+      <Modal open={open} closeHandler={() => setOpen(false)} hideCloseButton>
+        <Modal.Header>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', flex: 1 }}>
+            <Modal.Title>Year Group Settings</Modal.Title>
+            <p style={{ color: 'var(--color-grey-600)', margin: 0 }}>
+              Year 9 · Autumn Term 2024
+            </p>
+          </div>
+          <Modal.CloseButton />
+        </Modal.Header>
+        <Modal.Body>
+          <p>Adjust the settings for this year group.</p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Save Settings</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default YearGroupSettingsModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <ManualHeaderCompositionTemplate />,
+  },
+  [
+    'Full header composition using `Modal.Header` + `Modal.Title` instead of the `title` prop shortcut.',
+    'Use this pattern when the header needs more than a plain title string — a subtitle, an icon, or',
+    'custom header controls. Pass `hideCloseButton` on `<Modal>` to suppress the auto top-right X,',
+    'then place `<Modal.CloseButton />` inside the header where you want it.',
+  ].join(' '),
+);
+
+export const LongScrollingContent: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+function AttendancePolicyModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>View Attendance Policy</Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Attendance Policy">
+        <Modal.Body>
+          {/* Long content — Modal.Body scrolls independently; header and footer stay pinned */}
+          {sections.map((text, i) => <p key={i}>{text}</p>)}
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Close</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Acknowledge Policy</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default AttendancePolicyModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <LongScrollingContentTemplate />,
+  },
+  [
+    '`Modal.Body` scrolls independently when content overflows — the header and footer remain pinned.',
+    'The modal container enforces `max-height: calc(100vh - var(--spacing-medium))` so the dialog',
+    'never exceeds the viewport. No extra CSS needed on the consumer side.',
+  ].join(' '),
+);
+
+export const WithFormContent: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, FormField, Modal } from '@arbor-education/design-system.components';
+
+function AddPupilModal() {
+  const [open, setOpen] = useState(false);
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>Add New Pupil</Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Add New Pupil">
+        <Modal.Body>
+          <FormField
+            label="First name"
+            id="pupil-first-name"
+            inputType="text"
+            inputProps={{
+              value: firstName,
+              onChange: (e) => setFirstName(e.target.value),
+              placeholder: 'e.g. Emily',
+            }}
+          />
+          <FormField
+            label="Last name"
+            id="pupil-last-name"
+            inputType="text"
+            inputProps={{
+              value: lastName,
+              onChange: (e) => setLastName(e.target.value),
+              placeholder: 'e.g. Clarke',
+            }}
+          />
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={() => { setOpen(false); }}>Add Pupil</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default AddPupilModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <WithFormContentTemplate />,
+  },
+  [
+    'Form fields inside `Modal.Body` demonstrating the focus trap — Tab and Shift+Tab cycle only',
+    'within the open dialog. Radix UI Dialog handles this automatically; no additional `aria` or',
+    '`tabIndex` props are required. Use `FormField` with `inputType` + `inputProps` for consistent',
+    'layout and accessibility wiring.',
+  ].join(' '),
+);
+
+export const DeleteConfirmation: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Modal } from '@arbor-education/design-system.components';
+
+function RemovePupilConfirmation() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="secondary-destructive" onClick={() => setOpen(true)}>Remove Pupil</Button>
+      {/* No closeHandler — user must explicitly choose Cancel or Remove */}
+      <Modal open={open} title="Remove Emily Clarke?">
+        <Modal.Body>
+          <p>
+            You are about to permanently remove <strong>Emily Clarke (Year 9)</strong> from the
+            register. This action cannot be undone.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary-destructive" onClick={() => setOpen(false)}>Remove Pupil</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default RemovePupilConfirmation;
+`.trim(),
+        },
+      },
+    },
+    render: () => <DeleteConfirmationTemplate />,
+  },
+  [
+    'The destructive confirmation pattern. No `closeHandler` is provided — the user must explicitly',
+    'choose "Cancel" or "Remove Pupil". There is no X button and Escape does nothing, preventing an',
+    'accidental dismiss of a destructive action. Use `variant="primary-destructive"` on the confirm',
+    'button and `variant="secondary"` on the cancel button.',
+  ].join(' '),
+);
+
+export const WithDropdownInsideModal: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Dropdown, Modal } from '@arbor-education/design-system.components';
+
+function AssignTeacherModal() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>Assign Class Teacher</Button>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Assign Class Teacher">
+        <Modal.Body>
+          <p>Select a teacher to assign as the lead for this class.</p>
+          <Dropdown>
+            <Dropdown.Trigger>
+              <Button variant="dropdown">Select a teacher</Button>
+            </Dropdown.Trigger>
+            <Dropdown.Content>
+              <Dropdown.Item onSelect={() => {}}>Ms A. Johnson — English</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Mr B. Patel — Mathematics</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>Mrs C. Williams — Science</Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>Assign Teacher</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default AssignTeacherModal;
+`.trim(),
+        },
+      },
+    },
+    render: () => <WithDropdownInsideModalTemplate />,
+  },
+  [
+    'A `Dropdown` inside `Modal.Body`. Because `Modal` registers its overlay ref as a',
+    '`PopupParentContext`, the Dropdown menu portals into the modal overlay automatically — it will',
+    'never be clipped by the modal boundary or appear behind the overlay. No extra configuration',
+    'is required.',
+  ].join(' '),
+);