uikit-react-public 0.44.0 → 0.44.3

package/lib/components/Calendar/Calendar.stories.tsx

@@ -9,6 +9,7 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     pickedDate: { control: { type: 'date' } },
+    pickedMonth: { control: { type: 'date' } },
     minDate: { control: { type: 'date' } },
     maxDate: { control: { type: 'date' } },
     showAcademicWeeks: { control: { type: 'boolean' } },
@@ -37,6 +38,9 @@ export const Default: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -57,28 +61,66 @@ export const WithEvents: Story = {
       const currentYear = currentDate.getFullYear();
       const currentMonth = currentDate.getMonth();
       return [
-        // Grey event dots
+        // Events outside the current month are always shown as disabled, regardless of status
         { date: dateToISOString(new Date(currentYear, currentMonth, -2)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, -1)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, -1)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 0)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 0)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 0)) },
-        // Blue event dots
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, -1)),
+          status: 'pending',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, -1)),
+          status: 'pending',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 0)),
+          status: 'approved',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 0)),
+          status: 'approved',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 0)),
+          status: 'approved',
+        },
+        // Events within the current month show variant colours: brand (default), warning (pending), success (approved)
         { date: dateToISOString(new Date(currentYear, currentMonth, 1)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 2)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 2)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 3)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 3)) },
-        { date: dateToISOString(new Date(currentYear, currentMonth, 3)) },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 2)),
+          status: 'pending',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 2)),
+          status: 'pending',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 3)),
+          status: 'approved',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 3)),
+          status: 'pending',
+        },
+        {
+          date: dateToISOString(new Date(currentYear, currentMonth, 3)),
+          status: 'rejected',
+        },
       ];
     })(),
