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

package/src/components/slideoverManager/SlideoverManager.stories.tsx

@@ -1,374 +1,604 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Heading as DocHeading,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { SlideoverManager } from './SlideoverManager';
-import { SlideoverUtils } from '../../utils/SlideoverUtils';
-import { Button } from '../button/Button';
-import { Section } from '../section/Section';
-import { FormField } from '../formField/FormField';
-import { generateUuid } from '../../utils/generateUuid';
-import { allowedIcons, type IconName } from '../icon/allowedIcons';
+import { SlideoverUtils } from 'Utils/SlideoverUtils';
+import { Button } from 'Components/button/Button';
+import { FormField } from 'Components/formField/FormField';
+import { Section } from 'Components/section/Section';
 
-type SlideoverStoryArgs = {
-  headerIcon?: IconName;
-  centerHeaderText?: boolean;
-};
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
 
-const meta: Meta<SlideoverStoryArgs> = {
+const DESCRIPTION_INTRO = [
+  '`SlideoverManager` is a container that manages a **stack** of slideover panels.',
+  'Mount it once near the root of your application and push slideovers onto the stack via `SlideoverUtils.addSlideover()`.',
+  'The built-in **Back** button pops the top panel, enabling drill-down navigation patterns.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Editing a record** while keeping the parent list visible in context',
+  '- **Detail panels** — viewing supplementary information without a full-page navigation',
+  '- **Drill-down flows** — e.g. Pupil → Assessments → Edit Assessment (stacked panels)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| A short confirmation or irreversible action | [`Modal`](?path=/docs/components-modals-modal--docs) — modals are better for blocking decisions |',
+  '| Navigation to a distinct page/route | Standard page navigation |',
+  '| A floating menu or dropdown | [`Dropdown`](?path=/docs/components-dropdown--docs) |',
+  '',
+  '---',
+  '',
+  '### `SlideoverProps` — what goes inside each panel',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `title` | `string` | — | Header title text |',
+  '| `children` | `ReactNode` | — | Main scrollable content |',
+  '| `footerContents` | `ReactNode` | — | Sticky footer — use for primary actions (Save / Cancel) |',
+  '| `headerIcon` | `IconName` | — | Icon rendered next to the title |',
+  '| `centerHeaderText` | `boolean` | `true` | Whether the header text is centred |',
+  '| `hideBackButton` | `boolean` | — | Hides the Back chevron button in the header |',
+  '',
+  '---',
+  '',
+  '### `SlideoverManager` props',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `slideovers` | `SlideoverProps[]` | — | Initial stack of slideovers to mount pre-opened |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Setup — mount once at the app root',
+  '',
+  '`SlideoverManager` must be mounted **once** near the root of your application.',
+  'It subscribes to global PubSub events — mounting multiple instances means all receive the same events,',
+  'causing duplicate slideovers.',
+  '',
+  '```tsx',
+  '// App root',
+  'function App() {',
+  '  return (',
+  '    <div>',
+  '      <SlideoverManager slideovers={[]} />',
+  '      <YourRouter />',
+  '    </div>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### Pushing and popping slideovers',
+  '',
+  '```ts',
+  "import { SlideoverUtils } from '@arbor-education/design-system.components';",
+  '',
+  '// Push a new panel onto the stack',
+  'SlideoverUtils.addSlideover({',
+  "  title: 'Edit Pupil',",
+  '  children: <EditPupilForm />,',
+  '  footerContents: (',
+  '    <>',
+  '      <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>Cancel</Button>',
+  '      <Button onClick={handleSave}>Save</Button>',
+  '    </>',
+  '  ),',
+  '});',
+  '',
+  '// Pop the top panel',
+  'SlideoverUtils.removeSlideover();',
+  '',
+  '// Clear the entire stack',
+  'SlideoverUtils.removeAllSlideovers();',
+  '```',
+  '',
+  '---',
+  '',
+  '### Stacking behaviour',
+  '',
+  'Each `SlideoverUtils.addSlideover()` call pushes a new panel on top of the current one.',
+  'The **Back** button (rendered automatically in each header) calls `SlideoverUtils.removeSlideover()` to pop the top panel.',
+  'Set `hideBackButton={true}` on panels that should not allow the user to go back — use your own close action instead.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The overlay dims the background and traps focus inside the active slideover panel.',
+  '- The Back button is keyboard accessible and labelled.',
+  '- Ensure the `title` prop is always set — it is the visible and accessible heading for the panel.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Modal](?path=/docs/components-modals-modal--docs) · [ModalManager](?path=/docs/components-modals-modalmanager--docs) · [Section](?path=/docs/components-section--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function SlideoverManagerDocsPage() {
+  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/SlideoverManager',
+  component: SlideoverManager,
+  tags: ['autodocs'],
   parameters: {
     layout: 'fullscreen',
+    docs: {
+      page: SlideoverManagerDocsPage,
+    },
   },
   argTypes: {
-    headerIcon: {
-      control: { type: 'select' },
-      options: Object.keys(allowedIcons),
-      description: 'Icon to display in the slideover header',
+    slideovers: {
+      control: false,
+      description: 'Initial stack of `SlideoverProps` to display on mount. Pass `[]` for the standard programmatic use case.',
+      table: {
+        type: { summary: 'SlideoverProps[]' },
+        defaultValue: { summary: '[]' },
+      },
     },
-    centerHeaderText: {
-      control: { type: 'boolean' },
-      description: 'Whether to center the header text',
-    },
-  },
-  args: {
-    centerHeaderText: true,
   },
-  decorators: [
-    Story => (
-      <div>
-        <Story />
-        <div style={{ padding: '1rem' }}>
-          <p>
-            The SlideoverManager is a container that manages the display of slideovers. It listens for events to add or remove slideovers.
-          </p>
-          <p>
-            Use the buttons below to add slideovers with different content.
-          </p>
-        </div>
-      </div>
-    ),
-  ],
-};
+} satisfies Meta<typeof SlideoverManager>;
 
 export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Omit<Story, 'args'>, description: string): Story => ({
+  ...(story as Story),
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
 
-type Story = StoryObj<SlideoverStoryArgs>;
+// ---------------------------------------------------------------------------
+// Page wrapper used in all templates
+// ---------------------------------------------------------------------------
 
-let slideoverCount = 0;
+const PageBackground = ({ children }: { children: React.ReactNode }) => (
+  <div style={{ padding: 'var(--spacing-xlarge)', minHeight: '100vh', background: 'var(--color-grey-050)' }}>
+    <h1 style={{ margin: '0 0 var(--spacing-large)', fontSize: 'var(--font-size-5-18)', fontWeight: 600 }}>
+      Pupil List
+    </h1>
+    <p style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>
+      Click the button below to open a slideover panel.
+    </p>
+    {children}
+  </div>
+);
 
-const addSlideoverWithContent = (content: React.ReactNode, headerIcon?: IconName, centerHeaderText?: boolean) => {
-  slideoverCount++;
-  SlideoverUtils.addSlideover({
-    title: `Slideover ${slideoverCount}`,
-    children: content,
-    headerIcon,
-    centerHeaderText,
-  });
-};
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
 
-const removeSlideover = () => {
-  if (slideoverCount > 0) {
-    slideoverCount--;
-  }
-  SlideoverUtils.removeSlideover();
-};
+const DefaultTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <div style={{ display: 'flex', gap: 'var(--spacing-small)' }}>
+      <Button
+        onClick={() =>
+          SlideoverUtils.addSlideover({
+            title: 'Pupil Record',
+            children: (
+              <p>Select a pupil from the list to view their record here.</p>
+            ),
+          })}
+      >
+        Open slideover
+      </Button>
+      <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
+        Remove last
+      </Button>
+      <Button variant="primary-destructive" onClick={SlideoverUtils.removeAllSlideovers}>
+        Close all
+      </Button>
+    </div>
+  </PageBackground>
+);
 
-const removeAllSlideovers = () => {
-  slideoverCount = 0;
-  SlideoverUtils.removeAllSlideovers();
-};
+const WithFooterActionsTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <Button
+      onClick={() =>
+        SlideoverUtils.addSlideover({
+          title: 'Edit Pupil Details',
+          children: (
+            <Section title="Personal details">
+              <FormField
+                id="pupil-name"
+                label="Full name"
+                inputType="text"
+                inputProps={{ placeholder: 'e.g. Alex Johnson', defaultValue: 'Alex Johnson' }}
+              />
+              <FormField
+                id="pupil-dob"
+                label="Date of birth"
+                inputType="text"
+                inputProps={{ placeholder: 'DD/MM/YYYY', defaultValue: '12/03/2015' }}
+              />
+              <FormField
+                id="pupil-year"
+                label="Year group"
+                inputType="text"
+                inputProps={{ defaultValue: 'Year 5' }}
+              />
+            </Section>
+          ),
+          footerContents: (
+            <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+              <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
+                Cancel
+              </Button>
+              <Button onClick={SlideoverUtils.removeSlideover}>
+                Save changes
+              </Button>
+            </div>
+          ),
+        })}
+    >
+      Edit pupil details
+    </Button>
+  </PageBackground>
+);
 
