uikit-react-public 0.11.24 → 0.17.4

package/lib/components/Timepicker/utils/convertDateToTimeString.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import convertDatetoTimeString from './convertDateToTimeString';
+
+describe('convertDatetoTimeString', () => {
+  it('should return a formatted time string for a valid Date object', () => {
+    const date = new Date();
+    date.setHours(9);
+    date.setMinutes(5);
+
+    const result = convertDatetoTimeString(date);
+    expect(result).toBe('09:05');
+  });
+
+  it('should handle single-digit hours and minutes correctly', () => {
+    const date = new Date();
+    date.setHours(3);
+    date.setMinutes(7);
+
+    const result = convertDatetoTimeString(date);
+    expect(result).toBe('03:07');
+  });
+
+  it('should handle double-digit hours and minutes correctly', () => {
+    const date = new Date();
+    date.setHours(12);
+    date.setMinutes(30);
+
+    const result = convertDatetoTimeString(date);
+    expect(result).toBe('12:30');
+  });
+
+  it('should return an empty string for null input', () => {
+    const result = convertDatetoTimeString(null);
+    expect(result).toBe('');
+  });
+
+  it('should handle midnight (00:00) correctly', () => {
+    const date = new Date();
+    date.setHours(0);
+    date.setMinutes(0);
+
+    const result = convertDatetoTimeString(date);
+    expect(result).toBe('00:00');
+  });
+
+  it('should handle the last minute of the day (23:59) correctly', () => {
+    const date = new Date();
+    date.setHours(23);
+    date.setMinutes(59);
+
+    const result = convertDatetoTimeString(date);
+    expect(result).toBe('23:59');
+  });
+});

package/lib/components/Timepicker/utils/convertDateToTimeString.ts

@@ -0,0 +1,10 @@
+const convertDatetoTimeString = (time: Date | null): string => {
+  if (!time) {
+    return '';
+  }
+  const hours = time.getHours().toString().padStart(2, '0');
+  const minutes = time.getMinutes().toString().padStart(2, '0');
+  return `${hours}:${minutes}`;
+};
+
+export default convertDatetoTimeString;

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

@@ -0,0 +1 @@
+export { default as convertDatetoTimeString } from './convertDateToTimeString';

