@arbor-education/design-system.components 4.0.0 → 4.1.0

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

@@ -127,6 +127,55 @@ describe('WidgetCalendar', () => {
     expect(screen.getByRole('link', { name: 'Calendar' })).toHaveAttribute('href', '/calendar');
   });
 
+  test('forwards linkProps to the linked header', () => {
+    const onClick = vi.fn();
+
+    render(
+      <WidgetCalendar
+        heading="Calendar"
+        headingHref="/calendar"
+        linkProps={{ onClick, target: '_blank' }}
+        items={mockItems}
+      />,
+    );
+
+    const link = screen.getByRole('link', { name: 'Calendar' });
+    fireEvent.click(link);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(link).toHaveAttribute('target', '_blank');
+  });
+
+  test('rejects heading link props without headingHref at the type level', () => {
+    render(
+      <>
+        {/* @ts-expect-error linkProps requires headingHref */}
+        <WidgetCalendar heading="Calendar" items={mockItems} linkProps={{ onClick: vi.fn() }} />
+        {/* @ts-expect-error renderLink requires headingHref */}
+        <WidgetCalendar heading="Calendar" items={mockItems} renderLink={() => <a />} />
+      </>,
+    );
+
+    expect(screen.queryByRole('link', { name: 'Calendar' })).not.toBeInTheDocument();
+  });
+
+  test('renders the linked header through renderLink', () => {
+    render(
+      <WidgetCalendar
+        heading="Calendar"
+        headingHref="/calendar"
+        renderLink={({ href, className, children }) => (
+          <a href={href} className={className} data-router-link="true">
+            {children}
+          </a>
+        )}
+        items={mockItems}
+      />,
+    );
+
+    expect(screen.getByRole('link', { name: 'Calendar' })).toHaveAttribute('data-router-link', 'true');
+  });
+
   test('renders empty state when items is empty', () => {
     render(
       <WidgetCalendar heading="Calendar" items={[]} />,
@@ -206,4 +255,197 @@ describe('WidgetCalendar', () => {
       expect(onItemClick).toHaveBeenCalledWith('year-10');
     });
   });
+
+  describe('grouping', () => {
+    const groupedItem = (
+      id: string,
+      eventPrimaryDefinition: string,
+      group?: string,
+    ): WidgetCalendar.ItemData => ({
+      id,
+      eventType: 'primary',
+      eventPrimaryTerm: 'Class',
+      eventPrimaryDefinition,
+      eventSecondaryTerm: 'Time and location',
+      eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+      eventTimeLabel: '08:45 – 09:00',
+      ...(group ? { group } : {}),
+    });
+
+    const GROUP_HEADING_SELECTOR = '.ds-widget-calendar__group-heading';
+
+    const getGroupLabels = (container: HTMLElement): (string | null)[] => Array.from(
+      container.querySelectorAll(GROUP_HEADING_SELECTOR),
+    ).map(label => label.textContent);
+
+    const getRenderedGroups = (container: HTMLElement) => Array.from(
+      container.querySelectorAll('ul.ds-widget-calendar__list'),
+    )
+      .map(list => ({
+        label: list.previousElementSibling?.matches(GROUP_HEADING_SELECTOR)
+          ? list.previousElementSibling.textContent
+          : null,
+        items: Array.from(list.querySelectorAll('.ds-widget-calendar__primary-definition'))
+          .map(item => item.textContent),
+      }))
+      .filter(group => group.items.length > 0);
+
+    test('renders ungrouped items before all grouped items', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', 'Monday 8 June'),
+            groupedItem('detention-roster', 'Detention roster review'),
+            groupedItem('assembly', 'Whole-school assembly', 'Tuesday 9 June'),
+          ]}
+        />,
+      );
+
+      const lists = Array.from(container.querySelectorAll('ul.ds-widget-calendar__list'));
+      const ungroupedList = lists.find(list => list.textContent?.includes('Detention roster review'));
+
+      expect(ungroupedList).toBeDefined();
+      expect(lists.indexOf(ungroupedList!)).toBe(0);
+      expect(ungroupedList!.previousElementSibling).toBeNull();
+    });
+
+    test('renders group labels exactly as provided by the consumer', () => {
+      render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', 'Monday 8 June'),
+            groupedItem('assembly', 'Whole-school assembly', 'Tuesday 9 June'),
+          ]}
+        />,
+      );
+
+      expect(screen.getByText('Monday 8 June')).toBeInTheDocument();
+      expect(screen.getByText('Tuesday 9 June')).toBeInTheDocument();
+    });
+
+    test('renders each distinct group label once, with all matching items under it', () => {
+      render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', 'Monday 8 June'),
+            groupedItem('assembly', 'Whole-school assembly', 'Tuesday 9 June'),
+            groupedItem('maths-year-10', 'Maths: Year 10: 10x/Ma3', 'Monday 8 June'),
+          ]}
+        />,
+      );
+
+      const mondayList = screen.getByText('Monday 8 June').nextElementSibling;
+
+      expect(screen.getAllByText('Monday 8 June')).toHaveLength(1);
+      expect(mondayList).toContainElement(screen.getByText('Year 10: 10G'));
+      expect(mondayList).toContainElement(screen.getByText('Maths: Year 10: 10x/Ma3'));
+      expect(mondayList).not.toContainElement(screen.getByText('Whole-school assembly'));
+    });
+
+    test('renders groups in first-declared label order when items are interspersed', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', 'Mon 8 Jun'),
+            groupedItem('staff-briefing', 'Staff briefing', 'Tue 9 Jun'),
+            groupedItem('maths-year-10', 'Maths: Year 10: 10x/Ma3', 'Mon 8 Jun'),
+            groupedItem('assembly', 'Whole-school assembly', 'Wed 10 Jun'),
+            groupedItem('parents-evening', 'Parents’ evening — Year 9', 'Tue 9 Jun'),
+            groupedItem('detention-roster', 'Detention roster review', 'Thu 11 Jun'),
+          ]}
+        />,
+      );
+
+      expect(getGroupLabels(container)).toEqual(['Mon 8 Jun', 'Tue 9 Jun', 'Wed 10 Jun', 'Thu 11 Jun']);
+    });
+
+    test('respects declaration order when group labels are integer-like strings', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', '10'),
+            groupedItem('year-2', 'Year 2: 2B', '2'),
+            groupedItem('year-1', 'Year 1: 1A', '1'),
+          ]}
+        />,
+      );
+
+      expect(getGroupLabels(container)).toEqual(['10', '2', '1']);
+    });
+
+    test('respects declaration order when integer-like and non-numeric group labels are mixed', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('hall', 'Assembly', 'Main hall'),
+            groupedItem('room-3', 'Maths: 10x/Ma3', '3'),
+            groupedItem('gym', 'PE: Year 9', 'Sports hall'),
+            groupedItem('room-1', 'Science: 10y/Sc1', '1'),
+            groupedItem('room-2', 'English: 10z/En2', '2'),
+          ]}
+        />,
+      );
+
+      expect(getGroupLabels(container)).toEqual(['Main hall', '3', 'Sports hall', '1', '2']);
+    });
+
+    test('keeps the ungrouped bucket first and item order intact when integer-like labels are interspersed', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          groupItems
+          items={[
+            groupedItem('room-2-first', 'English: 10z/En2', '2'),
+            groupedItem('room-1-first', 'Science: 10y/Sc1', '1'),
+            groupedItem('no-room-first', 'Staff briefing'),
+            groupedItem('room-2-second', 'Maths: 10x/Ma3', '2'),
+            groupedItem('hall', 'Assembly', 'Main hall'),
+            groupedItem('no-room-second', 'Detention roster review'),
+            groupedItem('room-1-second', 'History: 10w/Hi4', '1'),
+          ]}
+        />,
+      );
+
+      expect(getRenderedGroups(container)).toEqual([
+        { label: null, items: ['Staff briefing', 'Detention roster review'] },
+        { label: '2', items: ['English: 10z/En2', 'Maths: 10x/Ma3'] },
+        { label: '1', items: ['Science: 10y/Sc1', 'History: 10w/Hi4'] },
+        { label: 'Main hall', items: ['Assembly'] },
+      ]);
+    });
+
+    test('drops group values when groupItems is not passed (defaults to false)', () => {
+      const { container } = render(
+        <WidgetCalendar
+          heading="Calendar"
+          items={[
+            groupedItem('year-10', 'Year 10: 10G', 'Monday 8 June'),
+            groupedItem('detention-roster', 'Detention roster review'),
+            groupedItem('assembly', 'Whole-school assembly', 'Tuesday 9 June'),
+          ]}
+        />,
+      );
+
+      expect(screen.queryByText('Monday 8 June')).not.toBeInTheDocument();
+      expect(screen.queryByText('Tuesday 9 June')).not.toBeInTheDocument();
+
+      const flatList = screen.getByText('Year 10: 10G').closest('ul');
+
+      expect(flatList).toContainElement(screen.getByText('Detention roster review'));
+      expect(flatList).toContainElement(screen.getByText('Whole-school assembly'));
+      expect(container.querySelector(GROUP_HEADING_SELECTOR)).toBeNull();
+    });
+  });
 });

