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

package/src/components/dropdown/Dropdown.tsx

@@ -0,0 +1,186 @@
+import { cloneElement, useMemo, useRef } from 'react';
+
+import classNames from 'classnames';
+
+import { List, ListProps } from '@lumx/react/components/list/List';
+import { Popover, PopoverProps } from '@lumx/react/components/popover/Popover';
+import { useInfiniteScroll } from '@lumx/react/hooks/useInfiniteScroll';
+import { GenericProps, isComponent } from '@lumx/react/utils/type';
+import { getRootClassName } from '@lumx/core/js/utils/className';
+import { Offset, Placement } from '@lumx/react/components/popover/constants';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+/**
+ * Defines the props of the component.
+ */
+export interface DropdownProps extends GenericProps {
+    /**
+     * Reference to the element around which the dropdown is placed.
+     * @see {@link PopoverProps#anchorRef}
+     */
+    anchorRef: PopoverProps['anchorRef'];
+    /** Dropdown content. */
+    children: React.ReactNode;
+    /**
+     * Whether a click anywhere out of the Dropdown would close it or not.
+     * @see {@link PopoverProps#closeOnClickAway}
+     */
+    closeOnClickAway?: boolean;
+    /**
+     * Whether to close the Dropdown when clicking in it or not.
+     */
+    closeOnClick?: boolean;
+    /**
+     * Whether an escape key press would close the Dropdown or not.
+     * @see {@link PopoverProps#closeOnEscape}
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Manage dropdown width:
+     *   - `maxWidth`: dropdown not bigger than anchor
+     *   - `minWidth` or `true`: dropdown not smaller than anchor
+     *   - `width`: dropdown equal to the anchor.
+     * @see {@link PopoverProps#fitToAnchorWidth}
+     */
+    fitToAnchorWidth?: PopoverProps['fitToAnchorWidth'];
+    /**
+     * Whether the dropdown should shrink to fit within the viewport height or not.
+     * @see {@link PopoverProps#fitWithinViewportHeight}
+     */
+    fitWithinViewportHeight?: boolean;
+    /**
+     * Whether the dropdown should be displayed or not. Useful to control the Dropdown from outside the component.
+     * @see {@link PopoverProps#isOpen}
+     */
+    isOpen: boolean;
+    /**
+     * Offset applied to the Dropdown position.
+     * @see {@link PopoverProps#offset}
+     */
+    offset?: Offset;
+    /**
+     * Preferred Dropdown placement against the anchor element.
+     * @see {@link PopoverProps#placement}
+     */
+    placement?: Placement;
+    /** Whether the focus should be set on the list when the dropdown is open or not. */
+    shouldFocusOnOpen?: boolean;
+    /** Whether the dropdown should be rendered into a DOM node that exists outside the DOM hierarchy of the parent component. */
+    usePortal?: boolean;
+    /** Whether the focus should go back on the anchor when dropdown closes and focus is within. */
+    focusAnchorOnClose?: boolean;
+    /**
+     * Z-axis position.
+     * @see {@link PopoverProps#zIndex}
+     */
+    zIndex?: number;
+    /**
+     * On close callback.
+     * @see {@link PopoverProps#onClose}
+     */
+    onClose?(): void;
+    /** On scroll end callback. */
+    onInfiniteScroll?(): void;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Dropdown';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<DropdownProps> = {
+    closeOnClick: true,
+    closeOnClickAway: true,
+    closeOnEscape: true,
+    fitToAnchorWidth: true,
+    fitWithinViewportHeight: true,
+    placement: Placement.BOTTOM_START,
+    shouldFocusOnOpen: true,
+    focusAnchorOnClose: true,
+};
+
+/**
+ * Dropdown component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Dropdown = forwardRef<DropdownProps, HTMLDivElement>((props, ref) => {
+    const {
+        anchorRef,
+        children,
+        className,
+        closeOnClick = DEFAULT_PROPS.closeOnClick,
+        closeOnClickAway = DEFAULT_PROPS.closeOnClickAway,
+        closeOnEscape = DEFAULT_PROPS.closeOnEscape,
+        fitToAnchorWidth = DEFAULT_PROPS.fitToAnchorWidth,
+        fitWithinViewportHeight = DEFAULT_PROPS.fitWithinViewportHeight,
+        isOpen,
+        offset,
+        focusAnchorOnClose = DEFAULT_PROPS.focusAnchorOnClose,
+        onClose,
+        onInfiniteScroll,
+        placement = DEFAULT_PROPS.placement,
+        shouldFocusOnOpen = DEFAULT_PROPS.shouldFocusOnOpen,
+        zIndex,
+        ...forwardedProps
+    } = props;
+    const innerRef = useRef<HTMLDivElement>(null);
+    const listElement = useRef(null);
+
+    useInfiniteScroll(innerRef, onInfiniteScroll);
+
+    const popperElement = useMemo(() => {
+        return !Array.isArray(children) && isComponent(List)(children)
+            ? cloneElement<ListProps>(children, {
+                  ...children.props,
+                  ref: listElement,
+                  onClick(evt: MouseEvent) {
+                      children.props.onClick?.(evt);
+
+                      if (closeOnClick) {
+                          onClose?.();
+                      }
+                  },
+                  isClickable: true,
+              })
+            : children;
+    }, [children, closeOnClick, onClose]);
+
+    return isOpen ? (
+        <Popover
+            ref={ref}
+            {...forwardedProps}
+            focusAnchorOnClose={focusAnchorOnClose}
+            anchorRef={anchorRef}
+            className={classNames(className, CLASSNAME)}
+            elevation={0 as any}
+            closeOnClickAway={closeOnClickAway}
+            closeOnEscape={closeOnEscape}
+            fitToAnchorWidth={fitToAnchorWidth}
+            fitWithinViewportHeight={fitWithinViewportHeight}
+            focusElement={shouldFocusOnOpen ? listElement : undefined}
+            isOpen={isOpen}
+            offset={offset}
+            onClose={onClose}
+            placement={placement}
+            zIndex={zIndex}
+        >
+            <div className={`${CLASSNAME}__menu`} ref={innerRef}>
+                {popperElement}
+            </div>
+        </Popover>
+    ) : null;
+});
+Dropdown.displayName = COMPONENT_NAME;
+Dropdown.className = CLASSNAME;
+Dropdown.defaultProps = DEFAULT_PROPS;

package/src/components/dropdown/index.ts

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

package/src/components/expansion-panel/ExpansionPanel.stories.tsx

@@ -0,0 +1,91 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+import React from 'react';
+
+import { ExpansionPanel, ExpansionPanelProps, Text } from '@lumx/react';
+import { withNestedProps } from '@lumx/react/stories/decorators/withNestedProps';
+
+function useBaseProps({
+    toggleButtonProps = { label: 'Toggle' },
+    isOpen: initiallyOpen,
+    ...args
+}: Partial<ExpansionPanelProps>) {
+    const [isOpen, setOpen] = React.useState(initiallyOpen);
+    return { isOpen, toggleButtonProps, onToggleOpen: setOpen, ...args };
+}
+
+export default {
+    title: 'LumX components/expansion-panel/ExpansionPanel',
+    component: ExpansionPanel,
+    args: {
+        'toggleButtonProps.label': 'Toggle',
+        children: (
+            <Text as="p" typography="body1" color="dark-L2" className="lumx-spacing-padding-big">
+                content
+            </Text>
+        ),
+        label: 'Label',
+    },
+    decorators: [withNestedProps()],
+    render(args: ExpansionPanelProps) {
+        return <ExpansionPanel {...useBaseProps(args)} />;
+    },
+};
+
+/** Minimal expansion panel config */
+export const Default = {};
+
+/** hasBackground variant */
+export const HasBackground = {
+    args: {
+        hasBackground: true,
+    },
+};
+
+/** hasHeaderDivider variant */
+export const HasHeaderDivider = {
+    args: {
+        isOpen: true,
+        hasBackground: true,
+        hasHeaderDivider: true,
+    },
+};
+
+/** Nested expansion panels */
+export const Nested = {
+    args: {},
+    render(args: ExpansionPanelProps) {
+        return (
+            <ExpansionPanel {...useBaseProps(args)}>
+                <ExpansionPanel
+                    label="Child 1"
+                    hasBackground
+                    className="lumx-spacing-margin-left-huge lumx-spacing-margin-bottom-big"
+                    {...useBaseProps(args)}
+                >
+                    <Text as="p" typography="body1" color="dark-L2" className="lumx-spacing-padding-big">
+                        content child 1
+                    </Text>
+                </ExpansionPanel>
+
+                <ExpansionPanel
+                    label="Child 2"
+                    hasBackground
+                    className="lumx-spacing-margin-left-huge lumx-spacing-margin-bottom-big"
+                    {...useBaseProps(args)}
+                >
+                    <Text as="p" typography="body1" color="dark-L2" className="lumx-spacing-padding-big">
+                        content child 2
+                    </Text>
+                </ExpansionPanel>
+            </ExpansionPanel>
+        );
+    },
+};
+
+/** Hide component instead of unmounting it */
+export const HideChildren = {
+    args: {
+        hasBackground: true,
+        closeMode: 'hide',
+    },
+};

