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

package/src/components/list/ListItem.test.tsx

@@ -0,0 +1,93 @@
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+import { render, screen } from '@testing-library/react';
+import { getByClassName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import userEvent from '@testing-library/user-event';
+
+import { ListItem, ListItemProps } from './ListItem';
+
+const CLASSNAME = ListItem.className as string;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (props: Partial<ListItemProps> = {}, { wrapper }: SetupRenderOptions = {}) => {
+    render(<ListItem {...(props as any)} />, { wrapper });
+    const listItem = getByClassName(document.body, CLASSNAME);
+    const link = queryByClassName(listItem, `${CLASSNAME}__link`);
+    return { props, listItem, link };
+};
+
+describe(`<${ListItem.displayName}>`, () => {
+    describe('Props', () => {
+        it('should render default', () => {
+            const { listItem, link } = setup({ children: 'Label' });
+            expect(listItem).toBeInTheDocument();
+            expect(link).not.toBeInTheDocument();
+            expect(listItem).toHaveTextContent('Label');
+        });
+
+        it('should render as a button', () => {
+            setup({ children: 'Label', onItemSelected: vi.fn() });
+            expect(screen.getByRole('button', { name: 'Label' })).toBeInTheDocument();
+        });
+
+        it('should render as a link', () => {
+            setup({ children: 'Label', linkProps: { href: '#' } });
+            expect(screen.getByRole('link', { name: 'Label' })).toBeInTheDocument();
+        });
+    });
+
+    describe('Disabled state', () => {
+        it('should render disabled list item button', async () => {
+            const onItemSelected = vi.fn();
+            const { link } = setup({ children: 'Label', isDisabled: true, onItemSelected });
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            // The `renderLink` util removes the onClick handler but `user-event` will also not fire events on disabled elements.
+            if (link) await userEvent.click(link);
+            expect(onItemSelected).not.toHaveBeenCalled();
+        });
+
+        it('should render disabled list item link', async () => {
+            const onItemSelected = vi.fn();
+            const { link } = setup({
+                children: 'Label',
+                isDisabled: true,
+                linkProps: { href: 'https://example.com' },
+                onItemSelected,
+            });
+            expect(link).not.toHaveAttribute('href');
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            if (link) await userEvent.click(link);
+            expect(onItemSelected).not.toHaveBeenCalled();
+        });
+
+        it('should render aria-disabled list item button', async () => {
+            const onItemSelected = vi.fn();
+            const { link } = setup({ children: 'Label', 'aria-disabled': true, onItemSelected });
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            if (link) await userEvent.click(link);
+            expect(onItemSelected).not.toHaveBeenCalled();
+        });
+
+        it('should render aria-disabled list item link', async () => {
+            const onItemSelected = vi.fn();
+            const { link } = setup({
+                children: 'Label',
+                'aria-disabled': true,
+                linkProps: { href: 'https://example.com' },
+                onItemSelected,
+            });
+            expect(link).not.toHaveAttribute('href');
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            if (link) await userEvent.click(link);
+            expect(onItemSelected).not.toHaveBeenCalled();
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'listItem',
+        forwardAttributes: 'listItem',
+    });
+});

package/src/components/list/ListItem.tsx

@@ -0,0 +1,157 @@
+import { ReactNode, Ref, SyntheticEvent, useMemo } from 'react';
+
+import classNames from 'classnames';
+import isEmpty from 'lodash/isEmpty';
+
+import { ListProps, Size } from '@lumx/react';
+import { GenericProps } from '@lumx/react/utils/type';
+import { onEnterPressed, onButtonPressed } from '@lumx/core/js/utils';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { renderLink } from '@lumx/react/utils/react/renderLink';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { useDisableStateProps } from '@lumx/react/utils/disabled/useDisableStateProps';
+import { HasAriaDisabled } from '@lumx/react/utils/type/HasAriaDisabled';
+
+export type ListItemSize = Extract<Size, 'tiny' | 'regular' | 'big' | 'huge'>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface ListItemProps extends GenericProps, HasAriaDisabled {
+    /** A component to be rendered after the content. */
+    after?: ReactNode;
+    /** A component to be rendered before the content. */
+    before?: ReactNode;
+    /** Content. */
+    children: string | ReactNode;
+    /** Whether the list item should be highlighted or not. */
+    isHighlighted?: boolean;
+    /** Whether the component is selected or not. */
+    isSelected?: boolean;
+    /** Whether link/button is disabled or not. */
+    isDisabled?: boolean;
+    /** Reference to the <li> element. */
+    listItemRef?: Ref<HTMLLIElement>;
+    /** Custom react component for the link (can be used to inject react router Link). */
+    linkAs?: 'a' | any;
+    /** Props that will be passed on to the Link */
+    linkProps?: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;
+    /** Reference to the link element. */
+    linkRef?: Ref<HTMLAnchorElement>;
+    /** Size variant. */
+    size?: ListItemSize;
+
+    /** On selected callback. */
+    onItemSelected?(evt: SyntheticEvent): void;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'ListItem';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<ListProps> = {
+    size: Size.regular,
+};
+
+/**
+ * Check if the list item is clickable.
+ * @return `true` if the list item is clickable; `false` otherwise.
+ */
+export function isClickable({ linkProps, onItemSelected }: Partial<ListItemProps>): boolean {
+    return !isEmpty(linkProps?.href) || !!onItemSelected;
+}
+
+/**
+ * ListItem component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const ListItem = forwardRef<ListItemProps, HTMLLIElement>((props, ref) => {
+    const { isAnyDisabled, disabledStateProps, otherProps } = useDisableStateProps(props);
+    const {
+        after,
+        before,
+        children,
+        className,
+        isHighlighted,
+        isSelected,
+        linkAs,
+        linkProps = {},
+        linkRef,
+        onItemSelected,
+        size = DEFAULT_PROPS.size,
+        ...forwardedProps
+    } = otherProps;
+
+    const role = linkAs || linkProps.href ? 'link' : 'button';
+    const onKeyDown = useMemo(() => {
+        if (onItemSelected && role === 'link') return onEnterPressed(onItemSelected as any);
+        if (onItemSelected && role === 'button') return onButtonPressed(onItemSelected as any);
+        return undefined;
+    }, [role, onItemSelected]);
+
+    const content = (
+        <>
+            {before && <div className={`${CLASSNAME}__before`}>{before}</div>}
+            <div className={`${CLASSNAME}__content`}>{children}</div>
+            {after && <div className={`${CLASSNAME}__after`}>{after}</div>}
+        </>
+    );
+
+    return (
+        <li
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    prefix: CLASSNAME,
+                    size,
+                }),
+            )}
+        >
+            {isClickable({ linkProps, onItemSelected }) ? (
+                /* Clickable list item */
+                renderLink(
+                    {
+                        linkAs,
+                        tabIndex: !disabledStateProps.disabled ? 0 : undefined,
+                        role,
+                        'aria-disabled': isAnyDisabled,
+                        ...linkProps,
+                        href: isAnyDisabled ? undefined : linkProps.href,
+                        className: classNames(
+                            handleBasicClasses({
+                                prefix: `${CLASSNAME}__link`,
+                                isHighlighted,
+                                isSelected,
+                                isDisabled: isAnyDisabled,
+                            }),
+                        ),
+                        onClick: isAnyDisabled ? undefined : onItemSelected,
+                        onKeyDown: isAnyDisabled ? undefined : onKeyDown,
+                        ref: linkRef,
+                    },
+                    content,
+                )
+            ) : (
+                /* Non clickable list item */
+                <div className={`${CLASSNAME}__wrapper`}>{content}</div>
+            )}
+        </li>
+    );
+});
+ListItem.displayName = COMPONENT_NAME;
+ListItem.className = CLASSNAME;
+ListItem.defaultProps = DEFAULT_PROPS;

