uikit-react-public 0.11.24 → 0.17.4

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

@@ -1,7 +1,12 @@
-import { describe, test, expect, vi } from 'vitest';
+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 +19,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 +31,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 +51,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 +121,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 +133,98 @@ 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);
+  });
+  // #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"
@@ -19,7 +18,11 @@ exports[`Datepicker > Snapshot: no date provided 1`] = `
       value=""
     />
     <div
-      class="css-3tb0p0"
+      aria-label="Open calendar"
+      class="css-nnfy6l"
+      data-testid="ucl-uikit-datepicker__visible-field-icon-button"
+      role="button"
+      tabindex="0"
     >
       <svg
         class="ucl-uikit-icon css-1u4xgls"
@@ -76,7 +79,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"
@@ -85,7 +87,11 @@ exports[`Datepicker > Snapshot: with date provided 1`] = `
       value="10/03/2025"
     />
     <div
-      class="css-3tb0p0"
+      aria-label="Open calendar"
+      class="css-nnfy6l"
+      data-testid="ucl-uikit-datepicker__visible-field-icon-button"
+      role="button"
+      tabindex="0"
     >
       <svg
         class="ucl-uikit-icon css-1u4xgls"

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())) {
@@ -75,9 +81,18 @@ const CustomDatepicker = ({
 
   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 +106,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 +165,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 +189,11 @@ const CustomDatepicker = ({
     setPanelOpen((prev) => !prev);
   };
 
+  const handleClear = (event: React.SyntheticEvent) => {
+    event.stopPropagation(); // Prevent opening the calendar panel
+    onValueChange(null);
+  };
+
   const baseStyle = css`
     width: 196px;
     height: 48px;
@@ -171,7 +201,7 @@ const CustomDatepicker = ({
     position: relative;
   `;
 
-  const style = cx(NAME, className, baseStyle);
+  const style = cx(NAME, baseStyle, className);
 
   return (
     <div
@@ -186,8 +216,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}`}
     />
   );
 };

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

@@ -7,7 +7,11 @@ interface PanelProps {
 
 const NAME = 'ucl-uikit-datepicker__panel';
 
-const Panel = ({ zIndex = 10, children }: PanelProps) => {
+const Panel = ({
+  zIndex = 10,
+  children,
+}: PanelProps) => {
+
   const datepickerHeight = 48;
   const gapFromDatepicker = 8;
 
@@ -27,6 +31,6 @@ const Panel = ({ zIndex = 10, children }: PanelProps) => {
       {children}
     </div>
   );
-};
+}
 
 export default Panel;

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

@@ -3,6 +3,7 @@ import { DatepickerInput } from './';
 import { Icon } from '../../..';
 import { useTheme } from '../../../theme';
 import React from 'react';
+import type { InputProps } from './DatepickerInput';
 
 interface VisibleFieldProps {
   inputValue: string;
@@ -10,8 +11,12 @@ interface VisibleFieldProps {
   onInputKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
   onInputFocus: () => void;
   onButtonClick: () => void;
+  onClear: (event: React.SyntheticEvent) => void;
   disabled: boolean;
+  clearable?: boolean;
+  hasValue?: boolean;
   inputRef: React.RefObject<HTMLInputElement | null>;
+  inputProps: InputProps;
 }
 
 const NAME = 'ucl-uikit-datepicker__visible-field';
@@ -22,8 +27,12 @@ const VisibleField = ({
   onInputKeyDown,
   onInputFocus,
   onButtonClick,
+  onClear,
   disabled,
+  clearable = false,
+  hasValue = false,
   inputRef,
+  inputProps,
 }: VisibleFieldProps) => {
   const [theme] = useTheme();
 
@@ -61,9 +70,15 @@ const VisibleField = ({
     display: flex;
     align-items: center;
     justify-content: center;
-    padding: 0 16px 0 4px;
+    padding: 0 16px;
+    // padding: 0 16px 0 4px;
     height: 100%;
     cursor: pointer;
+
+    &:focus-visible {
+      outline: none;
+      box-shadow: ${theme.boxShadow.focus};
+    }
   `;
 
   // `min-width` here accounts for a recurring problem,
@@ -76,6 +91,9 @@ const VisibleField = ({
       : '#8C8C8C'}; // TODO: Needs a design token
   `;
 
+  // Determine which icon to show
+  const showClearIcon = clearable && hasValue && !disabled;
+
   const style = cx(NAME, baseStyle, disabled && disabledStyle);
 
   return (
@@ -90,12 +108,31 @@ const VisibleField = ({
         onFocus={onInputFocus}
         disabled={disabled}
         ref={inputRef}
+        {...inputProps}
       />
       <div
-        onClick={onButtonClick}
+        onClick={showClearIcon ? onClear : onButtonClick}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            if (showClearIcon) {
+              onClear(e);
+            } else {
+              onButtonClick();
+            }
+          }
+        }}
         className={iconButtonStyle}
+        tabIndex={0}
+        role='button'
+        aria-label={showClearIcon ? 'Clear date' : 'Open calendar'}
+        data-testid={`${NAME}-icon-button`}
       >
-        <Icon.Calendar className={iconStyle} />
+        {showClearIcon ? (
+          <Icon.X className={iconStyle} />
+        ) : (
+          <Icon.Calendar className={iconStyle} />
+        )}
       </div>
     </div>
   );

package/lib/components/Datepicker/subcomponents/index.ts

@@ -1,5 +1,4 @@
 export { default as CustomDatepicker } from './CustomDatepicker';
-export { default as NativeDatepicker } from './NativeDatepicker';
 export { default as VisibleField } from './VisibleField';
 export { default as DatepickerInput } from './DatepickerInput';
 export { default as Panel } from './Panel';

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

@@ -1,2 +1 @@
-export { default as dateToLocaleISOString } from './dateToLocaleISOString/dateToLocaleISOString';
 export { default as parseInputValue } from './parseInputValue/parseInputValue';

package/lib/components/Dialog/BaseDialog.tsx

@@ -4,9 +4,12 @@ import React, {
   memo,
   useEffect,
   useRef,
+  useContext,
 } from 'react';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
+import { useFocusTrap } from '../../hooks/useFocusTrap';
+import { DialogContext } from './Dialog';
 
 export const NAME = 'ucl-uikit-base-dialog';
 export const SMALL_WIDTH = 495;
@@ -19,7 +22,14 @@ export interface BaseDialogProps extends HTMLAttributes<HTMLDialogElement> {
   modal?: boolean;
   closeOnClickOutside?: boolean;
   closeOnClickOutsideStopPropagation?: boolean;
-  onClose?: (ev: React.MouseEvent) => void;
+  nonModalCloseOnEscape?: boolean;
+  onClose?: (ev: React.MouseEvent | KeyboardEvent) => void;
+  // Focus trap related props
+  initialFocusRef?: React.RefObject<HTMLElement>;
+  finalFocusRef?: React.RefObject<HTMLElement>;
+  disableFocusTrap?: boolean;
+  restoreFocus?: boolean;
+  skipCloseOnInitialFocus?: boolean;
   testId?: string;
 }
 
@@ -29,10 +39,16 @@ const BaseDialog = ({
   modal = true,
   closeOnClickOutside = true,
   closeOnClickOutsideStopPropagation = true,
+  nonModalCloseOnEscape = false,
   onClose,
-  testId = NAME,
   className,
   children,
+  initialFocusRef,
+  finalFocusRef,
+  disableFocusTrap = false,
+  restoreFocus = true,
+  skipCloseOnInitialFocus = false,
+  testId = NAME,
   ...props
 }: BaseDialogProps) => {
   const width = {
@@ -46,6 +62,20 @@ const BaseDialog = ({
   const dialogRef = useRef<HTMLDialogElement>(null);
   const previousActiveElement = useRef<HTMLElement | null>(null);
 
+  const context = useContext(DialogContext);
+  const dialogHeaderId = context?.dialogHeaderId;
+  const dialogBodyId = context?.dialogBodyId;
+
+  // Use the focus trap hook
+  useFocusTrap({
+    isActive: open && modal && !disableFocusTrap,
+    containerRef: dialogRef,
+    initialFocusRef,
+    finalFocusRef,
+    restoreFocus,
+    skipFirstFocusable: skipCloseOnInitialFocus,
+  });
+
   const hideBodyScroll = css`
     overflow: hidden;
   `;
@@ -75,9 +105,27 @@ const BaseDialog = ({
       }
     } else if (!open && dialogElement.hasAttribute('open')) {
       dialogElement.close();
-      previousActiveElement.current?.focus();
+      // Focus restoration is handled by the focus trap hook for modal dialogs,
+      // but we keep the fallback for non-modal dialogs or when focus trap is disabled
+      if ((!modal || disableFocusTrap) && restoreFocus) {
+        previousActiveElement.current?.focus();
+      }
     }
-  }, [open, modal]);
+  }, [open, modal, disableFocusTrap, restoreFocus]);
+
+  // Handle Escape key to close dialog
+  useEffect(() => {
+    if (!open || modal || !nonModalCloseOnEscape) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && onClose) {
+        onClose(event);
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [open, modal, nonModalCloseOnEscape, onClose]);
 
   const handleClick = useCallback(
     (ev: React.MouseEvent<HTMLDialogElement>) => {
@@ -150,6 +198,9 @@ const BaseDialog = ({
         data-testid={testId}
         onClick={handleClick}
         onClose={handleDialogClose}
+        aria-modal={modal ? 'true' : 'false'}
+        aria-labelledby={dialogHeaderId}
+        aria-describedby={dialogBodyId}
         {...props}
       >
         {children}