package/src/components/expansion-panel/ExpansionPanel.test.tsx

@@ -0,0 +1,185 @@
+import { Mock } from 'vitest';
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+import { queryByRole, render, screen } from '@testing-library/react';
+import { getByClassName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import userEvent from '@testing-library/user-event';
+import { isFocusVisible } from '@lumx/react/utils/browser/isFocusVisible';
+
+import { useBooleanState } from '@lumx/react/hooks/useBooleanState';
+import { ExpansionPanel, ExpansionPanelProps } from '.';
+
+const CLASSNAME = ExpansionPanel.className as string;
+
+vi.mock('@lumx/react/utils/browser/isFocusVisible');
+
+const mockChildrenContent = 'children content';
+
+/** Controlled component that uses a local state to toggle the component */
+const ControlledComponent = (props: ExpansionPanelProps) => {
+    const [isOpen, handleClose, handleOpen] = useBooleanState(false);
+
+    return (
+        <ExpansionPanel isOpen={isOpen} onClose={handleClose} onOpen={handleOpen} {...props}>
+            {mockChildrenContent}
+        </ExpansionPanel>
+    );
+};
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (
+    propsOverride: Partial<ExpansionPanelProps> = {},
+    options: { controlled?: boolean; wrapper?: SetupRenderOptions['wrapper'] } = {},
+) => {
+    const props = {
+        toggleButtonProps: { label: 'Toggle' },
+        children: mockChildrenContent,
+        ...propsOverride,
+    };
+
+    const Component = options.controlled ? ControlledComponent : ExpansionPanel;
+    const { container } = render(<Component {...props} />, { wrapper: options.wrapper });
+
+    return {
+        container,
+        element: getByClassName(container, CLASSNAME),
+        query: {
+            toggleButton: () => queryByRole(container, 'button', { name: /Toggle/i }),
+            header: () => queryByClassName(container, `${CLASSNAME}__header`),
+            content: () => screen.queryByText(mockChildrenContent),
+        },
+        props,
+    };
+};
+
+describe(`<${ExpansionPanel.displayName}>`, () => {
+    (isFocusVisible as Mock).mockReturnValue(false);
+
+    describe('Render', () => {
+        it('should render default', () => {
+            const { element, query } = setup();
+            expect(element).toBeInTheDocument();
+            expect(element).toHaveClass(CLASSNAME);
+            expect(element).toHaveClass(`${CLASSNAME}--is-close`);
+            expect(element).toHaveClass(`${CLASSNAME}--theme-light`);
+
+            // Header is visible
+            expect(query.header()).toBeInTheDocument();
+
+            // Content is not visible
+            expect(query.content()).not.toBeInTheDocument();
+
+            expect(query.toggleButton()).toHaveAttribute('aria-expanded', 'false');
+        });
+
+        it('should render open', () => {
+            const { query } = setup({ isOpen: true });
+
+            // Content is visible
+            expect(query.content()).toBeInTheDocument();
+
+            expect(query.toggleButton()).toHaveAttribute('aria-expanded', 'true');
+        });
+
+        it('should show label', () => {
+            const labelText = 'Label text';
+            const { query } = setup({ label: labelText });
+
+            expect(query.header()).toHaveTextContent(labelText);
+        });
+
+        it('should show header instead of label', () => {
+            const labelText = 'Label text';
+            const headerText = 'Header text';
+            const { query } = setup({ label: labelText, children: <header>{headerText}</header> });
+
+            expect(query.header()).toHaveTextContent(headerText);
+        });
+    });
+
+    describe('Events', () => {
+        const onOpen = vi.fn();
+        const onClose = vi.fn();
+        const onToggleOpen = vi.fn();
+
+        beforeEach(onOpen.mockClear);
+        beforeEach(onClose.mockClear);
+        beforeEach(onToggleOpen.mockClear);
+
+        it('should open on click', async () => {
+            const { query } = setup({ isOpen: false, onOpen, onClose, onToggleOpen });
+
+            // Content is not visible
+            expect(query.content()).not.toBeInTheDocument();
+
+            // Click on toggle button
+            await userEvent.click(query.toggleButton() as any);
+            expect(onOpen).toHaveBeenCalled();
+            expect(onClose).not.toHaveBeenCalled();
+            expect(onToggleOpen).toHaveBeenCalledWith(true, expect.anything());
+        });
+
+        it('should close on click', async () => {
+            const { query } = setup({ isOpen: true, onOpen, onClose, onToggleOpen });
+
+            // Content is visible
+            expect(query.content()).toBeInTheDocument();
+
+            // Click on header
+            await userEvent.click(query.header() as any);
+            expect(onOpen).not.toHaveBeenCalled();
+            expect(onClose).toHaveBeenCalled();
+            expect(onToggleOpen).toHaveBeenCalledWith(false, expect.anything());
+        });
+
+        it('should unmount children after toggling the expansion panel', async () => {
+            const user = userEvent.setup();
+            const { query } = setup({}, { controlled: true });
+
+            // Content is not mounted by default
+            expect(query.content()).not.toBeInTheDocument();
+
+            await user.click(query.header() as any);
+
+            expect(query.content()).toBeInTheDocument();
+
+            await user.click(query.header() as any);
+
+            expect(query.content()).not.toBeInTheDocument();
+        });
+
+        it('should hide children after toggling the expansion panel', async () => {
+            const user = userEvent.setup();
+            const { element, query } = setup({ closeMode: 'hide' }, { controlled: true });
+
+            // Content is hidden (but mounted) by default
+            expect(query.content()).toBeInTheDocument();
+            expect(element).toHaveClass(`${CLASSNAME}--is-close`);
+
+            await user.click(query.header() as any);
+
+            expect(query.content()).toBeInTheDocument();
+            expect(element).toHaveClass(`${CLASSNAME}--is-open`);
+
+            await user.click(query.header() as any);
+
+            expect(query.content()).toBeInTheDocument();
+            expect(element).toHaveClass(`${CLASSNAME}--is-close`);
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'element',
+        forwardAttributes: 'element',
+        forwardRef: 'element',
+        applyTheme: {
+            affects: [{ element: 'element' }],
+            viaProp: true,
+            viaContext: true,
+            defaultTheme: 'light',
+        },
+    });
+});

package/src/components/expansion-panel/ExpansionPanel.tsx

@@ -0,0 +1,195 @@
+import React, { Children, PropsWithChildren, ReactNode, useRef } from 'react';
+
+import classNames from 'classnames';
+
+import { mdiChevronDown, mdiChevronUp } from '@lumx/icons';
+
+import isEmpty from 'lodash/isEmpty';
+
+import { ColorPalette, DragHandle, Emphasis, IconButton, IconButtonProps, Theme } from '@lumx/react';
+import { GenericProps, HasCloseMode, HasTheme, isComponent } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { partitionMulti } from '@lumx/react/utils/partitionMulti';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { IS_BROWSER } from '@lumx/react/constants';
+
+/**
+ * Defines the props of the component.
+ */
+export interface ExpansionPanelProps extends GenericProps, HasCloseMode, HasTheme {
+    /** Whether the expansion panel has a background. */
+    hasBackground?: boolean;
+    /** Whether the header has a divider. */
+    hasHeaderDivider?: boolean;
+    /** Whether the component is open or not. */
+    isOpen?: boolean;
+    /** Label text (overwritten if a `<header>` is provided in the children). */
+    label?: string;
+    /** On open callback. */
+    onOpen?: (event: React.MouseEvent) => void;
+    /** On close callback. */
+    onClose?: (event: React.MouseEvent) => void;
+    /** Props to pass to the toggle button (minus those already set by the ExpansionPanel props). */
+    toggleButtonProps: Pick<IconButtonProps, 'label'> &
+        Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis' | 'color'>;
+    /** On toggle open or close callback. */
+    onToggleOpen?(shouldOpen: boolean, event: React.MouseEvent): void;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'ExpansionPanel';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<ExpansionPanelProps> = {
+    closeMode: 'unmount',
+};
+
+const isDragHandle = isComponent(DragHandle);
+const isHeader = isComponent('header');
+const isFooter = isComponent('footer');
+
+/**
+ * ExpansionPanel component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const ExpansionPanel = forwardRef<ExpansionPanelProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        className,
+        closeMode = DEFAULT_PROPS.closeMode,
+        children: anyChildren,
+        hasBackground,
+        hasHeaderDivider,
+        isOpen,
+        label,
+        onClose,
+        onOpen,
+        onToggleOpen,
+        theme = defaultTheme,
+        toggleButtonProps,
+        ...forwardedProps
+    } = props;
+
+    const children: ReactNode[] = Children.toArray(anyChildren);
+
+    // Partition children by types.
+    const [[dragHandle], [header], [footer], content] = partitionMulti(children, [isDragHandle, isHeader, isFooter]);
+
+    // Either take the header in children or create one with the label.
+    const headerProps: PropsWithChildren<any> = React.isValidElement(header) ? header.props : {};
+    const headerContent = !isEmpty(headerProps.children) ? (
+        headerProps.children
+    ) : (
+        <span className={`${CLASSNAME}__label`}>{label}</span>
+    );
+
+    const toggleOpen = (event: React.MouseEvent) => {
+        const shouldOpen = !isOpen;
+
+        if (onOpen && shouldOpen) {
+            onOpen(event);
+        }
+        if (onClose && !shouldOpen) {
+            onClose(event);
+        }
+        if (onToggleOpen) {
+            onToggleOpen(shouldOpen, event);
+        }
+    };
+
+    const color = theme === Theme.dark ? ColorPalette.light : ColorPalette.dark;
+
+    const rootClassName = classNames(
+        className,
+        handleBasicClasses({
+            hasBackground,
+            hasHeader: Boolean(!isEmpty(headerProps.children)),
+            hasHeaderDivider,
+            isClose: !isOpen,
+            isDraggable: Boolean(dragHandle),
+            isOpen,
+            prefix: CLASSNAME,
+            theme,
+        }),
+    );
+
+    const wrapperRef = useRef<HTMLDivElement>(null);
+
+    // Children stay visible while the open/close transition is running
+    const [isChildrenVisible, setChildrenVisible] = React.useState(isOpen);
+
+    const isOpenRef = React.useRef(isOpen);
+    React.useEffect(() => {
+        if (isOpen || closeMode === 'hide') {
+            setChildrenVisible(true);
+        } else if (!IS_BROWSER) {
+            // Outside a browser we can't wait for the transition
+            setChildrenVisible(false);
+        }
+        isOpenRef.current = isOpen;
+    }, [closeMode, isOpen]);
+
+    // Change children's visibility on the transition end
+    React.useEffect(() => {
+        const { current: wrapper } = wrapperRef;
+        if (!IS_BROWSER || !wrapper) {
+            return undefined;
+        }
+        const onTransitionEnd = () => {
+            setChildrenVisible(isOpenRef.current || closeMode === 'hide');
+        };
+        wrapper.addEventListener('transitionend', onTransitionEnd);
+        return () => wrapper.removeEventListener('transitionend', onTransitionEnd);
+    }, [closeMode]);
+
+    return (
+        <section ref={ref} {...forwardedProps} className={rootClassName}>
+            {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events,jsx-a11y/no-static-element-interactions */}
+            <header className={`${CLASSNAME}__header`} onClick={toggleOpen}>
+                {dragHandle && <div className={`${CLASSNAME}__header-drag`}>{dragHandle}</div>}
+
+                <div {...headerProps} className={`${CLASSNAME}__header-content`}>
+                    {headerContent}
+                </div>
+
+                <div className={`${CLASSNAME}__header-toggle`}>
+                    <IconButton
+                        {...toggleButtonProps}
+                        color={color}
+                        emphasis={Emphasis.low}
+                        icon={isOpen ? mdiChevronUp : mdiChevronDown}
+                        aria-expanded={isOpen || 'false'}
+                    />
+                </div>
+            </header>
+
+            <div className={`${CLASSNAME}__wrapper`} ref={wrapperRef}>
+                {(isOpen || isChildrenVisible) && (
+                    <div className={`${CLASSNAME}__container`}>
+                        <div className={`${CLASSNAME}__content`}>{content}</div>
+
+                        {footer && <div className={`${CLASSNAME}__footer`}>{footer}</div>}
+                    </div>
+                )}
+            </div>
+        </section>
+    );
+});
+ExpansionPanel.displayName = COMPONENT_NAME;
+ExpansionPanel.className = CLASSNAME;
+ExpansionPanel.defaultProps = DEFAULT_PROPS;

package/src/components/expansion-panel/index.ts

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