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

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

@@ -93,6 +93,73 @@ const overflowItems: WidgetCalendar.ItemData[] = [
   ...initialItems.map((item, index) => ({ ...item, id: `${item.id}-overflow-${index}` })),
 ];
 
+const groupedItems: WidgetCalendar.ItemData[] = [
+  {
+    id: 'staff-briefing-grouped',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Meeting',
+    eventPrimaryDefinition: 'Staff briefing',
+    eventSecondaryTerm: 'Time',
+    eventDateTime: '2026-06-08T08:00/2026-06-08T08:15',
+    eventTimeLabel: '08:00 – 08:15',
+    group: 'Monday 8 June',
+  },
+  {
+    id: 'year-10-10g-grouped',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Year 10: 10G',
+    eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+    eventTimeLabel: '08:45 – 09:00',
+    eventLocation: 'Classroom 102',
+    eventSecondaryTerm: 'Time and location',
+    group: 'Monday 8 June',
+  },
+  {
+    id: 'maths-year-10-grouped',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Maths: Year 10: 10x/Ma3',
+    eventDateTime: '2026-06-08T11:15/2026-06-08T12:00',
+    eventTimeLabel: '11:15 – 12:00',
+    eventLocation: 'Classroom 102',
+    eventSecondaryTerm: 'Time and location',
+    group: 'Monday 8 June',
+  },
+  {
+    id: 'assembly-grouped',
+    eventType: 'secondary',
+    eventPrimaryTerm: 'Event',
+    eventPrimaryDefinition: 'Whole-school assembly',
+    eventDateTime: '2026-06-09T09:00/2026-06-09T09:30',
+    eventTimeLabel: '09:00 – 09:30',
+    eventLocation: 'Hall',
+    eventSecondaryTerm: 'Time and location',
+    group: 'Tuesday 9 June',
+  },
+  {
+    id: 'parents-evening-grouped',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Meeting',
+    eventPrimaryDefinition: 'Parents’ evening — Year 9',
+    eventDateTime: '2026-06-09T16:00/2026-06-09T19:00',
+    eventTimeLabel: '16:00 – 19:00',
+    eventLocation: 'Main hall',
+    eventSecondaryTerm: 'Time and location',
+    group: 'Tuesday 9 June',
+  },
+  {
+    id: 'detention-roster-ungrouped',
+    eventType: 'secondary',
+    eventPrimaryTerm: 'Event',
+    eventPrimaryDefinition: 'Detention roster review',
+    eventDateTime: '2026-06-10T15:00/2026-06-10T15:30',
+    eventTimeLabel: '15:00 – 15:30',
+    eventSecondaryTerm: 'Time',
+    // Deliberately no group — exercises the ungrouped-item fallback path
+  },
+];
+
 // ---------------------------------------------------------------------------
 // Docs page content
 // ---------------------------------------------------------------------------