package/lib/components/Toggle/Toggle.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Toggle from './Toggle';
 
 const meta = {
-  title: 'Components/Ready to use/Toggle',
+  title: 'Components/Toggle',
   component: Toggle,
   parameters: {
     layout: 'centered',

package/lib/components/Tooltip/Tooltip.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Tooltip from './Tooltip';
 
 const meta = {
-  title: 'Components/Ready to use/Tooltip',
+  title: 'Components/Tooltip',
   component: Tooltip,
   args: {
     children: 'Default tooltip text',

package/lib/components/WeekPicker/WeekPicker.stories.tsx

@@ -0,0 +1,147 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useArgs } from '@storybook/preview-api';
+import WeekPicker from './WeekPicker';
+
+const meta = {
+  title: 'Components/Work in progress/WeekPicker',
+  component: WeekPicker,
+  parameters: { layout: 'padded' },
+  argTypes: {
+    value: { control: { type: 'date' } },
+    minDate: { control: { type: 'date' } },
+    maxDate: { control: { type: 'date' } },
+    disabled: { control: { type: 'boolean' } },
+    showAcademicWeeks: { control: { type: 'boolean' } },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof WeekPicker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [args, updateArgs] = useArgs();
+
+    // Storybook controls provide UNIX timestamps for dates, need to convert
+    // https://storybook.js.org/docs/essentials/controls#annotation
+    args.value = args.value ? new Date(args.value) : null;
+    args.minDate = args.minDate
+      ? new Date(args.minDate).toLocaleDateString('sv-SE')
+      : null;
+    args.maxDate = args.maxDate
+      ? new Date(args.maxDate).toLocaleDateString('sv-SE')
+      : null;
+
+    const onValueChange = (value: Date | null) =>
+      updateArgs({ value: value });
+    return (
+      <WeekPicker
+        {...args}
+        onValueChange={onValueChange}
+      />
+    );
+  },
+};
+
+const academicWeeks = [
+  { 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 },
+];
+
+export const WithAcademicWeeks: Story = {
+  name: 'With academic weeks',
+  args: {
+    showAcademicWeeks: true,
+    academicWeeks: academicWeeks,
+    value: new Date(academicWeeks[0].start), // So the week numbers appear on story mount
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+
+    // Storybook controls provide UNIX timestamps for dates, need to convert
+    // https://storybook.js.org/docs/essentials/controls#annotation
+    args.value = args.value ? new Date(args.value) : null;
+    args.minDate = args.minDate
+      ? new Date(args.minDate).toLocaleDateString('sv-SE')
+      : null;
+    args.maxDate = args.maxDate
+      ? new Date(args.maxDate).toLocaleDateString('sv-SE')
+      : null;
+
+    const onValueChange = (value: Date | null) =>
+      updateArgs({ value: value });
+    return (
+      <WeekPicker
+        {...args}
+        onValueChange={onValueChange}
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  name: 'Disabled',
+  args: {
+    disabled: true,
+    value: new Date(),
+  },
+  render: () => {
+    const [args] = useArgs();
+
+    args.value = args.value ? new Date(args.value) : null;
+
+    return <WeekPicker {...args} />;
+  },
+};

package/lib/components/WeekPicker/WeekPicker.tsx

@@ -0,0 +1,26 @@
+import { CustomDatepicker } from './subcomponents';
+import type { WeekPickerProps } from './WeekPicker.types';
+
+const WeekPicker = ({
+  value,
+  onValueChange,
+  minDate,
+  maxDate,
+  disabled,
+  className,
+  ...props
+}: WeekPickerProps) => {
+  return (
+    <CustomDatepicker
+      value={value}
+      onValueChange={onValueChange}
+      minDate={minDate}
+      maxDate={maxDate}
+      className={className}
+      disabled={disabled}
+      {...props}
+    />
+  );
+};
+
+export default WeekPicker;

package/lib/components/WeekPicker/WeekPicker.types.ts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, RefObject } from 'react';
+import type { CalendarEvent, AcademicWeek } from '../Calendar';
+
+export type DatepickerValue = Date | null;
+
+export interface WeekPickerProps extends HTMLAttributes<HTMLDivElement> {
+  value?: DatepickerValue;
+  onValueChange?: (
+    value: DatepickerValue,
+    event?: React.SyntheticEvent
+  ) => void;
+  minDate?: string | null;
+  maxDate?: string | null;
+  disabled?: boolean;
+  events?: CalendarEvent[];
+  showAcademicWeeks?: boolean;
+  academicWeeks?: AcademicWeek[];
+  testId?: string;
+  ref?: RefObject<HTMLDivElement>;
+  inputRef?: RefObject<HTMLInputElement>;
+}

package/lib/components/WeekPicker/index.ts

@@ -0,0 +1,2 @@
+export { default } from './WeekPicker';
+export type { WeekPickerProps, DatepickerValue } from './WeekPicker.types';

package/lib/components/WeekPicker/subcomponents/CustomDatepicker.tsx

@@ -0,0 +1,298 @@
+import { useRef, useEffect, useState, useCallback } from 'react';
+import { css, cx } from '@emotion/css';
+import { VisibleField } from './';
+import { Panel } from '../../Datepicker/subcomponents';
+import { Calendar, Icon, IconButton } from '../..';
+import { parseInputValue } from '../../Datepicker/utils';
+import type { DatepickerValue } from '../WeekPicker.types';
+import type { CalendarEvent, AcademicWeek } from '../../Calendar';
+
+interface CustomDatepickerProps extends React.HTMLAttributes<HTMLDivElement> {
+  value?: DatepickerValue;
+  onValueChange?: (
+    value: DatepickerValue,
+    event?: React.SyntheticEvent
+  ) => void;
+  minDate?: string | null; // ISO date string: YYYY-MM-DD
+  maxDate?: string | null; // ISO date string: YYYY-MM-DD
+  disabled?: boolean;
+  events?: CalendarEvent[];
+  showAcademicWeeks?: boolean;
+  academicWeeks?: AcademicWeek[];
+  testId?: string;
+  ref?: React.RefObject<HTMLDivElement>;
+  inputRef?: React.RefObject<HTMLInputElement>;
+}
+
+const NAME = 'ucl-uikit-weekpicker';
+
+const CustomDatepicker = ({
+  value = null,
+  onValueChange = () => {},
+  minDate,
+  maxDate,
+  disabled = false,
+  events,
+  showAcademicWeeks,
+  academicWeeks = [],
+  testId = NAME,
+  className,
+  ref,
+  inputRef,
+  ...props
+}: CustomDatepickerProps) => {
+  if (value && isNaN(value.getTime())) {
+    console.warn('CustomDatepicker: value is invalid, defaulting to null');
+    value = null;
+  }
+
+  function parseDateFromInput(input: string): Date | null {
+    if (!input) return null;
+    const parts = input.split('/');
+    if (parts.length !== 3) return null;
+
+    const day = parseInt(parts[0]);
+    const month = parseInt(parts[1]) - 1;
+    const year = parseInt(parts[2]);
+
+    const date = new Date(year, month, day);
+    return isNaN(date.getTime()) ? null : date;
+  }
+
+  function getWeekRange(date: Date, startOnMonday = true) {
+    const input = new Date(date);
+    input.setHours(0, 0, 0, 0);
+
+    const day = input.getDay();
+
+    const diffToMonday = startOnMonday ? (day === 0 ? -6 : 1 - day) : -day;
+
+    const start = new Date(input);
+    start.setDate(input.getDate() + diffToMonday);
+
+    const end = new Date(start);
+    end.setDate(start.getDate() + 6);
+
+    return { start, end };
+  }
+
+  const internalRef = useRef<HTMLDivElement>(null);
+  const effectiveRef = ref || internalRef;
+  const internalInputRef = useRef<HTMLInputElement>(null);
+  const effectiveInputRef = inputRef || internalInputRef;
+
+  const [panelOpen, setPanelOpen] = useState(false);
+
+  // Derived props (tidier than using `date?.getDate()`, etc, everywhere.)
+  const day = value?.getDate().toString().padStart(2, '0') ?? '';
+  const month = value ? (value.getMonth() + 1).toString().padStart(2, '0') : '';
+  const year = value?.getFullYear().toString() ?? '';
+  const formattedDateString = value ? `${day}/${month}/${year}` : '';
+
+  const [inputValue, setInputValue] = useState(formattedDateString);
+
+  const resetField = useCallback(() => {
+    setInputValue(formattedDateString);
+  }, [setInputValue, formattedDateString]);
+
+  useEffect(() => {
+    // Reset the input field when the value changes.
+    resetField();
+  }, [value, resetField]);
+
+  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setInputValue(event.target.value);
+  };
+
+  const handleParseInput = (event: React.SyntheticEvent) => {
+    // `parseInputValue` checks the date is valid and within min/max range.
+    const parseDate = parseInputValue(inputValue, minDate, maxDate);
+    if (parseDate) {
+      onValueChange(parseDate, event);
+    } else {
+      resetField();
+    }
+  };
+
+  const handleInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') {
+      handleParseInput(event);
+    } else if (event.key === 'Escape') {
+      resetField();
+      effectiveInputRef.current?.blur();
+      setPanelOpen(false);
+    } else if (event.key === 'Tab') {
+      resetField();
+      setPanelOpen(false);
+    }
+  };
+
+  // If `value` is out of range, automatically set it to null.
+  // This is validation to prevent parent components passing invalid dates.
+  useEffect(() => {
+    const isDateOutOfRange = (date: Date | null): boolean => {
+      if (!date) return false;
+
+      const normaliseDate = (date: Date) => {
+        date.setHours(0, 0, 0, 0); // Normalize to UTC midnight to avoid time zone issues
+        return date;
+      };
+
+      const parsedMinDate = minDate ? normaliseDate(new Date(minDate)) : null;
+      const parsedMaxDate = maxDate ? normaliseDate(new Date(maxDate)) : null;
+      const normalisedDate = normaliseDate(date);
+
+      if (parsedMinDate && normalisedDate < parsedMinDate) return true;
+      if (parsedMaxDate && normalisedDate > parsedMaxDate) return true;
+      return false;
+    };
+
+    if (value && isDateOutOfRange(value)) {
+      console.warn('CustomDatepicker: value is out of range, setting to null');
+      onValueChange(null);
+    }
+  }, [value, minDate, maxDate, onValueChange]);
+
+  // Close the panel & reset the input field if we click away.
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        effectiveRef.current &&
+        !effectiveRef.current.contains(event.target as Node)
+      ) {
+        setPanelOpen(false);
+        resetField();
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [effectiveRef, setPanelOpen, resetField]);
+
+  useEffect(() => {
+    // Close the panel if the <Datepicker> becomes disabled
+    if (disabled && panelOpen) setPanelOpen(false);
+  }, [disabled, panelOpen]);
+
+  const handlePickCalendarDate = (
+    date: Date | null,
+    event?: React.SyntheticEvent
+  ) => {
+    if (onValueChange) {
+      onValueChange(date, event);
+    }
+    setPanelOpen(false);
+  };
+
+  const handleShowPanel = () => {
+    if (disabled) return;
+    setPanelOpen(true);
+  };
+
+  const handleTogglePanel = () => {
+    if (disabled) return;
+    setPanelOpen((prev) => !prev);
+  };
+
+  const baseStyle = css`
+    box-sizing: border-box;
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+  `;
+
+  const style = cx(NAME, className, baseStyle);
+
+  const parsedDate = parseDateFromInput(inputValue);
+  const weekRange = parsedDate ? getWeekRange(parsedDate) : null;
+
+  let academicWeekNumber: number | null = null;
+  if (parsedDate) {
+    for (let i = 0; i < academicWeeks.length; i++) {
+      const weekStart = new Date(academicWeeks[i].start);
+      const nextWeekStart =
+        i + 1 < academicWeeks.length
+          ? new Date(academicWeeks[i + 1].start)
+          : null;
+
+      weekStart.setHours(0, 0, 0, 0);
+      if (nextWeekStart) nextWeekStart.setHours(0, 0, 0, 0);
+
+      if (
+        parsedDate >= weekStart &&
+        (!nextWeekStart || parsedDate < nextWeekStart)
+      ) {
+        academicWeekNumber = academicWeeks[i].number;
+        break;
+      }
+    }
+  }
+
+  const handlePrevWeek = () => {
+    if (!parsedDate) return;
+    const newDate = new Date(parsedDate);
+    newDate.setDate(parsedDate.getDate() - 7);
+    onValueChange(newDate);
+  };
+
+  const handleNextWeek = () => {
+    if (!parsedDate) return;
+    const newDate = new Date(parsedDate);
+    newDate.setDate(parsedDate.getDate() + 7);
+    onValueChange(newDate);
+  };
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      ref={effectiveRef}
+      {...props}
+    >
+      <IconButton
+        onClick={handlePrevWeek}
+        disabled={disabled}
+        aria-label='Go to previous week'
+      >
+        <Icon.ChevronLeft />
+      </IconButton>
+      <VisibleField
+        inputValue={inputValue}
+        onInputChange={handleInputChange}
+        onInputKeyDown={handleInputKeyDown}
+        onInputFocus={handleShowPanel}
+        onButtonClick={handleTogglePanel}
+        disabled={disabled}
+        inputRef={effectiveInputRef}
+        beginningOfWeek={weekRange ? weekRange.start.toDateString() : ''}
+        endOfWeek={weekRange ? weekRange.end.toDateString() : ''}
+        academicWeekNumber={academicWeekNumber ?? undefined}
+      />
+      <IconButton
+        onClick={handleNextWeek}
+        disabled={disabled}
+        aria-label='Go to next week'
+      >
+        <Icon.ChevronRight />
+      </IconButton>
+      {panelOpen && (
+        <Panel>
+          <Calendar
+            pickedDate={value}
+            onDatePick={handlePickCalendarDate}
+            minDate={minDate}
+            maxDate={maxDate}
+            events={events}
+            showAcademicWeeks={showAcademicWeeks}
+            academicWeeks={academicWeeks}
+          />
+        </Panel>
+      )}
+    </div>
+  );
+};
+
+export default CustomDatepicker;