package/src/components/list/ListSubheader.stories.tsx

@@ -0,0 +1,11 @@
+import { ListSubheader } from '@lumx/react';
+
+export default {
+    title: 'LumX components/list/ListSubheader',
+    component: ListSubheader,
+    args: ListSubheader.defaultProps,
+};
+
+export const Default = {
+    args: { children: 'List subheader text' },
+};

package/src/components/list/ListSubheader.test.tsx

@@ -0,0 +1,21 @@
+import { commonTestsSuiteRTL } from '@lumx/react/testing/utils';
+import { render } from '@testing-library/react';
+import { queryByClassName } from '@lumx/react/testing/utils/queries';
+import { ListSubheader, ListSubheaderProps } from './ListSubheader';
+
+const CLASSNAME = ListSubheader.className as string;
+
+const setup = (props: Partial<ListSubheaderProps> = {}) => {
+    render(<ListSubheader {...(props as any)} />);
+    const listSubheader = queryByClassName(document.body, CLASSNAME);
+    return { props, listSubheader };
+};
+
+describe(`<${ListSubheader.displayName}>`, () => {
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'listSubheader',
+        forwardAttributes: 'listSubheader',
+    });
+});

package/src/components/list/ListSubheader.tsx

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+
+import classNames from 'classnames';
+
+import { GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+/**
+ * Defines the props of the component.
+ */
+export interface ListSubheaderProps extends GenericProps {
+    /** Content. */
+    children: string | ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'ListSubheader';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * ListSubheader component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const ListSubheader = forwardRef<ListSubheaderProps, HTMLLIElement>((props, ref) => {
+    const { children, className, ...forwardedProps } = props;
+
+    return (
+        <li ref={ref} {...forwardedProps} className={classNames(className, CLASSNAME)}>
+            {children}
+        </li>
+    );
+});
+ListSubheader.displayName = COMPONENT_NAME;
+ListSubheader.className = CLASSNAME;

package/src/components/list/index.ts

@@ -0,0 +1,4 @@
+export * from './List';
+export * from './ListItem';
+export * from './ListDivider';
+export * from './ListSubheader';

package/src/components/list/useInteractiveList.tsx

@@ -0,0 +1,202 @@
+import { ListItemProps } from '@lumx/react';
+import { isClickable } from '@lumx/react/components/list/ListItem';
+
+import { isComponent } from '@lumx/react/utils/type';
+import { flattenChildren } from '@lumx/react/utils/react/flattenChildren';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import get from 'lodash/get';
+import {
+    cloneElement,
+    Key,
+    ReactElement,
+    ReactNode,
+    RefObject,
+    SyntheticEvent,
+    useEffect,
+    useMemo,
+    useState,
+} from 'react';
+
+type Listener = (evt: KeyboardEvent) => void;
+
+interface Options {
+    /** List of items to navigate on. */
+    items: ReactNode[] | ReactNode;
+    /** Reference to the list-like element controlling the navigation. */
+    ref: RefObject<HTMLElement>;
+
+    /**
+     * On list item navigated callback (triggered on ARROW key navigation).
+     *
+     * @param index Index of the navigated item among the sibling items.
+     * @param key   React key of the navigated item.
+     */
+    onListItemNavigated?(index: number, key: Key | null): void;
+
+    /**
+     * On list item selected callback (via ENTER key or click).
+     *
+     * @param index Index of the selected item among the sibling items.
+     * @param key   React key of the selected item.
+     * @param evt   Source event (either mouse or keyboard event).
+     */
+    onListItemSelected?(index: number, key: Key | null, evt: SyntheticEvent): void;
+}
+
+interface Output {
+    /** List of items transformed to accommodate keyboard navigation. */
+    items: ReactNode[];
+    /** Whether the list contains clickable items or not. */
+    hasClickableItem: boolean;
+}
+
+export type useInteractiveList = (options: Options) => Output;
+
+const INITIAL_INDEX = -1;
+
+function onKeyboardFocus(props: any, handler: (evt: FocusEvent) => void) {
+    let isMouseDown = false;
+    return {
+        onFocus(evt: FocusEvent) {
+            props.onFocus?.(evt);
+            if (!isMouseDown) {
+                handler(evt);
+            }
+        },
+        onMouseDown(evt: MouseEvent) {
+            props.onMouseDown?.(evt);
+            isMouseDown = true;
+        },
+        onMouseUp(evt: MouseEvent) {
+            props.onMouseUp?.(evt);
+            isMouseDown = false;
+        },
+    };
+}
+
+const isNavigableItem = (node: ReactNode): node is ReactElement => {
+    return isComponent('ListItem')(node) && isClickable(node.props) && !node.props.isDisabled;
+};
+
+/**
+ * This custom hook detects clickable list item in a list and make them navigable with the keyboard.
+ *
+ * @param  options See {@link Options}
+ * @return See {@link Output}
+ */
+export const useInteractiveList: useInteractiveList = (options) => {
+    const { ref, onListItemSelected, onListItemNavigated } = options;
+    const items = useMemo(() => flattenChildren(options.items), [options.items]);
+    const [activeItemIndex, setActiveItemIndex] = useState(INITIAL_INDEX);
+
+    // Attach listeners to the list.
+    useEffect(() => {
+        const { current: listElement } = ref;
+        if (!listElement) {
+            return undefined;
+        }
+
+        /**
+         * This function calculates the next index in the list to be active
+         * @param  index current index
+         * @param  code  key code pressed
+         * @return next index
+         */
+        const getNextIndex = (index: number, key: string): number => {
+            switch (key) {
+                case 'ArrowDown':
+                    return index + 1 < items.length ? index + 1 : 0;
+                case 'ArrowUp':
+                    return index - 1 >= 0 ? index - 1 : items.length - 1;
+                default:
+                    return INITIAL_INDEX;
+            }
+        };
+
+        /**
+         * Resets the active index to the initial state
+         */
+        const resetActiveIndex = () => {
+            setActiveItemIndex(INITIAL_INDEX);
+        };
+
+        /**
+         * Handles navigation with the arrows using the keyboard
+         * @param evt Key event
+         */
+        const onArrowPressed: Listener = (evt) => {
+            const { key } = evt;
+            if (key !== 'ArrowUp' && key !== 'ArrowDown') {
+                return;
+            }
+
+            let nextIndex = activeItemIndex;
+            let iterations = 0;
+
+            // Move to next navigable item.
+            do {
+                nextIndex = getNextIndex(nextIndex, key);
+                iterations += 1;
+            } while (
+                nextIndex !== INITIAL_INDEX &&
+                nextIndex !== activeItemIndex &&
+                !isNavigableItem(items[nextIndex] as any) &&
+                iterations < items.length
+            );
+
+            setActiveItemIndex(nextIndex);
+            evt.preventDefault();
+            evt.stopPropagation();
+            onListItemNavigated?.(nextIndex, get(items, [nextIndex, 'key']));
+        };
+
+        /**
+         * Reset active list item index when focusing outside the list.
+         * @param evt Focus out event
+         */
+        const onFocusOut = (evt: FocusEvent) => {
+            if (!evt.relatedTarget || !listElement.contains(evt.relatedTarget as any)) {
+                resetActiveIndex();
+            }
+        };
+
+        listElement.addEventListener('focusout', onFocusOut);
+        listElement.addEventListener('keydown', onArrowPressed);
+        return () => {
+            listElement.removeEventListener('focusout', onFocusOut);
+            listElement.removeEventListener('keydown', onArrowPressed);
+        };
+    }, [ref, activeItemIndex, items, onListItemNavigated]);
+
+    return useMemo(() => {
+        let hasClickableItem = false;
+        const transformedItems = items.map((item, index) => {
+            // Ignore if list not clickable or item is not a simple list item.
+            if (!isNavigableItem(item)) {
+                return item;
+            }
+
+            hasClickableItem = true;
+            const isHighlighted = index === activeItemIndex;
+
+            // Clone list item: inject ref, add tab index and active state.
+            return cloneElement<ListItemProps>(item, {
+                ...item.props,
+                isHighlighted: item.props.isHighlighted ?? isHighlighted,
+                linkRef: mergeRefs(item.props.linkRef, (element: any) => {
+                    if (isHighlighted) {
+                        element?.focus();
+                    }
+                }),
+                onItemSelected(evt) {
+                    item.props.onItemSelected?.();
+                    onListItemSelected?.(index, item.key, evt);
+                },
+                ...onKeyboardFocus(item.props, () => {
+                    setActiveItemIndex(index);
+                }),
+            });
+        });
+        return { items: transformedItems, hasClickableItem };
+    }, [items, activeItemIndex, onListItemSelected]);
+};

package/src/components/message/Message.stories.tsx

@@ -0,0 +1,72 @@
+import { Kind, Message } from '@lumx/react';
+import { mdiDelete } from '@lumx/icons';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { loremIpsum } from '@lumx/react/stories/utils/lorem';
+import { iconArgType } from '@lumx/react/stories/controls/icons';
+import { withCombinations } from '@lumx/react/stories/decorators/withCombinations';
+import { withUndefined } from '@lumx/react/stories/controls/withUndefined';
+import { withNestedProps } from '../../stories/decorators/withNestedProps';
+
+export default {
+    title: 'LumX components/message/Message',
+    component: Message,
+    argTypes: {
+        kind: getSelectArgType(Kind),
+        hasBackground: { control: 'boolean' },
+        icon: iconArgType,
+    },
+    args: { ...Message.defaultProps, children: loremIpsum('tiny') },
+};
+
+/**
+ * Default message
+ */
+export const Default = {};
+
+/**
+ * All `kind` variants
+ */
+export const AllKinds = {
+    ...Default,
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'kind', options: withUndefined(Kind) },
+            },
+        }),
+    ],
+};
+
+/**
+ * All `kind` variants with `hasBackground`
+ */
+export const AllKindsWithBackground = {
+    ...AllKinds,
+    args: {
+        hasBackground: true,
+    },
+};
+
+/**
+ * With custom icon
+ */
+export const CustomIcon = {
+    args: {
+        icon: mdiDelete,
+    },
+};
+
+/**
+ * With close button (has background and kind info)
+ */
+export const ClosableMessage = {
+    args: {
+        'closeButtonProps.label': 'Close',
+        hasBackground: true,
+        kind: 'info',
+    },
+    argTypes: {
+        'closeButtonProps.onClick': { action: true },
+    },
+    decorators: [withNestedProps()],
+};