-export const Default: Story = {
-  render: args => (
-    <>
+const StackedSlideoverTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <Button
+      onClick={() =>
+        SlideoverUtils.addSlideover({
+          title: 'Pupil: Alex Johnson',
+          children: (
+            <Section title="Assessments">
+              <p style={{ margin: '0 0 var(--spacing-medium)' }}>
+                3 assessments recorded this term.
+              </p>
+              <Button
+                variant="secondary"
+                onClick={() =>
+                  SlideoverUtils.addSlideover({
+                    title: 'Edit Assessment',
+                    children: (
+                      <>
+                        <FormField
+                          id="assessment-name"
+                          label="Assessment name"
+                          inputType="text"
+                          inputProps={{ defaultValue: 'Autumn Reading Assessment' }}
+                        />
+                        <FormField
+                          id="assessment-score"
+                          label="Score"
+                          inputType="number"
+                          inputProps={{ defaultValue: '78', min: 0, max: 100 }}
+                        />
+                        <FormField
+                          id="assessment-notes"
+                          label="Notes"
+                          inputType="textarea"
+                          inputProps={{ placeholder: 'Add a note…' }}
+                        />
+                      </>
+                    ),
+                    footerContents: (
+                      <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                        <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
+                          Cancel
+                        </Button>
+                        <Button onClick={SlideoverUtils.removeSlideover}>
+                          Save
+                        </Button>
+                      </div>
+                    ),
+                  })}
+              >
+                Edit latest assessment
+              </Button>
+            </Section>
+          ),
+        })}
+    >
+      View pupil record
+    </Button>
+  </PageBackground>
+);
+
+const HideBackButtonTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <Button
+      onClick={() =>
+        SlideoverUtils.addSlideover({
+          title: 'Confirm deletion',
+          hideBackButton: true,
+          children: (
+            <p>
+              Are you sure you want to remove
+              {' '}
+              <strong>Alex Johnson</strong>
+              {' '}
+              from Year 5?
+              This cannot be undone.
+            </p>
+          ),
+          footerContents: (
+            <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+              <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
+                Cancel
+              </Button>
+              <Button variant="primary-destructive" onClick={SlideoverUtils.removeSlideover}>
+                Remove pupil
+              </Button>
+            </div>
+          ),
+        })}
+    >
+      Remove pupil
+    </Button>
+  </PageBackground>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SlideoverManager, SlideoverUtils } from '@arbor-education/design-system.components';
+
+// Mount SlideoverManager once near your app root.
+// Then call SlideoverUtils.addSlideover() from anywhere in the tree.
+function AppRoot() {
+  return (
+    <div>
       <SlideoverManager slideovers={[]} />
-      <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-        <Button
+      <main>
+        <button
+          type="button"
           onClick={() =>
-            addSlideoverWithContent(<p>This is a simple slideover.</p>, args.headerIcon, args.centerHeaderText)}
+            SlideoverUtils.addSlideover({
+              title: 'Pupil Record',
+              children: <p>Pupil details go here.</p>,
+            })
+          }
         >
-          Add Simple Slideover
-        </Button>
-        <Button onClick={removeSlideover} variant="secondary">
-          Remove Last Slideover
-        </Button>
-        <Button onClick={removeAllSlideovers} variant="primary-destructive">
-          Remove All
-        </Button>
-      </div>
-    </>
-  ),
-};
+          Open slideover
+        </button>
+      </main>
+    </div>
+  );
+}
+export default AppRoot;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Mount `SlideoverManager` once near the root of your application.',
+    'Then call `SlideoverUtils.addSlideover()` from anywhere — event handlers, Redux actions, or any component in the tree.',
+    'The **Back** button in the panel header calls `SlideoverUtils.removeSlideover()` automatically.',
+  ].join(' '),
+);
 
