uikit-react-public 0.30.0 → 0.32.3

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/components/Dropdown/Dropdown.stories.tsx

@@ -8,7 +8,6 @@ import IconButton from '../IconButton';
 import LabelledCheckbox from '../Checkbox/LabelledCheckbox';
 import useTheme from '../../theme/useTheme';
 import useMediaQuery from '../../hooks/useMediaQuery';
-import { ThemeContextProvider, lightTheme } from '../../theme';
 
 const meta = {
   title: 'Components/Dropdown',
@@ -74,55 +73,53 @@ export const HeaderResponsiveTrigger: Story = {
     `;
 
     return (
-      <ThemeContextProvider initialTheme={lightTheme}>
-        <div className={containerStyle}>
-          <HeaderNew title='Name of the application'>
-            <HeaderNew.MenuContainer>
-              <Dropdown {...args}>
-                <Dropdown.Trigger>
-                  {isDesktop ? (
-                    <Button
-                      variant='primary-subtle'
-                      size='small'
-                      icon={<Icon.Menu size={20} />}
-                      aria-label='Menu'
-                    >
-                      Menu
-                    </Button>
-                  ) : (
-                    <IconButton
-                      className={iconButtonStyle}
-                      aria-label='Menu'
-                    >
-                      <Icon.Menu size={20} />
-                    </IconButton>
-                  )}
-                </Dropdown.Trigger>
-                <Dropdown.Content className={menuStyle}>
-                  <button
-                    type='button'
-                    className={menuItemStyle}
+      <div className={containerStyle}>
+        <HeaderNew title='Name of the application'>
+          <HeaderNew.MenuContainer>
+            <Dropdown {...args}>
+              <Dropdown.Trigger>
+                {isDesktop ? (
+                  <Button
+                    variant='primary-subtle'
+                    size='small'
+                    icon={<Icon.Menu size={20} />}
+                    aria-label='Menu'
                   >
-                    View profile
-                  </button>
-                  <button
-                    type='button'
-                    className={menuItemStyle}
+                    Menu
+                  </Button>
+                ) : (
+                  <IconButton
+                    className={iconButtonStyle}
+                    aria-label='Menu'
                   >
-                    Team settings
-                  </button>
-                  <button
-                    type='button'
-                    className={menuItemStyle}
-                  >
-                    Sign out
-                  </button>
-                </Dropdown.Content>
-              </Dropdown>
-            </HeaderNew.MenuContainer>
-          </HeaderNew>
-        </div>
-      </ThemeContextProvider>
+                    <Icon.Menu size={20} />
+                  </IconButton>
+                )}
+              </Dropdown.Trigger>
+              <Dropdown.Content className={menuStyle}>
+                <button
+                  type='button'
+                  className={menuItemStyle}
+                >
+                  View profile
+                </button>
+                <button
+                  type='button'
+                  className={menuItemStyle}
+                >
+                  Team settings
+                </button>
+                <button
+                  type='button'
+                  className={menuItemStyle}
+                >
+                  Sign out
+                </button>
+              </Dropdown.Content>
+            </Dropdown>
+          </HeaderNew.MenuContainer>
+        </HeaderNew>
+      </div>
     );
   },
 };
@@ -152,33 +149,31 @@ export const StandaloneInfoPanel: Story = {
     `;
 
     return (
-      <ThemeContextProvider initialTheme={lightTheme}>
-        <div className={containerStyle}>
-          <Dropdown {...args}>
-            <Dropdown.Trigger>
-              <Button
-                variant='secondary'
-                size='small'
-                icon={<Icon.Info size={20} />}
-              >
-                Notification preferences
-              </Button>
-            </Dropdown.Trigger>
-            <Dropdown.Content
-              className={infoContentStyle}
-              align='left'
+      <div className={containerStyle}>
+        <Dropdown {...args}>
+          <Dropdown.Trigger>
+            <Button
+              variant='secondary'
+              size='small'
+              icon={<Icon.Info size={20} />}
             >
-              <p className={infoTitleStyle}>Weekly update</p>
-              <p className={infoBodyStyle}>
-                Get a summary of new activity in your workspace every Friday.
-              </p>
-              <LabelledCheckbox id='storybook-weekly-update-checkbox'>
-                Email me the weekly summary
-              </LabelledCheckbox>
-            </Dropdown.Content>
-          </Dropdown>
-        </div>
-      </ThemeContextProvider>
+              Notification preferences
+            </Button>
+          </Dropdown.Trigger>
+          <Dropdown.Content
+            className={infoContentStyle}
+            align='left'
+          >
+            <p className={infoTitleStyle}>Weekly update</p>
+            <p className={infoBodyStyle}>
+              Get a summary of new activity in your workspace every Friday.
+            </p>
+            <LabelledCheckbox id='storybook-weekly-update-checkbox'>
+              Email me the weekly summary
+            </LabelledCheckbox>
+          </Dropdown.Content>
+        </Dropdown>
+      </div>
     );
   },
 };

package/lib/components/Heading/Documentation.mdx

@@ -15,8 +15,7 @@ export const usage = {
   level2: `<Heading level={2}>Level 2 Heading</Heading>`,
   level3: `<Heading level={3}>Level 3 Heading</Heading>`,
   level4: `<Heading level={4}>Level 4 Heading</Heading>`,
-  withMargins: `<Heading margins={true} >Heading with margins</Heading>`,
-  noMargins: `<Heading margins={false} >Heading with no margins</Heading>`,
+  withMargins: `<Heading mb="24">Heading with bottom margin</Heading>`,
 };
 
 <Meta of={HeadingStories} />
@@ -52,7 +51,8 @@ All screens in UCL Experience apps should have a sensible semantic hierarchy. Th
 ### Props
 
 - `level`: A **number** from 1 to 4, corresponding to the level of the HTML heading element to be rendered. Default is 1, if otherwise unspecified.
-- `margins`: A **boolean** value. If `false`, the heading will have no margins. Default is `true`.
+- `m`, `mv`, `mh`, `mt`, `mb`, `ml`, `mr`: common margin props for applying theme spacing.
+- `margins`: Deprecated. If `false`, the heading will have no margins.
 - `testid`: A **string** value. If provided, the heading element will have a `data-testid` attribute with this value. The <a href="https://www.educative.io/answers/what-is-the-data-testid-attribute-in-testing" target="_blank">`data-testid` attribute</a> is used for identifying this element for testing. If unspecified, `ucl-uikit-heading` is used.
 
 Pass the text you want in the heading as children: `<Heading>My heading text</Heading>`.
@@ -99,20 +99,10 @@ Custom CSS styling can be added as with all UIKit-React components by passing an
 
 Red lines are added to the examples below to show the margins of the heading element.
 
-Note that `margins={true}` in the below example merely specifies explicitly the default behaviour.
-
 <Canvas
-  of={HeadingStories.Margins}
+  of={HeadingStories.withMargins}
   sourceState='shown'
   source={{
     code: usage.withMargins,
   }}
 />
-
-<Canvas
-  of={HeadingStories.NoMargins}
-  sourceState='shown'
-  source={{
-    code: usage.noMargins,
-  }}
-/>