uikit-react-public 0.11.16 → 0.11.24

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

@@ -0,0 +1,85 @@
+import type { AcademicWeek } from '../../';
+
+// 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 → Calendar}/utils/getDatesForCalendarGrid/getDatesForCalendarGrid.test.ts

@@ -1,78 +1,51 @@
 import { describe, expect, test } from 'vitest';
 import getDatesForCalendarGrid from './getDatesForCalendarGrid';
 
+// Note by Alex HF (2025-07-04): Some of these tests seem a bit excessive.
+// I pasted them in from my orginal <Datepicker> work.
+
 describe('getDatesForCalendarGrid', () => {
   test('Returns an array of Date objects', () => {
     const result = getDatesForCalendarGrid(new Date());
-    expect(
-      result.every((date) => date instanceof Date)
-    ).toBe(true);
+    expect(result.every((date) => date instanceof Date)).toBe(true);
   });
 
   test('Throws an error if no date is provided', () => {
     // @ts-expect-error - Expected behaviour is an error to be thrown
-    expect(() => getDatesForCalendarGrid()).toThrowError(
+    expect(() => getDatesForCalendarGrid()).toThrowError('No date provided');
+    // @ts-expect-error - Expected behaviour is an error to be thrown
+    expect(() => getDatesForCalendarGrid(null)).toThrowError(
       'No date provided'
     );
-    expect(() =>
-      // @ts-expect-error - Expected behaviour is an error to be thrown
-      getDatesForCalendarGrid(null)
-    ).toThrowError('No date provided');
-    expect(() =>
-      // @ts-expect-error - Expected behaviour is an error to be thrown
-      getDatesForCalendarGrid(undefined)
-    ).toThrowError('No date provided');
     // @ts-expect-error - Expected behaviour is an error to be thrown
-    expect(() => getDatesForCalendarGrid('')).toThrowError(
+    expect(() => getDatesForCalendarGrid(undefined)).toThrowError(
       'No date provided'
     );
     // @ts-expect-error - Expected behaviour is an error to be thrown
-    expect(() => getDatesForCalendarGrid(0)).toThrowError(
+    expect(() => getDatesForCalendarGrid('')).toThrowError('No date provided');
+    // @ts-expect-error - Expected behaviour is an error to be thrown
+    expect(() => getDatesForCalendarGrid(0)).toThrowError('No date provided');
+    // @ts-expect-error - Expected behaviour is an error to be thrown
+    expect(() => getDatesForCalendarGrid('1st of March')).toThrowError(
       'No date provided'
     );
-    expect(() =>
-      // @ts-expect-error - Expected behaviour is an error to be thrown
-      getDatesForCalendarGrid('1st of March')
-    ).toThrowError('No date provided');
   });
 
   test('Total dates returned are always divisible by 7', () => {
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 1, 1)).length %
-        7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 2, 5)).length %
-        7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 3, 15))
-        .length % 7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 4, 20))
-        .length % 7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 5, 25))
-        .length % 7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 6, 30))
-        .length % 7
-    ).toBe(0);
-    expect(
-      getDatesForCalendarGrid(new Date(2025, 12, 0))
-        .length % 7
-    ).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 1, 1)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 2, 5)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 3, 15)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 4, 20)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 5, 25)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 6, 30)).length % 7).toBe(0);
+    expect(getDatesForCalendarGrid(new Date(2025, 12, 0)).length % 7).toBe(0);
   });
 