-export const WithSections: Story = {
-  render: args => (
+export const WithFooterActions: Story = withDescription(
+  {
+    render: WithFooterActionsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button, FormField, Section, SlideoverManager, SlideoverUtils } from '@arbor-education/design-system.components';
+
+function EditPupilButton() {
+  return (
     <>
       <SlideoverManager slideovers={[]} />
-      <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-        <Button
-          onClick={() =>
-            addSlideoverWithContent(
-              <>
-                <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. Deserunt dolor veniam sit mollit elit aliquip duis.</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>
-              </>,
-              args.headerIcon,
-              args.centerHeaderText,
-            )}
-        >
-          Add Slideover with Sections
-        </Button>
-        <Button onClick={removeSlideover} variant="secondary">
-          Remove Last Slideover
-        </Button>
-        <Button onClick={removeAllSlideovers} variant="primary-destructive">
-          Remove All
-        </Button>
-      </div>
+      <Button
+        onClick={() =>
+          SlideoverUtils.addSlideover({
+            title: 'Edit Pupil Details',
+            children: (
+              <Section title="Personal details">
+                <FormField id="pupil-name" label="Full name" inputType="text" inputProps={{ placeholder: 'e.g. Alex Johnson' }} />
+                <FormField id="pupil-dob" label="Date of birth" inputType="text" inputProps={{ placeholder: 'DD/MM/YYYY' }} />
+              </Section>
+            ),
+            footerContents: (
+              <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
+                  Cancel
+                </Button>
+                <Button onClick={() => { /* save logic */ SlideoverUtils.removeSlideover(); }}>
+                  Save changes
+                </Button>
+              </div>
+            ),
+          })
+        }
+      >
+        Edit pupil details
+      </Button>
     </>
-  ),
-};
-
-export const WithFormFields: Story = {
-  render: (args) => {
-    const formFieldId = generateUuid();
-    return (
-      <>
-        <SlideoverManager slideovers={[]} />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() =>
-              addSlideoverWithContent(
-                <>
-                  <FormField
-                    id={formFieldId}
-                    label="Your Name"
-                    inputType="text"
-                    inputProps={{ placeholder: 'e.g. Jane Doe' }}
-                    fieldDescription="Please enter your full name."
-                  />
-                </>,
-                args.headerIcon,
-                args.centerHeaderText,
-              )}
-          >
-            Add Slideover with Form
-          </Button>
-          <Button onClick={removeSlideover} variant="secondary">
-            Remove Last Slideover
-          </Button>
-          <Button onClick={removeAllSlideovers} variant="primary-destructive">
-            Remove All
-          </Button>
-        </div>
-      </>
-    );
+  );
+}
+export default EditPupilButton;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Pass `footerContents` to render a sticky footer with action buttons.',
+    'Use `SlideoverUtils.removeSlideover()` in your Save and Cancel handlers to close the panel after the action completes.',
+  ].join(' '),
+);
 
