@arbor-education/design-system.components 4.2.0 → 4.4.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/components/widgetCalendar/WidgetCalendar.stories.tsx

@@ -166,7 +166,7 @@ const groupedItems: WidgetCalendar.ItemData[] = [
 
 const DESCRIPTION_INTRO = [
   '`WidgetCalendar` is a pre-composed dashboard widget for date/time-anchored calendar events.',
-  'It wraps [`Widget`](?path=/docs/components-widget--docs) with an event list, primary/secondary type indicators, and',
+  'It wraps [`Widget`](?path=/docs/components-widget--docs) with an event list, an eight-value event type indicator, and',
   'optional heading navigation. Each item renders a semantic `<time>` element from an ISO `eventDateTime` and a',
   'human-readable `eventTimeLabel`.',
 ].join('\n');
@@ -214,9 +214,12 @@ const DEVELOPER_NOTES = [
   'fall into the ungrouped bucket, which renders above all groups to prevent ambiguity about which group',
   'an item belongs to. Groups appear in the order their labels are first declared.',
   '',
-  '**The type-bar colour is semantic, not decorative.** `eventType="primary"` renders the brand-green bar',
-  '(`--widget-calendar-type-primary-color`), `"secondary"` renders neutral grey',
-  '(`--widget-calendar-type-secondary-color`). Choose deliberately — don\'t treat it as a purely visual toggle.',
+  '**`eventType` selects one of eight type-bar colours.** The accepted values are `primary` (the default),',
+  '`secondary`, `destructive`, `caution`, `info`, `warning`, `green`, and `purple`, matching the eight index',
+  'colours in the design. The colour is chosen by the school per event and carries no meaning of its own —',
+  '`WidgetCalendar` attaches no semantics to the value, so the same colour can represent different event',
+  'categories in different schools. Pass the value the data source supplies rather than inferring one from',
+  'the event content.',
   '',
   '**No loading, disabled, or error state exists on this component.** Handle those states in the consumer',
   '(e.g. render a Skeleton in place of `WidgetCalendar` while data loads). `isLoading` and `loadingLabel` are',
@@ -688,6 +691,80 @@ export const SecondaryEventType: Story = withDescription(
   'Isolates `eventType="secondary"` — the neutral grey type bar, used for lower-priority or generic events.',
 );
 
+export const AllEventTypes: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      items: [
+        {
+          id: 'type-primary',
+          eventType: 'primary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 10: 10G',
+          ...classEventTime,
+        },
+        {
+          id: 'type-secondary',
+          eventType: 'secondary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 8: 8B',
+          ...classEventTime,
+        },
+        {
+          id: 'type-destructive',
+          eventType: 'destructive',
+          eventPrimaryTerm: 'Exam',
+          eventPrimaryDefinition: 'GCSE Maths: Paper 1',
+          ...classEventTime,
+        },
+        {
+          id: 'type-caution',
+          eventType: 'caution',
+          eventPrimaryTerm: 'Trip',
+          eventPrimaryDefinition: 'Geography field trip',
+          ...classEventTime,
+        },
+        {
+          id: 'type-info',
+          eventType: 'info',
+          eventPrimaryTerm: 'Meeting',
+          eventPrimaryDefinition: 'Parents\' evening',
+          ...classEventTime,
+        },
+        {
+          id: 'type-warning',
+          eventType: 'warning',
+          eventPrimaryTerm: 'Deadline',
+          eventPrimaryDefinition: 'Reports due to head of year',
+          ...classEventTime,
+        },
+        {
+          id: 'type-green',
+          eventType: 'green',
+          eventPrimaryTerm: 'Club',
+          eventPrimaryDefinition: 'Football: Year 9',
+          ...classEventTime,
+        },
+        {
+          id: 'type-purple',
+          eventType: 'purple',
+          eventPrimaryTerm: 'Assembly',
+          eventPrimaryDefinition: 'Whole-school assembly',
+          ...classEventTime,
+        },
+      ],
+      onItemClick: fn(),
+    },
+    render: args => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'All eight `eventType` values side by side, so the full set of type-bar colours can be compared in one view.',
+    'The colour is chosen by the school per event — `WidgetCalendar` attaches no semantics to any of the eight',
+    'values. See the Developer notes above for the full list.',
+  ].join(' '),
+);
+
 export const NonInteractiveItems: Story = withDescription(
   {
     args: {

package/src/components/widgetCalendar/WidgetCalendar.test.tsx

@@ -60,6 +60,54 @@ describe('WidgetCalendar', () => {
     expect(container.querySelector('.ds-widget-calendar__item--secondary')).toBeInTheDocument();
   });
 
+  const eventTypes: WidgetCalendar.EventType[] = [
+    'primary',
+    'secondary',
+    'destructive',
+    'caution',
+    'info',
+    'warning',
+    'green',
+    'purple',
+  ];
+
+  test.each(eventTypes)('applies the %s modifier class and no other event type class', (eventType) => {
+    const { container } = render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={[{ ...mockItems[0]!, eventType }]}
+      />,
+    );
+
+    const item = container.querySelector('.ds-widget-calendar__item');
+
+    expect(item).toHaveClass(`ds-widget-calendar__item--${eventType}`);
+
+    eventTypes
+      .filter(otherType => otherType !== eventType)
+      .forEach((otherType) => {
+        expect(item).not.toHaveClass(`ds-widget-calendar__item--${otherType}`);
+      });
+  });
+
+  test('defaults to the primary modifier class when eventType is omitted', () => {
+    const { container } = render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={[{
+          id: 'no-type',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 10: 10G',
+          eventSecondaryTerm: 'Time and location',
+          eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+          eventTimeLabel: '08:45 – 09:00',
+        }]}
+      />,
+    );
+
+    expect(container.querySelector('.ds-widget-calendar__item')).toHaveClass('ds-widget-calendar__item--primary');
+  });
+
   test('calls onItemClick with item id', async () => {
     const user = userEvent.setup();
     const onItemClick = vi.fn();

package/src/components/widgetCalendar/WidgetCalendarItem.tsx

@@ -3,7 +3,15 @@ import { Icon } from 'Components/icon/Icon';
 import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
-export type WidgetCalendarEventType = 'primary' | 'secondary';
+export type WidgetCalendarEventType
+  = 'primary'
+    | 'secondary'
+    | 'destructive'
+    | 'caution'
+    | 'info'
+    | 'warning'
+    | 'green'
+    | 'purple';
 
 export type WidgetCalendarItemProps = {
   id: string;
@@ -68,9 +76,7 @@ export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.El
     <li
       className={classNames(
         'ds-widget-calendar__item',
-        eventType === 'secondary'
-          ? 'ds-widget-calendar__item--secondary'
-          : 'ds-widget-calendar__item--primary',
+        `ds-widget-calendar__item--${eventType}`,
         isInteractive && 'ds-widget-calendar__item--interactive',
         className,
       )}