uikit-react-public 0.14.21 → 0.21.8

package/lib/components/Datepicker/Datepicker.types.ts

@@ -1,5 +1,6 @@
-import type { InputHTMLAttributes, HTMLAttributes, RefObject } from 'react';
+import type { HTMLAttributes, RefObject } from 'react';
 import type { CalendarEvent, AcademicWeek } from '../Calendar';
+import type { InputProps } from './subcomponents/DatepickerInput';
 
 export type DatepickerValue = Date | null;
 
@@ -16,23 +17,13 @@ interface BaseDatepickerProps {
   academicWeeks?: AcademicWeek[];
   testId?: string;
   disabled?: boolean;
+  clearable?: boolean;
   ref?: RefObject<HTMLDivElement>;
   inputRef?: RefObject<HTMLInputElement>;
+  inputProps?: InputProps;
 }
 
-// Valid HTML attributes for <input type="date">
-type NativeDatepickerAttributeProps = Omit<
-  InputHTMLAttributes<HTMLInputElement>,
-  // Remove shared 'top-level' & handled props
-  'value' | 'onChange' | 'min' | 'max' | 'className' | 'disabled'
->;
-
 // `className?: string` is received automatically from `HTMLAttributes<HTMLDivElement>`
 export interface DatepickerProps
   extends BaseDatepickerProps,
-    HTMLAttributes<HTMLDivElement> {
-  native?: boolean;
-  // Attached as a nested object
-  nativeHTMLAttributes?: NativeDatepickerAttributeProps;
-  nativeRef?: RefObject<HTMLInputElement>;
-}
+    HTMLAttributes<HTMLDivElement> {}

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

@@ -1,7 +1,13 @@
-import { describe, test, expect, vi } from 'vitest';
+import { useState } from 'react';
+import { describe, test, expect, vi, beforeEach } from 'vitest';
 import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { ThemeContextProvider } from '../../../theme';
 import Datepicker from '..';
+import announce from '../../../utils/announce';
+
+// Mock the announce utility
+vi.mock('../../../utils/announce');
 
 const defaultTestId = 'ucl-uikit-datepicker';
 
