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

package/src/components/modal/modalManager/ModalManager.stories.tsx

@@ -1,497 +1,655 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Heading as DocHeading,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { ModalManager } from './ModalManager';
-import { ModalUtils } from '../../../utils/ModalUtils';
-import { Button } from '../../button/Button';
-import { Section } from '../../section/Section';
-import { FormField } from '../../formField/FormField';
-import { generateUuid } from '../../../utils/generateUuid';
-import { Modal } from '../Modal';
-import { fn } from 'storybook/test';
+import { Modal } from 'Components/modal/Modal';
+import { Button } from 'Components/button/Button';
+import { FormField } from 'Components/formField/FormField';
 import { Icon } from 'Components/icon/Icon';
 
-const meta: Meta = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`ModalManager` is a singleton container that opens and closes modals programmatically via PubSub events.',
+  'Mount it once near your app root, then call `ModalUtils.addModal(props)` from anywhere in the component',
+  'tree — no prop drilling, no shared state. For modals that are tightly coupled to their trigger,',
+  'prefer the raw [`Modal`](?path=/docs/components-modals-modal--docs) component with local state instead.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Deep action handlers** — triggering a modal from an API response, a table row action, or a',
+  '  notification handler that has no direct access to modal state',
+  '- **Cross-cutting concerns** — session-expiry dialogs, global error modals, or app-level confirmations',
+  '  that can be triggered from any module',
+  '- **Avoiding prop drilling** — when the modal trigger and the `Modal` render point are far apart in',
+  '  the component tree',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Modal is directly triggered by a parent component | Raw [`Modal`](?path=/docs/components-modals-modal--docs) with local `useState` |',
+  '| Multiple modals open simultaneously | Not supported — `ModalManager` holds one modal at a time |',
+  '| You need full control of `open`/`closeHandler` lifecycle | Raw `Modal` component |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Setup',
+  '',
+  'Mount `<ModalManager />` once, near your application root:',
+  '',
+  '```tsx',
+  "import { ModalManager } from '@arbor-education/design-system.components';",
+  '',
+  'function App() {',
+  '  return (',
+  '    <>',
+  '      <ModalManager />',
+  '      <Router>',
+  '        {/* rest of your app */}',
+  '      </Router>',
+  '    </>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### ModalUtils API',
+  '',
+  '```ts',
+  "import { ModalUtils } from '@arbor-education/design-system.components';",
+  '',
+  '// Open a modal — pass any ModalProps except open and closeHandler',
+  'ModalUtils.addModal({',
+  '  title: "Confirm deletion",',
+  '  children: (',
+  '    <>',
+  '      <Modal.Body>Are you sure?</Modal.Body>',
+  '      <Modal.Footer>',
+  '        <Button onClick={() => ModalUtils.removeModal()}>Cancel</Button>',
+  '        <Button variant="primary-destructive" onClick={handleDelete}>Delete</Button>',
+  '      </Modal.Footer>',
+  '    </>',
+  '  ),',
+  '});',
+  '',
+  '// Close the current modal',
+  'ModalUtils.removeModal();',
+  '',
+  '// Close all modals (also clears any queued modal state)',
+  'ModalUtils.removeAllModals();',
+  '```',
+  '',
+  '---',
+  '',
+  '### Critical notes',
+  '',
+  '**Do NOT pass `closeHandler` via `ModalUtils.addModal()`.**',
+  '`ModalManager` always provides its own `closeHandler` — passing one in `modalProps` would override it',
+  'and break the X button and Escape key dismissal.',
+  '',
+  '**`ModalManager` holds one modal at a time.**',
+  'Calling `ModalUtils.addModal()` while a modal is open replaces it immediately. If you need a queue or',
+  'multiple layered modals, manage that state yourself and call `addModal` once you are ready to show the next.',
+  '',
+  '**The `modal` prop sets an initial modal at mount.**',
+  'Useful for route-based or server-rendered scenarios where the modal state is known before the component mounts.',
+  'Once mounted, further changes are driven by `ModalUtils`.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Focus trapping and restoration are inherited from the underlying `Modal` component',
+  '- `ModalManager` always provides a `closeHandler`, so the X button and Escape key are always active',
+  '- Ensure modal content includes an accessible title — use `title` prop or `Modal.Header` + `Modal.Title`',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { ModalManager } from '@arbor-education/design-system.components';",
+  "import type { ModalProps } from '@arbor-education/design-system.components';",
+  '',
+  '// ModalManagerProps',
+  'type ModalManagerProps = {',
+  '  modal?: ModalProps; // optional initial modal shown at mount',
+  '};',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Modal](?path=/docs/components-modals-modal--docs) · [Button](?path=/docs/components-button--docs) · [FormField](?path=/docs/components-formfield--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function ModalManagerDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <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/ModalManager',
+  component: ModalManager,
+  tags: ['autodocs'],
   parameters: {
-    layout: 'fullscreen',
+    layout: 'padded',
     docs: {
-      description: {
-        component: 'The ModalManager is a container that manages the display of modals. It listens for events to add or remove modals.',
+      page: ModalManagerDocsPage,
+    },
+  },
+  argTypes: {
+    modal: {
+      control: false,
+      description: [
+        'Optional initial modal to show at mount. Pass any `ModalProps` value — `open` and `closeHandler`',
+        'are always managed by `ModalManager` itself and cannot be overridden.',
+        'Once mounted, further changes are driven by `ModalUtils.addModal()` and `ModalUtils.removeModal()`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'ModalProps' },
+        defaultValue: { summary: 'undefined' },
       },
     },
   },
-
-  tags: ['autodocs'],
-};
+} satisfies Meta<typeof ModalManager>;
 
 export default meta;