package/src/components/widgetCalendar/WidgetCalendar.tsx

@@ -1,8 +1,10 @@
 import { EmptyState } from 'Components/emptyState/EmptyState';
 import { Icon } from 'Components/icon/Icon';
 import { Widget } from 'Components/widget/Widget';
+import type { WidgetHeadingLinkProps } from 'Components/widget/types';
 import type { WidgetCalendarEventType, WidgetCalendarItemProps } from './WidgetCalendarItem.js';
 import { WidgetCalendarItem } from './WidgetCalendarItem.js';
+import { Fragment } from 'react/jsx-runtime';
 
 type WidgetCalendarItemData = {
   id: string;
@@ -16,17 +18,18 @@ type WidgetCalendarItemData = {
   eventSecondaryDefinition?: React.ReactNode;
   buttonA11yText?: string;
   tooltip?: string;
+  group?: string;
 };
 
-type WidgetCalendarProps = {
+type WidgetCalendarProps = WidgetHeadingLinkProps & {
   heading: React.ReactNode;
   tooltip?: string;
-  headingHref?: string;
   items: WidgetCalendarItemData[];
   isFloating?: boolean;
   onItemClick?: (id: string) => void;
   emptyState?: React.ReactNode;
   className?: string;
+  groupItems?: boolean;
 };
 
 const defaultEmptyState = (
@@ -43,43 +46,42 @@ export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element =>
     heading,
     tooltip,
     headingHref,
+    renderLink,
+    linkProps,
     items,
     isFloating = false,
     onItemClick,
     emptyState = defaultEmptyState,
     className,
+    groupItems,
   } = props;
 
   const isEmpty = items.length === 0;
 
-  const body = (
-    <>
-      <Widget.Header>{heading}</Widget.Header>
-      <Widget.Body>
-        {!isEmpty && (
-          <ul className="ds-widget-calendar__list">
-            {items.map(item => (
-              <WidgetCalendarItem
-                key={item.id}
-                id={item.id}
-                eventType={item.eventType}
-                eventPrimaryTerm={item.eventPrimaryTerm}
-                eventPrimaryDefinition={item.eventPrimaryDefinition}
-                eventSecondaryTerm={item.eventSecondaryTerm}
-                eventDateTime={item.eventDateTime}
-                eventTimeLabel={item.eventTimeLabel}
-                eventLocation={item.eventLocation}
-                eventSecondaryDefinition={item.eventSecondaryDefinition}
-                buttonA11yText={item.buttonA11yText}
-                onItemClick={onItemClick ? () => onItemClick(item.id) : undefined}
-                tooltip={item.tooltip}
-              />
-            ))}
-          </ul>
-        )}
-      </Widget.Body>
-    </>
-  );
+  const groups = ['_ungrouped'];
+
+  const groupMap: Record<string, WidgetCalendarItemData[]> = {
+    _ungrouped: [],
+  };
+
+  if (groupItems) {
+    items.forEach((item) => {
+      if (item.group) {
+        if (!groups.includes(item.group)) {
+          groupMap[item.group] = [];
+          groups.push(item.group);
+        }
+
+        groupMap[item.group]?.push(item);
+      }
+      else {
+        groupMap._ungrouped!.push(item);
+      }
+    });
+  }
+  else {
+    groupMap._ungrouped = [...items];
+  }
 
   const widgetProps = {
     tooltip,
@@ -87,12 +89,54 @@ export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element =>
     isEmpty,
     emptyState,
     className,
-    ...(headingHref ? { href: headingHref } : {}),
+    ...(headingHref ? { href: headingHref, renderLink, linkProps } : {}),
   } as Widget.Props;
 
   return (
     <Widget {...widgetProps}>
-      {body}
+      <Widget.Header>{heading}</Widget.Header>
+      <Widget.Body>
+        {!isEmpty && (
+          groups.map((group) => {
+            const label = group;
+            const eventItems = groupMap[group]!;
+
+            return (
+              <Fragment key={`widgetCalendarGroup_${group}`}>
+                {label !== '_ungrouped' && (
+                  <span
+                    key={`groupLabel_${label}`}
+                    className="ds-widget-calendar__group-heading"
+                  >
+                    {label}
+                  </span>
+                )}
+                {eventItems.length > 0 && (
+                  <ul key={label} className="ds-widget-calendar__list">
+                    {eventItems.map(item => (
+                      <WidgetCalendarItem
+                        key={item.id}
+                        id={item.id}
+                        eventType={item.eventType}
+                        eventPrimaryTerm={item.eventPrimaryTerm}
+                        eventPrimaryDefinition={item.eventPrimaryDefinition}
+                        eventSecondaryTerm={item.eventSecondaryTerm}
+                        eventDateTime={item.eventDateTime}
+                        eventTimeLabel={item.eventTimeLabel}
+                        eventLocation={item.eventLocation}
+                        eventSecondaryDefinition={item.eventSecondaryDefinition}
+                        buttonA11yText={item.buttonA11yText}
+                        onItemClick={onItemClick ? () => onItemClick(item.id) : undefined}
+                        tooltip={item.tooltip}
+                      />
+                    ))}
+                  </ul>
+                )}
+              </Fragment>
+            );
+          })
+        )}
+      </Widget.Body>
     </Widget>
   );
 };

package/src/components/widgetCalendar/widgetCalendar.scss

@@ -122,3 +122,12 @@
 .ds-widget-calendar__item--interactive:hover .ds-widget-calendar__action {
   color: var(--widget-list-row-hover-color-icon-arrow);
 }
+
+.ds-widget-calendar__group-heading {
+  color: var(--widget-calendar-color-text);
+  font-family: var(--type-body-bold-family);
+  font-size: var(--type-body-bold-size);
+  font-style: normal;
+  font-weight: var(--type-body-bold-weight);
+  line-height: 150%;
+}

package/src/components/widgetFavourites/WidgetFavourites.stories.tsx

@@ -25,6 +25,12 @@ const initialItems: WidgetFavouritesItemData[] = [
   { id: 'calendar', label: 'School Calendar', href: '/calendar' },
 ];
 
+const longListItems: WidgetFavouritesItemData[] = Array.from({ length: 20 }, (_, index) => ({
+  id: `favourite-${index + 1}`,
+  label: `Favourite page ${index + 1}`,
+  href: `/favourites/${index + 1}`,
+}));
+
 const DESCRIPTION_INTRO = [
   '`WidgetFavourites` is a pre-composed dashboard widget for starred pages.',
   'It wraps [`Widget`](?path=/docs/components-widget--docs) with a linked header and a list of favourite rows —',
@@ -59,11 +65,22 @@ const DEVELOPER_NOTES = [
   '**Row link and remove are siblings.** The remove button is not nested inside the row anchor —',
   'same pattern as sidebar favourites. Click handlers call `event.stopPropagation()`.',
   '',
+  '**Height is bounded by a token.** `WidgetFavourites` caps itself at `--widget-favourites-max-height` (375px),',
+  'so a long list scrolls inside the widget body instead of growing the page. Override the token on an ancestor',
+  'to change the cap; no parent height is required.',
+  '',
   '**Empty list uses Widget empty state.** When `items` is empty, `WidgetFavourites` sets `isEmpty` on the',
   'underlying `Widget` and renders the default or custom `emptyState`.',
   '',
   '**Undo removal.** Wire removal in the parent and pass a foreground toast with `toastActions` for the recommended product flow.',
   '',
+  '**`renderLink` and `linkProps` apply to the heading link only.** Both are forwarded to `Widget` only when',
+  '`headingHref` is set, and the types reject either prop without `headingHref`.',
+  '',
+  '**Items accept `linkProps` for row click handling.** `items[].linkProps` (or `linkProps` on',
+  '`WidgetFavourites.Item`) is spread onto the row `<a>`. `href` and `className` are applied after the spread',
+  'and cannot be overridden.',
+  '',
   '---',
   '',
   '### Accessibility',
@@ -300,6 +317,90 @@ const WithConfirmRemoveTemplate = () => {
   );
 };
 
+// Modifier-clicks (cmd/ctrl/shift/alt) open new tabs or windows, so leave them to the browser.
+const isModifiedClick = (event: React.MouseEvent<HTMLAnchorElement>) =>
+  event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+
+const LastClicked = ({ label, placeholder }: { label: string | null; placeholder: string }) => (
+  <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+    {label
+      ? (
+          <>
+            Last clicked:
+            {' '}
+            {label}
+          </>
+        )
+      : placeholder}
+  </span>
+);
+
+const handleHeadingLinkClick = fn().mockName('linkProps.onClick');
+const handleItemLinkClick = fn().mockName('items[].linkProps.onClick');
+
+const WithHeadingLinkPropsTemplate = () => {
+  const [lastClickedHref, setLastClickedHref] = useState<string | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetFavourites
+        heading={`Favourites (${initialItems.length})`}
+        tooltip="Your starred pages appear here"
+        headingHref="/favourites"
+        isFloating
+        items={initialItems}
+        linkProps={{
+          onClick: (event) => {
+            handleHeadingLinkClick(event);
+            if (isModifiedClick(event)) {
+              return;
+            }
+            event.preventDefault();
+            setLastClickedHref(event.currentTarget.getAttribute('href'));
+          },
+        }}
+      />
+      <LastClicked
+        label={lastClickedHref}
+        placeholder="Click the heading to see the handled navigation captured here."
+      />
+    </div>
+  );
+};
+
+const WithItemLinkPropsTemplate = () => {
+  const [lastClickedLabel, setLastClickedLabel] = useState<string | null>(null);
+
+  const items = initialItems.map((item): WidgetFavouritesItemData => ({
+    ...item,
+    linkProps: {
+      onClick: (event) => {
+        handleItemLinkClick(item.id, event);
+        if (isModifiedClick(event)) {
+          return;
+        }
+        event.preventDefault();
+        setLastClickedLabel(item.label);
+      },
+    },
+  }));
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetFavourites
+        heading={`Favourites (${items.length})`}
+        tooltip="Your starred pages appear here"
+        isFloating
+        items={items}
+      />
+      <LastClicked
+        label={lastClickedLabel}
+        placeholder="Click a favourite to see it captured here."
+      />
+    </div>
+  );
+};
+
 const EmptyTemplate = () => (
   <WidgetFavourites
     heading="Favourites (0)"
@@ -320,6 +421,112 @@ export const Default: Story = withDescription(
   'Recommended product flow: remove a favourite, then undo via a foreground toast. Each row shows the remove button when `onRemoveItem` is wired.',
 );
 
+export const WithHeadingLinkProps: Story = {
+  name: 'With heading linkProps',
+  ...withDescription(
+    {
+      render: WithHeadingLinkPropsTemplate,
+      parameters: {
+        controls: { disable: true },
+        docs: {
+          source: {
+            language: 'tsx',
+            code: `
+import { WidgetFavourites } from '@arbor-education/design-system.components';
+
+function FavouritesHeadingLinkPropsExample() {
+  return (
+    <WidgetFavourites
+      heading="Favourites"
+      headingHref="/favourites"
+      isFloating
+      items={items}
+      linkProps={{
+        onClick: (event) => {
+          // Leave modifier-clicks (new tab/window) to the browser.
+          if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            return;
+          }
+          event.preventDefault();
+          navigate('/favourites');
+        },
+      }}
+    />
+  );
+}
+export default FavouritesHeadingLinkPropsExample;
+`.trim(),
+          },
+        },
+      },
+    },
+    [
+      '**Demonstrates the `linkProps` prop** (forwarded to `Widget` when `headingHref` is set). `linkProps` is',
+      'spread onto the heading `<a>`, so consumers can attach `onClick` for analytics or client-side navigation.',
+      'Each click is logged to the Actions panel as `linkProps.onClick`. A plain click calls `preventDefault()`',
+      'and shows the destination below the widget as "Last clicked: {href}"; modifier-clicks (cmd/ctrl/shift/alt)',
+      'are left to the browser. For a custom link element (e.g. a router link) use `renderLink` instead, as in',
+      'the `Widget` "With Render Link" story. For row clicks, see "With item linkProps".',
+    ].join(' '),
+  ),
+};
+
+export const WithItemLinkProps: Story = {
+  name: 'With item linkProps',
+  ...withDescription(
+    {
+      render: WithItemLinkPropsTemplate,
+      parameters: {
+        controls: { disable: true },
+        docs: {
+          source: {
+            language: 'tsx',
+            code: `
+import { useState } from 'react';
+import { WidgetFavourites } from '@arbor-education/design-system.components';
+import type { WidgetFavouritesItemData } from '@arbor-education/design-system.components';
+
+function FavouritesItemLinkPropsExample() {
+  const [lastClicked, setLastClicked] = useState<string | null>(null);
+
+  const items: WidgetFavouritesItemData[] = favourites.map(item => ({
+    ...item,
+    linkProps: {
+      onClick: (event) => {
+        // Leave modifier-clicks (new tab/window) to the browser.
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+          return;
+        }
+        event.preventDefault();
+        setLastClicked(item.label);
+        navigate(item.href);
+      },
+    },
+  }));
+
+  return (
+    <>
+      <WidgetFavourites heading="Favourites" isFloating items={items} />
+      <span>Last clicked: {lastClicked ?? 'none yet'}</span>
+    </>
+  );
+}
+export default FavouritesItemLinkPropsExample;
+`.trim(),
+          },
+        },
+      },
+    },
+    [
+      '**Demonstrates the `linkProps` field on `items`** (also accepted by `WidgetFavourites.Item`). Each item\'s',
+      '`linkProps` is spread onto its row `<a>`; `href` and `className` are applied after the spread and cannot',
+      'be overridden. Each click is logged to the Actions panel as `items[].linkProps.onClick` with the item id.',
+      'A plain click calls `preventDefault()` and shows the clicked favourite below the widget as',
+      '"Last clicked: {label}"; modifier-clicks (cmd/ctrl/shift/alt) are left to the browser.',
+    ].join(' '),
+  ),
+};
+
 export const WithConfirmRemove: Story = withDescription(
   {
     render: WithConfirmRemoveTemplate,
@@ -330,6 +537,16 @@ export const WithConfirmRemove: Story = withDescription(
   'Alternative flow when removal must be confirmed before mutating state. The remove button opens a destructive modal.',
 );
 
+export const LongList: Story = withDescription(
+  {
+    args: {
+      heading: `Favourites (${longListItems.length})`,
+      items: longListItems,
+    },
+  },
+  'A long list stays within `--widget-favourites-max-height` (375px). The header stays fixed and only the list scrolls.',
+);
+
 export const Empty: Story = withDescription(
   {
     render: EmptyTemplate,