@@ -14,8 +20,11 @@ const customRender = (ui: React.ReactElement) => {
 };
 
 describe('Datepicker', () => {
-  // Snapshot tests
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
 
+  // #region Snapshot tests
   test('Snapshot: no date provided', () => {
     const renderResult = customRender(<Datepicker />);
     expect(renderResult.container.firstChild).toMatchSnapshot();
@@ -23,13 +32,13 @@ describe('Datepicker', () => {
 
   test('Snapshot: with date provided', () => {
     const renderResult = customRender(
-      <Datepicker value={new Date('2025-03-10')} />
+      <Datepicker value={new Date(2025, 2, 10)} />
     );
     expect(renderResult.container.firstChild).toMatchSnapshot();
   });
+  // #endregion
 
-  // Unit tests
-
+  // #region Functional tests
   test('Can be found via default test ID', () => {
     customRender(<Datepicker />);
     const datepicker = screen.getByTestId(defaultTestId);
@@ -43,8 +52,55 @@ describe('Datepicker', () => {
     expect(datepicker).toBeInTheDocument();
   });
 
+  test('Parses date on ENTER key press', async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    customRender(<Datepicker onValueChange={onValueChange} />);
+
+    // Internal <input> (the user types into)
+    const datepickerInput = screen.getByRole('textbox');
+    await user.type(datepickerInput, '10/03/2025');
+    // Internal input holds typed value before parsing
+    expect(datepickerInput).toHaveValue('10/03/2025');
+
+    // Wait for ENTER key press to trigger parsing
+    expect(onValueChange).not.toHaveBeenCalled();
+
+    // Trigger user-entered date parsing
+    await user.keyboard('{Enter}');
+
+    expect(onValueChange).toHaveBeenCalledWith(
+      new Date('2025-03-10'),
+      expect.anything() // 2nd parameter is the event object (which we're not testing here)
+    );
+  });
+
+  test('Parses date on TAB key press', async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    customRender(<Datepicker onValueChange={onValueChange} />);
+
+    // Internal <input> (the user types into)
+    const datepickerInput = screen.getByRole('textbox');
+    await user.type(datepickerInput, '10/03/2025');
+    // Internal input holds typed value before parsing
+    expect(datepickerInput).toHaveValue('10/03/2025');
+
+    // Wait for TAB key press to trigger parsing
+    expect(onValueChange).not.toHaveBeenCalled();
+
+    // Trigger user-entered date parsing
+    await user.keyboard('{Tab}');
+
+    expect(onValueChange).toHaveBeenCalledWith(
+      new Date('2025-03-10'),
+      expect.anything() // 2nd parameter is the event object (which we're not testing here)
+    );
+  });
+
   test('Input value reflects the date', () => {
-    customRender(<Datepicker value={new Date('2025-03-10')} />);
+    // 10th March 2025 (2 is March, because month is 0-indexed in Date constructor)
+    customRender(<Datepicker value={new Date(2025, 2, 10)} />);
     const input = screen.getByTestId('ucl-uikit-datepicker__input');
     expect(input).toHaveValue('10/03/2025');
   });
@@ -66,7 +122,7 @@ describe('Datepicker', () => {
     const onValueChange = vi.fn();
     customRender(
       <Datepicker
-        value={new Date('2025-01-10')} // Before minDate
+        value={new Date(2025, 0, 10)} // Before minDate (0 is January, because month is 0-indexed in Date constructor)
         minDate='2025-02-01'
         onValueChange={onValueChange}
       />
@@ -78,11 +134,214 @@ describe('Datepicker', () => {
     const onValueChange = vi.fn();
     customRender(
       <Datepicker
-        value={new Date('2025-03-10')} // After maxDate
+        value={new Date(2025, 2, 10)} // After maxDate (2 is March, because month is 0-indexed in Date constructor)
         maxDate='2025-01-31'
         onValueChange={onValueChange}
       />
     );
     expect(onValueChange).toHaveBeenCalledWith(null);
   });
+
+  test('Input can receive additional HTML attributes via inputProps', () => {
+    customRender(
+      <Datepicker
+        inputProps={{
+          'aria-describedby': 'customValue',
+          'aria-required': 'true',
+        }}
+      />
+    );
+    const input = screen.getByTestId('ucl-uikit-datepicker__input');
+    expect(input).toHaveAttribute('aria-describedby', 'customValue');
+    expect(input).toHaveAttribute('aria-required', 'true');
+  });
+  // #endregion
+
+  // #region Accessibility tests
+  test("Input can be found via getByRole('textbox')", () => {
+    customRender(<Datepicker />);
+    const input = screen.getByRole('textbox');
+    expect(input).toBeInTheDocument();
+  });
+
+  test('Announces date on input text parse', () => {
+    customRender(<Datepicker />);
+    const input = screen.getByTestId('ucl-uikit-datepicker__input');
+    fireEvent.change(input, { target: { value: '15/03/2026' } });
+    fireEvent.keyDown(input, { key: 'Enter' });
+
+    expect(announce).toHaveBeenCalledWith(
+      'Selected date ' +
+        // March is month 2 in 0-indexed Date constructor
+        new Date(2026, 2, 15).toLocaleDateString('en-GB', {
+          weekday: 'long',
+          day: 'numeric',
+          month: 'long',
+          year: 'numeric',
+        })
+    );
+  });
+
+  test("Announces picked date on Calendar 'pick'", () => {
+    customRender(<Datepicker value={new Date(2026, 2, 10)} />);
+    // TODO: Separate this button from the 'clear date' button - [Datepicker_improv_005]
+    const openCalendarButton = screen.getByTestId(
+      'ucl-uikit-datepicker__visible-field-icon-button'
+    );
+    fireEvent.click(openCalendarButton);
+
+    const days = screen.getAllByTestId('ucl-uikit-calendar__day');
+    // Pick 15th March 2026:
+    // 6 days of previous month
+    // + 15 days of current month (1st to 15th)
+    // - 1 because of 0-indexing in the array
+    const dateArrayIndex = 6 + 15 - 1;
+    fireEvent.click(days[dateArrayIndex]);
+
+    expect(announce).toHaveBeenCalledWith(
+      'Selected date ' +
+        // March is month 2 in 0-indexed Date constructor
+        new Date(2026, 2, 15).toLocaleDateString('en-GB', {
+          weekday: 'long',
+          day: 'numeric',
+          month: 'long',
+          year: 'numeric',
+        })
+    );
+  });
+
+  test('Input can be found via label text when associated via id', () => {
+    customRender(
+      <>
+        <label htmlFor='my-datepicker'>Date of event</label>
+        <Datepicker inputProps={{ id: 'my-datepicker' }} />
+      </>
+    );
+    const input = screen.getByLabelText('Date of event');
+    expect(input).toHaveAttribute('data-testid', 'ucl-uikit-datepicker__input');
+  });
+
+  test('Custom aria-label can be set via inputProps', () => {
+    const customAriaLabel = 'Custom aria label';
+    customRender(<Datepicker inputProps={{ 'aria-label': customAriaLabel }} />);
+    const input = screen.getByTestId('ucl-uikit-datepicker__input');
+    expect(input).toHaveAttribute('aria-label', customAriaLabel);
+  });
+
+  test('Default Datepicker does not add an extra icon tab stop', async () => {
+    const user = userEvent.setup();
+
+    customRender(
+      <div>
+        <button type='button'>Before</button>
+        <Datepicker />
+        <button type='button'>After</button>
+      </div>
+    );
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Before' })).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('textbox')).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  test('Clearable Datepicker clear icon is focusable when a value is present', async () => {
+    const user = userEvent.setup();
+
+    customRender(
+      <div>
+        <button type='button'>Before</button>
+        <Datepicker
+          clearable
+          value={new Date(2025, 2, 10)}
+        />
+        <button type='button'>After</button>
+      </div>
+    );
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Before' })).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('textbox')).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Clear date' })).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  test('Clearing with the keyboard restores focus to the input', async () => {
+    const user = userEvent.setup();
+
+    const ControlledDatepicker = () => {
+      const [value, setValue] = useState<Date | null>(new Date(2025, 2, 10));
+
+      return (
+        <Datepicker
+          clearable
+          value={value}
+          onValueChange={setValue}
+        />
+      );
+    };
+
+    customRender(<ControlledDatepicker />);
+
+    await user.tab();
+    expect(screen.getByRole('textbox')).toHaveFocus();
+
+    await user.tab();
+    const clearButton = screen.getByRole('button', { name: 'Clear date' });
+    expect(clearButton).toHaveFocus();
+
+    await user.keyboard('{Enter}');
+
+    expect(screen.getByRole('textbox')).toHaveFocus();
+    expect(
+      screen.queryByRole('button', { name: 'Clear date' })
+    ).not.toBeInTheDocument();
+  });
+
+  test('Disabled Datepicker is skipped when tabbing', async () => {
+    const user = userEvent.setup();
+
+    customRender(
+      <div>
+        <button type='button'>Before</button>
+        <Datepicker disabled />
+        <button type='button'>After</button>
+      </div>
+    );
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Before' })).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  test('Disabled Datepicker icon control is not tabbable and cannot open', async () => {
+    const user = userEvent.setup();
+
+    customRender(<Datepicker disabled />);
+
+    const iconButton = screen.getByTestId(
+      'ucl-uikit-datepicker__visible-field-icon-button'
+    );
+
+    expect(iconButton).toHaveAttribute('aria-label', 'Open calendar');
+    expect(iconButton).toHaveAttribute('tabindex', '-1');
+    expect(iconButton).toBeDisabled();
+
+    await user.click(iconButton);
+
+    expect(screen.queryByTestId('ucl-uikit-calendar')).not.toBeInTheDocument();
+  });
+  // #endregion
 });

package/lib/components/Datepicker/__tests__/__snapshots__/Datepicker.test.tsx.snap

@@ -10,7 +10,6 @@ exports[`Datepicker > Snapshot: no date provided 1`] = `
     data-testid="ucl-uikit-datepicker__visible-field"
   >
     <input
-      aria-label="Currently selected date: "
       class="ucl-uikit-datepicker__input css-1k3pose"
       data-testid="ucl-uikit-datepicker__input"
       inputmode="numeric"
@@ -18,13 +17,18 @@ exports[`Datepicker > Snapshot: no date provided 1`] = `
       type="text"
       value=""
     />
-    <div
-      class="css-3tb0p0"
+    <button
+      aria-label="Open calendar"
+      class="ucl-uikit-icon-button css-1uz96ir"
+      data-testid="ucl-uikit-datepicker__visible-field-icon-button"
+      tabindex="-1"
+      type="button"
     >
       <svg
         class="ucl-uikit-icon css-1u4xgls"
         data-testid="ucl-uikit-icon"
         fill="none"
+        focusable="false"
         height="24"
         stroke="currentColor"
         stroke-linecap="round"
@@ -42,26 +46,11 @@ exports[`Datepicker > Snapshot: no date provided 1`] = `
           x="3"
           y="4"
         />
-        <line
-          x1="16"
-          x2="16"
-          y1="2"
-          y2="6"
-        />
-        <line
-          x1="8"
-          x2="8"
-          y1="2"
-          y2="6"
-        />
-        <line
-          x1="3"
-          x2="21"
-          y1="10"
-          y2="10"
+        <path
+          d="M16 2v4M8 2v4m-5 4h18"
         />
       </svg>
-    </div>
+    </button>
   </div>
 </div>
 `;
@@ -76,7 +65,6 @@ exports[`Datepicker > Snapshot: with date provided 1`] = `
     data-testid="ucl-uikit-datepicker__visible-field"
   >
     <input
-      aria-label="Currently selected date: 10/03/2025"
       class="ucl-uikit-datepicker__input css-1k3pose"
       data-testid="ucl-uikit-datepicker__input"
       inputmode="numeric"
@@ -84,13 +72,18 @@ exports[`Datepicker > Snapshot: with date provided 1`] = `
       type="text"
       value="10/03/2025"
     />
-    <div
-      class="css-3tb0p0"
+    <button
+      aria-label="Open calendar"
+      class="ucl-uikit-icon-button css-1uz96ir"
+      data-testid="ucl-uikit-datepicker__visible-field-icon-button"
+      tabindex="-1"
+      type="button"
     >
       <svg
         class="ucl-uikit-icon css-1u4xgls"
         data-testid="ucl-uikit-icon"
         fill="none"
+        focusable="false"
         height="24"
         stroke="currentColor"
         stroke-linecap="round"
@@ -108,26 +101,11 @@ exports[`Datepicker > Snapshot: with date provided 1`] = `
           x="3"
           y="4"
         />
-        <line
-          x1="16"
-          x2="16"
-          y1="2"
-          y2="6"
-        />
-        <line
-          x1="8"
-          x2="8"
-          y1="2"
-          y2="6"
-        />
-        <line
-          x1="3"
-          x2="21"
-          y1="10"
-          y2="10"
+        <path
+          d="M16 2v4M8 2v4m-5 4h18"
         />
       </svg>
-    </div>
+    </button>
   </div>
 </div>
 `;

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

@@ -3,8 +3,10 @@ import { css, cx } from '@emotion/css';
 import { VisibleField, Panel } from '.';
 import { Calendar } from '../..';
 import { parseInputValue } from '../utils';
+import announce from '../../../utils/announce';
 import type { DatepickerValue } from '../Datepicker.types';
 import type { CalendarEvent, AcademicWeek } from '../../Calendar';
+import type { InputProps } from './DatepickerInput';
 
 interface CustomDatepickerProps extends React.HTMLAttributes<HTMLDivElement> {
   value?: DatepickerValue;
@@ -15,12 +17,14 @@ interface CustomDatepickerProps extends React.HTMLAttributes<HTMLDivElement> {
   minDate?: string | null; // ISO date string: YYYY-MM-DD
   maxDate?: string | null; // ISO date string: YYYY-MM-DD
   disabled?: boolean;
+  clearable?: boolean;
   events?: CalendarEvent[];
   showAcademicWeeks?: boolean;
   academicWeeks?: AcademicWeek[];
   testId?: string;
   ref?: React.RefObject<HTMLDivElement>;
   inputRef?: React.RefObject<HTMLInputElement>;
+  inputProps?: InputProps;
 }
 
 const NAME = 'ucl-uikit-datepicker';
@@ -31,6 +35,7 @@ const CustomDatepicker = ({
   minDate,
   maxDate,
   disabled = false,
+  clearable = false,
   events,
   showAcademicWeeks,
   academicWeeks = [],
@@ -38,6 +43,7 @@ const CustomDatepicker = ({
   className,
   ref,
   inputRef,
+  inputProps = {},
   ...props
 }: CustomDatepickerProps) => {
   if (value && isNaN(value.getTime())) {
@@ -49,6 +55,7 @@ const CustomDatepicker = ({
   const effectiveRef = ref || internalRef;
   const internalInputRef = useRef<HTMLInputElement>(null);
   const effectiveInputRef = inputRef || internalInputRef;
+  const restoreFocusAfterClearRef = useRef(false);
 
   const [panelOpen, setPanelOpen] = useState(false);
 
@@ -69,15 +76,31 @@ const CustomDatepicker = ({
     resetField();
   }, [value, resetField]);
 
+  useEffect(() => {
+    if (!value && restoreFocusAfterClearRef.current) {
+      effectiveInputRef.current?.focus();
+      restoreFocusAfterClearRef.current = false;
+    }
+  }, [value, effectiveInputRef]);
+
   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);
+    const parsedDate = parseInputValue(inputValue, minDate, maxDate);
+    if (parsedDate) {
+      announce(
+        'Selected date ' +
+          parsedDate.toLocaleDateString('en-GB', {
+            weekday: 'long',
+            day: 'numeric',
+            month: 'long',
+            year: 'numeric',
+          })
+      );
+      onValueChange(parsedDate, event);
     } else {
       resetField();
     }
@@ -91,7 +114,8 @@ const CustomDatepicker = ({
       effectiveInputRef.current?.blur();
       setPanelOpen(false);
     } else if (event.key === 'Tab') {
-      resetField();
+      // Parse input on TAB (same as ENTER) for better accessibility
+      handleParseInput(event);
       setPanelOpen(false);
     }
   };
@@ -149,6 +173,15 @@ const CustomDatepicker = ({
     event?: React.SyntheticEvent
   ) => {
     if (onValueChange) {
+      announce(
+        'Selected date ' +
+          date?.toLocaleDateString('en-GB', {
+            weekday: 'long',
+            day: 'numeric',
+            month: 'long',
+            year: 'numeric',
+          })
+      );
       onValueChange(date, event);
     }
     setPanelOpen(false);
@@ -164,6 +197,12 @@ const CustomDatepicker = ({
     setPanelOpen((prev) => !prev);
   };
 
+  const handleClear = (event: React.SyntheticEvent) => {
+    event.stopPropagation(); // Prevent opening the calendar panel
+    restoreFocusAfterClearRef.current = true;
+    onValueChange(null, event);
+  };
+
   const baseStyle = css`
     width: 196px;
     height: 48px;
@@ -171,7 +210,7 @@ const CustomDatepicker = ({
     position: relative;
   `;
 
-  const style = cx(NAME, className, baseStyle);
+  const style = cx(NAME, baseStyle, className);
 
   return (
     <div
@@ -186,8 +225,12 @@ const CustomDatepicker = ({
         onInputKeyDown={handleInputKeyDown}
         onInputFocus={handleShowPanel}
         onButtonClick={handleTogglePanel}
+        onClear={handleClear}
         disabled={disabled}
+        clearable={clearable}
+        hasValue={!!value}
         inputRef={effectiveInputRef}
+        inputProps={inputProps}
       />
       {panelOpen && (
         <Panel>

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

@@ -1,7 +1,24 @@
 import { css, cx } from '@emotion/css';
 import { useTheme } from '../../../theme';
 
-interface DatepickerInputProps {
+/**
+ * HTML attributes that consumers can pass to the underlying `<input>` via the
+ * `inputProps` prop on `<Datepicker>`.
+ *
+ * Controlled and internally-managed attributes are omitted to prevent conflicts.
+ */
+export type InputProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  'value' | 'onChange' | 'onKeyDown' | 'onFocus' | 'disabled' | 'type'
+> & {
+  testId?: string;
+};
+
+/**
+ * Internal props for `<DatepickerInput>`, combining consumer-facing
+ *  input attributes with controlled props managed by `<VisibleField>`.
+ */
+interface DatepickerInputProps extends InputProps {
   value: string;
   onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
   onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
@@ -13,12 +30,12 @@ interface DatepickerInputProps {
 const NAME = 'ucl-uikit-datepicker__input';
 
 const DatepickerInput = ({
-  value,
-  onChange,
-  onKeyDown,
-  onFocus,
   disabled,
-  ref,
+  placeholder = 'DD/MM/YYYY',
+  inputMode = 'numeric',
+  testId = NAME,
+  className,
+  ...props
 }: DatepickerInputProps) => {
   const [theme] = useTheme();
 
@@ -51,22 +68,18 @@ const DatepickerInput = ({
     }
   `;
 
-  const style = cx(NAME, baseStyle, disabled && disabledStyle);
+  const style = cx(NAME, baseStyle, disabled && disabledStyle, className);
 
   return (
     <input
-      value={value}
-      onChange={onChange}
-      onKeyDown={onKeyDown}
-      onFocus={onFocus}
+      placeholder={placeholder}
+      inputMode={inputMode}
+      data-testid={testId}
+      className={style}
+      {...props}
+      // Controlled attributes -- not exposed to consumers to prevent conflicts
       disabled={disabled}
       type='text'
-      inputMode='numeric'
-      placeholder='DD/MM/YYYY'
-      className={style}
-      data-testid={NAME}
-      ref={ref}
-      aria-label={`Currently selected date: ${value}`}
     />
   );
 };