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

package/dist/components/modal/modalManager/ModalManager.stories.js

@@ -1,110 +1,488 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Heading as DocHeading, Markdown, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import { ModalManager } from './ModalManager';
-import { ModalUtils } from '../../../utils/ModalUtils';
+import { Modal } from '../../modal/Modal';
 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 { Icon } from '../../icon/Icon';
+// ---------------------------------------------------------------------------
+// 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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// 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'],
 };
 export default meta;
-let modalCount = 0;
-const addModalWithContent = (content) => {
-    modalCount++;
-    ModalUtils.addModal({
-        children: content,
-    });
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// 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 DefaultTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsx(Modal, { open: open, closeHandler: () => setOpen(false), title: "Assessment Period Added", children: _jsx(Modal.Body, { children: _jsx("p", { children: "The Spring 2026 assessment period has been added successfully. Pupils will now be able to submit work for grading." }) }) }), _jsx(Button, { onClick: () => setOpen(true), children: "Open modal" })] }));
 };
-const removeModal = () => {
-    if (modalCount > 0) {
-        modalCount--;
-    }
-    ModalUtils.removeModal();
+const WithFooterActionsTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsxs(Modal, { open: open, closeHandler: () => setOpen(false), title: "Edit Pupil Details", children: [_jsx(Modal.Body, { children: _jsx("p", { children: "Update the details below. Changes will be saved to the pupil record immediately." }) }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: () => setOpen(false), children: "Cancel" }), _jsx(Button, { variant: "primary", onClick: () => setOpen(false), children: "Save changes" })] }) })] }), _jsx(Button, { onClick: () => setOpen(true), children: "Edit pupil details" })] }));
 };
-export const Default = {
-    render: () => (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Simple Modal" }) }), _jsx(Modal.Body, { children: _jsx("p", { children: "This is a simple modal with basic content." }) })] })), children: "Open Simple Modal" }) })] })),
+const WithFormContentTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsxs(Modal, { open: open, closeHandler: () => setOpen(false), title: "Add New Staff Member", children: [_jsxs(Modal.Body, { children: [_jsx(FormField, { id: "staff-first-name", label: "First name", inputType: "text", inputProps: { placeholder: 'e.g. Sarah' } }), _jsx(FormField, { id: "staff-last-name", label: "Last name", inputType: "text", inputProps: { placeholder: 'e.g. Clarke' } }), _jsx(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." })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: () => setOpen(false), children: "Cancel" }), _jsx(Button, { variant: "primary", onClick: () => setOpen(false), children: "Add staff member" })] }) })] }), _jsx(Button, { onClick: () => setOpen(true), children: "Add staff member" })] }));
 };
-export const WithHeaderAndFooter = {
-    render: () => {
-        const handleSave = () => {
-            alert('Save clicked!');
-            ModalUtils.removeModal();
-        };
-        const handleCancel = () => {
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Modal with Header and Footer" }) }), _jsx(Modal.Body, { children: _jsx("p", { children: "This modal has both a header with a close button and a footer with action buttons." }) }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: handleCancel, children: "Cancel" }), _jsx(Button, { variant: "primary", onClick: handleSave, children: "Save Changes" })] }) })] })), children: "Open Modal with Footer" }) })] }));
-    },
+const DeleteConfirmationTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsxs(Modal, { open: open, title: "Remove Emily Clarke?", children: [_jsx(Modal.Body, { children: _jsx("p", { children: "Removing Emily Clarke will permanently delete her assessment records for this term. This action cannot be undone." }) }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: () => setOpen(false), children: "Cancel" }), _jsx(Button, { variant: "primary-destructive", onClick: () => setOpen(false), children: "Remove pupil" })] }) })] }), _jsx(Button, { variant: "secondary-destructive", onClick: () => setOpen(true), children: "Remove pupil" })] }));
 };