package/lib/components/WeekPicker/subcomponents/DatepickerInput.tsx

@@ -0,0 +1,111 @@
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../../theme';
+import { useState } from 'react';
+
+interface DatepickerInputProps {
+  value: string;
+  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  onFocus: () => void;
+  disabled: boolean;
+  ref: React.RefObject<HTMLInputElement | null>;
+  beginningOfWeek?: string;
+  endOfWeek?: string;
+  academicWeekNumber?: number;
+}
+
+const NAME = 'ucl-uikit-weekpicker__input';
+
+const DatepickerInput = ({
+  value,
+  onChange,
+  onKeyDown,
+  onFocus,
+  disabled,
+  beginningOfWeek,
+  endOfWeek,
+  academicWeekNumber,
+  ref,
+}: DatepickerInputProps) => {
+  const [theme] = useTheme();
+
+  const [isFocused, setIsFocused] = useState(false);
+
+  const baseStyle = css`
+    width: 100%;
+    height: 100%;
+    border: none;
+    color: ${theme.color.text.primary};
+    font-family: ${theme.font.family.primary};
+    font-size: ${theme.font.size.f16};
+    letter-spacing: 1px;
+    caret-color: ${theme.color.text.primary};
+    padding: 0px;
+
+    &:focus {
+      outline: none;
+    }
+
+    &::placeholder {
+      color: #8c8c8c; // TODO: Needs a design token -- Figma says 'color/text/tertiary'
+    }
+  `;
+
+  const disabledStyle = css`
+    color: ${theme.color.text.disabled};
+    background-color: ${theme.color.neutral.white};
+
+    &::placeholder {
+      color: ${theme.color.text.disabled};
+    }
+  `;
+
+  const style = cx(NAME, baseStyle, disabled && disabledStyle);
+
+  const formatStart = (dateString: string) => {
+    const date = new Date(dateString);
+    return date.toLocaleDateString('en-GB', {
+      day: '2-digit',
+      month: 'short',
+    });
+  };
+
+  const formatEnd = (dateString: string) => {
+    const date = new Date(dateString);
+    return date.toLocaleDateString('en-GB', {
+      day: '2-digit',
+      month: 'short',
+      year: 'numeric',
+    });
+  };
+
+  const formattedLabel =
+    beginningOfWeek && endOfWeek
+      ? `${formatStart(beginningOfWeek)} - ${formatEnd(endOfWeek)}`
+      : '';
+
+  const displayValue = isFocused ? value : formattedLabel;
+
+  return (
+    <input
+      value={displayValue}
+      onChange={onChange}
+      onKeyDown={onKeyDown}
+      onFocus={() => {
+        setIsFocused(true);
+        onFocus();
+      }}
+      onBlur={() => setIsFocused(false)}
+      disabled={disabled}
+      type='text'
+      inputMode='numeric'
+      placeholder='DD/MM/YYYY'
+      className={style}
+      data-testid={NAME}
+      ref={ref}
+      aria-label={`Currently selected date: ${value} - Week from ${formattedLabel}. ${academicWeekNumber ? `(Academic Week ${academicWeekNumber})` : ''}`}
+    />
+  );
+};
+
+export default DatepickerInput;