-  test('If date is in Jan 2025, returns all dates in January 2024', () => {
+  test('If date is in Jan 2025, returns all dates in January 2025', () => {
     const date = new Date(2025, 0, 1);
     const result = getDatesForCalendarGrid(date);
     const janDates = [];
-    for (let i = 1; i <= 31; i++)
-      janDates.push(new Date(2025, 0, i));
+    for (let i = 1; i <= 31; i++) janDates.push(new Date(2025, 0, i));
     janDates.forEach((dateInJan) => {
       expect(result).toContainEqual(dateInJan);
     });
@@ -88,12 +61,8 @@ describe('getDatesForCalendarGrid', () => {
   test('If date is in Jan 2025, returns 1st & 2nd Feb 2025 at the end', () => {
     const date = new Date(2025, 0, 1);
     const result = getDatesForCalendarGrid(date);
-    expect(result[result.length - 2]).toEqual(
-      new Date(2025, 1, 1)
-    );
-    expect(result[result.length - 1]).toEqual(
-      new Date(2025, 1, 2)
-    );
+    expect(result[result.length - 2]).toEqual(new Date(2025, 1, 1));
+    expect(result[result.length - 1]).toEqual(new Date(2025, 1, 2));
   });
 
   test('If month starts on a Sunday, the total dates returned are divisible by 7', () => {
@@ -101,12 +70,12 @@ describe('getDatesForCalendarGrid', () => {
     const result = getDatesForCalendarGrid(date);
     expect(result.length % 7).toBe(0);
   });
+
   test('handles February in leap year correctly', () => {
     const leapYear = new Date(2024, 1, 1); // February 2024
     const result = getDatesForCalendarGrid(leapYear);
     const febDates = [];
-    for (let i = 1; i <= 29; i++)
-      febDates.push(new Date(2024, 1, i));
+    for (let i = 1; i <= 29; i++) febDates.push(new Date(2024, 1, i));
     febDates.forEach((date) => {
       expect(result).toContainEqual(date);
     });
@@ -116,8 +85,7 @@ describe('getDatesForCalendarGrid', () => {
     const nonLeapYear = new Date(2025, 1, 1); // February 2025
     const result = getDatesForCalendarGrid(nonLeapYear);
     const febDates = [];
-    for (let i = 1; i <= 28; i++)
-      febDates.push(new Date(2025, 1, i));
+    for (let i = 1; i <= 28; i++) febDates.push(new Date(2025, 1, i));
     febDates.forEach((date) => {
       expect(result).toContainEqual(date);
     });
@@ -127,18 +95,14 @@ describe('getDatesForCalendarGrid', () => {
     const date = new Date(2025, 3, 1); // April 2025
     const result = getDatesForCalendarGrid(date);
     for (let i = 1; i < result.length; i++) {
-      expect(result[i].getTime()).toBeGreaterThan(
-        result[i - 1].getTime()
-      );
+      expect(result[i].getTime()).toBeGreaterThan(result[i - 1].getTime());
     }
   });
 
   test('correctly handles months with 31 days', () => {
     const date = new Date(2025, 0, 1); // January 2025
     const result = getDatesForCalendarGrid(date);
-    expect(
-      result.filter((d) => d.getMonth() === 0).length
-    ).toBe(31);
+    expect(result.filter((d) => d.getMonth() === 0).length).toBe(31);
   });
 
   test('week always starts with Monday', () => {

package/lib/components/{Datepicker → Calendar}/utils/getDatesForCalendarGrid/getDatesForCalendarGrid.ts

@@ -17,24 +17,15 @@
  * ```
  */
 const getDatesForCalendarGrid = (date: Date): Date[] => {
-  if (!date || !(date instanceof Date))
-    throw new Error('No date provided');
+  if (!date || !(date instanceof Date)) throw new Error('No date provided');
 
   const month = date.getMonth();
-  const daysInMonth = new Date(
-    date.getFullYear(),
-    month + 1,
-    0
-  ).getDate();
+  const daysInMonth = new Date(date.getFullYear(), month + 1, 0).getDate();
 
   // Get all days in current month
   const dates: Date[] = [];
   for (let day = 1; day <= daysInMonth; day++) {
-    const newDate = new Date(
-      date.getFullYear(),
-      month,
-      day
-    );
+    const newDate = new Date(date.getFullYear(), month, day);
     if (newDate.getMonth() !== month) break;
     dates.push(newDate);
   }
@@ -43,28 +34,14 @@ const getDatesForCalendarGrid = (date: Date): Date[] => {
   // Sunday (0) should become 6
   // Monday (1) should become 0
   // Tuesday (2) should become 1, etc.
-  const adjustDay = (day: number): number =>
-    day === 0 ? 6 : day - 1;
+  const adjustDay = (day: number): number => (day === 0 ? 6 : day - 1);
 
   // Calculate previous month's "grey days"
   const prevMonthGreyDays = [];
-  const prevMonth = new Date(
-    date.getFullYear(),
-    month - 1,
-    1
-  );
-  const firstDayOfMonth = new Date(
-    date.getFullYear(),
-    month,
-    1
-  ).getDay();
-  const numberOfDaysFromPrevMonth =
-    adjustDay(firstDayOfMonth);
-  const totalDaysInPrevMonth = new Date(
-    date.getFullYear(),
-    month,
-    0
-  ).getDate();
+  const prevMonth = new Date(date.getFullYear(), month - 1, 1);
+  const firstDayOfMonth = new Date(date.getFullYear(), month, 1).getDay();
+  const numberOfDaysFromPrevMonth = adjustDay(firstDayOfMonth);
+  const totalDaysInPrevMonth = new Date(date.getFullYear(), month, 0).getDate();
 
   for (let i = numberOfDaysFromPrevMonth; i > 0; i--) {
     prevMonthGreyDays.push(
@@ -78,26 +55,17 @@ const getDatesForCalendarGrid = (date: Date): Date[] => {
 
   // Calculate next month's "grey days"
   const nextMonthGreyDays = [];
-  const nextMonth = new Date(
-    date.getFullYear(),
-    month + 1,
-    1
-  );
+  const nextMonth = new Date(date.getFullYear(), month + 1, 1);
   const lastDayOfMonth = new Date(
     date.getFullYear(),
     month,
     daysInMonth
   ).getDay();
-  const numberOfDaysFromNextMonth =
-    6 - adjustDay(lastDayOfMonth);
+  const numberOfDaysFromNextMonth = 6 - adjustDay(lastDayOfMonth);
 
   for (let i = 1; i <= numberOfDaysFromNextMonth; i++) {
     nextMonthGreyDays.push(
-      new Date(
-        nextMonth.getFullYear(),
-        nextMonth.getMonth(),
-        i
-      )
+      new Date(nextMonth.getFullYear(), nextMonth.getMonth(), i)
     );
   }
 

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

@@ -0,0 +1,4 @@
+export { default as normaliseMonth } from './normaliseMonth/normaliseMonth';
+export { default as parseDateFromString } from './parseDateFromString/parseDateFromString';
+export { default as getAcademicWeekNumbers } from './getAcademicWeekNumbers/getAcademicWeekNumbers';
+export { default as getDatesForCalendarGrid } from './getDatesForCalendarGrid/getDatesForCalendarGrid';

package/lib/components/Calendar/utils/normaliseMonth/normaliseMonth.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'vitest';
+import normaliseMonth from './normaliseMonth';
+
+describe('Calendar: normaliseMonth', () => {
+  test('Should return null if given undefined', () => {
+    expect(normaliseMonth(undefined)).toBeNull();
+  });
+
+  test('Should return null if given null', () => {
+    expect(normaliseMonth(null)).toBeNull();
+  });
+
+  test('Returns a Date object set to the first of the month', () => {
+    const date = new Date('2025-03-10');
+    const normalisedDate = normaliseMonth(date);
+    expect(normalisedDate).toBeInstanceOf(Date);
+    expect(normalisedDate?.getFullYear()).toBe(2025);
+    expect(normalisedDate?.getMonth()).toBe(2); // March (0-indexed)
+    expect(normalisedDate?.getDate()).toBe(1);
+  });
+
+  test('Works for a date within daylight saving time', () => {
+    const date = new Date('2025-06-15');
+    const normalisedDate = normaliseMonth(date);
+    expect(normalisedDate).toBeInstanceOf(Date);
+    expect(normalisedDate?.getFullYear()).toBe(2025);
+    expect(normalisedDate?.getMonth()).toBe(5); // June (0-indexed)
+    expect(normalisedDate?.getDate()).toBe(1);
+  });
+
+  test('Returned date is normalised for midnight', () => {
+    const date = new Date('2025-01-01T12:34:56');
+    const normalisedDate = normaliseMonth(date);
+    expect(normalisedDate).toBeInstanceOf(Date);
+    expect(normalisedDate?.getFullYear()).toBe(2025);
+    expect(normalisedDate?.getMonth()).toBe(0); // January (0-indexed)
+    expect(normalisedDate?.getDate()).toBe(1);
+    expect(normalisedDate?.getHours()).toBe(0);
+  });
+});

package/lib/components/Calendar/utils/normaliseMonth/normaliseMonth.ts

@@ -0,0 +1,16 @@
+/**
+ * Normalises a given date to the first day of its month (with the time set to midnight).
+ * If the input date is undefined, it returns null.
+ * Used in <Calendar> to track the displayed month.
+ * @param date The date to normalise.
+ * @returns A new Date object set to the first day of the month with the time at midnight, or null if the input was null or undefined.
+ */
+const normaliseMonth = (date: Date | null | undefined) => {
+  if (!date) return null;
+  const newDate = new Date(date);
+  newDate.setDate(1);
+  newDate.setHours(0, 0, 0, 0);
+  return newDate;
+};
+
+export default normaliseMonth;

package/lib/components/Calendar/utils/parseDateFromString/parseDateFromString.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vitest';
+import parseDateFromString from './parseDateFromString';
+
+describe('Calendar: parseDateFromString', () => {
+  test('Should return null for an invalid date string', () => {
+    expect(parseDateFromString('invalid-date')).toBeNull();
+    expect(parseDateFromString('')).toBeNull();
+    expect(parseDateFromString('      ')).toBeNull();
+  });
+
+  test('Should return a valid date for a valid date string', () => {
+    expect(parseDateFromString('2023-03-15')).toEqual(new Date('2023-03-15'));
+    expect(parseDateFromString('2025-06-30')).toEqual(new Date('2025-06-30'));
+  });
+});

package/lib/components/Calendar/utils/parseDateFromString/parseDateFromString.ts

@@ -0,0 +1,19 @@
+/**
+ * Parses a date string into a Date object.
+ * Returns null if the input is invalid.
+ *
+ * @param dateString - The date string to parse (can be in ISO format or UNIX timestamp).
+ * @returns A Date object, or null if invalid.
+ */
+const parseDateFromString = (dateString: string): Date | null => {
+  const date = new Date(dateString);
+  if (isNaN(date.getTime())) {
+    console.warn(
+      `Calendar: Invalid date string provided: "${dateString}". Expected format is ISO 8601 (YYYY-MM-DD)`
+    );
+    return null;
+  }
+  return date;
+};
+
+export default parseDateFromString;