@arbor-education/design-system.components 4.3.0 → 4.5.0

package/src/components/slideover/Slideover.test.tsx

@@ -1,5 +1,5 @@
-import { expect, test, describe, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { expect, test, describe, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, createEvent, act } from '@testing-library/react';
 import { Slideover } from './Slideover.js';
 import '@testing-library/jest-dom/vitest';
 import { SlideoverUtils } from 'Utils/SlideoverUtils';
@@ -10,7 +10,17 @@ vi.mock('Utils/SlideoverUtils', () => ({
   },
 }));
 
+const fireTransitionEnd = (element: Element, propertyName: string) => {
+  const event = createEvent.transitionEnd(element);
+  Object.defineProperty(event, 'propertyName', { value: propertyName });
+  fireEvent(element, event);
+};
+
 describe('Slideover', () => {
+  beforeEach(() => {
+    vi.mocked(SlideoverUtils.removeSlideover).mockClear();
+  });
+
   test('renders the title and children', () => {
     render(<Slideover title="My Test Slideover"><div>My Content</div></Slideover>);
     expect(screen.getByText('My Test Slideover')).toBeInTheDocument();
@@ -33,4 +43,144 @@ describe('Slideover', () => {
     fireEvent.click(backButton);
     expect(SlideoverUtils.removeSlideover).toHaveBeenCalled();
   });
+
+  describe('onBack', () => {
+    test('calls onBack instead of removeSlideover when provided', () => {
+      const onBack = vi.fn();
+      render(<Slideover onBack={onBack} />);
+
+      fireEvent.click(screen.getByRole('button', { name: /Back/i }));
+
+      expect(onBack).toHaveBeenCalledTimes(1);
+      expect(SlideoverUtils.removeSlideover).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('backButtonText', () => {
+    test('labels the back button with backButtonText', () => {
+      render(<Slideover backButtonText="Yn ôl" />);
+      expect(screen.getByRole('button', { name: 'Yn ôl' })).toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: 'Back' })).not.toBeInTheDocument();
+    });
+
+    test('defaults the label to Back', () => {
+      render(<Slideover />);
+      expect(screen.getByRole('button', { name: 'Back' })).toBeInTheDocument();
+    });
+  });
+
+  describe('headerActions', () => {
+    test('renders header actions in the header', () => {
+      render(<Slideover title="Student" headerActions={<button type="button">Edit</button>} />);
+      const header = screen.getByRole('heading', { name: 'Student' }).parentElement;
+      expect(header).toContainElement(screen.getByRole('button', { name: 'Edit' }));
+    });
+
+    test('renders no header actions container when headerActions is not provided', () => {
+      const { container } = render(<Slideover />);
+      expect(container.querySelector('.ds-slideover__header-actions')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('closing', () => {
+    test('is not marked as closing by default', () => {
+      const { container } = render(<Slideover />);
+      expect(container.querySelector('.ds-slideover')).not.toHaveClass('ds-slideover--closing');
+    });
+
+    test('is marked as closing when isClosing is set', () => {
+      const { container } = render(<Slideover isClosing />);
+      expect(container.querySelector('.ds-slideover')).toHaveClass('ds-slideover--closing');
+    });
+
+    test('calls onCloseTransitionEnd when the closing slide-out finishes', () => {
+      const onCloseTransitionEnd = vi.fn();
+      const { container } = render(<Slideover isClosing onCloseTransitionEnd={onCloseTransitionEnd} />);
+
+      fireTransitionEnd(container.querySelector('.ds-slideover')!, 'right');
+
+      expect(onCloseTransitionEnd).toHaveBeenCalledTimes(1);
+    });
+
+    test('does not call onCloseTransitionEnd when the enter slide-in finishes', () => {
+      const onCloseTransitionEnd = vi.fn();
+      const { container } = render(<Slideover onCloseTransitionEnd={onCloseTransitionEnd} />);
+
+      fireTransitionEnd(container.querySelector('.ds-slideover')!, 'right');
+
+      expect(onCloseTransitionEnd).not.toHaveBeenCalled();
+    });
+
+    describe('when the slide-out transition never runs', () => {
+      beforeEach(() => {
+        vi.useFakeTimers();
+      });
+
+      afterEach(() => {
+        vi.useRealTimers();
+      });
+
+      test('still calls onCloseTransitionEnd once the transition time has passed', () => {
+        const onCloseTransitionEnd = vi.fn();
+        render(<Slideover isClosing onCloseTransitionEnd={onCloseTransitionEnd} />);
+
+        act(() => {
+          vi.advanceTimersByTime(299);
+        });
+        expect(onCloseTransitionEnd).not.toHaveBeenCalled();
+
+        act(() => {
+          vi.advanceTimersByTime(200);
+        });
+        expect(onCloseTransitionEnd).toHaveBeenCalledTimes(1);
+      });
+
+      test('calls onCloseTransitionEnd once when the transition does finish', () => {
+        const onCloseTransitionEnd = vi.fn();
+        const { container } = render(<Slideover isClosing onCloseTransitionEnd={onCloseTransitionEnd} />);
+
+        fireTransitionEnd(container.querySelector('.ds-slideover')!, 'right');
+        act(() => {
+          vi.advanceTimersByTime(1000);
+        });
+
+        expect(onCloseTransitionEnd).toHaveBeenCalledTimes(1);
+      });
+
+      test('does not call onCloseTransitionEnd if closing is cancelled first', () => {
+        const onCloseTransitionEnd = vi.fn();
+        const { rerender } = render(<Slideover isClosing onCloseTransitionEnd={onCloseTransitionEnd} />);
+
+        rerender(<Slideover onCloseTransitionEnd={onCloseTransitionEnd} />);
+        act(() => {
+          vi.advanceTimersByTime(1000);
+        });
+
+        expect(onCloseTransitionEnd).not.toHaveBeenCalled();
+      });
+    });
+
+    test('ignores transitions of other properties and of child elements', () => {
+      const onCloseTransitionEnd = vi.fn();
+      const { container } = render(
+        <Slideover isClosing onCloseTransitionEnd={onCloseTransitionEnd}>
+          <div data-testid="child" />
+        </Slideover>,
+      );
+
+      fireTransitionEnd(container.querySelector('.ds-slideover')!, 'opacity');
+      fireTransitionEnd(screen.getByTestId('child'), 'right');
+
+      expect(onCloseTransitionEnd).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('accessibility attributes', () => {
+    test('forwards role and aria attributes to the panel', () => {
+      render(<Slideover title="Student" role="dialog" aria-label="Student details" aria-modal />);
+      const panel = screen.getByRole('dialog', { name: 'Student details' });
+      expect(panel).toHaveAttribute('aria-modal', 'true');
+      expect(panel).toHaveClass('ds-slideover');
+    });
+  });
 });

package/src/components/slideover/Slideover.tsx

@@ -3,18 +3,26 @@ import { Button } from 'Components/button/Button';
 import { Heading } from 'Components/heading/Heading';
 import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
-import { useState, type ReactNode } from 'react';
+import { useEffect, useRef, useState, type HTMLAttributes, type ReactNode, type TransitionEvent } from 'react';
 import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
 import { SlideoverUtils } from 'Utils/SlideoverUtils';
 
+// just over the 300ms transition in slideover.scss
+const CLOSE_TRANSITION_FALLBACK_MS = 400;
+
 export type SlideoverProps = {
   title?: string;
   children?: ReactNode;
   footerContents?: ReactNode;
   headerIcon?: IconName;
+  headerActions?: ReactNode;
   centerHeaderText?: boolean;
   hideBackButton?: boolean;
-};
+  backButtonText?: string;
+  onBack?: () => void;
+  isClosing?: boolean;
+  onCloseTransitionEnd?: () => void;
+} & Omit<HTMLAttributes<HTMLElement>, 'title' | 'children' | 'className' | 'onTransitionEnd'>;
 
 export const Slideover = (props: SlideoverProps) => {
   const {
@@ -22,8 +30,14 @@ export const Slideover = (props: SlideoverProps) => {
     children,
     footerContents,
     headerIcon,
+    headerActions,
     centerHeaderText = true,
     hideBackButton,
+    backButtonText = 'Back',
+    onBack = SlideoverUtils.removeSlideover,
+    isClosing = false,
+    onCloseTransitionEnd,
+    ...rest
   } = props;
 
   const [isFirstRender, setIsFirstRender] = useState(true);
@@ -32,19 +46,51 @@ export const Slideover = (props: SlideoverProps) => {
     setIsFirstRender(false);
   });
 
+  const hasFinishedClosingRef = useRef(false);
+  const onCloseTransitionEndRef = useRef(onCloseTransitionEnd);
+  onCloseTransitionEndRef.current = onCloseTransitionEnd;
+
+  const finishClosing = () => {
+    if (hasFinishedClosingRef.current) {
+      return;
+    }
+    hasFinishedClosingRef.current = true;
+    onCloseTransitionEndRef.current?.();
+  };
+
+  // transitionend does not fire if the slide-out never runs, so also finish on a timer
+  useEffect(() => {
+    if (!isClosing) {
+      hasFinishedClosingRef.current = false;
+      return;
+    }
+    const timeout = setTimeout(finishClosing, CLOSE_TRANSITION_FALLBACK_MS);
+    return () => clearTimeout(timeout);
+  }, [isClosing]);
+
+  const handleTransitionEnd = (event: TransitionEvent<HTMLElement>) => {
+    if (isClosing && event.target === event.currentTarget && event.propertyName === 'right') {
+      finishClosing();
+    }
+  };
+
   return (
-    <aside className={classNames('ds-slideover',
-      {
-        'ds-slideover--initial': isFirstRender,
-      },
-    )}
+    <aside
+      {...rest}
+      className={classNames('ds-slideover',
+        {
+          'ds-slideover--initial': isFirstRender,
+          'ds-slideover--closing': isClosing,
+        },
+      )}
+      onTransitionEnd={handleTransitionEnd}
     >
       <div className={classNames('ds-slideover__header', { 'ds-slideover__header--center': centerHeaderText })}>
         {
           !hideBackButton && (
-            <Button variant="tertiary" onClick={SlideoverUtils.removeSlideover}>
+            <Button variant="tertiary" onClick={() => onBack()}>
               <Icon name="chevrons-left" />
-              Back
+              {backButtonText}
             </Button>
           )
         }
@@ -52,6 +98,7 @@ export const Slideover = (props: SlideoverProps) => {
           {title}
           {headerIcon && <Icon name={headerIcon} />}
         </Heading>
+        {headerActions && <div className="ds-slideover__header-actions">{headerActions}</div>}
       </div>
 
       <div className="ds-slideover__contents">{children}</div>

package/src/components/slideover/slideover.scss

@@ -9,7 +9,8 @@
   align-items: stretch;
   transition: right 300ms ease;
 
-  &--initial {
+  &--initial,
+  &--closing {
     right: -580px;
   }
 
@@ -34,6 +35,12 @@
     }
   }
 
+  &__header-actions {
+    display: flex;
+    align-items: center;
+    gap: var(--slideover-header-spacing-padding);
+  }
+
   &__contents {
     flex-grow: 1;
     overflow-y: scroll;

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

@@ -11,6 +11,10 @@ import { SlideoverUtils } from 'Utils/SlideoverUtils';
 import { Button } from 'Components/button/Button';
 import { FormField } from 'Components/formField/FormField';
 import { Section } from 'Components/section/Section';
+import { Slideover } from 'Components/slideover/Slideover';
+import { Icon } from 'Components/icon/Icon';
+import { useState } from 'react';
+import { fn } from 'storybook/test';
 
 // ---------------------------------------------------------------------------
 // Docs page content
@@ -49,8 +53,15 @@ const USAGE_GUIDANCE = [
   '| `children` | `ReactNode` | — | Main scrollable content |',
   '| `footerContents` | `ReactNode` | — | Sticky footer — use for primary actions (Save / Cancel) |',
   '| `headerIcon` | `IconName` | — | Icon rendered next to the title |',
+  '| `headerActions` | `ReactNode` | — | Actions rendered at the end of the header, e.g. an Edit button |',
   '| `centerHeaderText` | `boolean` | `true` | Whether the header text is centred |',
   '| `hideBackButton` | `boolean` | — | Hides the Back chevron button in the header |',
+  '| `backButtonText` | `string` | `\'Back\'` | Label for the Back button — pass a translated string |',
+  '| `onBack` | `() => void` | `SlideoverUtils.removeSlideover` | Replaces what the Back button does, e.g. to confirm unsaved changes before closing |',
+  '| `isClosing` | `boolean` | `false` | Plays the slide-out transition. Keep the panel mounted until `onCloseTransitionEnd` fires |',
+  '| `onCloseTransitionEnd` | `() => void` | — | Called once the slide-out transition started by `isClosing` has finished |',
+  '',
+  'Any other HTML attribute (`role`, `aria-label`, `aria-modal`, `id`, …) is forwarded to the panel\'s `<aside>` element.',
   '',
   '---',
   '',
@@ -118,9 +129,22 @@ const DEVELOPER_NOTES = [
   '',
   '### 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.',
+  '- The overlay dims the background. It does **not** trap focus, move focus into the panel on open, or close on Escape — consumers that need modal behaviour must provide it.',
+  '- The panel renders as an `<aside>`. Pass `role="dialog"`, `aria-modal` and an `aria-label` when the slideover is used as a dialog.',
+  '- The Back button is keyboard accessible and labelled. Pass `backButtonText` to translate it.',
+  '- Ensure the `title` prop is always set — it is the visible heading for the panel.',
+].join('\n');
+
+const CUSTOM_BEHAVIOUR_NOTES = [
+  '### Intercepting Back',
+  '',
+  'By default the Back button pops the top panel. Pass `onBack` to run your own logic first — for example, asking the user to confirm before unsaved changes are lost — and call `SlideoverUtils.removeSlideover()` yourself when it is safe to close.',
+  '',
+  '### Animating a panel out',
+  '',
+  'Panels slide in on mount. To slide one out, set `isClosing` and remove it from your stack in `onCloseTransitionEnd`. This is for consumers rendering `Slideover` from their own stack; `SlideoverUtils.addSlideover` does not accept these props, because `SlideoverManager` cannot update a panel once it is added.',
+  '',
+  '`onCloseTransitionEnd` fires when the slide-out finishes, or after a short fallback delay if no transition runs (for example when the panel is hidden or motion is reduced), so a closing panel is never left mounted.',
 ].join('\n');
 
 const RELATED_COMPONENTS = [
@@ -143,6 +167,7 @@ function SlideoverManagerDocsPage() {
       <Markdown>{USAGE_GUIDANCE}</Markdown>
       <DocHeading>Developer notes</DocHeading>
       <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <Markdown>{CUSTOM_BEHAVIOUR_NOTES}</Markdown>
       <DocHeading>Examples</DocHeading>
       <Stories title="" />
       <Markdown>{RELATED_COMPONENTS}</Markdown>
@@ -384,6 +409,89 @@ const HideBackButtonTemplate = () => (
   </PageBackground>
 );
 
+const ConfirmOnBackTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <Button
+      onClick={() =>
+        SlideoverUtils.addSlideover({
+          title: 'Edit Pupil Details',
+          onBack: () => {
+            if (window.confirm('You have unsaved changes. Leave without saving?')) {
+              SlideoverUtils.removeSlideover();
+            }
+          },
+          children: (
+            <FormField
+              id="pupil-name-confirm"
+              label="Full name"
+              inputType="text"
+              inputProps={{ defaultValue: 'Alex Johnson' }}
+            />
+          ),
+        })}
+    >
+      Edit pupil details
+    </Button>
+  </PageBackground>
+);
+
+const handleEditClick = fn().mockName('headerActions Edit onClick');
+
+const HeaderActionsTemplate = () => (
+  <PageBackground>
+    <SlideoverManager slideovers={[]} />
+    <Button
+      onClick={() =>
+        SlideoverUtils.addSlideover({
+          title: 'Pupil: Alex Johnson',
+          headerActions: (
+            <Button variant="secondary" size="S" onClick={handleEditClick}>
+              <Icon name="pencil" />
+              Edit
+            </Button>
+          ),
+          children: <p>Year 5 · Registration group 5B</p>,
+        })}
+    >
+      View pupil record
+    </Button>
+  </PageBackground>
+);
+
+const ClosingTransitionTemplate = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [isClosing, setIsClosing] = useState(false);
+
+  return (
+    <PageBackground>
+      <Button
+        onClick={() => {
+          setIsClosing(false);
+          setIsOpen(true);
+        }}
+      >
+        Open slideover
+      </Button>
+      {isOpen && (
+        <div className="ds-slideover-manager ds-slideover-manager--active">
+          <Slideover
+            title="Pupil Record"
+            onBack={() => setIsClosing(true)}
+            isClosing={isClosing}
+            onCloseTransitionEnd={() => setIsOpen(false)}
+            role="dialog"
+            aria-modal
+            aria-label="Pupil Record"
+          >
+            <p>Press Back to watch the panel slide out before it is removed.</p>
+          </Slideover>
+        </div>
+      )}
+    </PageBackground>
+  );
+};
+
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -602,3 +710,39 @@ export default RemovePupilButton;
     'Without a Back button, the user must interact with the footer actions — reducing accidental dismissal.',
   ].join(' '),
 );
+
+export const ConfirmOnBack: Story = withDescription(
+  {
+    render: ConfirmOnBackTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Pass `onBack` to replace what the Back button does.',
+    'Here it asks for confirmation before closing, the pattern for protecting unsaved changes.',
+    'Call `SlideoverUtils.removeSlideover()` yourself once it is safe to close.',
+  ].join(' '),
+);
+
+export const HeaderActions: Story = withDescription(
+  {
+    render: HeaderActionsTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Use `headerActions` to place actions such as Edit at the end of the header.',
+    'Clicking Edit here logs to the Actions panel.',
+    'Pass `backButtonText` to replace the Back label, for example with a translated string.',
+  ].join(' '),
+);
+
+export const ClosingTransition: Story = withDescription(
+  {
+    render: ClosingTransitionTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Set `isClosing` to slide a panel out, and unmount it in `onCloseTransitionEnd`.',
+    'This example renders `Slideover` from its own state rather than through `SlideoverManager`,',
+    'and forwards `role`, `aria-modal` and `aria-label` to use the panel as a dialog.',
+  ].join(' '),
+);

package/src/docs/Contributing.mdx

@@ -225,6 +225,8 @@ Both are defined in `vitest.config.ts` as named Vitest projects (`unit` and `sto
 
 The Storybook project needs Playwright's Chromium browser installed locally the first time: `yarn playwright install chromium`. You can also run these tests interactively right here — click **Run Tests** in the bottom-left panel of this Storybook.
 
+Every story also runs axe-core accessibility checks scoped to WCAG 2.2 A/AA. Every story and component should meet WCAG 2.2 standards — violations surface as warnings in the test output, so address them when you touch the affected component rather than leaving them for someone else to find.
+
 ---
 
 ## Quality gates

package/src/index.ts

@@ -10,6 +10,7 @@ export { Card, type CardProps } from 'Components/card/Card';
 export { Combobox } from 'Components/combobox/Combobox';
 export { DataViewCard, type DataViewCardProps } from 'Components/dataViewCard/DataViewCard';
 export { DatePicker } from 'Components/datePicker/DatePicker';
+export { DatePickerPopover } from 'Components/datePicker/DatePickerPopover';
 export { DateTimePicker } from 'Components/dateTimePicker/DateTimePicker';
 export { Dot } from 'Components/dot/Dot';
 export { Dropdown } from 'Components/dropdown/Dropdown';

package/src/utils/SlideoverUtils.ts

@@ -2,8 +2,11 @@ import type { SlideoverProps } from 'Components/slideover/Slideover';
 import { SLIDEOVER } from './Constants.js';
 import PubSub from './PubSub.js';
 
+// SlideoverManager cannot update a panel once added, so closing props would do nothing
+type ManagedSlideoverProps = Omit<SlideoverProps, 'isClosing' | 'onCloseTransitionEnd'>;
+
 export const SlideoverUtils = {
-  addSlideover: (slideoverConfig: SlideoverProps) => PubSub.publish(SLIDEOVER.ADD_SLIDEOVER, slideoverConfig),
+  addSlideover: (slideoverConfig: ManagedSlideoverProps) => PubSub.publish(SLIDEOVER.ADD_SLIDEOVER, slideoverConfig),
   removeSlideover: () => PubSub.publish(SLIDEOVER.REMOVE_SLIDEOVER),
   removeAllSlideovers: () => PubSub.publish(SLIDEOVER.REMOVE_ALL_SLIDEOVERS),
 };