uikit-react-public 0.11.16 → 0.11.20

package/lib/components/Datepicker/index.ts

@@ -1,2 +1,3 @@
 export { default } from './Datepicker';
 export type { DatepickerProps } from './Datepicker';
+export type { CalendarEvent, AcademicWeek } from './Datepicker.types';

package/lib/components/Datepicker/subcomponents/AcademicWeek.tsx

@@ -0,0 +1,36 @@
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../../theme';
+
+const NAME = 'ucl-uikit-datepicker__academic-week';
+
+interface AcademicWeekProps {
+  weekNumber?: number | null;
+}
+
+const AcademicWeek = ({ weekNumber }: AcademicWeekProps) => {
+  const [theme] = useTheme();
+
+  const baseStyle = css`
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 40px;
+    font-family: ${theme.font.family.primary};
+    font-size: ${theme.font.size.f14};
+    color: #6345a5; // TODO: Needs a sensible design token
+  `;
+
+  const style = cx(NAME, baseStyle);
+
+  return (
+    <div
+      data-testid={NAME}
+      className={style}
+    >
+      {weekNumber && 'W ' + weekNumber.toString().padStart(2, '0')}
+    </div>
+  );
+};
+
+export default AcademicWeek;

package/lib/components/Datepicker/subcomponents/AcademicWeeks.tsx

