@lumx/react 3.20.1-alpha.20 → 3.20.1-alpha.21

package/src/components/popover/constants.ts

@@ -0,0 +1,62 @@
+import { ValueOf } from '@lumx/react/utils/type';
+
+/**
+ * Different possible placements for the popover.
+ */
+export const Placement = {
+    AUTO: 'auto',
+    AUTO_END: 'auto-end',
+    AUTO_START: 'auto-start',
+
+    TOP: 'top',
+    TOP_END: 'top-end',
+    TOP_START: 'top-start',
+
+    RIGHT: 'right',
+    RIGHT_END: 'right-end',
+    RIGHT_START: 'right-start',
+
+    BOTTOM: 'bottom',
+    BOTTOM_END: 'bottom-end',
+    BOTTOM_START: 'bottom-start',
+
+    LEFT: 'left',
+    LEFT_END: 'left-end',
+    LEFT_START: 'left-start',
+} as const;
+export type Placement = ValueOf<typeof Placement>;
+
+/**
+ * Offset of the popover.
+ */
+export interface Offset {
+    /** Offset size along the reference. */
+    along?: number;
+    /** Offset size away from the reference. */
+    away?: number;
+}
+
+/**
+ * Popover elevation index.
+ */
+export type Elevation = 1 | 2 | 3 | 4 | 5;
+
+/**
+ * Popover fit anchor width options.
+ */
+export const FitAnchorWidth = {
+    MAX_WIDTH: 'maxWidth',
+    MIN_WIDTH: 'minWidth',
+    WIDTH: 'width',
+} as const;
+export type FitAnchorWidth = ValueOf<typeof FitAnchorWidth>;
+
+/**
+ * Arrow size (in pixel).
+ */
+export const ARROW_SIZE = 14;
+
+/**
+ * Popover default z-index
+ */
+export const POPOVER_ZINDEX = 9999;

package/src/components/popover/index.ts

@@ -0,0 +1,3 @@
+export * from './Popover';
+export type { Offset, Elevation } from './constants';
+export { Placement } from './constants';

package/src/components/popover/usePopoverStyle.tsx