+type Story = StoryObj<typeof meta>;
 
-type Story = StoryObj;
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
 
-let modalCount = 0;
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
 
-const addModalWithContent = (content: React.ReactNode) => {
-  modalCount++;
-  ModalUtils.addModal({
-    children: content,
-  });
-};
+// ---------------------------------------------------------------------------
+// Templates
+// NOTE: Story templates use raw <Modal> with local useState so the portal
+// renders to document.body and works correctly in Storybook's canvas context.
+// Production code uses ModalUtils.addModal() — see each story's source code.
+// ---------------------------------------------------------------------------
 
-const removeModal = () => {
-  if (modalCount > 0) {
-    modalCount--;
-  }
-  ModalUtils.removeModal();
+const DefaultTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Modal
+        open={open}
+        closeHandler={() => setOpen(false)}
+        title="Assessment Period Added"
+      >
+        <Modal.Body>
+          <p>The Spring 2026 assessment period has been added successfully. Pupils will now be able to submit work for grading.</p>
+        </Modal.Body>
+      </Modal>
+      <Button onClick={() => setOpen(true)}>Open modal</Button>
+    </>
+  );
 };
 
-export const Default: Story = {
-  render: () => (
+const WithFooterActionsTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
     <>
-      <ModalManager />
-      <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-        <Button
-          onClick={() =>
-            addModalWithContent(
-              <>
-                <Modal.Header>
-                  <Modal.Title>Simple Modal</Modal.Title>
-                </Modal.Header>
-                <Modal.Body>
-                  <p>This is a simple modal with basic content.</p>
-                </Modal.Body>
-              </>,
-            )}
-        >
-          Open Simple Modal
-        </Button>
-      </div>
+      <Modal
+        open={open}
+        closeHandler={() => setOpen(false)}
+        title="Edit Pupil Details"
+      >
+        <Modal.Body>
+          <p>Update the details below. Changes will be saved to the pupil record immediately.</p>
+        </Modal.Body>
+        <Modal.Footer>
+          <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+            <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button variant="primary" onClick={() => setOpen(false)}>Save changes</Button>
+          </div>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpen(true)}>Edit pupil details</Button>
     </>
-  ),
+  );
 };
 
