uikit-react-public 0.11.16 → 0.11.24

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

@@ -0,0 +1,209 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Calendar from './Calendar';
+import { useArgs } from '@storybook/preview-api';
+import type { AcademicWeek } from './Calendar.types';
+
+const meta = {
+  title: 'Components/Work in progress/Calendar',
+  component: Calendar,
+  parameters: { layout: 'padded' },
+  argTypes: {
+    pickedDate: { control: { type: 'date' } },
+    minDate: { control: { type: 'date' } },
+    maxDate: { control: { type: 'date' } },
+    showAcademicWeeks: { control: { type: 'boolean' } },
+    testId: { control: { type: 'text' } },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Calendar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Convert UNIX timestamp from Storybook controls to `Date` object
+// https://storybook.js.org/docs/essentials/controls#annotation
+const parseDateFromUNIXTimestamp = (timestamp: number) => {
+  const date = new Date(timestamp);
+  return isNaN(date.getTime()) ? null : date;
+};
+
+const dateToISOString = (date: Date) => {
+  return date.toISOString().split('T')[0];
+};
+
+export const Default: Story = {
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    args.pickedDate = args.pickedDate
+      ? parseDateFromUNIXTimestamp(args.pickedDate)
+      : null;
+    const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
+    return (
+      <Calendar
+        {...args}
+        onDatePick={onDatePick}
+      />
+    );
+  },
+};
+
+// Story repeated in Datepicker.stories.tsx
+export const WithEvents: Story = {
+  name: 'With events',
+  args: {
+    // IIFE gives us event dots for the current month
+    events: (() => {
+      const currentDate = new Date();
+      const currentYear = currentDate.getFullYear();
+      const currentMonth = currentDate.getMonth();
+      return [
+        // Grey event dots
+        { 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)) },
+        { 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)) },
+      ];
+    })(),
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    args.pickedDate = args.pickedDate
+      ? parseDateFromUNIXTimestamp(args.pickedDate)
+      : null;
+    const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
+    return (
+      <Calendar
+        {...args}
+        onDatePick={onDatePick}
+      />
+    );
+  },
+};
+
+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 },
+  { start: '2025-12-01', number: 15 },
+  { start: '2025-12-08', number: 16 },
+  { start: '2025-12-15', number: 17 },
+  { start: '2025-12-22', number: 18 },
+  { start: '2025-12-29', number: 19 },
+  { start: '2026-01-05', number: 20 },
+  { start: '2026-01-12', number: 21 },
+  { start: '2026-01-19', number: 22 },
+  { start: '2026-01-26', number: 23 },
+  { start: '2026-02-02', number: 24 },
+  { start: '2026-02-09', number: 25 },
+  { start: '2026-02-16', number: 26 },
+  { start: '2026-02-23', number: 27 },
+  { start: '2026-03-02', number: 28 },
+  { start: '2026-03-09', number: 29 },
+  { start: '2026-03-16', number: 30 },
+  { start: '2026-03-23', number: 31 },
+  { start: '2026-03-30', number: 32 },
+  { start: '2026-04-06', number: 33 },
+  { start: '2026-04-13', number: 34 },
+  { start: '2026-04-20', number: 35 },
+  { start: '2026-04-27', number: 36 },
+  { start: '2026-05-04', number: 37 },
+  { start: '2026-05-11', number: 38 },
+  { start: '2026-05-18', number: 39 },
+  { start: '2026-05-25', number: 40 },
+  { start: '2026-06-01', number: 41 },
+  { start: '2026-06-08', number: 42 },
+  { start: '2026-06-15', number: 43 },
+  { start: '2026-06-22', number: 44 },
+  { start: '2026-06-29', number: 45 },
+  { start: '2026-07-06', number: 46 },
+  { start: '2026-07-13', number: 47 },
+  { start: '2026-07-20', number: 48 },
+  { start: '2026-07-27', number: 49 },
+  { start: '2026-08-03', number: 50 },
+  { start: '2026-08-10', number: 51 },
+  { start: '2026-08-17', number: 52 },
+  { start: '2026-08-24', number: 53 },
+];
+
+// Story repeated in Datepicker.stories.tsx
+export const WithAcademicWeeks: Story = {
+  name: 'With academic weeks',
+  args: {
+    showAcademicWeeks: true,
+    academicWeeks: academicWeeks,
+    pickedDate: new Date(academicWeeks[0].start), // So the week numbers appear on story mount
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    args.pickedDate = args.pickedDate
+      ? parseDateFromUNIXTimestamp(args.pickedDate)
+      : null;
+    const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
+    return (
+      <Calendar
+        {...args}
+        onDatePick={onDatePick}
+      />
+    );
+  },
+};
+
+// Story repeated in Datepicker.stories.tsx
+export const MinMaxDates: Story = {
+  name: 'With min and max dates',
+  args: {
+    // Initialise min date as 5 days into the current month
+    minDate: (() => {
+      const now = new Date();
+      return new Date(now.getFullYear(), now.getMonth(), 5)
+        .toISOString()
+        .split('T')[0];
+    })(),
+    // Initialise max date as 5 days before the last day of the current month
+    maxDate: (() => {
+      const now = new Date();
+      // Get last day of current month
+      const lastDay = new Date(
+        now.getFullYear(),
+        now.getMonth() + 1,
+        0
+      ).getDate();
+      return new Date(now.getFullYear(), now.getMonth(), lastDay - 5)
+        .toISOString()
+        .split('T')[0];
+    })(),
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    args.pickedDate = args.pickedDate
+      ? parseDateFromUNIXTimestamp(args.pickedDate)
+      : null;
+    const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
+    return (
+      <Calendar
+        {...args}
+        onDatePick={onDatePick}
+      />
+    );
+  },
+};