@@ -0,0 +1,44 @@
+import { css, cx } from '@emotion/css';
+import AcademicWeek from './AcademicWeek';
+import { getAcademicWeekNumbers } from './../utils';
+import { useTheme } from '../../../theme';
+import type { AcademicWeek as AcademicWeekType } from '../Datepicker.types';
+
+const NAME = 'ucl-uikit-datepicker__academic-weeks';
+
+interface AcademicWeeksProps {
+  date: Date;
+  academicWeeks: AcademicWeekType[];
+}
+
+const AcademicWeeks = ({ date, academicWeeks }: AcademicWeeksProps) => {
+  const [theme] = useTheme();
+
+  const academicWeekNumbers = getAcademicWeekNumbers(academicWeeks, date);
+
+  const baseStyle = css`
+    display: flex;
+    flex-direction: column;
+    padding-top: 32px;
+    width: 50px;
+    background-color: ${theme.color.interaction.blue5};
+  `;
+
+  const style = cx(NAME, baseStyle);
+
+  return (
+    <div
+      data-testid={NAME}
+      className={style}
+    >
+      {academicWeekNumbers.map((weekNumber) => (
+        <AcademicWeek
+          key={weekNumber}
+          weekNumber={weekNumber}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default AcademicWeeks;

package/lib/components/Datepicker/subcomponents/CalendarGrid/CalendarGrid.tsx

@@ -2,16 +2,15 @@ import { css } from '@emotion/css';
 import { ColumnHeadings, Day } from '../';
 import useTheme from '../../../../theme/useTheme';
 import { getDatesForCalendarGrid } from '../../utils';
+import { CalendarEvent } from '../../Datepicker.types';
 
 interface CalendarGridProps {
   date: Date | null | undefined;
   onDatePick: (date: Date) => void;
+  events: CalendarEvent[];
 }
 
-const CalendarGrid = ({
-  date,
-  onDatePick,
-}: CalendarGridProps) => {
+const CalendarGrid = ({ date, onDatePick, events }: CalendarGridProps) => {
   const [theme] = useTheme();
 
   const dates = date
@@ -35,21 +34,17 @@ const CalendarGrid = ({
         <Day
           key={mappedDate.toISOString()}
           date={mappedDate}
-          isSelected={
-            date?.toDateString() ===
-            mappedDate.toDateString()
-          }
-          isToday={
-            mappedDate.toDateString() ===
-            new Date().toDateString()
-          }
+          isSelected={date?.toDateString() === mappedDate.toDateString()}
+          isToday={mappedDate.toDateString() === new Date().toDateString()}
           isInCurrentMonth={
             date
               ? mappedDate.getMonth() === date?.getMonth()
-              : mappedDate.getMonth() ===
-                new Date().getMonth()
+              : mappedDate.getMonth() === new Date().getMonth()
           }
           onPick={onDatePick}
+          events={events.filter(
+            (event) => event.date === mappedDate.toISOString().split('T')[0]
+          )}
         />
       ))}
     </div>

package/lib/components/Datepicker/subcomponents/CalendarMenu/CalendarMenu.tsx

@@ -1,12 +1,17 @@
 import { css } from '@emotion/css';
 import MonthSelector from '../MonthSelector';
 import CalendarGrid from '../CalendarGrid';
+import AcademicWeeks from '../AcademicWeeks';
 import useTheme from '../../../../theme/useTheme';
+import { CalendarEvent, AcademicWeek } from '../../Datepicker.types';
 
 interface CalendarMenuProps {
   date: Date | null | undefined;
   setDate: (date: Date) => void;
   onDatePick: () => void;
+  events: CalendarEvent[];
+  showAcademicWeeks?: boolean;
+  academicWeeks: AcademicWeek[];
   testId?: string;
 }
 
@@ -14,6 +19,9 @@ const CalendarMenu = ({
   date,
   setDate,
   onDatePick,
+  events,
+  showAcademicWeeks,
+  academicWeeks,
   testId = 'ucl',
 }: CalendarMenuProps) => {
   const [theme] = useTheme();
@@ -24,21 +32,30 @@ const CalendarMenu = ({
     setDate(newDate);
   };
 
+  const width = showAcademicWeeks ? '370' : '312';
+
   const style = css`
     display: flex;
     flex-direction: column;
     align-items: center;
     gap: 16px;
-    width: 280px;
-    height: 320px;
+    width: ${width}px;
     z-index: 10;
     position: absolute;
     top: 60px;
+    box-sizing: border-box;
     border: 1px solid ${theme.color.neutral.grey20};
     padding: 16px;
     background-color: ${theme.color.neutral.white};
   `;
 
+  const innerContainerStyle = css`
+    display: flex;
+    flex-direction: row;
+    gap: 8px;
+    width: 100%;
+  `;
+
   const handlePick = (pickedDate: Date) => {
     setDate(pickedDate);
     onDatePick();
@@ -53,10 +70,19 @@ const CalendarMenu = ({
         date={date}
         changeMonth={onMonthChange}
       />
-      <CalendarGrid
-        date={date}
-        onDatePick={handlePick}
-      />
+      <div className={innerContainerStyle}>
+        {showAcademicWeeks && (
+          <AcademicWeeks
+            date={date || new Date()} // TODO: more comprehsensive handling of null/undefined dates
+            academicWeeks={academicWeeks}
+          />
+        )}
+        <CalendarGrid
+          date={date}
+          onDatePick={handlePick}
+          events={events}
+        />
+      </div>
     </div>
   );
 };

package/lib/components/Datepicker/subcomponents/Day/Day.stories.tsx

@@ -4,6 +4,14 @@ import Day from './Day';
 const meta = {
   title: 'Components/Work in progress/Datepicker/Day',
   component: Day,
+  argTypes: {
+    events: {
+      table: {
+        // We don't want to show an empty array in the controls
+        disable: true,
+      },
+    },
+  },
 } satisfies Meta<typeof Day>;
 
 export default meta;
@@ -63,6 +71,21 @@ export const NotInCurrentMonth: Story = {
   },
 };
 
+export const WithEventDots: Story = {
+  args: {
+    date: new Date(),
+    events: [
+      { date: new Date().toISOString() },
+      { date: new Date().toISOString() },
+      { date: new Date().toISOString() },
+    ],
+  },
+  render: (args) => {
+    args.date = args.date ? new Date(args.date) : null;
+    return <Day {...args} />;
+  },
+};
+
 export const AlertOnPick: Story = {
   name: '(Trigger alert on pick)',
   args: {

package/lib/components/Datepicker/subcomponents/Day/Day.tsx

@@ -1,25 +1,32 @@
 import { css } from '@emotion/css';
+import EventDot from '../EventDot';
 import { useTheme } from '../../../../theme/';
+import { CalendarEvent } from '../../Datepicker.types';
 
 export interface DayProps {
   date: Date | null | undefined;
+  onPick?: (date: Date) => void;
   isSelected?: boolean;
   isToday?: boolean;
   isInCurrentMonth?: boolean;
   isDisabled?: boolean;
-  onPick?: (date: Date) => void;
+  events?: CalendarEvent[]; // Max 3 events are displayed as dots
 }
 
 const Day = ({
   date,
-  isSelected,
+  onPick,
+  isSelected = false,
   isToday = false,
   isInCurrentMonth = true,
   isDisabled = false,
-  onPick,
+  events = [],
 }: DayProps) => {
   const [theme] = useTheme();
 
+  // More than 3 dots displayed breaks the layout
+  const displayedEvents = events.slice(0, 3);
+
   const onClick = () => {
     if (date && onPick) onPick(date);
   };
@@ -28,6 +35,7 @@ const Day = ({
     display: flex;
     justify-content: center;
     align-items: center;
+    position: relative;
     width: 40px;
     height: 40px;
     background-color: ${theme.color.neutral.white};
@@ -44,8 +52,7 @@ const Day = ({
       color: ${theme.color.text.inverted};
 
       &:hover {
-        background-color: ${theme.color.interaction
-          .blue100};
+        background-color: ${theme.color.interaction.blue100};
       }
     `}
     ${isDisabled &&
@@ -77,6 +84,16 @@ const Day = ({
     `}
   `;
 
+  const eventDotsContainerStyle = css`
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 3px;
+    position: absolute;
+    bottom: 3px;
+    width: 100%;
+  `;
+
   return (
     <div
       className={backgroundStyle}
@@ -84,8 +101,15 @@ const Day = ({
       aria-label={`Select ${date?.toDateString()}`}
       onClick={onClick}
     >
-      <div className={foregroundStyle}>
-        {date?.getDate()}
+      <div className={foregroundStyle}>{date?.getDate()}</div>
+      <div className={eventDotsContainerStyle}>
+        {displayedEvents.map((_event, index) => (
+          <EventDot
+            key={index}
+            inverted={isSelected}
+            inCurrentMonth={isInCurrentMonth}
+          />
+        ))}
       </div>
     </div>
   );

package/lib/components/Datepicker/subcomponents/EventDot.tsx

@@ -0,0 +1,40 @@
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../../theme';
+
+const NAME = 'ucl-uikit-datepicker__event-dot';
+
+type EventDotProps = {
+  inverted: boolean;
+  inCurrentMonth: boolean;
+};
+
+const EventDot = ({ inverted, inCurrentMonth }: EventDotProps) => {
+  const [theme] = useTheme();
+
+  const invertedColour = theme.color.neutral.white;
+  const outOfCurrentMonthColour = '#8C8C8C'; // TODO: Needs adding to `defaultTheme.ts`, as a design token
+
+  const backgroundColour = inCurrentMonth
+    ? inverted
+      ? invertedColour
+      : theme.color.interaction.blue70
+    : outOfCurrentMonthColour;
+
+  const baseStyle = css`
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background-color: ${backgroundColour};
+  `;
+
+  const style = cx(NAME, baseStyle);
+
+  return (
+    <div
+      data-testid={NAME}
+      className={style}
+    />
+  );
+};
+
+export default EventDot;

package/lib/components/Datepicker/utils/getAcademicWeekNumbers/getAcademicWeekNumbers.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test, vi } from 'vitest';
+import getAcademicWeekNumbers, { getMonday } from './getAcademicWeekNumbers';
+import type { AcademicWeek } from '../../Datepicker.types';
+
+describe('getMonday', () => {
+  test('Returns the Monday for the week of the given date', () => {
+    const date = new Date('2025-09-03'); // Wednesday
+    const monday = getMonday(date);
+    expect(monday.getFullYear()).toBe(2025);
+    expect(monday.getMonth()).toBe(8); // September (0-indexed)
+    expect(monday.getDate()).toBe(1); // 1st September 2025
+    expect(monday.getDay()).toBe(1); // Monday
+  });
+
+  test('Works for a date that is already a Monday', () => {
+    const date = new Date('2025-10-06'); // Monday
+    const monday = getMonday(date);
+    expect(monday.getFullYear()).toBe(2025);
+    expect(monday.getMonth()).toBe(9); // October (0-indexed)
+    expect(monday.getDate()).toBe(6); // 6th October 2025
+    expect(monday.getDay()).toBe(1); // Monday
+  });
+});
+
+describe('getAcademicWeekNumbers', () => {
+  test('Returns an array of the correct numbers (works as expected)', () => {
+    const targetDate = new Date('2025-09-01'); // Monday 1st September 2025
+    const academicWeeks: AcademicWeek[] = [
+      { start: '2025-08-25', number: 1 },
+      { start: '2025-09-01', number: 2 },
+      { start: '2025-09-08', number: 3 },
+      { start: '2025-09-15', number: 4 },
+      { start: '2025-09-22', number: 5 },
+      { start: '2025-09-29', number: 6 },
+      { start: '2025-10-06', number: 7 },
+      { start: '2025-10-13', number: 8 },
+      { start: '2025-10-20', number: 9 },
+      { start: '2025-10-27', number: 10 },
+      { start: '2025-11-03', number: 11 },
+      { start: '2025-11-10', number: 12 },
+      { start: '2025-11-17', number: 13 },
+      { start: '2025-11-24', number: 14 },
+      // Etc ...
+    ];
+
+    const result = getAcademicWeekNumbers(academicWeeks, targetDate);
+    expect(result).toEqual([2, 3, 4, 5, 6]);
+  });
+
+  // Empty array for `academicWeeks` is default parameter value in `Datepicker.tsx`
+  test('Returns empty array if academicWeeks are empty', () => {
+    console.warn = vi.fn();
+    const emptyArray: AcademicWeek[] = [];
+    const result = getAcademicWeekNumbers(emptyArray, new Date());
+    expect(result).toEqual([]);
+    expect(console.warn).toHaveBeenCalledWith(
+      'Datepicker: No academic weeks provided'
+    );
+  });
+
+  test('Returns empty array if targetDate is invalid', () => {
+    const result = getAcademicWeekNumbers(
+      [{ start: '2025-08-25', number: 1 }],
+      new Date('invalid-date')
+    );
+    expect(result).toEqual([]);
+
+    const result2 = getAcademicWeekNumbers(
+      [{ start: '2025-08-25', number: 1 }],
+      null as unknown as Date
+    );
+    expect(result2).toEqual([]);
+
+    const result3 = getAcademicWeekNumbers(
+      [{ start: '2025-08-25', number: 1 }],
+      undefined as unknown as Date
+    );
+    expect(result3).toEqual([]);
+  });
+
+  test('Returns array of undefined if no academic weeks match the current date', () => {
+    // A pretend very short example for academic weeks
+    const academicWeeks: AcademicWeek[] = [
+      { start: '2025-09-01', number: 1 },
+      { start: '2025-09-08', number: 2 },
+      { start: '2025-09-15', number: 3 },
+      { start: '2025-09-22', number: 4 },
+    ];
+
+    // The date is in October, which has no matching academic weeks
+    const targetDate = new Date('2025-10-01');
+
+    const result = getAcademicWeekNumbers(academicWeeks, targetDate);
+
+    // We expect 5 weeks displayed in the calendar, with no matching academic weeks
+    expect(result).toEqual([
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+  });
+});

package/lib/components/Datepicker/utils/getAcademicWeekNumbers/getAcademicWeekNumbers.ts

@@ -0,0 +1,85 @@
+import type { AcademicWeek } from '../../Datepicker.types';
+
+// The 'calendar period' is defined here as all the dates the calendar displays,
+// which may include some dates in the previous month and some dates in the next month.
+// This is because we display complete weeks in the calendar.
+
+/**
+ * Returns the Monday for the week of the given date.
+ * For example:
+ * - If the input date is a Wednesday, it returns the Monday of that week.
+ * - If the input date is already a Monday, it returns that date.
+ * @param {Date} d - The input date.
+ * @returns {Date} The Monday of the week of the input date.
+ */
+export const getMonday = (d: Date) => {
+  const date = new Date(d);
+  const day = date.getDay();
+  const delta = (day + 6) % 7;
+  date.setDate(date.getDate() - delta);
+  date.setHours(0, 0, 0, 0);
+  return date;
+};
+
+/**
+ * Calculates the academic week numbers for each week displayed in a calendar month.
+ * Used by `<AcademicWeeks />` component in the Datepicker.
+ * It determines the Mondays of each week shown in the calendar for the `targetDate`'s month.
+ * Then, it maps these Mondays to the corresponding academic week number from the `academicWeeks` array.
+ * If an academic week is not found for a given Monday, `undefined` is used, in place in the returned array.
+ *
+ * @param {AcademicWeek[]} academicWeeks - An array of academic week objects, each with a `start` date and `number`.
+ * @param {Date} targetDate - The date used to generate the calendar display.
+ * @returns {(number | undefined)[]} An array of academic week numbers or `undefined` for each week in the calendar display.
+ * Returns an empty array if `academicWeeks` is empty or `targetDate` is invalid, with console warnings, in the interest of safe usage.
+ */
+const getAcademicWeekNumbers = (
+  academicWeeks: AcademicWeek[],
+  targetDate: Date
+) => {
+  if (!academicWeeks || academicWeeks.length === 0) {
+    console.warn('Datepicker: No academic weeks provided');
+    return [];
+  }
+  if (
+    !targetDate ||
+    !(targetDate instanceof Date) ||
+    Number.isNaN(targetDate.getTime())
+  ) {
+    console.warn('Datepicker: Invalid target date provided');
+    return [];
+  }
+
+  // Normalise to the first Monday of calendar period
+  const targetYear = targetDate.getFullYear();
+  const targetMonth = targetDate.getMonth();
+  const firstOfMonth = new Date(targetYear, targetMonth, 1);
+  const firstMonday = getMonday(firstOfMonth);
+
+  const calendarWeeks: Date[] = [];
+  calendarWeeks.push(firstMonday);
+
+  // Increment to the next Monday of the calendar period
+  const nextMonday = new Date(firstMonday);
+  nextMonday.setDate(firstMonday.getDate() + 7);
+
+  // Then keep incrementing until the end of the calendar period
+  while (nextMonday.getMonth() === targetMonth) {
+    calendarWeeks.push(new Date(nextMonday));
+    nextMonday.setDate(nextMonday.getDate() + 7);
+  }
+
+  // We need an array of actual week numbers to pass to the UI
+  const weekNumbers: (number | undefined)[] = calendarWeeks.map((date) => {
+    // `Array.find()` will return `undefined` if no match is found.
+    // `undefined` is used by `<AcademicWeek />` for row placement.
+    const matchedWeek = academicWeeks.find(
+      (week) => new Date(week.start).toDateString() === date.toDateString()
+    );
+    return matchedWeek?.number;
+  });
+
+  return weekNumbers;
+};
+
+export default getAcademicWeekNumbers;

package/lib/components/Datepicker/utils/index.ts

@@ -1,2 +1,3 @@
 export { default as getDatesForCalendarGrid } from './getDatesForCalendarGrid/getDatesForCalendarGrid';
 export { default as parseDate } from './parseDateForDateField/parseDateForDateField';
+export { default as getAcademicWeekNumbers } from './getAcademicWeekNumbers/getAcademicWeekNumbers';

package/lib/components/Header/Header.tsx

@@ -1,12 +1,13 @@
-import React, { memo, HTMLAttributes } from 'react';
+import { memo, HTMLAttributes } from 'react';
 import { css, cx } from '@emotion/css';
 import { useTheme } from '../..';
 import UclLogo from '../UclLogo/UclLogo';
 import HeaderMenu from './HeaderMenu';
 
 export const NAME = 'ucl-uikit-header';
-export const HEADER_TOP_HEIGHT = 72;
-export const Z_INDEX = 3;
+export const HEADER_DESKTOP_HEIGHT_PX = 72;
+export const HEADER_MOBILE_HEIGHT_PX = 48;
+export const DEFAULT_Z_INDEX = 3;
 
 export interface HeaderProps extends HTMLAttributes<HTMLElement> {
   title?: string;
@@ -24,17 +25,6 @@ const Header = ({
 }: HeaderProps) => {
   const [theme] = useTheme();
 
-  const menuChildren: React.ReactNode[] = [];
-  const nonMenuChildren: React.ReactNode[] = [];
-
-  React.Children.forEach(children, (child) => {
-    if (React.isValidElement(child) && child.type === HeaderMenu) {
-      menuChildren.push(child);
-    } else {
-      nonMenuChildren.push(child);
-    }
-  });
-
   const baseStyle = css`
     background-color: ${theme.color.neutral.white};
     font-family: ${theme.font.family.primary};
@@ -42,6 +32,17 @@ const Header = ({
     text-rendering: optimizeLegibility;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
+    position: relative;
+    background-color: ${theme.color.neutral.grey90};
+    color: ${theme.color.text.inverted};
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    height: ${HEADER_MOBILE_HEIGHT_PX}px;
+
+    @media (min-width: ${theme.breakpoints.desktop}px) {
+      height: ${HEADER_DESKTOP_HEIGHT_PX}px;
+    }
   `;
 
   const fixedStyle = css`
@@ -49,34 +50,34 @@ const Header = ({
     left: 0;
     top: 0;
     width: 100%;
-    z-index: ${Z_INDEX};
+    z-index: ${DEFAULT_Z_INDEX};
   `;
 
   const style = cx(NAME, baseStyle, fixed && fixedStyle, className);
 
-  const topStyle = css`
-    position: relative;
-    height: ${HEADER_TOP_HEIGHT}px;
-    background-color: ${theme.color.neutral.grey90};
-    color: ${theme.color.text.inverted};
-    display: flex;
-    justify-content: center;
-    align-items: center;
-  `;
-
   const uclLogoStyle = css`
     position: absolute;
-    left: 56px;
+    left: 16px;
     bottom: -0.5px;
-    height: 40px;
+    width: auto;
+    height: 21px;
+
+    @media (min-width: ${theme.breakpoints.desktop}px) {
+      left: 56px;
+      height: 40px;
+    }
   `;
 
   const titleStyle = css`
-    display: block;
+    display: none;
     margin: 0;
     font-size: ${theme.font.size.f18};
     font-weight: 700;
     text-align: center;
+
+    @media (min-width: ${theme.breakpoints.desktop}px) {
+      display: block;
+    }
   `;
 
   return (
@@ -85,12 +86,10 @@ const Header = ({
       data-testid={testId}
       {...props}
     >
-      <div className={topStyle}>
-        <UclLogo className={uclLogoStyle} />
-        {title && <h1 className={titleStyle}>{title}</h1>}
+      <UclLogo className={uclLogoStyle} />
+      {title && <h1 className={titleStyle}>{title}</h1>}
 
-        {children}
-      </div>
+      {children}
     </header>
   );
 };