-export const WithFooterContent: Story = {
-  render: (args) => {
-    const handleSave = () => {
-      alert('Save clicked!');
-      SlideoverUtils.removeSlideover();
-    };
+export const StackedSlideovers: Story = withDescription(
+  {
+    render: StackedSlideoverTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button, FormField, Section, SlideoverManager, SlideoverUtils } from '@arbor-education/design-system.components';
 
-    const handleCancel = () => {
-      SlideoverUtils.removeSlideover();
-    };
-
-    const footerContent = (
-      <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>
-    );
-
-    return (
-      <>
-        <SlideoverManager slideovers={[]} />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() => {
-              slideoverCount++;
-              SlideoverUtils.addSlideover({
-                title: `Slideover ${slideoverCount}`,
-                children: (
-                  <>
-                    <Section title="Edit Settings">
-                      <FormField
-                        id={generateUuid()}
-                        label="Setting Name"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter setting name' }}
-                      />
-                      <FormField
-                        id={generateUuid()}
-                        label="Description"
-                        inputType="textarea"
-                        inputProps={{ placeholder: 'Enter description', rows: 4 }}
-                      />
-                    </Section>
-                  </>
-                ),
-                footerContents: footerContent,
-                headerIcon: args.headerIcon,
-                centerHeaderText: args.centerHeaderText,
-              });
-            }}
-          >
-            Add Slideover with Footer
-          </Button>
-          <Button onClick={removeSlideover} variant="secondary">
-            Remove Last Slideover
-          </Button>
-          <Button onClick={removeAllSlideovers} variant="primary-destructive">
-            Remove All
-          </Button>
-        </div>
-      </>
-    );
+// Each addSlideover() call stacks a new panel on top.
+// The Back button in each header pops the top panel.
+function PupilDrillDown() {
+  return (
+    <>
+      <SlideoverManager slideovers={[]} />
+      <Button
+        onClick={() =>
+          SlideoverUtils.addSlideover({
+            title: 'Pupil: Alex Johnson',
+            children: (
+              <Section title="Assessments">
+                <Button
+                  variant="secondary"
+                  onClick={() =>
+                    SlideoverUtils.addSlideover({
+                      title: 'Edit Assessment',
+                      children: (
+                        <FormField id="score" label="Score" inputType="number" inputProps={{ defaultValue: '78' }} />
+                      ),
+                      footerContents: (
+                        <Button onClick={SlideoverUtils.removeSlideover}>Save</Button>
+                      ),
+                    })
+                  }
+                >
+                  Edit latest assessment
+                </Button>
+              </Section>
+            ),
+          })
+        }
+      >
+        View pupil record
+      </Button>
+    </>
+  );
+}
+export default PupilDrillDown;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Each `SlideoverUtils.addSlideover()` call stacks a new panel on top of the current one.',
+    'The user can drill down through related records and navigate back with the **Back** button.',
+    'This is the primary pattern for Pupil → Assessment → Edit flows in Arbor.',
+  ].join(' '),
+);
 