-export const WithHeaderAndFooter: Story = {
-  render: () => {
-    const handleSave = () => {
-      alert('Save clicked!');
-      ModalUtils.removeModal();
-    };
-
-    const handleCancel = () => {
-      ModalUtils.removeModal();
-    };
+const WithFormContentTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Modal open={open} closeHandler={() => setOpen(false)} title="Add New Staff Member">
+        <Modal.Body>
+          <FormField
+            id="staff-first-name"
+            label="First name"
+            inputType="text"
+            inputProps={{ placeholder: 'e.g. Sarah' }}
+          />
+          <FormField
+            id="staff-last-name"
+            label="Last name"
+            inputType="text"
+            inputProps={{ placeholder: 'e.g. Clarke' }}
+          />
+          <FormField
+            id="staff-email"
+            label="Email address"
+            inputType="text"
+            inputProps={{ placeholder: 'e.g. s.clarke@school.edu', type: 'email' }}
+            fieldDescription="The staff member will receive a login invitation at this address."
+          />
+        </Modal.Body>
+        <Modal.Footer>
+          <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+            <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button variant="primary" onClick={() => setOpen(false)}>Add staff member</Button>
+          </div>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpen(true)}>Add staff member</Button>
+    </>
+  );
+};
 
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Modal.Title>Modal with Header and Footer</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <p>This modal has both a header with a close button and a footer with action buttons.</p>
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="secondary" onClick={handleCancel}>
-                        Cancel
-                      </Button>
-                      <Button variant="primary" onClick={handleSave}>
-                        Save Changes
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Modal with Footer
-          </Button>
-        </div>
-      </>
-    );
-  },
+const DeleteConfirmationTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Modal open={open} title="Remove Emily Clarke?">
+        <Modal.Body>
+          <p>
+            Removing Emily Clarke will permanently delete her assessment records for this term.
+            This action cannot be undone.
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+            <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button variant="primary-destructive" onClick={() => setOpen(false)}>Remove pupil</Button>
+          </div>
+        </Modal.Footer>
+      </Modal>
+      <Button variant="secondary-destructive" onClick={() => setOpen(true)}>Remove pupil</Button>
+    </>
+  );
 };
 
-export const WithSections: Story = {
-  render: () => (
+const ErrorModalTemplate = () => {
+  const [open, setOpen] = useState(false);
+  return (
     <>
-      <ModalManager />
-      <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-        <Button
-          onClick={() =>
-            addModalWithContent(
-              <>
-                <Modal.Header>
-                  <Modal.Title>Modal with Sections</Modal.Title>
-                </Modal.Header>
-                <Modal.Body>
-                  <Section title="Section 1" collapsible>
-                    <p>
-                      Aliquip ea tempor officia irure do qui culpa. Laborum proident laboris aliqua ad Lorem eiusmod fugiat dolore qui occaecat adipisicing.
-                      Dolore quis nisi occaecat commodo labore ad nulla aliquip in. Enim labore nisi laborum nostrud officia ad nulla ut quis.
-                      Aute excepteur quis amet aliquip. Excepteur Lorem cupidatat adipisicing consectetur ipsum Lorem.
-                    </p>
-                  </Section>
-                  <Section title="Section 2" collapsible collapsed>
-                    <p>
-                      Veniam adipisicing culpa id esse duis in officia consequat veniam ad ullamco sint sunt anim.
-                      Incididunt exercitation dolor Lorem anim aute ad deserunt. Nulla culpa sint aliqua ea Lorem sint.
-                      Elit sit consectetur minim cillum consectetur pariatur Lorem labore consectetur nisi consectetur officia exercitation.
-                      Est consectetur commodo deserunt ipsum aliqua occaecat qui sunt consectetur.
-                    </p>
-                  </Section>
-                  <Section title="Section 3" collapsible>
-                    <p>
-                      Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
-                      totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
-                    </p>
-                  </Section>
-                </Modal.Body>
-              </>,
-            )}
-        >
-          Open Modal with Sections
-        </Button>
-      </div>
+      <Modal open={open} closeHandler={() => setOpen(false)}>
+        <Modal.Header>
+          <Icon name="triangle-alert" size={24} color="var(--color-semantic-destructive-500)" />
+          <Modal.Title>Sorry, we cannot find this page</Modal.Title>
+        </Modal.Header>
+        <Modal.Body>
+          <p>
+            <strong>Please try finding the page using the navigation.</strong>
+            {' '}
+            If you cannot find what you are looking for, contact support with the error ID below.
+          </p>
+          <p style={{ marginTop: 'var(--spacing-small)', fontFamily: 'monospace', fontSize: 'var(--font-size-2-13)' }}>
+            ID: f47ecbd4-319b-11f0-a5ae-06f9b8bc5d95
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+            <Button variant="tertiary" onClick={() => setOpen(false)}>Close</Button>
+            <Button variant="primary" onClick={() => setOpen(false)}>Contact support</Button>
+          </div>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpen(true)}>Simulate page not found</Button>
     </>
-  ),
+  );
 };
 
