uikit-react-public 0.30.0 → 0.30.1

package/dist/utils/announce.d.ts

@@ -1,6 +1,7 @@
 /**
  * Announces a message to screen readers.
+ *
  */
-declare const announce: (message: string, force?: boolean) => void;
+declare const announce: (message: string, force?: boolean, container?: HTMLElement | null) => void;
 export declare const __resetForTesting: () => void;
 export default announce;

package/lib/components/Dialog/BaseDialog.tsx

@@ -5,6 +5,7 @@ import React, {
   useEffect,
   useRef,
   useContext,
+  forwardRef,
 } from 'react';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
@@ -33,182 +34,200 @@ export interface BaseDialogProps extends HTMLAttributes<HTMLDialogElement> {
   testId?: string;
 }
 
-const BaseDialog = ({
-  open = false,
-  size = 'medium',
-  modal = true,
-  closeOnClickOutside = true,
-  closeOnClickOutsideStopPropagation = true,
-  nonModalCloseOnEscape = false,
-  onClose,
-  className,
-  children,
-  initialFocusRef,
-  finalFocusRef,
-  disableFocusTrap = false,
-  restoreFocus = true,
-  skipCloseOnInitialFocus = false,
-  testId = NAME,
-  ...props
-}: BaseDialogProps) => {
-  const width = {
-    small: SMALL_WIDTH,
-    medium: MEDIUM_WIDTH,
-    large: LARGE_WIDTH,
-  }[size];
-
-  const [theme] = useTheme();
-
-  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;
-  `;
-
-  useEffect(() => {
-    if (open && modal) {
-      document.body.classList.add(hideBodyScroll);
-    } else {
-      document.body.classList.remove(hideBodyScroll);
-    }
-    return () => {
-      document.body.classList.remove(hideBodyScroll);
-    };
-  }, [open, modal, hideBodyScroll]);
-
-  useEffect(() => {
-    const dialogElement = dialogRef.current;
-
-    if (!dialogElement) return;
+const BaseDialog = forwardRef<HTMLDialogElement, BaseDialogProps>(
+  function BaseDialog(
+    {
+      open = false,
+      size = 'medium',
+      modal = true,
+      closeOnClickOutside = true,
+      closeOnClickOutsideStopPropagation = true,
+      nonModalCloseOnEscape = false,
+      onClose,
+      className,
+      children,
+      initialFocusRef,
+      finalFocusRef,
+      disableFocusTrap = false,
+      restoreFocus = true,
+      skipCloseOnInitialFocus = false,
+      testId = NAME,
+      ...props
+    }: BaseDialogProps,
+    ref
+  ) {
+    const width = {
+      small: SMALL_WIDTH,
+      medium: MEDIUM_WIDTH,
+      large: LARGE_WIDTH,
+    }[size];
+
+    const [theme] = useTheme();
+
+    const dialogRef = useRef<HTMLDialogElement>(null);
+    const previousActiveElement = useRef<HTMLElement | null>(null);
+
+    const setDialogRef = useCallback(
+      (node: HTMLDialogElement | null) => {
+        dialogRef.current = node;
+
+        if (typeof ref === 'function') {
+          ref(node);
+        } else if (ref) {
+          ref.current = node;
+        }
+      },
+      [ref]
+    );
 
-    if (open && !dialogElement.hasAttribute('open')) {
-      previousActiveElement.current = document.activeElement as HTMLElement;
-      if (modal) {
-        dialogElement.showModal();
+    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;
+    `;
+
+    useEffect(() => {
+      if (open && modal) {
+        document.body.classList.add(hideBodyScroll);
       } else {
-        dialogElement.show();
-      }
-    } else if (!open && dialogElement.hasAttribute('open')) {
-      dialogElement.close();
-      // 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();
+        document.body.classList.remove(hideBodyScroll);
       }
-    }
-  }, [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);
+      return () => {
+        document.body.classList.remove(hideBodyScroll);
+      };
+    }, [open, modal, hideBodyScroll]);
+
+    useEffect(() => {
+      const dialogElement = dialogRef.current;
+
+      if (!dialogElement) return;
+
+      if (open && !dialogElement.hasAttribute('open')) {
+        previousActiveElement.current = document.activeElement as HTMLElement;
+        if (modal) {
+          dialogElement.showModal();
+        } else {
+          dialogElement.show();
+        }
+      } else if (!open && dialogElement.hasAttribute('open')) {
+        dialogElement.close();
+        // 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, disableFocusTrap, restoreFocus]);
 
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [open, modal, nonModalCloseOnEscape, onClose]);
+    // Handle Escape key to close dialog
+    useEffect(() => {
+      if (!open || modal || !nonModalCloseOnEscape) return;
 
-  const handleClick = useCallback(
-    (ev: React.MouseEvent<HTMLDialogElement>) => {
-      if (closeOnClickOutside && onClose && dialogRef.current) {
-        if (closeOnClickOutsideStopPropagation) {
-          ev.stopPropagation();
+      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>) => {
+        if (closeOnClickOutside && onClose && dialogRef.current) {
+          if (closeOnClickOutsideStopPropagation) {
+            ev.stopPropagation();
+          }
+          const rect = dialogRef.current.getBoundingClientRect();
+          const isInDialog =
+            rect.top <= ev.clientY &&
+            ev.clientY <= rect.top + rect.height &&
+            rect.left <= ev.clientX &&
+            ev.clientX <= rect.left + rect.width;
+          if (!isInDialog) {
+            onClose(ev);
+          }
         }
-        const rect = dialogRef.current.getBoundingClientRect();
-        const isInDialog =
-          rect.top <= ev.clientY &&
-          ev.clientY <= rect.top + rect.height &&
-          rect.left <= ev.clientX &&
-          ev.clientX <= rect.left + rect.width;
-        if (!isInDialog) {
+      },
+      [closeOnClickOutside, closeOnClickOutsideStopPropagation, onClose]
+    );
+
+    const handleDialogClose = useCallback(
+      (ev: React.MouseEvent<HTMLDialogElement>) => {
+        if (onClose) {
           onClose(ev);
         }
-      }
-    },
-    [closeOnClickOutside, closeOnClickOutsideStopPropagation, onClose]
-  );
-
-  const handleDialogClose = useCallback(
-    (ev: React.MouseEvent<HTMLDialogElement>) => {
-      if (onClose) {
-        onClose(ev);
-      }
-    },
-    [onClose]
-  );
-
-  const baseStyle = css`
-    padding: 0;
-    border: none;
-    background: ${theme.color.neutral.white};
-    color: ${theme.color.text.primary};
-    font-family: ${theme.font.family.primary};
-    font-size: ${theme.font.size.f16};
-    width: 100vw;
-    height: 100vh;
-    margin: auto;
-
-    &:modal {
-      max-width: none;
-      max-height: none;
-    }
+      },
+      [onClose]
+    );
 
-    @media (min-width: ${theme.breakpoints.tablet}px) {
-      width: ${width}px;
-      max-width: calc(100vw - ${theme.margin.m16});
-      height: fit-content;
+    const baseStyle = css`
+      padding: 0;
+      border: none;
+      background: ${theme.color.neutral.white};
+      color: ${theme.color.text.primary};
+      font-family: ${theme.font.family.primary};
+      font-size: ${theme.font.size.f16};
+      width: 100vw;
+      height: 100vh;
+      margin: auto;
 
       &:modal {
-        max-width: min(${width}px, calc(100vw - ${theme.margin.m16}));
-        max-height: calc(100vh - 32px);
+        max-width: none;
+        max-height: none;
       }
-    }
 
-    &::backdrop {
-      background-color: ${theme.color.overlay.blanket};
+      @media (min-width: ${theme.breakpoints.tablet}px) {
+        width: ${width}px;
+        max-width: calc(100vw - ${theme.margin.m16});
+        height: fit-content;
+
+        &:modal {
+          max-width: min(${width}px, calc(100vw - ${theme.margin.m16}));
+          max-height: calc(100vh - 32px);
+        }
+      }
+
+      &::backdrop {
+        background-color: ${theme.color.overlay.blanket};
+      }
+    `;
+
+    const style = cx(NAME, baseStyle, className);
+
+    if (open) {
+      return (
+        <dialog
+          ref={setDialogRef}
+          className={style}
+          data-testid={testId}
+          onClick={handleClick}
+          onClose={handleDialogClose}
+          aria-modal={modal ? 'true' : 'false'}
+          aria-labelledby={dialogHeaderId}
+          aria-describedby={dialogBodyId}
+          {...props}
+        >
+          {children}
+        </dialog>
+      );
+    } else {
+      return null;
     }
-  `;
-
-  const style = cx(NAME, baseStyle, className);
-
-  if (open) {
-    return (
-      <dialog
-        ref={dialogRef}
-        className={style}
-        data-testid={testId}
-        onClick={handleClick}
-        onClose={handleDialogClose}
-        aria-modal={modal ? 'true' : 'false'}
-        aria-labelledby={dialogHeaderId}
-        aria-describedby={dialogBodyId}
-        {...props}
-      >
-        {children}
-      </dialog>
-    );
-  } else {
-    return null;
   }
-};
+);
 
 export default memo(BaseDialog);

package/lib/components/Dialog/Dialog.tsx

@@ -1,4 +1,4 @@
-import { createContext, useId } from 'react';
+import { createContext, forwardRef, useId } from 'react';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
 import BaseDialog, { BaseDialogProps } from './BaseDialog';
@@ -23,15 +23,18 @@ export interface DialogProps extends BaseDialogProps {
   onSecondaryAction?: () => void;
 }
 
-const Dialog = ({
-  onClose,
-  onAction,
-  onSecondaryAction,
-  testId = NAME,
-  className,
-  children,
-  ...props
-}: DialogProps) => {
+const Dialog = forwardRef<HTMLDialogElement, DialogProps>(function Dialog(
+  {
+    onClose,
+    onAction,
+    onSecondaryAction,
+    testId = NAME,
+    className,
+    children,
+    ...props
+  }: DialogProps,
+  ref
+) {
   const [theme] = useTheme();
   const dialogHeaderId = useId();
   const dialogBodyId = useId();
@@ -53,6 +56,7 @@ const Dialog = ({
   return (
     <DialogContext value={contextValue}>
       <BaseDialog
+        ref={ref}
         onClose={onClose}
         testId={testId}
         className={style}
@@ -63,7 +67,7 @@ const Dialog = ({
       </BaseDialog>
     </DialogContext>
   );
-};
+});
 
 export interface DialogSubComponents {
   Header: typeof DialogHeader;

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

@@ -60,6 +60,59 @@ describe('announce (ARIA live region)', () => {
     expect(allRegions.length).toBe(1);
   });
 
+  test('appends the live region to the provided container', async () => {
+    const container = document.createElement('section');
+    container.setAttribute('data-testid', 'announce-container');
+    document.body.appendChild(container);
+
+    announce('Container message', false, container);
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    expect(container.contains(region)).toBe(true);
+    expect(document.body.contains(region)).toBe(true);
+  });
+
+  test('falls back to document.body when no container is provided', async () => {
+    announce('Default container message');
+
+    const region = await screen.findByTestId('aria-live-region');
+
+    expect(region.parentElement).toBe(document.body);
+  });
+
+  test('moves live region when a new container is provided later', async () => {
+    const firstContainer = document.createElement('div');
+    const secondContainer = document.createElement('div');
+    document.body.appendChild(firstContainer);
+    document.body.appendChild(secondContainer);
+
+    announce('First container message', false, firstContainer);
+
+    const region = await screen.findByTestId('aria-live-region');
+    expect(firstContainer.contains(region)).toBe(true);
+
+    announce('Second container message', false, secondContainer);
+
+    expect(firstContainer.contains(region)).toBe(false);
+    expect(secondContainer.contains(region)).toBe(true);
+  });
+
+  test('recreates live region when previous one was removed from the DOM', async () => {
+    announce('Initial message');
+
+    const initialRegion = await screen.findByTestId('aria-live-region');
+    initialRegion.remove();
+
+    expect(screen.queryByTestId('aria-live-region')).toBeNull();
+
+    announce('Message after removal');
+
+    const recreatedRegion = await screen.findByTestId('aria-live-region');
+    expect(recreatedRegion).not.toBe(initialRegion);
+    expect(recreatedRegion.parentElement).toBe(document.body);
+  });
+
   test('queues multiple announcements and processes sequentially', async () => {
     vi.useFakeTimers();
 

package/lib/utils/announce.ts

@@ -11,6 +11,10 @@
  *
  * @param force - If true, forces the announcement even if it's the same as the last one.
  *
+ * @param container - Optional element to contain the live region. Accepts `null`
+ * to support passing values like `ref.current`; falls back to `document.body`
+ * when no container is available.
+ *
  * @example
  * announce("Item removed");
  *
@@ -26,14 +30,28 @@ 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.
+ * Creates the live region if it does not already exist, or moves it to a new
+ * container if one is provided. If the existing region has been removed from
+ * the DOM (e.g. a dialog unmounted), it will be recreated.
  */
-const initLiveRegion = (): void => {
-  if (typeof document === 'undefined' || liveRegion) return;
+const initLiveRegion = (container?: HTMLElement | null): void => {
+  if (typeof document === 'undefined') return;
 
-  // Guard: body may not exist yet (e.g., script in <head>)
-  const container = document.body || document.documentElement;
-  if (!container) return;
+  // Reset if existing region has been removed from the DOM
+  if (liveRegion && !document.contains(liveRegion)) {
+    liveRegion = null;
+  }
+
+  const target = container || document.body || document.documentElement;
+  if (!target) return;
+
+  // If a specific container is requested and the region is elsewhere, move it
+  if (liveRegion && container && liveRegion.parentNode !== container) {
+    container.appendChild(liveRegion);
+    return;
+  }
+
+  if (liveRegion) return;
 
   const region = document.createElement('div');
   region.setAttribute('aria-live', 'polite');
@@ -48,7 +66,7 @@ const initLiveRegion = (): void => {
   region.style.height = '1px';
   region.style.overflow = 'hidden';
 
-  document.body.appendChild(region);
+  target.appendChild(region);
   liveRegion = region;
 };
 
@@ -86,13 +104,18 @@ const processQueue = (): void => {
 
 /**
  * Announces a message to screen readers.
+ *
  */
-const announce = (message: string, force = false): void => {
+const announce = (
+  message: string,
+  force = false,
+  container?: HTMLElement | null
+): void => {
   // SSR guard: do nothing if document is unavailable
   if (typeof document === 'undefined') return;
 
-  // Initialize live region on first use
-  if (!liveRegion) initLiveRegion();
+  // Ensure live region exists and is attached to the requested container when provided
+  initLiveRegion(container);
 
   // If forcing, clear the queue to prevent old messages
   if (force) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "uikit-react-public",
   "private": false,
   "license": "UNLICENSED",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",