-export const WithSections = {
-    render: () => (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Modal with Sections" }) }), _jsxs(Modal.Body, { children: [_jsx(Section, { title: "Section 1", collapsible: true, children: _jsx("p", { children: "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." }) }), _jsx(Section, { title: "Section 2", collapsible: true, collapsed: true, children: _jsx("p", { children: "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." }) }), _jsx(Section, { title: "Section 3", collapsible: true, children: _jsx("p", { children: "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." }) })] })] })), children: "Open Modal with Sections" }) })] })),
+const ErrorModalTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsxs(Modal, { open: open, closeHandler: () => setOpen(false), children: [_jsxs(Modal.Header, { children: [_jsx(Icon, { name: "triangle-alert", size: 24, color: "var(--color-semantic-destructive-500)" }), _jsx(Modal.Title, { children: "Sorry, we cannot find this page" })] }), _jsxs(Modal.Body, { children: [_jsxs("p", { children: [_jsx("strong", { children: "Please try finding the page using the navigation." }), ' ', "If you cannot find what you are looking for, contact support with the error ID below."] }), _jsx("p", { style: { marginTop: 'var(--spacing-small)', fontFamily: 'monospace', fontSize: 'var(--font-size-2-13)' }, children: "ID: f47ecbd4-319b-11f0-a5ae-06f9b8bc5d95" })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "tertiary", onClick: () => setOpen(false), children: "Close" }), _jsx(Button, { variant: "primary", onClick: () => setOpen(false), children: "Contact support" })] }) })] }), _jsx(Button, { onClick: () => setOpen(true), children: "Simulate page not found" })] }));
 };
-export const WithFormFields = {
-    render: () => {
-        const handleSubmit = () => {
-            alert('Form submitted!');
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "User Information Form" }) }), _jsxs(Modal.Body, { children: [_jsx(FormField, { id: generateUuid(), label: "Your Name", inputType: "text", inputProps: { placeholder: 'e.g. Jane Doe' }, fieldDescription: "Please enter your full name." }), _jsx(FormField, { id: generateUuid(), label: "Email Address", inputType: "text", inputProps: { placeholder: 'e.g. jane@example.com', type: 'email' } }), _jsx(FormField, { id: generateUuid(), label: "Message", inputType: "textarea", inputProps: { placeholder: 'Enter your message here...', rows: 4 }, fieldDescription: "Maximum 500 characters." }), _jsx(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(),
-                                            } })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: removeModal, children: "Cancel" }), _jsx(Button, { variant: "primary", onClick: handleSubmit, children: "Submit" })] }) })] })), children: "Open Form Modal" }) })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    render: DefaultTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { ModalManager, ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
+
+// Mount once at your app root
+function App() {
+  return (
+    <>
+      <ModalManager />
+      {/* rest of your app */}
+    </>
+  );
+}
+
+// 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(),
+            },
+        },
     },
-};
-export const WithScrollableContent = {
-    render: () => {
-        const handleClose = () => {
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Long Content Modal" }) }), _jsxs(Modal.Body, { children: [_jsx(Section, { title: "Introduction", collapsible: true, children: _jsx("p", { children: "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." }) }), _jsxs(Section, { title: "Details", collapsible: true, children: [_jsx("p", { children: "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." }), _jsx(FormField, { id: generateUuid(), label: "Field 1", inputType: "text", inputProps: { placeholder: 'Enter value' } }), _jsx(FormField, { id: generateUuid(), label: "Field 2", inputType: "text", inputProps: { placeholder: 'Enter value' } })] }), _jsxs(Section, { title: "Additional Information", collapsible: true, children: [_jsx("p", { children: "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." }), _jsx(FormField, { id: generateUuid(), label: "Long Text Field", inputType: "textarea", inputProps: { placeholder: 'Enter long text', rows: 6 } })] }), _jsxs(Section, { title: "More Content", collapsible: true, children: [_jsx("p", { children: "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." }), _jsx(FormField, { id: generateUuid(), label: "Field 3", inputType: "number", inputProps: { placeholder: 'Enter number' } }), _jsx(FormField, { id: generateUuid(), label: "Field 4", inputType: "text", inputProps: { placeholder: 'Enter value' } })] }), _jsxs(Section, { title: "Final Section", collapsible: true, collapsed: true, children: [_jsx("p", { children: "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." }), _jsx(FormField, { id: generateUuid(), label: "Final Field", inputType: "text", inputProps: { placeholder: 'Enter value' } })] })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: handleClose, children: "Close" }), _jsx(Button, { variant: "primary", onClick: handleClose, children: "Save" })] }) })] })), children: "Open Scrollable Modal" }) })] }));
+}, [
+    '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 WithFooterActions = withDescription({
+    render: WithFooterActionsTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
+
+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(),
+            },
+        },
     },