package/lib/components/Calendar/Calendar.tsx

@@ -0,0 +1,121 @@
+import { useState, useEffect, useRef } from 'react';
+import { css, cx } from '@emotion/css';
+import { Controls, AcademicWeeks, Grid } from './subcomponents';
+import { normaliseMonth, parseDateFromString } from './utils';
+import { useTheme } from '../../theme';
+import type { CalendarProps } from './Calendar.types';
+
+const NAME = 'ucl-uikit-calendar';
+
+const Calendar = ({
+  pickedDate = null,
+  onDatePick,
+  minDate = null,
+  maxDate = null,
+  events = [],
+  showAcademicWeeks = false,
+  academicWeeks = [],
+  testId = NAME,
+  className,
+}: CalendarProps) => {
+  const [theme] = useTheme();
+
+  if (pickedDate && isNaN(pickedDate.getTime())) {
+    console.warn('Calendar: pickedDate is invalid, defaulting to null');
+    pickedDate = null;
+  }
+
+  // Used to track prop value changes
+  const pickedDateRef = useRef<Date | null>(pickedDate ?? null);
+
+  // 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
+    normaliseMonth(pickedDate ?? new Date()) as Date
+  );
+
+  // Parse min and max dates from strings to Date objects
+  const minDateParsed = minDate ? parseDateFromString(minDate) : null;
+  const maxDateParsed = maxDate ? parseDateFromString(maxDate) : null;
+
+  // Snap displayed month to the picked date's 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 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(normaliseMonth(pickedDate) as Date);
+      }
+    }
+    // Update the ref to the new picked date
+    pickedDateRef.current = pickedDate;
+  }, [pickedDate, displayMonth]);
+
+  const handleMonthChange = (change: number) => {
+    const newDate = new Date(displayMonth);
+    newDate.setMonth(newDate.getMonth() + change);
+    setDisplayMonth(normaliseMonth(newDate) as Date);
+  };
+
+  const width = showAcademicWeeks ? '370' : '312';
+
+  const baseStyle = css`
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 16px;
+    width: ${width}px;
+    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 style = cx(testId, baseStyle, className);
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+    >
+      <Controls
+        month={displayMonth}
+        changeMonth={handleMonthChange}
+      />
+      <div className={innerContainerStyle}>
+        {showAcademicWeeks && (
+          <AcademicWeeks
+            date={displayMonth}
+            weeks={academicWeeks}
+          />
+        )}
+        <Grid
+          month={displayMonth}
+          pickedDate={pickedDate}
+          onDatePick={onDatePick}
+          minDate={minDateParsed}
+          maxDate={maxDateParsed}
+          events={events}
+        />
+      </div>
+    </div>
+  );
+};
+
+export default Calendar;

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

@@ -0,0 +1,21 @@
+// Used to display EventDots inside `<Day>` component
+export type CalendarEvent = {
+  date: string; // Date string in YYYY-MM-DD format
+};
+
+export type AcademicWeek = {
+  start: string; // ISO date string: YYYY-MM-DD format
+  number: number;
+};
+
+export interface CalendarProps {
+  pickedDate?: Date | null;
+  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
+  events?: CalendarEvent[];
+  showAcademicWeeks?: boolean;
+  academicWeeks?: AcademicWeek[];
+  testId?: string;
+  className?: string;
+}

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

@@ -0,0 +1,71 @@
+import { describe, test, expect, vi, beforeAll } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { ThemeContextProvider } from '../../../theme';
+import Calendar from '../Calendar';
+
+const defaultTestId = 'ucl-uikit-calendar';
+
+const customRender = (ui: React.ReactElement) => {
+  return render(ui, {
+    wrapper: ({ children }) => (
+      <ThemeContextProvider>{children}</ThemeContextProvider>
+    ),
+  });
+};
+
+describe('Calendar', () => {
+  beforeAll(() => {
+    // Snapshot tests will fail because the Calendar Grid includes styling for "today's date".
+    // Therefore, we need to use Vitest to mock the current date.
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2025-03-10')); // Arbitrary fixed date -- Alex's birthday :)
+  });
+
+  // Snapshot tests
+
+  test('Snapshot: no date provided', () => {
+    const renderResult = customRender(<Calendar />);
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('Snapshot: with date provided', () => {
+    const renderResult = customRender(
+      <Calendar pickedDate={new Date('2025-01-06')} />
+    );
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  // Unit tests
+
+  test('Can be found via default test id', () => {
+    customRender(<Calendar />);
+    const calendar = screen.getByTestId(defaultTestId);
+    expect(calendar).toBeInTheDocument();
+  });
+
+  test('Can be found custom test id', () => {
+    const customTestId = '123';
+    customRender(<Calendar testId={customTestId} />);
+    const calendar = screen.getByTestId(customTestId);
+    expect(calendar).toBeInTheDocument();
+  });
+
+  test('Can pick a date', () => {
+    const dateToPick = new Date('2025-03-22');
+    const onDatePick = vi.fn();
+    customRender(
+      <Calendar
+        pickedDate={new Date('2025-03-01')} // To ensure the calendar is displayed for March 2025
+        onDatePick={onDatePick}
+      />
+    );
+    const dayButton = screen.getByText('22');
+
+    fireEvent.click(dayButton);
+    // OnDatePick = (date: Date | null, event: React.SyntheticEvent) => void
+    const [firstArg, secondArg] = onDatePick.mock.calls[0];
+    expect(firstArg).toEqual(dateToPick);
+    expect(secondArg).toHaveProperty('type', 'click');
+    expect(secondArg).toHaveProperty('target');
+  });
+});