uikit-react-public 0.30.0 → 0.32.3

package/lib/components/Snackbar/Snackbars.stories.tsx

@@ -0,0 +1,130 @@
+import { useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import Button from '../Button/Button';
+import Snackbars, { type SnackbarsItem } from './Snackbars';
+
+const meta = {
+  title: 'Components/Snackbars',
+  component: Snackbars,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: 'Manages a stack of Snackbar notifications.',
+      },
+    },
+  },
+  argTypes: {
+    items: { control: false },
+    onDismiss: { control: false },
+    duration: { control: { type: 'number' } },
+    transitionDuration: { control: { type: 'number' } },
+    maxVisible: { control: { type: 'number' } },
+    placement: {
+      control: { type: 'select' },
+      options: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
+    },
+  },
+  args: {
+    duration: 0,
+    transitionDuration: 200,
+    maxVisible: 3,
+    placement: 'bottom-right',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Snackbars>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const previewStyle = css`
+  min-height: 360px;
+  padding: 24px;
+`;
+
+export const Interactive: Story = {
+  args: {
+    duration: 5000,
+    items: [],
+    onDismiss: () => undefined,
+  },
+  render: (args) => {
+    const snackbarIdCounterRef = useRef(0);
+    const [items, setItems] = useState<SnackbarsItem[]>([
+      {
+        id: 'initial',
+        children: 'Use the buttons to add more snackbars',
+        duration: 0,
+      },
+    ]);
+
+    const controlsStyle = css`
+      display: flex;
+      flex-wrap: wrap;
+      gap: 12px;
+      padding: 24px;
+    `;
+
+    const getNextSnackbarId = () => {
+      snackbarIdCounterRef.current += 1;
+      return `storybook-snackbar-${snackbarIdCounterRef.current}`;
+    };
+
+    const addSnackbar = (item: Omit<SnackbarsItem, 'id'>) => {
+      setItems((current) => [
+        ...current,
+        {
+          ...item,
+          id: getNextSnackbarId(),
+        },
+      ]);
+    };
+
+    return (
+      <div className={previewStyle}>
+        <div className={controlsStyle}>
+          <Button
+            onClick={() =>
+              addSnackbar({
+                children: `Snackbar ${items.length + 1}`,
+              })
+            }
+          >
+            Add snackbar
+          </Button>
+          <Button
+            onClick={() =>
+              addSnackbar({
+                action: 'undo',
+                children: 'Snackbar with undo',
+                onUndo: () => alert('Undo action triggered'),
+              })
+            }
+          >
+            Add snackbar with undo
+          </Button>
+          <Button
+            onClick={() =>
+              addSnackbar({
+                children: 'Error snackbar',
+                size: 'small',
+                variant: 'error',
+              })
+            }
+          >
+            Add error snackbar
+          </Button>
+        </div>
+        <Snackbars
+          {...args}
+          items={items}
+          onDismiss={(id) =>
+            setItems((current) => current.filter((item) => item.id !== id))
+          }
+        />
+      </div>
+    );
+  },
+};

package/lib/components/Snackbar/Snackbars.tsx

@@ -0,0 +1,377 @@
+import {
+  type HTMLAttributes,
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { css, cx, keyframes } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import Snackbar, { type SnackbarProps } from './Snackbar';
+
+export const NAME = 'ucl-uikit-snackbars';
+
+export type SnackbarsPlacement =
+  'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+const DEFAULT_AUTO_DISMISS_DURATION = 5000;
+
+export interface SnackbarsItem extends SnackbarProps {
+  id: string;
+  duration?: number;
+}
+
+export interface SnackbarsProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children'
+> {
+  items: SnackbarsItem[];
+  onDismiss: (id: string) => void;
+  duration?: number;
+  transitionDuration?: number;
+  maxVisible?: number;
+  placement?: SnackbarsPlacement;
+  testId?: string;
+}
+
+const Snackbars = ({
+  items,
+  onDismiss,
+  duration = DEFAULT_AUTO_DISMISS_DURATION,
+  transitionDuration = 200,
+  maxVisible = 3,
+  placement = 'bottom-right',
+  testId = NAME,
+  className,
+  ...props
+}: SnackbarsProps) => {
+  const [theme] = useTheme();
+  const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
+  const autoDismissTimersRef = useRef<Record<string, number>>({});
+  const autoDismissStartedAtRef = useRef<Record<string, number>>({});
+  const autoDismissRemainingRef = useRef<Record<string, number>>({});
+  const exitTimersRef = useRef<Record<string, number>>({});
+  const dismissRef = useRef(onDismiss);
+  const focusedIdsRef = useRef<Set<string>>(new Set());
+
+  useEffect(() => {
+    dismissRef.current = onDismiss;
+  }, [onDismiss]);
+
+  const visibleItems = useMemo(
+    () => items.slice(0, maxVisible),
+    [items, maxVisible]
+  );
+
+  const visibleItemIds = useMemo(
+    () => new Set(visibleItems.map((item) => item.id)),
+    [visibleItems]
+  );
+
+  const itemIds = useMemo(() => new Set(items.map((item) => item.id)), [items]);
+
+  const clearAutoDismissTimer = useCallback((id: string) => {
+    if (autoDismissTimersRef.current[id] === undefined) return;
+
+    window.clearTimeout(autoDismissTimersRef.current[id]);
+    delete autoDismissTimersRef.current[id];
+    delete autoDismissStartedAtRef.current[id];
+  }, []);
+
+  const beginDismiss = useCallback(
+    (id: string) => {
+      clearAutoDismissTimer(id);
+      delete autoDismissRemainingRef.current[id];
+      focusedIdsRef.current.delete(id);
+
+      setExitingIds((current) => {
+        if (current.has(id)) return current;
+
+        const next = new Set(current);
+        next.add(id);
+        return next;
+      });
+
+      if (exitTimersRef.current[id] !== undefined) return;
+
+      exitTimersRef.current[id] = window.setTimeout(() => {
+        delete exitTimersRef.current[id];
+        setExitingIds((current) => {
+          const next = new Set(current);
+          next.delete(id);
+          return next;
+        });
+        dismissRef.current(id);
+      }, transitionDuration);
+    },
+    [clearAutoDismissTimer, transitionDuration]
+  );
+
+  const startAutoDismissTimer = useCallback(
+    (id: string, timeoutDuration: number) => {
+      autoDismissStartedAtRef.current[id] = Date.now();
+      autoDismissTimersRef.current[id] = window.setTimeout(() => {
+        delete autoDismissTimersRef.current[id];
+        delete autoDismissStartedAtRef.current[id];
+        delete autoDismissRemainingRef.current[id];
+        beginDismiss(id);
+      }, timeoutDuration);
+    },
+    [beginDismiss]
+  );
+
+  const pauseAutoDismiss = useCallback(
+    (id: string) => {
+      if (autoDismissTimersRef.current[id] === undefined) return;
+
+      const startedAt = autoDismissStartedAtRef.current[id];
+      const remainingDuration = autoDismissRemainingRef.current[id];
+
+      if (startedAt !== undefined && remainingDuration !== undefined) {
+        autoDismissRemainingRef.current[id] = Math.max(
+          0,
+          remainingDuration - (Date.now() - startedAt)
+        );
+      }
+
+      clearAutoDismissTimer(id);
+    },
+    [clearAutoDismissTimer]
+  );
+
+  const resumeAutoDismiss = useCallback(
+    (id: string) => {
+      if (focusedIdsRef.current.has(id)) return;
+      if (autoDismissTimersRef.current[id] !== undefined) return;
+
+      const remainingDuration = autoDismissRemainingRef.current[id];
+      if (remainingDuration === undefined) return;
+
+      if (remainingDuration <= 0) {
+        beginDismiss(id);
+        return;
+      }
+
+      startAutoDismissTimer(id, remainingDuration);
+    },
+    [beginDismiss, startAutoDismissTimer]
+  );
+
+  const getAutoDismissDuration = useCallback(
+    (item: SnackbarsItem) => {
+      const itemDuration = item.duration ?? duration;
+
+      if ((item.action ?? 'close') !== 'undo' || itemDuration > 0) {
+        return itemDuration;
+      }
+
+      return duration > 0 ? duration : DEFAULT_AUTO_DISMISS_DURATION;
+    },
+    [duration]
+  );
+
+  useEffect(() => {
+    visibleItems.forEach((item) => {
+      if (exitingIds.has(item.id)) return;
+      if (autoDismissTimersRef.current[item.id] !== undefined) return;
+
+      const itemDuration = getAutoDismissDuration(item);
+      if (itemDuration <= 0) return;
+
+      const remainingDuration =
+        autoDismissRemainingRef.current[item.id] ?? itemDuration;
+      autoDismissRemainingRef.current[item.id] = remainingDuration;
+
+      if (focusedIdsRef.current.has(item.id)) return;
+
+      startAutoDismissTimer(item.id, remainingDuration);
+    });
+  }, [
+    clearAutoDismissTimer,
+    exitingIds,
+    getAutoDismissDuration,
+    startAutoDismissTimer,
+    visibleItems,
+  ]);
+
+  useEffect(() => {
+    setExitingIds((current) => {
+      const next = new Set([...current].filter((id) => visibleItemIds.has(id)));
+      return next.size === current.size ? current : next;
+    });
+
+    Object.entries(exitTimersRef.current).forEach(([id, timerId]) => {
+      if (itemIds.has(id)) return;
+
+      window.clearTimeout(timerId);
+      delete exitTimersRef.current[id];
+    });
+
+    Object.entries(autoDismissTimersRef.current).forEach(([id, timerId]) => {
+      if (visibleItemIds.has(id)) return;
+
+      window.clearTimeout(timerId);
+      delete autoDismissTimersRef.current[id];
+      delete autoDismissStartedAtRef.current[id];
+      delete autoDismissRemainingRef.current[id];
+      focusedIdsRef.current.delete(id);
+    });
+
+    Object.keys(autoDismissRemainingRef.current).forEach((id) => {
+      if (visibleItemIds.has(id)) return;
+
+      delete autoDismissRemainingRef.current[id];
+      focusedIdsRef.current.delete(id);
+    });
+  }, [itemIds, visibleItemIds]);
+
+  useEffect(() => {
+    const autoDismissTimers = autoDismissTimersRef.current;
+    const exitTimers = exitTimersRef.current;
+
+    return () => {
+      Object.values(autoDismissTimers).forEach((timerId) =>
+        window.clearTimeout(timerId)
+      );
+      Object.values(exitTimers).forEach((timerId) =>
+        window.clearTimeout(timerId)
+      );
+    };
+  }, []);
+
+  const isBottomPlacement = placement.startsWith('bottom');
+  const isRightPlacement = placement.endsWith('right');
+  const stackedItems = isBottomPlacement
+    ? [...visibleItems].reverse()
+    : visibleItems;
+
+  const enterAnimation = keyframes`
+    from {
+      opacity: 0;
+      transform: translateY(
+        ${isBottomPlacement ? theme.margin.m8 : `-${theme.margin.m8}`}
+      );
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  `;
+
+  const containerStyle = css`
+    position: fixed;
+    z-index: 9999;
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.margin.m8};
+    pointer-events: none;
+    ${
+      isBottomPlacement
+        ? `bottom: ${theme.margin.m24};`
+        : `top: ${theme.margin.m24};`
+    }
+    right: ${theme.margin.m16};
+    left: ${theme.margin.m16};
+
+    @media (min-width: ${theme.breakpoints.tablet}px) {
+      ${
+        isRightPlacement
+          ? `right: ${theme.margin.m24}; left: auto;`
+          : `right: auto; left: ${theme.margin.m24};`
+      }
+    }
+  `;
+
+  const snackbarStyle = css`
+    position: static;
+    pointer-events: auto;
+    opacity: 1;
+    transform: translateY(0);
+    transition:
+      opacity ${transitionDuration}ms ease,
+      transform ${transitionDuration}ms ease;
+    animation: ${enterAnimation} ${transitionDuration}ms ease;
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+      animation: none;
+    }
+  `;
+
+  const exitingStyle = css`
+    animation: none;
+    opacity: 0;
+    transform: translateY(
+      ${isBottomPlacement ? theme.margin.m8 : `-${theme.margin.m8}`}
+    );
+  `;
+
+  const style = cx(NAME, containerStyle, className);
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      {...props}
+    >
+      {stackedItems.map(({ id, ...item }) => {
+        const itemIsExiting = exitingIds.has(id);
+        delete item.duration;
+
+        return (
+          <Snackbar
+            key={id}
+            action={item.action ?? 'close'}
+            {...item}
+            actionDisabled={item.actionDisabled || itemIsExiting}
+            className={cx(
+              snackbarStyle,
+              itemIsExiting && exitingStyle,
+              item.className
+            )}
+            onClose={() => {
+              if (exitTimersRef.current[id] !== undefined) return;
+
+              item.onClose?.();
+              beginDismiss(id);
+            }}
+            onUndo={() => {
+              if (exitTimersRef.current[id] !== undefined) return;
+
+              item.onUndo?.();
+              beginDismiss(id);
+            }}
+            onFocus={(event) => {
+              item.onFocus?.(event);
+              focusedIdsRef.current.add(id);
+              pauseAutoDismiss(id);
+            }}
+            onBlur={(event) => {
+              item.onBlur?.(event);
+              const nextFocusedElement = event.relatedTarget;
+              if (
+                nextFocusedElement instanceof Node &&
+                event.currentTarget.contains(nextFocusedElement)
+              ) {
+                return;
+              }
+
+              focusedIdsRef.current.delete(id);
+              resumeAutoDismiss(id);
+            }}
+            size={item.size}
+            testId={item.testId ?? `${testId}-${id}`}
+            variant={item.variant}
+          >
+            {item.children}
+          </Snackbar>
+        );
+      })}
+    </div>
+  );
+};
+
+export default memo(Snackbars);

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

@@ -62,6 +62,78 @@ describe('Snackbar', () => {
     expect(customTestId).toBeDefined();
   });
 
+  test('passes ref to the root element', () => {
+    const ref = { current: null as HTMLDivElement | null };
+
+    render(
+      <ThemeContextProvider>
+        <Snackbar ref={ref}>Test snackbar</Snackbar>
+      </ThemeContextProvider>
+    );
+
+    expect(ref.current).toBe(screen.getByTestId('ucl-uikit-snackbar'));
+  });
+
+  test('Default variant uses polite status semantics', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar action='undo'>Test snackbar</Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const snackbar = screen.getByRole('status');
+    expect(snackbar.textContent).toBe('Test snackbar');
+  });
+
+  test('Error variant uses assertive alert semantics', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar
+          action='close'
+          variant='error'
+        >
+          Test snackbar
+        </Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const snackbar = screen.getByRole('alert');
+    expect(snackbar.textContent).toBe('Test snackbar');
+  });
+
+  test('Close button has a default accessible name', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar action='close'>Test snackbar</Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const closeButton = screen.getByRole('button', {
+      name: 'Dismiss notification',
+    });
+
+    expect(closeButton).toBeDefined();
+  });
+
+  test('Close button accessible name can be customised', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar
+          action='close'
+          closeButtonAriaLabel='Dismiss saved notification'
+        >
+          Test snackbar
+        </Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const closeButton = screen.getByRole('button', {
+      name: 'Dismiss saved notification',
+    });
+
+    expect(closeButton).toBeDefined();
+  });
+
   test('Close callback is called', () => {
     const onClose = vi.fn();
     render(
@@ -96,6 +168,38 @@ describe('Snackbar', () => {
     expect(onUndo).toHaveBeenCalled();
   });
 
+  test('Error variant renders warning icon', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar
+          action='close'
+          variant='error'
+        >
+          Test snackbar
+        </Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const [icon] = screen.getAllByTestId('ucl-uikit-icon');
+    const warningIconPath = icon.querySelector('path');
+
+    expect(warningIconPath?.getAttribute('d')).toContain('M10.29 3.86');
+  });
+
+  test('Decorative icons are hidden from assistive technology', () => {
+    render(
+      <ThemeContextProvider>
+        <Snackbar action='close'>Test snackbar</Snackbar>
+      </ThemeContextProvider>
+    );
+
+    const icons = screen.getAllByTestId('ucl-uikit-icon');
+
+    icons.forEach((icon) => {
+      expect(icon.getAttribute('aria-hidden')).toBe('true');
+    });
+  });
+
   test("Close callback cannot be called when action is 'undo'", () => {
     const onClose = vi.fn();
     render(