uikit-react-public 0.14.21 → 0.17.4

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

@@ -1,5 +1,5 @@
 import { CustomDatepicker } from './subcomponents';
-import type { DatepickerProps } from '../Datepicker';
+import type { WeekPickerProps } from './WeekPicker.types';
 
 const WeekPicker = ({
   value,
@@ -9,7 +9,7 @@ const WeekPicker = ({
   disabled,
   className,
   ...props
-}: DatepickerProps) => {
+}: WeekPickerProps) => {
   return (
     <CustomDatepicker
       value={value}

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

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

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

@@ -4,7 +4,7 @@ import { VisibleField } from './';
 import { Panel } from '../../Datepicker/subcomponents';
 import { Calendar, Icon, IconButton } from '../..';
 import { parseInputValue } from '../../Datepicker/utils';
-import type { DatepickerValue } from '../../Datepicker/Datepicker.types';
+import type { DatepickerValue } from '../WeekPicker.types';
 import type { CalendarEvent, AcademicWeek } from '../../Calendar';
 
 interface CustomDatepickerProps extends React.HTMLAttributes<HTMLDivElement> {

package/lib/components/common/Common.mdx

@@ -76,7 +76,7 @@ The available margin props are:
   include={['m', 'm', 'mv', 'mh', 'mt', 'mb', 'ml', 'mr', 'noMargins']} 
 />
 
-[A live example of common margin props can be found in this `<Button>` story.](?path=/story/components-ready-to-use-button--common-margins)
+[A live example of common margin props can be found in this `<Button>` story.](?path=/story/components-button--common-margins)
 
 Implementation details can be found in <a href='https://github.com/ucl-isd/uikit-react/blob/main/lib/components/common/marginsStyle.ts' target='_blank'>uikit-react/components/common/MarginsStyle.tsx</a>
 

package/lib/components/index.ts

@@ -103,8 +103,8 @@ export type { TabsProps } from './Tabs';
 export type { TabProps } from './Tabs/Tab';
 
 // todo:
-// export { default as Accordion } from './Accordion';
-// export type { AccordionProps } from './Accordion';
+export { default as Accordion } from './Accordion';
+export type { AccordionProps } from './Accordion';
 
 export { default as Field } from './Field';
 export type { FieldProps } from './Field';
@@ -134,6 +134,9 @@ export type { RadioProps, LabelledRadioProps } from './Radio';
 export { default as Datepicker } from './Datepicker';
 export type { DatepickerProps } from './Datepicker';
 
+export { default as NativeDatepicker } from './NativeDatepicker';
+export type { NativeDatepickerProps } from './NativeDatepicker';
+
 export { default as Calendar } from './Calendar';
 export type { CalendarProps } from './Calendar';
 
@@ -150,3 +153,9 @@ export type { CookieNoticeProps } from './CookieNotice';
 
 export { default as Search } from './Search';
 export type { SearchProps } from './Search';
+
+export { default as Layout } from './Layout';
+export type { LayoutProps } from './Layout';
+
+export { default as Main } from './Main';
+export type { MainProps } from './Main';

package/lib/hooks/useFocusTrap.ts

@@ -22,6 +22,7 @@ interface UseFocusTrapOptions {
   initialFocusRef?: React.RefObject<HTMLElement>;
   finalFocusRef?: React.RefObject<HTMLElement>;
   restoreFocus?: boolean;
+  skipFirstFocusable?: boolean;
 }
 
 export const useFocusTrap = ({
@@ -30,6 +31,7 @@ export const useFocusTrap = ({
   initialFocusRef,
   finalFocusRef,
   restoreFocus = true,
+  skipFirstFocusable = false,
 }: UseFocusTrapOptions) => {
   const previousActiveElement = useRef<HTMLElement | null>(null);
 
@@ -87,10 +89,26 @@ export const useFocusTrap = ({
     previousActiveElement.current = document.activeElement as HTMLElement;
 
     // Focus the specified initial element or the first focusable element
-    const focusElement = initialFocusRef?.current || getFocusableElements()[0];
+    const focusableElements = getFocusableElements();
+    const defaultIndex =
+      skipFirstFocusable && focusableElements.length > 1 ? 1 : 0;
+    const focusElement =
+      initialFocusRef?.current || focusableElements[defaultIndex];
+
+    let requestAnimationFrameId: number | null = null;
+    let setTimeoutId: ReturnType<typeof setTimeout> | undefined;
+
     if (focusElement) {
-      // Use setTimeout to ensure the element is rendered and focusable
-      setTimeout(() => focusElement.focus(), 0);
+      // Use requestAnimationFrame if available, otherwise setTimeout
+      if (typeof requestAnimationFrame === 'function') {
+        requestAnimationFrameId = requestAnimationFrame(() => {
+          focusElement.focus();
+        });
+      } else {
+        setTimeoutId = setTimeout(() => {
+          focusElement.focus();
+        }, 0);
+      }
     }
 
     // Add event listener for keyboard navigation
@@ -98,8 +116,26 @@ export const useFocusTrap = ({
 
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
+      if (
+        typeof requestAnimationFrame === 'function' &&
+        requestAnimationFrameId !== null
+      ) {
+        cancelAnimationFrame(requestAnimationFrameId);
+      }
+      if (
+        typeof requestAnimationFrame !== 'function' &&
+        setTimeoutId !== undefined
+      ) {
+        clearTimeout(setTimeoutId);
+      }
     };
-  }, [isActive, initialFocusRef, getFocusableElements, handleKeyDown]);
+  }, [
+    isActive,
+    initialFocusRef,
+    getFocusableElements,
+    handleKeyDown,
+    skipFirstFocusable,
+  ]);
 
   // Restore focus when trap becomes inactive
   useEffect(() => {

package/lib/index.ts

@@ -2,3 +2,4 @@ export { cx, css } from '@emotion/css';
 export * from './components';
 export * from './theme';
 export * from './hooks';
+export * from './utils';

package/lib/utils/__tests__/announce.test.ts

@@ -0,0 +1,121 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import announce, { __resetForTesting } from '../announce';
+
+describe('announce (ARIA live region)', () => {
+  beforeEach(() => {
+    // Reset DOM before each test
+    document.body.innerHTML = '';
+    __resetForTesting();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test('creates a live region on first announce', async () => {
+    announce('Hello world');
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    expect(region).toBeTruthy();
+    expect(region.getAttribute('aria-live')).toBe('polite');
+    expect(region.getAttribute('aria-atomic')).toBe('true');
+  });
+
+  test('visually hides the live region but keeps it accessible', async () => {
+    announce('Hidden message');
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    expect(region.style.position).toBe('absolute');
+    expect(region.style.left).toBe('-9999px');
+    expect(region.style.width).toBe('1px');
+    expect(region.style.height).toBe('1px');
+    expect(region.style.overflow).toBe('hidden');
+  });
+
+  test('clears text and sets message after timeout', async () => {
+    announce('This is an announcement');
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    await waitFor(() => {
+      expect(region.textContent).toBe('This is an announcement');
+    });
+  });
+
+  test('reuses the same live region on multiple announcements', async () => {
+    announce('First message');
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    expect(region).toBeTruthy();
+
+    announce('Second message');
+
+    // Query all instances
+    const allRegions = await screen.findAllByTestId('aria-live-region');
+
+    expect(allRegions.length).toBe(1);
+  });
+
+  test('queues multiple announcements and processes sequentially', async () => {
+    vi.useFakeTimers();
+
+    announce('First message');
+    announce('Second message');
+
+    // Query the live region
+    const region = document.querySelector(
+      '[data-testid="aria-live-region"]'
+    ) as HTMLElement;
+
+    // Initially empty
+    expect(region.textContent).toBe('');
+
+    // After 100ms, first message appears
+    vi.advanceTimersByTime(100);
+    expect(region.textContent).toBe('First message');
+
+    // Second message should NOT appear yet (need to wait 1000ms + 100ms more)
+    vi.advanceTimersByTime(500);
+    expect(region.textContent).toBe('First message');
+
+    // After remaining 500ms of the 1000ms delay, queue processes but text is cleared
+    vi.advanceTimersByTime(500);
+    expect(region.textContent).toBe('');
+
+    // After another 100ms, second message appears
+    vi.advanceTimersByTime(100);
+    expect(region.textContent).toBe('Second message');
+  });
+
+  test('duplicate prevention while currently announcing', async () => {
+    vi.useFakeTimers();
+
+    announce('Processing');
+    announce('Processing'); // Duplicate - should be ignored
+    announce('Processing'); // Duplicate - should be ignored
+    announce('Done'); // Different message - should be queued
+
+    const region = document.querySelector(
+      '[data-testid="aria-live-region"]'
+    ) as HTMLElement;
+
+    // First message appears
+    vi.advanceTimersByTime(100);
+    expect(region.textContent).toBe('Processing');
+
+    // Complete first message, next should be "Done" (duplicates were ignored)
+    vi.advanceTimersByTime(1000);
+    vi.advanceTimersByTime(100);
+    expect(region.textContent).toBe('Done');
+
+    // No more messages in queue
+    vi.advanceTimersByTime(1000);
+    vi.advanceTimersByTime(100);
+    // Still "Done" - nothing else was queued
+    expect(region.textContent).toBe('Done');
+  });
+});

package/lib/utils/announce.ts

@@ -0,0 +1,134 @@
+/**
+ * Sends a message to screen readers using an ARIA live region.
+ *
+ * Automatically initializes a hidden live region the first time it is used.
+ * This allows screen readers (NVDA, JAWS, VoiceOver) to announce dynamic
+ * updates such as "Item removed", "Saved", etc.
+ *
+ * The live region is visually hidden but remains accessible.
+ *
+ * @param message - The message to announce to screen readers.
+ *
+ * @param force - If true, forces the announcement even if it's the same as the last one.
+ *
+ * @example
+ * announce("Item removed");
+ *
+ * @example
+ * announce("Form submitted successfully");
+ */
+let liveRegion: HTMLDivElement | null = null;
+let announcementQueue: string[] = [];
+let isAnnouncing = false;
+let lastAnnouncement = '';
+
+const SR_DETECTION_DELAY = 100; // Time for SR to detect change
+const SR_PROCESSING_DELAY = 1000; // Time for SR to finish announcement
+
+/**
+ * Creates the live region if it does not already exist.
+ */
+const initLiveRegion = (): void => {
+  if (typeof document === 'undefined' || liveRegion) return;
+
+  // Guard: body may not exist yet (e.g., script in <head>)
+  const container = document.body || document.documentElement;
+  if (!container) return;
+
+  const region = document.createElement('div');
+  region.setAttribute('aria-live', 'polite');
+  region.setAttribute('aria-atomic', 'true');
+  region.setAttribute('role', 'status');
+  region.setAttribute('data-testid', 'aria-live-region');
+
+  // Visually hide but keep accessible
+  region.style.position = 'absolute';
+  region.style.left = '-9999px';
+  region.style.width = '1px';
+  region.style.height = '1px';
+  region.style.overflow = 'hidden';
+
+  document.body.appendChild(region);
+  liveRegion = region;
+};
+
+/**
+ * Processes the announcement queue sequentially.
+ */
+const processQueue = (): void => {
+  if (isAnnouncing || announcementQueue.length === 0) return;
+
+  if (!liveRegion) {
+    // If no live region, do not drop the message or update lastAnnouncement
+    return;
+  }
+
+  // Only shift and update lastAnnouncement if liveRegion exists
+  const message = announcementQueue.shift()!;
+  lastAnnouncement = message;
+  isAnnouncing = true;
+  // Clear previous message to force announcement
+  liveRegion.textContent = '';
+
+  // brief delay ensures SRs detect the change
+  setTimeout(() => {
+    if (liveRegion) {
+      liveRegion.textContent = message;
+    }
+
+    // Wait for screen reader to process, then announce next
+    setTimeout(() => {
+      isAnnouncing = false;
+      processQueue();
+    }, SR_PROCESSING_DELAY);
+  }, SR_DETECTION_DELAY);
+};
+
+/**
+ * Announces a message to screen readers.
+ */
+const announce = (message: string, force = false): void => {
+  // SSR guard: do nothing if document is unavailable
+  if (typeof document === 'undefined') return;
+
+  // Initialize live region on first use
+  if (!liveRegion) initLiveRegion();
+
+  // If forcing, clear the queue to prevent old messages
+  if (force) {
+    announcementQueue.length = 0;
+  }
+
+  // Skip if the same message was just announced or is already queued
+  if (
+    !force &&
+    message === lastAnnouncement &&
+    announcementQueue.length === 0
+  ) {
+    return;
+  }
+
+  // Prevent adding duplicate messages to the queue (including if currently announcing)
+  if (
+    announcementQueue.includes(message) ||
+    (isAnnouncing && lastAnnouncement === message)
+  ) {
+    return;
+  }
+
+  announcementQueue.push(message);
+  processQueue();
+};
+
+// Export for testing purposes
+export const __resetForTesting = (): void => {
+  if (liveRegion && liveRegion.parentNode) {
+    liveRegion.parentNode.removeChild(liveRegion);
+  }
+  liveRegion = null;
+  announcementQueue = [];
+  isAnnouncing = false;
+  lastAnnouncement = '';
+};
+
+export default announce;

package/lib/utils/index.ts

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

package/package.json

@@ -2,7 +2,7 @@
   "name": "uikit-react-public",
   "private": false,
   "license": "UNLICENSED",
-  "version": "0.14.21",
+  "version": "0.17.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,9 +10,6 @@
     "dist",
     "lib"
   ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
   "scripts": {
     "dev": "vite",
     "dev_expose": "vite --host",
@@ -45,8 +42,8 @@
     "@floating-ui/react-dom": "^2.1.2"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@azure/msal-browser": "^4.7.0",

package/dist/components/Datepicker/subcomponents/NativeDatepicker.d.ts

@@ -1,6 +0,0 @@
-interface NativeDatepickerProps extends React.InputHTMLAttributes<HTMLInputElement> {
-    testId?: string;
-    ref?: React.RefObject<HTMLInputElement>;
-}
-declare const NativeDatepicker: ({ value, onChange, min, max, className, disabled, testId, ref, ...props }: NativeDatepickerProps) => import("react/jsx-runtime").JSX.Element;
-export default NativeDatepicker;