package/src/components/message/Message.test.tsx

@@ -0,0 +1,76 @@
+import { commonTestsSuiteRTL } from '@lumx/react/testing/utils';
+import { Kind } from '@lumx/react';
+
+import { queryByRole, render } from '@testing-library/react';
+import { getByClassName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import { mdiAbTesting } from '@lumx/icons';
+
+import userEvent from '@testing-library/user-event';
+import { Message, MessageProps } from './Message';
+
+const CLASSNAME = Message.className as string;
+
+type SetupProps = Partial<MessageProps>;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (propsOverride: SetupProps = {}) => {
+    const props: any = { ...propsOverride };
+    render(<Message {...props} />);
+    const message = getByClassName(document.body, CLASSNAME);
+    const icon = queryByClassName(message, `${CLASSNAME}__icon`);
+    const closeButton = queryByRole(message, 'button', { name: props.closeButtonProps?.label });
+    return { message, icon, closeButton, props };
+};
+
+describe(`<${Message.displayName}>`, () => {
+    describe('Props', () => {
+        it('should render default', () => {
+            const { message, icon } = setup({ children: 'Message text' });
+            expect(message).toBeInTheDocument();
+            expect(message.className).toMatchInlineSnapshot('"lumx-message"');
+            expect(message).toHaveTextContent('Message text');
+
+            expect(icon).not.toBeInTheDocument();
+        });
+
+        it('should render hasBackground', () => {
+            const { message } = setup({ hasBackground: true });
+            expect(message).toHaveClass(`${CLASSNAME}--has-background`);
+        });
+
+        it('should render icon', () => {
+            const { icon } = setup({ icon: mdiAbTesting });
+            expect(icon).toBeInTheDocument();
+        });
+
+        it.each(Object.values(Kind))('should render kind %s', (kind) => {
+            const { message, icon, closeButton } = setup({ kind });
+            expect(message.className).toEqual(expect.stringMatching(/\blumx-message--color-\w+\b/));
+            expect(icon).toBeInTheDocument();
+            expect(closeButton).not.toBeInTheDocument();
+        });
+
+        it('should render close button', async () => {
+            const onClick = vi.fn();
+            const { closeButton } = setup({
+                hasBackground: true,
+                kind: 'info',
+                closeButtonProps: {
+                    label: 'Close',
+                    onClick,
+                },
+            });
+
+            expect(closeButton).toBeInTheDocument();
+
+            await userEvent.click(closeButton as HTMLElement);
+
+            expect(onClick).toHaveBeenCalled();
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, { baseClassName: CLASSNAME, forwardClassName: 'message', forwardAttributes: 'message' });
+});