+    statuses: {
+      pending: { variant: 'warning', ariaLabel: 'Pending' },
+      approved: { variant: 'success', ariaLabel: 'Approved' },
+      rejected: { variant: 'critical', ariaLabel: 'Rejected' },
+    },
   },
   render: () => {
     const [args, updateArgs] = useArgs();
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -158,6 +200,9 @@ export const WithAcademicWeeks: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -198,6 +243,9 @@ export const MinMaxDates: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar

package/lib/components/Calendar/Calendar.tsx

@@ -11,12 +11,14 @@ const DEFAULT_MAX_YEAR = 2100;
 
 const Calendar = ({
   pickedDate = null,
+  pickedMonth = null,
   onDatePick,
   minDate = null,
   maxDate = null,
   minYear = DEFAULT_MIN_YEAR,
   maxYear = DEFAULT_MAX_YEAR,
   events = [],
+  statuses = {},
   showAcademicWeeks = false,
   academicWeeks = [],
   testId = NAME,
@@ -37,6 +39,11 @@ const Calendar = ({
     pickedDate = null;
   }
 
+  if (pickedMonth && isNaN(pickedMonth.getTime())) {
+    console.warn('Calendar: pickedMonth is invalid, defaulting to null');
+    pickedMonth = null;
+  }
+
   const clampDisplayMonth = useCallback(
     (date: Date) => {
       const year = date.getFullYear();
@@ -54,36 +61,35 @@ const Calendar = ({
     [yearRangeEnd, yearRangeStart]
   );
 
+  // pickedDate takes precedence over pickedMonth
+  const activePickedDate = pickedDate ?? pickedMonth;
+
   // Used to track prop value changes
-  const pickedDateRef = useRef<Date | null>(pickedDate ?? null);
+  const activePickedDateRef = useRef<Date | null>(activePickedDate);
 
   // Determines the month currently displayed in the calendar
   const [displayMonth, setDisplayMonth] = useState<Date>(
-    // Display month initialises as either the picked date's month or the current month
-    clampDisplayMonth(pickedDate ?? new Date())
+    // Display month initialises as the picked date's month, else the picked month, else the current month
+    clampDisplayMonth(activePickedDate ?? new Date())
   );
 
-  // Snap displayed month to the picked date's month if it changes
+  // Snap displayed month to the active picked date/month if it changes
   useEffect(() => {
     if (
-      // If the picked date is valid
-      pickedDate &&
-      !isNaN(pickedDate.getTime()) &&
-      // If the picked date has changed
-      pickedDateRef.current?.getTime() !== pickedDate.getTime()
+      // If there's an active picked date/month
+      activePickedDate &&
+      // If it has changed
+      activePickedDateRef.current?.getTime() !== activePickedDate.getTime() &&
+      // If it's not in the currently displayed month
+      (activePickedDate.getMonth() !== displayMonth.getMonth() ||
+        activePickedDate.getFullYear() !== displayMonth.getFullYear())
     ) {
-      // If the picked date is not in the currently displayed month
-      if (
-        pickedDate.getMonth() !== displayMonth.getMonth() ||
-        pickedDate.getFullYear() !== displayMonth.getFullYear()
-      ) {
-        // Update the display month to the picked date's month
-        setDisplayMonth(clampDisplayMonth(pickedDate));
-      }
+      // Update the display month to match
+      setDisplayMonth(clampDisplayMonth(activePickedDate));
     }
-    // Update the ref to the new picked date
-    pickedDateRef.current = pickedDate;
-  }, [pickedDate, displayMonth, clampDisplayMonth]);
+    // Update the ref to the new active picked date/month
+    activePickedDateRef.current = activePickedDate;
+  }, [activePickedDate, displayMonth, clampDisplayMonth]);
 
   useEffect(() => {
     const clampedDisplayMonth = clampDisplayMonth(displayMonth);
@@ -161,6 +167,7 @@ const Calendar = ({
           minDate={minDateParsed}
           maxDate={maxDateParsed}
           events={events}
+          statuses={statuses}
         />
       </div>
     </div>

package/lib/components/Calendar/Calendar.types.ts

@@ -1,6 +1,20 @@
+// Used to determine the colour of the EventDot
+export type CalendarEventVariant =
+  'critical' | 'success' | 'caution' | 'warning' | 'info';
+
+// Maps a status key to the EventDot variant and Day aria-label it should apply
+export type CalendarStatusConfig = {
+  variant: CalendarEventVariant;
+  ariaLabel: string;
+};
+
+// Keyed by the status names referenced by `CalendarEvent.status`
+export type CalendarStatuses = Record<string, CalendarStatusConfig>;
+
 // Used to display EventDots inside `<Day>` component
 export type CalendarEvent = {
   date: string; // Date string in YYYY-MM-DD format
+  status?: string; // Key into the `statuses` prop on `<Calendar>`
 };
 
 export type AcademicWeek = {
@@ -9,13 +23,15 @@ export type AcademicWeek = {
 };
 
 export interface CalendarProps {
-  pickedDate?: Date | null;
+  pickedDate?: Date | null; // Date to select and display
+  pickedMonth?: Date | null; // Date whose month is displayed when pickedDate is not set
   onDatePick?: (date: Date | null, event?: React.SyntheticEvent) => void;
   minDate?: string | null; // ISO date string: YYYY-MM-DD format
   maxDate?: string | null; // ISO date string: YYYY-MM-DD format
   minYear?: number;
   maxYear?: number;
   events?: CalendarEvent[];
+  statuses?: CalendarStatuses;
   showAcademicWeeks?: boolean;
   academicWeeks?: AcademicWeek[];
   testId?: string;

package/lib/components/Calendar/__tests__/Calendar.test.tsx

@@ -1,10 +1,19 @@
 import { describe, test, expect, vi, beforeAll } from 'vitest';
-import { fireEvent, render, screen } from '@testing-library/react';
-import { ThemeContextProvider } from '../../../theme';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { ThemeContextProvider, theme } from '../../../theme';
 import Calendar from '../Calendar';
 
 const defaultTestId = 'ucl-uikit-calendar';
 
+const hexToRgb = (hex: string) => {
+  const value = hex.replace('#', '');
+  const red = parseInt(value.slice(0, 2), 16);
+  const green = parseInt(value.slice(2, 4), 16);
+  const blue = parseInt(value.slice(4, 6), 16);
+
+  return `rgb(${red}, ${green}, ${blue})`;
+};
+
 const customRender = (ui: React.ReactElement) => {
   return render(ui, {
     wrapper: ({ children }) => (
@@ -84,6 +93,45 @@ describe('Calendar', () => {
     );
   });
 
+  test('Displays the picked month without selecting an individual date', () => {
+    customRender(<Calendar pickedMonth={new Date('2025-07-01')} />);
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'July'
+    );
+    expect(screen.getByRole('combobox', { name: 'Year' })).toHaveTextContent(
+      '2025'
+    );
+  });
+
+  test('pickedDate takes precedence over pickedMonth for the displayed month', () => {
+    customRender(
+      <Calendar
+        pickedDate={new Date('2025-03-22')}
+        pickedMonth={new Date('2025-07-01')}
+      />
+    );
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'March'
+    );
+  });
+
+  test('Updates the displayed month when the pickedMonth prop changes', () => {
+    const { rerender } = customRender(
+      <Calendar pickedMonth={new Date('2025-07-01')} />
+    );
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'July'
+    );
+
+    rerender(<Calendar pickedMonth={new Date('2025-09-01')} />);
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'September'
+    );
+  });
+
   test('Can change the displayed year with the year select', () => {
     customRender(<Calendar pickedDate={new Date('2025-03-01')} />);
 
@@ -142,6 +190,32 @@ describe('Calendar', () => {
     ).not.toBeInTheDocument();
   });
 
+  test('Applies EventDot colours and Day aria-labels from the statuses prop', () => {
+    customRender(
+      <Calendar
+        pickedDate={new Date('2025-03-01')} // To ensure the calendar is displayed for March 2025
+        events={[
+          { date: '2025-03-15', status: 'pending' },
+          { date: '2025-03-15', status: 'pending' },
+        ]}
+        statuses={{
+          pending: { variant: 'warning', ariaLabel: 'Pending' },
+        }}
+      />
+    );
+
+    const day = screen
+      .getByText('15')
+      .closest('[data-testid="ucl-uikit-calendar__day"]') as HTMLElement;
+
+    expect(day).toHaveAttribute('aria-label', '15 March 2025, 2 Pending');
+
+    const dot = within(day).getAllByTestId('ucl-uikit-calendar__event-dot')[0];
+    expect(getComputedStyle(dot).backgroundColor).toBe(
+      hexToRgb(theme.colour.icon.warning)
+    );
+  });
+
   test('Year select uses minDate and maxDate years when provided', () => {
     customRender(
       <Calendar