@@ -0,0 +1,184 @@
+import { useEffect, useMemo, useState } from 'react';
+import memoize from 'lodash/memoize';
+import { detectOverflow } from '@popperjs/core';
+
+import { DOCUMENT, WINDOW } from '@lumx/react/constants';
+import { PopoverProps } from '@lumx/react/components/popover/Popover';
+import { usePopper } from '@lumx/react/hooks/usePopper';
+import { ARROW_SIZE, FitAnchorWidth, Placement } from './constants';
+
+/**
+ * Popper js modifier to fit popover min width to the anchor width.
+ */
+const sameWidth = memoize((anchorWidthOption: FitAnchorWidth) => ({
+    name: 'sameWidth',
+    enabled: true,
+    phase: 'beforeWrite',
+    requires: ['computeStyles'],
+    fn({ state }: any) {
+        // eslint-disable-next-line no-param-reassign
+        state.styles.popper[anchorWidthOption] = `${state.rects.reference.width}px`;
+    },
+    effect({ state }: any) {
+        // eslint-disable-next-line no-param-reassign
+        state.elements.popper.style[anchorWidthOption] = `${state.elements.reference.offsetWidth}px`;
+    },
+}));
+
+/**
+ * Popper js modifier to compute max size of the popover.
+ */
+const maxSize = {
+    name: 'maxSize',
+    enabled: true,
+    phase: 'main',
+    requiresIfExists: ['offset', 'preventOverflow', 'flip'],
+    fn({ state, name, options }: any) {
+        const overflow = detectOverflow(state, options);
+
+        const { y = 0, x = 0 } = state.modifiersData.preventOverflow;
+        const { width, height } = state.rects.popper;
+
+        const [basePlacement] = state.placement.split('-');
+
+        const widthProp = basePlacement === 'left' ? 'left' : 'right';
+        const heightProp = basePlacement === 'top' ? 'top' : 'bottom';
+        // eslint-disable-next-line no-param-reassign
+        state.modifiersData[name] = {
+            width: width - overflow[widthProp] - x,
+            height: height - overflow[heightProp] - y,
+        };
+    },
+};
+
+/**
+ * Popper js modifier to apply the max height.
+ */
+const applyMaxHeight = {
+    name: 'applyMaxHeight',
+    enabled: true,
+    phase: 'beforeWrite',
+    requires: ['maxSize'],
+    fn({ state }: any) {
+        const { height } = state.modifiersData.maxSize;
+        // eslint-disable-next-line no-param-reassign
+        state.elements.popper.style.maxHeight = `${height - ARROW_SIZE}px`;
+    },
+};
+
+type Options = Pick<
+    PopoverProps,
+    | 'offset'
+    | 'hasArrow'
+    | 'fitToAnchorWidth'
+    | 'fitWithinViewportHeight'
+    | 'boundaryRef'
+    | 'anchorRef'
+    | 'placement'
+    | 'style'
+    | 'zIndex'
+>;
+
+interface Output {
+    styles: { arrow?: React.CSSProperties; popover?: React.CSSProperties };
+    attributes: any;
+    isPositioned: boolean;
+    position?: Placement;
+    setArrowElement?: React.Ref<HTMLDivElement>;
+    setPopperElement?: React.Ref<HTMLDivElement>;
+    popperElement: HTMLElement | null;
+}
+
+export function usePopoverStyle({
+    offset,
+    hasArrow,
+    fitToAnchorWidth,
+    fitWithinViewportHeight,
+    boundaryRef,
+    anchorRef,
+    placement,
+    style,
+    zIndex,
+}: Options): Output {
+    const [popperElement, setPopperElement] = useState<null | HTMLElement>(null);
+    const [arrowElement, setArrowElement] = useState<null | HTMLElement>(null);
+
+    const actualOffset: [number, number] = [offset?.along ?? 0, (offset?.away ?? 0) + (hasArrow ? ARROW_SIZE : 0)];
+    const modifiers: any = [
+        {
+            name: 'offset',
+            options: { offset: actualOffset },
+        },
+    ];
+    if (hasArrow && arrowElement) {
+        modifiers.push({
+            name: 'arrow',
+            options: {
+                element: arrowElement,
+                padding: ARROW_SIZE / 2,
+            },
+        });
+    }
+    if (fitToAnchorWidth) {
+        const fitWidth = typeof fitToAnchorWidth === 'string' ? fitToAnchorWidth : FitAnchorWidth.MIN_WIDTH;
+        modifiers.push(sameWidth(fitWidth));
+    }
+    if (fitWithinViewportHeight) {
+        modifiers.push({ ...maxSize, options: { boundary: boundaryRef?.current } }, applyMaxHeight);
+    }
+    if (boundaryRef) {
+        modifiers.push(
+            { name: 'flip', options: { boundary: boundaryRef.current } },
+            { name: 'preventOverflow', options: { boundary: boundaryRef.current } },
+        );
+    }
+
+    const { styles, attributes, state, update } = usePopper(anchorRef.current, popperElement, { placement, modifiers });
+
+    // Auto update popover
+    useEffect(() => {
+        const { current: anchorElement } = anchorRef;
+        if (!update || !popperElement || !anchorElement || !WINDOW?.ResizeObserver) {
+            return undefined;
+        }
+        let running: ReturnType<typeof setTimeout> | undefined;
+        function updateRateLimited() {
+            if (running) return;
+            update?.();
+            running = setTimeout(() => {
+                running = undefined;
+            }, 100);
+        }
+        updateRateLimited();
+
+        // On anchor or popover resize
+        const resizeObserver = new ResizeObserver(updateRateLimited);
+        resizeObserver.observe(anchorElement);
+        resizeObserver.observe(popperElement);
+        return () => {
+            resizeObserver.disconnect();
+        };
+    }, [anchorRef, popperElement, update]);
+
+    const position = state?.placement ?? placement;
+
+    const popoverStyle = useMemo(() => {
+        const newStyles = { ...style, ...styles.popper, zIndex };
+
+        if (fitWithinViewportHeight && !newStyles.maxHeight) {
+            newStyles.maxHeight = WINDOW?.innerHeight || DOCUMENT?.documentElement.clientHeight;
+        }
+
+        return newStyles;
+    }, [style, styles.popper, zIndex, fitWithinViewportHeight]);
+
+    return {
+        styles: { arrow: styles.arrow, popover: popoverStyle },
+        attributes,
+        isPositioned: (state?.rects?.popper?.y ?? -1) >= 0,
+        position,
+        setArrowElement,
+        setPopperElement,
+        popperElement,
+    };
+}