-export const WithScrollableContent: Story = {
-  render: (args) => {
-    const footerContent = (
-      <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end' }}>
-        <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>
-          Cancel
-        </Button>
-        <Button variant="primary" onClick={SlideoverUtils.removeSlideover}>
-          Save
-        </Button>
-      </div>
-    );
+export const HideBackButton: Story = withDescription(
+  {
+    render: HideBackButtonTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button, SlideoverManager, SlideoverUtils } from '@arbor-education/design-system.components';
 
-    return (
-      <>
-        <SlideoverManager slideovers={[]} />
-        <div style={{ padding: '1rem', display: 'flex', gap: '1rem' }}>
-          <Button
-            onClick={() => {
-              slideoverCount++;
-              SlideoverUtils.addSlideover({
-                title: `Slideover ${slideoverCount}`,
-                children: (
-                  <>
-                    <Section title="Section 1" 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>
-                      <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="Section 2" 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 3"
-                        inputType="textarea"
-                        inputProps={{ placeholder: 'Enter long text', rows: 6 }}
-                      />
-                    </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>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 4"
-                        inputType="number"
-                        inputProps={{ placeholder: 'Enter number' }}
-                      />
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 5"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                    <Section title="Section 4" collapsible>
-                      <p>
-                        Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores
-                        eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 6"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                    <Section title="Section 5" collapsible>
-                      <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.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 7"
-                        inputType="textarea"
-                        inputProps={{ placeholder: 'Enter description', rows: 4 }}
-                      />
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 8"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                    <Section title="Section 6" collapsible collapsed>
-                      <p>
-                        Similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
-                        Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio.
-                      </p>
-                      <FormField
-                        id={generateUuid()}
-                        label="Field 9"
-                        inputType="text"
-                        inputProps={{ placeholder: 'Enter value' }}
-                      />
-                    </Section>
-                  </>
-                ),
-                footerContents: footerContent,
-                headerIcon: args.headerIcon,
-                centerHeaderText: args.centerHeaderText,
-              });
-            }}
-          >
-            Add Slideover with Scrollable Content
-          </Button>
-          <Button onClick={removeSlideover} variant="secondary">
-            Remove Last Slideover
-          </Button>
-          <Button onClick={removeAllSlideovers} variant="primary-destructive">
-            Remove All
-          </Button>
-        </div>
-      </>
-    );
+// hideBackButton prevents the user navigating back — use when the action must be
+// explicitly confirmed or cancelled, not dismissed by accident.
+function RemovePupilButton() {
+  return (
+    <>
+      <SlideoverManager slideovers={[]} />
+      <Button
+        variant="primary-destructive"
+        onClick={() =>
+          SlideoverUtils.addSlideover({
+            title: 'Confirm deletion',
+            hideBackButton: true,
+            children: (
+              <p>Are you sure you want to remove Alex Johnson from Year 5?</p>
+            ),
+            footerContents: (
+              <div style={{ display: 'flex', gap: 'var(--spacing-small)', justifyContent: 'flex-end' }}>
+                <Button variant="secondary" onClick={SlideoverUtils.removeSlideover}>Cancel</Button>
+                <Button variant="primary-destructive" onClick={SlideoverUtils.removeSlideover}>Remove pupil</Button>
+              </div>
+            ),
+          })
+        }
+      >
+        Remove pupil
+      </Button>
+    </>
+  );
+}
+export default RemovePupilButton;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Set `hideBackButton={true}` when the panel represents an action the user must explicitly confirm or cancel.',
+    'Without a Back button, the user must interact with the footer actions — reducing accidental dismissal.',
+  ].join(' '),
+);