uikit-react-public 0.43.4 → 0.44.2

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

@@ -9,6 +9,7 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     pickedDate: { control: { type: 'date' } },
+    pickedMonth: { control: { type: 'date' } },
     minDate: { control: { type: 'date' } },
     maxDate: { control: { type: 'date' } },
     showAcademicWeeks: { control: { type: 'boolean' } },
@@ -37,6 +38,9 @@ export const Default: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -79,6 +83,9 @@ export const WithEvents: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -158,6 +165,9 @@ export const WithAcademicWeeks: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar
@@ -198,6 +208,9 @@ export const MinMaxDates: Story = {
     args.pickedDate = args.pickedDate
       ? parseDateFromUNIXTimestamp(args.pickedDate)
       : null;
+    args.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
       <Calendar

package/lib/components/Calendar/Calendar.tsx

@@ -11,6 +11,7 @@ const DEFAULT_MAX_YEAR = 2100;
 
 const Calendar = ({
   pickedDate = null,
+  pickedMonth = null,
   onDatePick,
   minDate = null,
   maxDate = null,
@@ -37,6 +38,11 @@ const Calendar = ({
     pickedDate = null;
   }
 
+  if (pickedMonth && isNaN(pickedMonth.getTime())) {
+    console.warn('Calendar: pickedMonth is invalid, defaulting to null');
+    pickedMonth = null;
+  }
+
   const clampDisplayMonth = useCallback(
     (date: Date) => {
       const year = date.getFullYear();
@@ -54,36 +60,35 @@ const Calendar = ({
     [yearRangeEnd, yearRangeStart]
   );
 
+  // pickedDate takes precedence over pickedMonth
+  const activePickedDate = pickedDate ?? pickedMonth;
+
   // Used to track prop value changes
-  const pickedDateRef = useRef<Date | null>(pickedDate ?? null);
+  const activePickedDateRef = useRef<Date | null>(activePickedDate);
 
   // 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
-    clampDisplayMonth(pickedDate ?? new Date())
+    // Display month initialises as the picked date's month, else the picked month, else the current month
+    clampDisplayMonth(activePickedDate ?? new Date())
   );
 
-  // Snap displayed month to the picked date's month if it changes
+  // Snap displayed month to the active picked date/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 there's an active picked date/month
+      activePickedDate &&
+      // If it has changed
+      activePickedDateRef.current?.getTime() !== activePickedDate.getTime() &&
+      // If it's not in the currently displayed month
+      (activePickedDate.getMonth() !== displayMonth.getMonth() ||
+        activePickedDate.getFullYear() !== displayMonth.getFullYear())
     ) {
-      // 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(clampDisplayMonth(pickedDate));
-      }
+      // Update the display month to match
+      setDisplayMonth(clampDisplayMonth(activePickedDate));
     }
-    // Update the ref to the new picked date
-    pickedDateRef.current = pickedDate;
-  }, [pickedDate, displayMonth, clampDisplayMonth]);
+    // Update the ref to the new active picked date/month
+    activePickedDateRef.current = activePickedDate;
+  }, [activePickedDate, displayMonth, clampDisplayMonth]);
 
   useEffect(() => {
     const clampedDisplayMonth = clampDisplayMonth(displayMonth);

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

@@ -9,7 +9,8 @@ export type AcademicWeek = {
 };
 
 export interface CalendarProps {
-  pickedDate?: Date | null;
+  pickedDate?: Date | null; // Date to select and display
+  pickedMonth?: Date | null; // Date whose month is displayed when pickedDate is not set
   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

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

@@ -84,6 +84,45 @@ describe('Calendar', () => {
     );
   });
 
+  test('Displays the picked month without selecting an individual date', () => {
+    customRender(<Calendar pickedMonth={new Date('2025-07-01')} />);
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'July'
+    );
+    expect(screen.getByRole('combobox', { name: 'Year' })).toHaveTextContent(
+      '2025'
+    );
+  });
+
+  test('pickedDate takes precedence over pickedMonth for the displayed month', () => {
+    customRender(
+      <Calendar
+        pickedDate={new Date('2025-03-22')}
+        pickedMonth={new Date('2025-07-01')}
+      />
+    );
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'March'
+    );
+  });
+
+  test('Updates the displayed month when the pickedMonth prop changes', () => {
+    const { rerender } = customRender(
+      <Calendar pickedMonth={new Date('2025-07-01')} />
+    );
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'July'
+    );
+
+    rerender(<Calendar pickedMonth={new Date('2025-09-01')} />);
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'September'
+    );
+  });
+
   test('Can change the displayed year with the year select', () => {
     customRender(<Calendar pickedDate={new Date('2025-03-01')} />);
 

package/lib/components/Datepicker/Datepicker.stories.tsx

@@ -12,6 +12,7 @@ const meta = {
     value: { control: { type: 'date' } },
     minDate: { control: { type: 'date' } },
     maxDate: { control: { type: 'date' } },
+    pickedMonth: { control: { type: 'date' } },
     disabled: { control: { type: 'boolean' } },
     clearable: { control: { type: 'boolean' } },
     showAcademicWeeks: { control: { type: 'boolean' } },
@@ -22,6 +23,13 @@ const meta = {
 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];
 };
@@ -29,9 +37,9 @@ const dateToISOString = (date: Date) => {
 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')
@@ -54,9 +62,9 @@ export const Default: Story = {
 export const InAField: 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')
@@ -116,9 +124,9 @@ export const WithEvents: 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')
@@ -204,9 +212,9 @@ export const WithAcademicWeeks: 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')
@@ -253,9 +261,9 @@ export const MinMaxDates: 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')
@@ -283,9 +291,9 @@ export const Clearable: 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.pickedMonth = args.pickedMonth
+      ? parseDateFromUNIXTimestamp(args.pickedMonth)
+      : null;
     args.value = args.value ? new Date(args.value) : null;
     args.minDate = args.minDate
       ? new Date(args.minDate).toLocaleDateString('sv-SE')

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

@@ -14,6 +14,7 @@ interface BaseDatepickerProps {
   maxDate?: string | null; // ISO date string: YYYY-MM-DD
   minYear?: number;
   maxYear?: number;
+  pickedMonth?: Date | null; // Pre-selects a month to display when no value is set
   events?: CalendarEvent[];
   showAcademicWeeks?: boolean;
   academicWeeks?: AcademicWeek[];

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

@@ -107,6 +107,55 @@ describe('Datepicker', () => {
     );
   });
 
+  test('Does not submit an enclosing form on ENTER key press', async () => {
+    const onValueChange = vi.fn();
+    const onSubmit = vi.fn((event: React.FormEvent) => event.preventDefault());
+    const user = userEvent.setup();
+    customRender(
+      <form onSubmit={onSubmit}>
+        <Datepicker onValueChange={onValueChange} />
+      </form>
+    );
+
+    // Internal <input> (the user types into)
+    const datepickerInput = screen.getByRole('textbox');
+    await user.type(datepickerInput, '10/03/2025');
+    expect(datepickerInput).toHaveValue('10/03/2025');
+
+    // Trigger user-entered date parsing
+    await user.keyboard('{Enter}');
+
+    // The date is still parsed as normal...
+    expect(onValueChange).toHaveBeenCalledWith(
+      new Date('2025-03-10'),
+      expect.anything() // 2nd parameter is the event object (which we're not testing here)
+    );
+    // ...but the enclosing form is not submitted
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  test('Does not bubble {Enter} key press to a parent element', async () => {
+    const onValueChange = vi.fn();
+    const parentKeyDown = vi.fn();
+    const user = userEvent.setup();
+    customRender(
+      <div onKeyDown={parentKeyDown}>
+        <Datepicker onValueChange={onValueChange} />
+      </div>
+    );
+
+    const datepickerInput = screen.getByRole('textbox');
+    await user.type(datepickerInput, '10/03/2025');
+    // Typing the digits/slashes above also fires keydown events that
+    // correctly bubble (only Enter is stopped, to prevent it submitting an
+    // enclosing form) - clear those out so only Enter is captured below.
+    parentKeyDown.mockClear();
+
+    await user.keyboard('{Enter}');
+
+    expect(parentKeyDown).not.toHaveBeenCalled();
+  });
+
   test('Input value reflects the date', () => {
     // 10th March 2025 (2 is March, because month is 0-indexed in Date constructor)
     customRender(<Datepicker value={new Date(2025, 2, 10)} />);
@@ -153,6 +202,21 @@ describe('Datepicker', () => {
     expect(panel.parentElement).toHaveClass('ucl-overlay');
   });
 
+  test('Forwards pickedMonth to the Calendar panel without affecting the input value', () => {
+    customRender(<Datepicker pickedMonth={new Date('2026-07-01')} />);
+
+    const input = screen.getByTestId('ucl-uikit-datepicker__input');
+    fireEvent.focus(input);
+
+    expect(screen.getByRole('combobox', { name: 'Month' })).toHaveTextContent(
+      'July'
+    );
+    expect(screen.getByRole('combobox', { name: 'Year' })).toHaveTextContent(
+      '2026'
+    );
+    expect(input).toHaveValue('');
+  });
+
   test('Panel escapes a containing dialog via fixed positioning', () => {
     customRender(
       <dialog open>

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

@@ -20,6 +20,7 @@ interface CustomDatepickerProps extends React.HTMLAttributes<HTMLDivElement> {
   maxDate?: string | null; // ISO date string: YYYY-MM-DD
   minYear?: number;
   maxYear?: number;
+  pickedMonth?: Date | null; // Pre-selects a month to display when no value is set
   disabled?: boolean;
   clearable?: boolean;
   events?: CalendarEvent[];
@@ -40,6 +41,7 @@ const CustomDatepicker = ({
   maxDate,
   minYear,
   maxYear,
+  pickedMonth = null,
   disabled = false,
   clearable = false,
   events,
@@ -116,6 +118,11 @@ const CustomDatepicker = ({
 
   const handleInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
     if (event.key === 'Enter') {
+      // Stop the native "Enter submits the enclosing form" behaviour.
+      event.preventDefault();
+      // Key events must not bubble out of the datepicker (e.g. so a parent
+      // form's own key handlers don't also see this Enter).
+      event.stopPropagation();
       handleParseInput(event);
     } else if (event.key === 'Escape') {
       resetField();
@@ -260,6 +267,7 @@ const CustomDatepicker = ({
           <Panel>
             <Calendar
               pickedDate={value}
+              pickedMonth={pickedMonth}
               onDatePick={handlePickCalendarDate}
               minDate={minDate}
               maxDate={maxDate}

package/lib/components/Header/Header.mdx

@@ -3,6 +3,7 @@ import { Meta, Title, Subtitle, Canvas, Controls } from "@storybook/addon-docs/b
 
 export const usage = {
   default: `<Header title='App Name' />`,
+  noBorder: `<Header title='App Name' showBorder={false} />`,
   homeLink: `<Header title='App Name' homeLinkHref='/' homeLinkAriaLabel='Go to home' />`,
   menu: `<Header title='App Name' homeLinkHref='/'>
   <Header.Menu>
@@ -26,6 +27,12 @@ to add a menu button on the right.
 
 <Canvas source={{ code: usage.default }} />
 
+## Border
+
+Set `showBorder={false}` when another component, such as `NavigationBar`, sits directly below the header and should provide the dividing border.
+
+<Canvas of={HeaderStories.WithoutBorder} source={{ code: usage.noBorder }} />
+
 ## Home link
 
 Add `homeLinkHref` (and optionally `homeLinkAriaLabel`) to make the logo/title act as a home link.
@@ -49,4 +56,4 @@ Use `fixed` to pin the header to the top of the viewport.
 Full props specification for `<Header>` is below.
 <Canvas source={{ code: usage.default }} />
 You can use the controls below to manipulate the `<Header>` component above.
-<Controls />
+<Controls />

package/lib/components/Header/Header.stories.tsx

@@ -13,6 +13,7 @@ const meta = {
   },
   argTypes: {
     title: { control: 'text' },
+    showBorder: { control: 'boolean' },
     fixed: { control: 'boolean' },
     homeLinkHref: { control: 'text' },
     homeLinkAriaLabel: { control: 'text' },
@@ -77,6 +78,18 @@ export const WithHomeLink: Story = {
   },
 };
 
+export const WithoutBorder: Story = {
+  name: 'Without border',
+  render: (args) => (
+    <div style={{ overflow: 'hidden' }}>
+      <Header {...args} />
+    </div>
+  ),
+  args: {
+    showBorder: false,
+  },
+};
+
 export const WithMenu: Story = {
   render: (args) => (
     <div style={storyWrapperStyle}>

package/lib/components/Header/Header.tsx

@@ -13,6 +13,7 @@ export const DEFAULT_Z_INDEX = 3;
 
 export interface HeaderProps extends HTMLAttributes<HTMLElement> {
   title?: string;
+  showBorder?: boolean;
   /** @deprecated Only used by the default-theme legacy Header. */
   fixed?: boolean;
   titleAs?: React.ElementType<React.HTMLAttributes<HTMLElement>>;
@@ -164,6 +165,7 @@ const LegacyHeader = ({
 
 const Header = ({
   title,
+  showBorder = true,
   titleAs = 'div',
   titleClassName,
   titleProps,
@@ -206,6 +208,7 @@ const Header = ({
   return (
     <HeaderNew
       title={title ?? ''}
+      showBorder={showBorder}
       titleAs={titleAs}
       titleClassName={titleClassName}
       titleProps={titleProps}

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

@@ -89,4 +89,26 @@ describe('Header', () => {
     expect(link).toBeInTheDocument();
     expect(link.getAttribute('href')).toBe('/');
   });
+
+  test('passes showBorder to the new header implementation', () => {
+    render(
+      <ThemeContextProvider theme='light'>
+        <Header
+          title='LIDS'
+          showBorder={false}
+        />
+      </ThemeContextProvider>
+    );
+
+    const header = screen.getByTestId('ucl-uikit-header');
+    const generatedClass = [...header.classList].find((className) =>
+      className.startsWith('css-')
+    );
+
+    expect(generatedClass).toBeDefined();
+    expect(header).not.toHaveAttribute('showBorder');
+    expect(document.head.textContent).toContain(
+      `.${generatedClass}{height:78px;padding:0 48px 0 64px;}`
+    );
+  });
 });

package/lib/components/HeaderNew/Header.tsx

@@ -12,6 +12,7 @@ export const NAME = 'ucl-uikit-header';
 
 export interface HeaderProps extends HTMLAttributes<HTMLElement> {
   title: string;
+  showBorder?: boolean;
   titleAs?: React.ElementType<React.HTMLAttributes<HTMLElement>>;
   titleClassName?: string;
   titleProps?: Record<string, unknown>;
@@ -22,6 +23,7 @@ export interface HeaderProps extends HTMLAttributes<HTMLElement> {
 
 const Header = ({
   title,
+  showBorder = true,
   titleAs = 'div',
   titleClassName,
   titleProps,
@@ -51,7 +53,11 @@ const Header = ({
     @media (min-width: ${theme.breakpoints.desktop}px) {
       height: ${HEADER_TABLET_HEIGHT_PX}px;
       padding: 0 ${theme.padding.p48} 0 ${theme.padding.p64};
-      border-bottom: 1px solid ${theme.colour.border.subtle};
+      ${
+        showBorder
+          ? `border-bottom: 1px solid ${theme.colour.border.subtle};`
+          : ''
+      }
     }
   `;
 

package/lib/components/HeaderNew/__tests__/Header.test.tsx

@@ -40,6 +40,47 @@ describe('Header', () => {
     expect(link.getAttribute('href')).toBe('/');
   });
 
+  test('shows the bottom border by default and can hide it', () => {
+    const { rerender } = render(
+      <ThemeContextProvider>
+        <Header title='LIDS' />
+      </ThemeContextProvider>
+    );
+
+    const header = screen.getByTestId('ucl-uikit-header');
+    const defaultClass = [...header.classList].find((className) =>
+      className.startsWith('css-')
+    );
+
+    expect(defaultClass).toBeDefined();
+    expect(document.head.textContent).toContain(
+      `.${defaultClass}{position:relative`
+    );
+    expect(document.head.textContent).toContain(
+      `.${defaultClass}{height:78px;padding:0 48px 0 64px;border-bottom:1px solid`
+    );
+
+    rerender(
+      <ThemeContextProvider>
+        <Header
+          title='LIDS'
+          showBorder={false}
+        />
+      </ThemeContextProvider>
+    );
+
+    const borderlessHeader = screen.getByTestId('ucl-uikit-header');
+    const borderlessClass = [...borderlessHeader.classList].find((className) =>
+      className.startsWith('css-')
+    );
+
+    expect(borderlessClass).toBeDefined();
+    expect(borderlessHeader).not.toHaveAttribute('showBorder');
+    expect(document.head.textContent).toContain(
+      `.${borderlessClass}{height:78px;padding:0 48px 0 64px;}`
+    );
+  });
+
   test('spaces subsequent header items on smaller screens and resets spacing on desktop', () => {
     render(
       <ThemeContextProvider>