package/src/components/popover/useRestoreFocusOnClose.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { getFirstAndLastFocusable } from '@lumx/react/utils/browser/focus/getFirstAndLastFocusable';
+import { OnBeforeUnmount } from '@lumx/react/utils/react/OnBeforeUnmount';
+import type { PopoverProps } from './Popover';
+
+/**
+ * Provides an unmount sentinel to inject in the popover to detect when it closes and restore the focus to the
+ * anchor if needed.
+ */
+export function useRestoreFocusOnClose(
+    {
+        focusAnchorOnClose,
+        anchorRef,
+        parentElement,
+    }: Pick<PopoverProps, 'focusAnchorOnClose' | 'anchorRef' | 'parentElement'>,
+    popoverElement?: HTMLElement | null,
+) {
+    const onBeforeUnmountRef = React.useRef<(() => void) | undefined>();
+
+    React.useEffect(() => {
+        if (!popoverElement || !focusAnchorOnClose) {
+            onBeforeUnmountRef.current = undefined;
+            return;
+        }
+
+        onBeforeUnmountRef.current = () => {
+            const isFocusWithin = popoverElement?.contains(document.activeElement);
+            if (!isFocusWithin) return;
+
+            // On next render
+            setTimeout(() => {
+                const anchor = anchorRef.current;
+                const elementToFocus =
+                    // Provided parent element
+                    parentElement?.current ||
+                    // Or first focusable element in anchor
+                    (anchor ? getFirstAndLastFocusable(anchor).first : undefined) ||
+                    // Fallback to anchor
+                    anchor;
+
+                elementToFocus?.focus({ preventScroll: true });
+            }, 0);
+        };
+    }, [anchorRef, focusAnchorOnClose, parentElement, popoverElement]);
+
+    return <OnBeforeUnmount callbackRef={onBeforeUnmountRef} />;
+}

package/src/components/popover-dialog/PopoverDialog.stories.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import { useBooleanState } from '@lumx/react/hooks/useBooleanState';
+import { mdiMenuDown } from '@lumx/icons';
+import { PopoverDialog } from '.';
+import { Button, IconButton } from '../button';
+
+export default {
+    title: 'LumX components/popover-dialog/PopoverDialog',
+    component: PopoverDialog,
+    parameters: { chromatic: { disableSnapshot: true } },
+};
+
+/**
+ * Example PopoverDialog using a button as a trigger
+ */
+export const WithButtonTrigger = (props: any) => {
+    const anchorRef = React.useRef(null);
+    const [isOpen, close, open] = useBooleanState(false);
+
+    return (
+        <>
+            <Button ref={anchorRef} onClick={open}>
+                Open popover
+            </Button>
+            <PopoverDialog
+                anchorRef={anchorRef}
+                isOpen={isOpen}
+                onClose={close}
+                placement="bottom"
+                className="lumx-spacing-padding-huge"
+                {...props}
+            >
+                <Button onClick={close}>Close</Button>
+                <Button emphasis="medium">Other button</Button>
+            </PopoverDialog>
+        </>
+    );
+};
+
+/**
+ * Example PopoverDialog using an icon button as a trigger
+ */
+export const WithIconButtonTrigger = ({ children, ...props }: any) => {
+    const anchorRef = React.useRef(null);
+    const [isOpen, close, open] = useBooleanState(false);
+
+    return (
+        <>
+            <IconButton label="Open popover" ref={anchorRef} onClick={open} icon={mdiMenuDown} />
+            <PopoverDialog
+                anchorRef={anchorRef}
+                isOpen={isOpen}
+                onClose={close}
+                placement="bottom"
+                className="lumx-spacing-padding-huge"
+                label="Example popover"
+                {...props}
+            >
+                <Button onClick={close}>Close</Button>
+                {children}
+            </PopoverDialog>
+        </>
+    );
+};