@@ -140,12 +207,23 @@ const DEVELOPER_NOTES = [
   'default time + location composition — `eventLocation` becomes dead data with no warning. Never pass both',
   'in the same item.',
   '',
+  '**`group` is an arbitrary display label, not a date.** It is the pre-formatted text rendered as the',
+  'group subheading when `groupItems` groups items (e.g. `"Monday 8 June"` — but it could equally be a',
+  'location or an event type). The component performs no formatting of its own — all label formatting and',
+  'sorting is delegated to the consumer, so pass the exact label you want displayed. Items without a `group`',
+  '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.',
   '',
   '**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).',
+  '(e.g. render a Skeleton in place of `WidgetCalendar` while data loads). `isLoading` and `loadingLabel` are',
+  'deliberately not forwarded to `Widget`; consumers render loading content via `emptyState`.',
+  '',
+  '**`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`.',
   '',
   '---',
   '',
@@ -227,7 +305,10 @@ const meta = {
       description: [
         'Array of `WidgetCalendar.ItemData` objects rendered as event rows. Each item requires `id`,',
         '`eventPrimaryTerm`, `eventPrimaryDefinition`, `eventSecondaryTerm`, `eventDateTime`, and `eventTimeLabel`.',
-        '`eventType`, `eventLocation`, `eventSecondaryDefinition`, `buttonA11yText`, and `tooltip` are optional.',
+        '`eventType`, `eventLocation`, `eventSecondaryDefinition`, `buttonA11yText`, `tooltip`, and',
+        '`group` are optional. `group` is an arbitrary pre-formatted display label (e.g. `"Monday 8 June"`,',
+        'a location, or an event type) used to group items under a shared subheading — the consumer owns',
+        'all label formatting.',
       ].join(' '),
       table: {
         type: { summary: 'WidgetCalendar.ItemData[]' },
@@ -270,6 +351,19 @@ const meta = {
         type: { summary: 'string' },
       },
     },
+    groupItems: {
+      control: 'boolean',
+      description: [
+        'When `true`, items are bucketed by their `group` display label and each group is',
+        'rendered under a single subheading. Items with no `group` render first, above all',
+        'grouped items, and groups appear in the order their labels are first declared. Defaults to `false`,',
+        'so grouping is opt-in — omit the prop and `group` values are ignored entirely.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
   },
 } satisfies Meta<typeof WidgetCalendar>;
 
@@ -352,6 +446,48 @@ const InteractiveTemplate = () => {
   );
 };
 
+// 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 handleHeadingLinkClick = fn().mockName('linkProps.onClick');
+
+const WithHeadingLinkPropsTemplate = () => {
+  const [lastClickedHref, setLastClickedHref] = useState<string | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetCalendar
+        heading="Calendar"
+        headingHref="/calendar"
+        isFloating
+        items={initialItems.slice(0, 3)}
+        linkProps={{
+          onClick: (event) => {
+            handleHeadingLinkClick(event);
+            if (isModifiedClick(event)) {
+              return;
+            }
+            event.preventDefault();
+            setLastClickedHref(event.currentTarget.getAttribute('href'));
+          },
+        }}
+      />
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+        {lastClickedHref
+          ? (
+              <>
+                Last clicked:
+                {' '}
+                {lastClickedHref}
+              </>
+            )
+          : 'Click the heading to see the handled navigation captured here.'}
+      </span>
+    </div>
+  );
+};
+
 const handleComposableItemClick = fn();
 
 const ComposableTemplate = () => (
@@ -440,6 +576,56 @@ export default InteractiveCalendarExample;
   ].join(' '),
 );
 
+export const WithHeadingLinkProps: Story = {
+  name: 'With heading linkProps',
+  ...withDescription(
+    {
+      render: WithHeadingLinkPropsTemplate,
+      parameters: {
+        controls: { disable: true },
+        docs: {
+          source: {
+            language: 'tsx',
+            code: `
+import { WidgetCalendar } from '@arbor-education/design-system.components';
+
+function CalendarHeadingLinkPropsExample() {
+  return (
+    <WidgetCalendar
+      heading="Calendar"
+      headingHref="/calendar"
+      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('/calendar');
+        },
+      }}
+    />
+  );
+}
+export default CalendarHeadingLinkPropsExample;
+`.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.',
+    ].join(' '),
+  ),
+};
+
 export const PrimaryEventType: Story = withDescription(
   {
     args: {
@@ -754,3 +940,83 @@ export default ComposableCalendarExample;
     'unlike the parent `WidgetCalendar`\'s `onItemClick(id)`.',
   ].join(' '),
 );
+
+export const Grouped: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      groupItems: true,
+      items: groupedItems,
+      onItemClick: fn(),
+    },
+    render: args => <WidgetCalendar {...args} />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { WidgetCalendar } from '@arbor-education/design-system.components';
+
+function GroupedExample() {
+  return (
+    <WidgetCalendar
+      heading="Calendar"
+      groupItems
+      items={items}
+    />
+  );
+}
+export default GroupedExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`groupItems` is set and every grouped item carries a `group` display label',
+    '(`"Monday 8 June"`, `"Tuesday 9 June"` — the labels here happen to be dates, but any label works,',
+    'such as a location or event type). Each distinct label renders once, as a subheading above the',
+    'items that share it, and groups appear in the order their labels are first declared. The ungrouped',
+    'item has no `group`, so it renders first — above every grouped item — to prevent ambiguity',
+    'about which group it belongs to.',
+  ].join(' '),
+);
+
+export const Ungrouped: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      items: groupedItems,
+      onItemClick: fn(),
+    },
+    render: args => <WidgetCalendar {...args} />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { WidgetCalendar } from '@arbor-education/design-system.components';
+
+function UngroupedExample() {
+  return (
+    <WidgetCalendar
+      heading="Calendar"
+      items={items}
+    />
+  );
+}
+export default UngroupedExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`groupItems` is omitted, so it defaults to `false` and the list renders flat — the',
+    '`group` values on these items are ignored entirely and no subheadings appear.',
+    'Compare against the Grouped story: the two use the same fixture data, so any visible',
+    'difference is the grouping alone.',
+  ].join(' '),
+);

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();
+    });
+  });
 });