-};
-export const DestructiveAction = {
-    render: () => {
-        const handleDelete = () => {
-            alert('Item deleted!');
-            ModalUtils.removeModal();
-        };
-        const handleCancel = () => {
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Confirm Deletion" }) }), _jsxs(Modal.Body, { children: [_jsx("p", { children: "Are you sure you want to delete this item? This action cannot be undone." }), _jsx("p", { style: { marginTop: '1rem', fontWeight: 'bold' }, children: "Item: Important Document.pdf" })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: handleCancel, children: "Cancel" }), _jsx(Button, { variant: "primary-destructive", onClick: handleDelete, children: "Delete" })] }) })] })), children: "Open Deletion Confirmation Modal" }) })] }));
+}, [
+    '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(' '));
+export const WithFormContent = 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(),
+            },
+        },
     },
-};
-export const SimpleConfirmation = {
-    render: () => {
-        const handleConfirm = () => {
-            alert('Confirmed!');
-            ModalUtils.removeModal();
-        };
-        const handleCancel = () => {
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsx(Modal.Header, { children: _jsx(Modal.Title, { children: "Confirm Action" }) }), _jsx(Modal.Body, { children: _jsx("p", { children: "Are you sure you want to proceed with this action?" }) }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "secondary", onClick: handleCancel, children: "No" }), _jsx(Button, { variant: "primary", onClick: handleConfirm, children: "Yes" })] }) })] })), children: "Open Confirmation Modal" }) })] }));
+}, [
+    '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 DeleteConfirmation = withDescription({
+    render: DeleteConfirmationTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { ModalUtils, Modal, Button } from '@arbor-education/design-system.components';
+
+function RemovePupilButton() {
+  const handleDelete = () => {
+    // perform the deletion...
+    ModalUtils.removeModal();
+  };
+
+  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(),
+            },
+        },
     },
-};
-export const ExampleErrorModal = {
-    render: () => {
-        const handleConfirm = () => {
-            ModalUtils.removeModal();
-        };
-        const handleCancel = () => {
-            ModalUtils.removeModal();
-        };
-        return (_jsxs(_Fragment, { children: [_jsx(ModalManager, {}), _jsx("div", { style: { padding: '1rem', display: 'flex', gap: '1rem' }, children: _jsx(Button, { onClick: () => addModalWithContent(_jsxs(_Fragment, { children: [_jsxs(Modal.Header, { children: [_jsx(Icon, { name: "triangle-alert", size: 24, color: "var(--color-semantic-destructive-500)" }), _jsx(Modal.Title, { children: "Sorry, we can\u2019t find this page" })] }), _jsxs(Modal.Body, { children: [_jsxs("span", { children: [_jsx("b", { children: "Please try finding the page using the navigation." }), ' ', "If you can't find what you're looking for, there are two options depending on your support plan:"] }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("b", { children: "Arbor supported:" }), ' ', "Press here to send an email to our Support Team using our Contact Us form (the error ID will be added automatically)."] }), _jsxs("li", { children: [_jsx("b", { children: "Partner supported:" }), ' ', "Please get in touch with your Support Partner, and let them know the error ID below."] })] }), _jsx("span", { children: "ID:f47ecbd4-319b-11f0-a5ae-06f9b8bc5d95" })] }), _jsx(Modal.Footer, { children: _jsxs("div", { style: { display: 'flex', gap: '1rem', justifyContent: 'flex-end' }, children: [_jsx(Button, { variant: "tertiary", onClick: handleCancel, children: "Close" }), _jsx(Button, { variant: "primary", onClick: handleConfirm, children: "Primary Action" })] }) })] })), children: "Open Deletion Confirmation Modal" }) })] }));
+}, [
+    '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 ErrorModal = withDescription({
+    render: ErrorModalTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { ModalUtils, Modal, Button, Icon } from '@arbor-education/design-system.components';
+
+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(' '));
 //# sourceMappingURL=ModalManager.stories.js.map