package/src/components/popover-dialog/PopoverDialog.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { Heading, HeadingLevelProvider } from '@lumx/react';
+import { WithButtonTrigger, WithIconButtonTrigger } from './PopoverDialog.stories';
+import { PopoverDialog } from './PopoverDialog';
+
+vi.mock('@lumx/react/utils/browser/isFocusVisible');
+
+describe(`<${PopoverDialog.displayName}>`, () => {
+    it('should open and init focus', async () => {
+        const label = 'Test Label';
+        render(<WithButtonTrigger label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        const dialog = await screen.findByRole('dialog', { name: label });
+
+        // Focused the first button
+        expect(within(dialog).getAllByRole('button')[0]).toHaveFocus();
+    });
+
+    it('should work with aria-label', async () => {
+        const label = 'Test Label';
+        render(<WithButtonTrigger aria-label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        expect(await screen.findByRole('dialog', { name: label })).toBeInTheDocument();
+    });
+
+    it('should trap focus', async () => {
+        const label = 'Test Label';
+        render(<WithButtonTrigger label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        const dialog = await screen.findByRole('dialog', { name: label });
+
+        const dialogButtons = within(dialog).getAllByRole('button');
+
+        // First button should have focus by default on opening
+        expect(dialogButtons[0]).toHaveFocus();
+
+        // Tab to next button
+        await userEvent.tab();
+
+        // Second button should have focus
+        expect(dialogButtons[1]).toHaveFocus();
+
+        // Tab to next button
+        await userEvent.tab();
+
+        // As there is no more button, focus should loop back to first button.
+        expect(dialogButtons[0]).toHaveFocus();
+    });
+
+    it('should close on escape and restore focus to trigger', async () => {
+        const label = 'Test Label';
+        render(<WithButtonTrigger label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        const dialog = await screen.findByRole('dialog', { name: label });
+
+        // Close the popover
+        await userEvent.keyboard('{escape}');
+
+        expect(dialog).not.toBeInTheDocument();
+
+        // Focus restored to the trigger element
+        expect(triggerElement).toHaveFocus();
+    });
+
+    it('should close externally and restore focus to trigger', async () => {
+        const label = 'Test Label';
+        render(<WithButtonTrigger label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        const dialog = await screen.findByRole('dialog', { name: label });
+
+        // Close the popover
+        await userEvent.click(screen.getByRole('button', { name: 'Close' }));
+
+        expect(dialog).not.toBeInTheDocument();
+
+        // Focus restored to the trigger element
+        expect(triggerElement).toHaveFocus();
+    });
+
+    it('should close on escape and restore focus to trigger having a tooltip', async () => {
+        const label = 'Test Label';
+        render(<WithIconButtonTrigger label={label} />);
+
+        // Open popover
+        const triggerElement = screen.getByRole('button', { name: 'Open popover' });
+        await userEvent.click(triggerElement);
+
+        const dialog = await screen.findByRole('dialog', { name: label });
+
+        // Close the popover
+        await userEvent.keyboard('{escape}');
+
+        expect(dialog).not.toBeInTheDocument();
+
+        // Focus restored to the trigger element
+        expect(triggerElement).toHaveFocus();
+    });
+
+    it('should have reset the heading level context', async () => {
+        render(
+            // This level context should not affect headings inside the popover dialog
+
+            <HeadingLevelProvider level={3}>
+                <WithIconButtonTrigger>
+                    {/* Heading inside the popover dialog */}
+                    <Heading>Title</Heading>
+                </WithIconButtonTrigger>
+            </HeadingLevelProvider>,
+        );
+
+        // Open popover
+        await userEvent.click(screen.getByRole('button', { name: 'Open popover' }));
+
+        // Heading inside should use the popover dialog heading level 2
+        expect(screen.getByRole('heading', { name: 'Title', level: 2 })).toBeInTheDocument();
+    });
+});

package/src/components/popover-dialog/PopoverDialog.tsx

@@ -0,0 +1,74 @@
+import classNames from 'classnames';
+
+import { HasAriaLabelOrLabelledBy } from '@lumx/react/utils/type';
+import { getRootClassName } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { HeadingLevelProvider } from '@lumx/react/components/heading';
+import { Popover, PopoverProps } from '../popover/Popover';
+
+/**
+ * PopoverDialog props.
+ * The PopoverDialog has the same props as the Popover but requires an accessible label.
+ */
+export type PopoverDialogProps = PopoverProps & HasAriaLabelOrLabelledBy;
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'PopoverDialog';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<PopoverDialogProps> = {};
+
+/**
+ * PopoverDialog component.
+ * Defines a popover that acts like a dialog
+ * * Has a dialog aria role
+ * * Sets a focus trap within the popover
+ * * Closes on click away and escape.
+ */
+export const PopoverDialog = forwardRef<PopoverDialogProps, HTMLDivElement>((props, ref) => {
+    const {
+        children,
+        isOpen,
+        focusElement,
+        'aria-label': ariaLabel,
+        label = ariaLabel,
+        className,
+        ...forwardedProps
+    } = props;
+
+    return (
+        <Popover
+            {...forwardedProps}
+            ref={ref}
+            className={classNames(className, CLASSNAME)}
+            role="dialog"
+            aria-modal="true"
+            /**
+             * If a label is set, set as aria-label.
+             * If it is undefined, the label can be set using the `aria-label` and `aria-labelledby` props
+             */
+            aria-label={label}
+            isOpen={isOpen}
+            focusElement={focusElement}
+            closeOnClickAway
+            closeOnEscape
+            withFocusTrap
+        >
+            <HeadingLevelProvider level={2}>{children}</HeadingLevelProvider>
+        </Popover>
+    );
+});
+
+PopoverDialog.displayName = COMPONENT_NAME;
+PopoverDialog.className = CLASSNAME;
+PopoverDialog.defaultProps = DEFAULT_PROPS;

package/src/components/popover-dialog/index.tsx

@@ -0,0 +1 @@
+export * from './PopoverDialog';

package/src/components/post-block/PostBlock.test.tsx

@@ -0,0 +1,27 @@
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+import { render } from '@testing-library/react';
+import { queryByClassName } from '@lumx/react/testing/utils/queries';
+import { PostBlock, PostBlockProps } from './PostBlock';
+
+const CLASSNAME = PostBlock.className as string;
+
+const setup = (props: Partial<PostBlockProps> = {}, { wrapper }: SetupRenderOptions = {}) => {
+    render(<PostBlock {...(props as any)} />, { wrapper });
+    const postBlock = queryByClassName(document.body, CLASSNAME);
+    return { props, postBlock };
+};
+
+describe(`<${PostBlock.displayName}>`, () => {
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'postBlock',
+        forwardAttributes: 'postBlock',
+        applyTheme: {
+            affects: [{ element: 'postBlock' }],
+            viaProp: true,
+            viaContext: true,
+            defaultTheme: 'light',
+        },
+    });
+});