-export const WithFormFields: Story = {
-  render: () => {
-    const handleSubmit = () => {
-      alert('Form submitted!');
-      ModalUtils.removeModal();
-    };
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Modal.Title>User Information Form</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <FormField
-                      id={generateUuid()}
-                      label="Your Name"
-                      inputType="text"
-                      inputProps={{ placeholder: 'e.g. Jane Doe' }}
-                      fieldDescription="Please enter your full name."
-                    />
-                    <FormField
-                      id={generateUuid()}
-                      label="Email Address"
-                      inputType="text"
-                      inputProps={{ placeholder: 'e.g. jane@example.com', type: 'email' }}
-                    />
-                    <FormField
-                      id={generateUuid()}
-                      label="Message"
-                      inputType="textarea"
-                      inputProps={{ placeholder: 'Enter your message here...', rows: 4 }}
-                      fieldDescription="Maximum 500 characters."
-                    />
-                    <FormField
-                      id={generateUuid()}
-                      label="Password"
-                      inputType="selectDropdown"
-                      inputProps={{
-                        options: [{ label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, { label: 'Option 3', value: 'option3' }],
-                        onSelectionChange: fn(),
-                      }}
-                    />
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="secondary" onClick={removeModal}>
-                        Cancel
-                      </Button>
-                      <Button variant="primary" onClick={handleSubmit}>
-                        Submit
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Form Modal
-          </Button>
-        </div>
-      </>
-    );
-  },
-};
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ModalManager, ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
 
-export const WithScrollableContent: Story = {
-  render: () => {
-    const handleClose = () => {
-      ModalUtils.removeModal();
-    };
+// Mount once at your app root
+function App() {
+  return (
+    <>
+      <ModalManager />
+      {/* rest of your app */}
+    </>
+  );
+}
 
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Modal.Title>Long Content Modal</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <Section title="Introduction" collapsible>
-                      <p>
-                        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-                        Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-                      </p>
-                    </Section>
-                    <Section title="Details" collapsible>
-                      <p>
-                        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
-                        Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 1"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 2"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                    <Section title="Additional Information" collapsible>
-                      <p>
-                        Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
-                        totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
-                        Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores
-                        eos qui ratione voluptatem sequi nesciunt.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Long Text Field"
-                        inputType="textarea"
-                        inputProps={{ placeholder: 'Enter long text', rows: 6 }}
-                      />
-                    </Section>
-                    <Section title="More Content" collapsible>
-                      <p>
-                        Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit,
-                        sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
-                        Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 3"
-                        inputType="number"
-                        inputProps={{ placeholder: 'Enter number' }}
-                      />
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 4"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                    <Section title="Final Section" collapsible collapsed>
-                      <p>
-                        At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque
-                        corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa
-                        qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Final Field"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="secondary" onClick={handleClose}>
-                        Close
-                      </Button>
-                      <Button variant="primary" onClick={handleClose}>
-                        Save
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Scrollable Modal
-          </Button>
-        </div>
-      </>
-    );
+// Then trigger from anywhere:
+function AssessmentActions() {
+  return (
+    <Button
+      onClick={() =>
+        ModalUtils.addModal({
+          title: 'Assessment Period Added',
+          children: (
+            <Modal.Body>
+              <p>The Spring 2026 assessment period has been added successfully.</p>
+            </Modal.Body>
+          ),
+        })
+      }
+    >
+      Open modal
+    </Button>
+  );
+}
+export default AssessmentActions;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'The canonical `ModalManager` usage pattern. Mount `<ModalManager />` once at the app root,',
+    'then call `ModalUtils.addModal(props)` from any component in the tree.',
+    '`ModalManager` always provides its own `closeHandler` — the X button and Escape key are always active.',
+    'Click the button to open the modal, then dismiss it with the X button or by pressing Escape.',
+  ].join(' '),
+);
 
-export const DestructiveAction: Story = {
-  render: () => {
-    const handleDelete = () => {
-      alert('Item deleted!');
-      ModalUtils.removeModal();
-    };
+export const WithFooterActions: Story = withDescription(
+  {
+    render: WithFooterActionsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
 
-    const handleCancel = () => {
-      ModalUtils.removeModal();
-    };
+function EditPupilButton() {
+  return (
+    <Button
+      onClick={() =>
+        ModalUtils.addModal({
+          title: 'Edit Pupil Details',
+          children: (
+            <>
+              <Modal.Body>
+                <p>Update the details below. Changes will be saved to the pupil record immediately.</p>
+              </Modal.Body>
+              <Modal.Footer>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                  <Button variant="secondary" onClick={() => ModalUtils.removeModal()}>
+                    Cancel
+                  </Button>
+                  <Button variant="primary" onClick={() => ModalUtils.removeModal()}>
+                    Save changes
+                  </Button>
+                </div>
+              </Modal.Footer>
+            </>
+          ),
+        })
+      }
+    >
+      Edit pupil details
+    </Button>
+  );
+}
+export default EditPupilButton;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A modal with a full header, body, and footer. Use `Modal.Footer` for action buttons.',
+    'Always place the primary action on the right and the cancel action on the left.',
+    'Call `ModalUtils.removeModal()` inside button handlers to close the modal after the action completes.',
+  ].join(' '),
+);
 
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Modal.Title>Confirm Deletion</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <p>Are you sure you want to delete this item? This action cannot be undone.</p>
-                    <p style={{ marginTop: '1rem', fontWeight: 'bold' }}>
-                      Item: Important Document.pdf
-                    </p>
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="secondary" onClick={handleCancel}>
-                        Cancel
-                      </Button>
-                      <Button variant="primary-destructive" onClick={handleDelete}>
-                        Delete
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Deletion Confirmation Modal
-          </Button>
-        </div>
-      </>
-    );
+export const WithFormContent: Story = withDescription(
+  {
+    render: WithFormContentTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ModalUtils, Modal, Button, FormField } from '@arbor-education/design-system.components';
+
+function AddStaffButton() {
+  return (
+    <Button
+      onClick={() =>
+        ModalUtils.addModal({
+          title: 'Add New Staff Member',
+          children: (
+            <>
+              <Modal.Body>
+                <FormField
+                  id="staff-first-name"
+                  label="First name"
+                  inputType="text"
+                  inputProps={{ placeholder: 'e.g. Sarah' }}
+                />
+                <FormField
+                  id="staff-last-name"
+                  label="Last name"
+                  inputType="text"
+                  inputProps={{ placeholder: 'e.g. Clarke' }}
+                />
+                <FormField
+                  id="staff-email"
+                  label="Email address"
+                  inputType="text"
+                  inputProps={{ placeholder: 'e.g. s.clarke@school.edu', type: 'email' }}
+                  fieldDescription="The staff member will receive a login invitation at this address."
+                />
+              </Modal.Body>
+              <Modal.Footer>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                  <Button variant="secondary" onClick={() => ModalUtils.removeModal()}>Cancel</Button>
+                  <Button variant="primary" onClick={() => ModalUtils.removeModal()}>Add staff member</Button>
+                </div>
+              </Modal.Footer>
+            </>
+          ),
+        })
+      }
+    >
+      Add staff member
+    </Button>
+  );
+}
+export default AddStaffButton;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'A modal containing a form with `FormField` components. The `Modal.Body` provides a scrollable',
+    'container so long forms scroll independently of the header and footer.',
+    'Wrap form fields in `Modal.Body` and action buttons in `Modal.Footer` to preserve this layout.',
+  ].join(' '),
+);
 
-export const SimpleConfirmation: Story = {
-  render: () => {
-    const handleConfirm = () => {
-      alert('Confirmed!');
-      ModalUtils.removeModal();
-    };
+export const DeleteConfirmation: Story = withDescription(
+  {
+    render: DeleteConfirmationTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
 
-    const handleCancel = () => {
-      ModalUtils.removeModal();
-    };
+function RemovePupilButton() {
+  const handleDelete = () => {
+    // perform the deletion...
+    ModalUtils.removeModal();
+  };
 
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Modal.Title>Confirm Action</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <p>Are you sure you want to proceed with this action?</p>
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="secondary" onClick={handleCancel}>
-                        No
-                      </Button>
-                      <Button variant="primary" onClick={handleConfirm}>
-                        Yes
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Confirmation Modal
-          </Button>
-        </div>
-      </>
-    );
+  return (
+    <Button
+      variant="secondary-destructive"
+      onClick={() =>
+        ModalUtils.addModal({
+          title: 'Remove Emily Clarke?',
+          children: (
+            <>
+              <Modal.Body>
+                <p>
+                  Removing Emily Clarke will permanently delete her assessment records for this term.
+                  This action cannot be undone.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                  <Button variant="secondary" onClick={() => ModalUtils.removeModal()}>
+                    Cancel
+                  </Button>
+                  <Button variant="primary-destructive" onClick={handleDelete}>
+                    Remove pupil
+                  </Button>
+                </div>
+              </Modal.Footer>
+            </>
+          ),
+        })
+      }
+    >
+      Remove pupil
+    </Button>
+  );
+}
+export default RemovePupilButton;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'The Arbor delete confirmation pattern. Use `variant="secondary-destructive"` on the trigger button',
+    'and `variant="primary-destructive"` on the confirm action inside the modal.',
+    'Always name the item being deleted in the modal title so users are certain of what they are removing.',
+    'Cancel goes on the left; the destructive action goes on the right.',
+  ].join(' '),
+);
 
-export const ExampleErrorModal: Story = {
-  render: () => {
-    const handleConfirm = () => {
-      ModalUtils.removeModal();
-    };
+export const ErrorModal: Story = withDescription(
+  {
+    render: ErrorModalTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ModalUtils, Modal, Button, Icon } from '@arbor-education/design-system.components';
 
-    const handleCancel = () => {
-      ModalUtils.removeModal();
-    };
-    return (
-      <>
-        <ModalManager />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addModalWithContent(
-                <>
-                  <Modal.Header>
-                    <Icon name="triangle-alert" size={24} color="var(--color-semantic-destructive-500)" />
-                    <Modal.Title>Sorry, we can’t find this page</Modal.Title>
-                  </Modal.Header>
-                  <Modal.Body>
-                    <span>
-                      <b>Please try finding the page using the navigation.</b>
-                      {' '}
-                      If you can't find what you're looking for, there are two options depending on your support plan:
-                    </span>
-                    <ul>
-                      <li>
-                        <b>Arbor supported:</b>
-                        {' '}
-                        Press here to send an email to our Support Team using our Contact Us form (the error ID will be added automatically).
-                      </li>
-                      <li>
-                        <b>Partner supported:</b>
-                        {' '}
-                        Please get in touch with your Support Partner, and let them know the error ID below.
-                      </li>
-                    </ul>
-                    <span>ID:f47ecbd4-319b-11f0-a5ae-06f9b8bc5d95</span>
-                  </Modal.Body>
-                  <Modal.Footer>
-                    <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-                      <Button variant="tertiary" onClick={handleCancel}>
-                        Close
-                      </Button>
-                      <Button variant="primary" onClick={handleConfirm}>
-                        Primary Action
-                      </Button>
-                    </div>
-                  </Modal.Footer>
-                </>,
-              )}
-          >
-            Open Deletion Confirmation Modal
-          </Button>
-        </div>
-      </>
-    );
+function SimulateError() {
+  return (
+    <Button
+      onClick={() =>
+        ModalUtils.addModal({
+          children: (
+            <>
+              <Modal.Header>
+                <Icon name="triangle-alert" size={24} color="var(--color-semantic-destructive-500)" />
+                <Modal.Title>Sorry, we cannot find this page</Modal.Title>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  <strong>Please try finding the page using the navigation.</strong>{' '}
+                  If you cannot find what you are looking for, contact support with the error ID below.
+                </p>
+                <p style={{ fontFamily: 'monospace', fontSize: 'var(--font-size-2-13)' }}>
+                  ID: f47ecbd4-319b-11f0-a5ae-06f9b8bc5d95
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                  <Button variant="tertiary" onClick={() => ModalUtils.removeModal()}>Close</Button>
+                  <Button variant="primary" onClick={() => ModalUtils.removeModal()}>Contact support</Button>
+                </div>
+              </Modal.Footer>
+            </>
+          ),
+        })
+      }
+    >
+      Simulate page not found
+    </Button>
+  );
+}
+export default SimulateError;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'An application-level error modal using `Modal.Header` for custom icon + title composition.',
+    'Note that `title` is omitted from `ModalUtils.addModal()` here — when using `Modal.Header` manually,',
+    'omit the `title` prop to avoid rendering two titles. Add `hideCloseButton` if you need to suppress',
+    'the auto-rendered X button when placing `Modal.CloseButton` inside the header.',
+  ].join(' '),
+);