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

package/src/components/link-preview/LinkPreview.test.tsx

@@ -0,0 +1,105 @@
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+import { Size, Theme } from '@lumx/core/js/constants';
+import { Thumbnail } from '@lumx/react';
+import { render, screen, within } from '@testing-library/react';
+import { getByClassName, queryByClassName, queryAllByClassName } from '@lumx/react/testing/utils/queries';
+
+import { LinkPreview, LinkPreviewProps } from './LinkPreview';
+
+const CLASSNAME = LinkPreview.className as string;
+
+type SetupProps = Partial<LinkPreviewProps>;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (propsOverride: SetupProps = {}, { wrapper }: SetupRenderOptions = {}) => {
+    const props: any = { ...propsOverride };
+
+    render(<LinkPreview {...props} />, { wrapper });
+    const linkPreview = getByClassName(document.body, CLASSNAME);
+    const thumbnail = queryByClassName(linkPreview, Thumbnail.className as string);
+    const title = queryByClassName(linkPreview, `${CLASSNAME}__title`);
+    const description = queryByClassName(linkPreview, `${CLASSNAME}__description`);
+    const link = queryAllByClassName(linkPreview, `${CLASSNAME}__link`)?.[1];
+
+    return { props, linkPreview, thumbnail, title, description, link };
+};
+
+describe(`<${LinkPreview.displayName}>`, () => {
+    it('should render with default props', () => {
+        const { linkPreview, thumbnail, title, link, description } = setup();
+        expect(linkPreview).toHaveClass(CLASSNAME);
+        expect(linkPreview).toHaveClass(`${CLASSNAME}--size-regular`);
+        expect(linkPreview).toHaveClass(`${CLASSNAME}--theme-light`);
+
+        expect(thumbnail).not.toBeInTheDocument();
+        expect(title).not.toBeInTheDocument();
+        expect(link).toBeInTheDocument();
+        expect(link).not.toHaveAttribute('tabindex');
+        expect(description).not.toBeInTheDocument();
+    });
+
+    it('should render with only the title', () => {
+        const { props, title, link } = setup({ title: 'Title', link: 'https://example.com' });
+
+        expect(title).toBe(screen.queryByRole('heading', { name: props.title }));
+        const titleLink = within(title as any).queryByRole('link');
+        expect(titleLink).toBeInTheDocument();
+        expect(titleLink).toHaveAttribute('href', props.link);
+
+        expect(link).toBeInTheDocument();
+        expect(link).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('should render with complete props', () => {
+        const { linkPreview, thumbnail, title, link, description, props } = setup({
+            size: Size.big,
+            theme: Theme.dark,
+            thumbnailProps: { image: 'https://example.com/thumbnail.jpg', alt: '' },
+            link: 'https://example.com',
+            linkProps: { 'data-custom-attr': 'true' },
+            title: 'Title',
+            description: 'Description',
+        });
+
+        const validateLink = (linkElement: any) => {
+            expect(linkElement).toHaveAttribute('href', props.link);
+            // Props forwarding
+            expect(linkElement).toHaveAttribute('data-custom-attr', 'true');
+        };
+
+        expect(linkPreview).toBeInTheDocument();
+        expect(linkPreview).toHaveClass(`${CLASSNAME}--size-big`);
+        expect(linkPreview).toHaveClass(`${CLASSNAME}--theme-dark`);
+
+        // Thumbnail
+        expect(thumbnail).toBeInTheDocument();
+        validateLink(thumbnail);
+
+        // Title
+        expect(title).toHaveTextContent(props.title);
+        validateLink(within(title as any).queryByRole('link'));
+
+        // Link
+        expect(link).toHaveTextContent(props.link);
+        validateLink(link);
+
+        // Description
+        expect(description).toHaveTextContent(props.description);
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'linkPreview',
+        forwardAttributes: 'linkPreview',
+        forwardRef: 'linkPreview',
+        applyTheme: {
+            affects: [{ element: 'linkPreview' }],
+            viaProp: true,
+            viaContext: true,
+            defaultTheme: 'light',
+        },
+    });
+});

package/src/components/link-preview/LinkPreview.tsx

@@ -0,0 +1,158 @@
+import classNames from 'classnames';
+
+import {
+    AspectRatio,
+    ColorPalette,
+    ColorVariant,
+    Link,
+    LinkProps,
+    Size,
+    Theme,
+    Thumbnail,
+    ThumbnailProps,
+} from '@lumx/react';
+
+import { GenericProps, HeadingElement, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+/**
+ * Defines the props of the component.
+ */
+export interface LinkPreviewProps extends GenericProps, HasTheme {
+    /** Description. */
+    description?: string;
+    /** Link URL. */
+    link: string;
+    /** Custom react component for the link (can be used to inject react router Link). */
+    linkAs?: 'a' | any;
+    /** Props to pass to the link (minus those already set by the LinkPreview props). */
+    linkProps?: Omit<LinkProps, 'color' | 'colorVariant' | 'href' | 'target'>;
+    /** Size variant. */
+    size?: Extract<Size, 'regular' | 'big'>;
+    /** Thumbnail for the link preview. */
+    thumbnailProps?: ThumbnailProps;
+    /** Title. */
+    title?: string;
+    /** Customize the title heading tag. */
+    titleHeading?: HeadingElement;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'LinkPreview';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS = {
+    size: Size.regular,
+    titleHeading: 'h2',
+} as const;
+
+/**
+ * LinkPreview component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const LinkPreview = forwardRef<LinkPreviewProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        className,
+        description,
+        link,
+        linkAs,
+        linkProps,
+        size = DEFAULT_PROPS.size,
+        theme = defaultTheme,
+        thumbnailProps,
+        title,
+        titleHeading = DEFAULT_PROPS.titleHeading,
+        ...forwardedProps
+    } = props;
+    // Use title heading as title wrapper (see DEFAULT_PROPS for the default value).
+    const TitleHeading = titleHeading as HeadingElement;
+
+    return (
+        <article
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    prefix: CLASSNAME,
+                    size: size === Size.big && thumbnailProps ? Size.big : Size.regular,
+                    theme,
+                }),
+            )}
+        >
+            <div className={`${CLASSNAME}__wrapper`}>
+                {thumbnailProps && (
+                    <div className={`${CLASSNAME}__thumbnail`}>
+                        <Thumbnail
+                            {...thumbnailProps}
+                            linkAs={linkAs}
+                            linkProps={{
+                                ...linkProps,
+                                href: link,
+                                target: '_blank',
+                                // Avoid redundant links in focus order
+                                tabIndex: -1,
+                            }}
+                            aspectRatio={AspectRatio.free}
+                            fillHeight
+                        />
+                    </div>
+                )}
+
+                <div className={`${CLASSNAME}__container`}>
+                    {title && (
+                        <TitleHeading className={`${CLASSNAME}__title`}>
+                            <Link
+                                {...linkProps}
+                                linkAs={linkAs}
+                                target="_blank"
+                                href={link}
+                                color={theme === Theme.light ? ColorPalette.dark : ColorPalette.light}
+                                colorVariant={ColorVariant.N}
+                            >
+                                {title}
+                            </Link>
+                        </TitleHeading>
+                    )}
+
+                    {description && <p className={`${CLASSNAME}__description`}>{description}</p>}
+
+                    <div className={`${CLASSNAME}__link`}>
+                        <Link
+                            {...linkProps}
+                            linkAs={linkAs}
+                            className={classNames(`${CLASSNAME}__link`, linkProps?.className)}
+                            target="_blank"
+                            href={link}
+                            color={theme === Theme.light ? ColorPalette.primary : ColorPalette.light}
+                            colorVariant={ColorVariant.N}
+                            // Avoid redundant links in focus order
+                            tabIndex={title ? '-1' : undefined}
+                        >
+                            {link}
+                        </Link>
+                    </div>
+                </div>
+            </div>
+        </article>
+    );
+});
+
+LinkPreview.displayName = COMPONENT_NAME;
+LinkPreview.className = CLASSNAME;
+LinkPreview.defaultProps = DEFAULT_PROPS;

package/src/components/link-preview/index.ts

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

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

@@ -0,0 +1,116 @@
+import { useRef } from 'react';
+
+import { mdiAccount, mdiOpenInNew } from '@lumx/icons';
+import { Icon, ListDivider, ListProps, ListSubheader, Size } from '@lumx/react';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+
+import { List } from './List';
+import { ListItem } from './ListItem';
+import ListItemStories from './ListItem.stories';
+
+export default {
+    title: 'LumX components/list/List',
+    component: List,
+    args: List.defaultProps,
+    argTypes: {
+        itemPadding: getSelectArgType<ListProps['itemPadding']>([Size.big, Size.huge]),
+        onListItemSelected: { action: true },
+        'children.onItemSelected': { action: true },
+        'children.size': ListItemStories.argTypes.size,
+    },
+};
+
+const CustomListItem = (props: any) => <ListItem {...props}>Custom list item</ListItem>;
+
+export const KeyboardNavigation = ({
+    'children.onItemSelected': childrenOnItemSelected,
+    'children.size': childrenSize,
+    ...props
+}: any) => {
+    const listRef = useRef<any>();
+    const firstItemRef = useRef<any>();
+
+    const focusList = () => {
+        return listRef.current?.focus();
+    };
+
+    const focusFirsItem = () => {
+        return firstItemRef.current?.focus();
+    };
+
+    return (
+        <>
+            <button type="button" onClick={focusList}>
+                focus list
+            </button>
+            <button type="button" onClick={focusFirsItem}>
+                focus first item
+            </button>
+            <List ref={listRef} {...props}>
+                <ListItem size={childrenSize} linkRef={firstItemRef} onItemSelected={childrenOnItemSelected}>
+                    Clickable item 1
+                </ListItem>
+                <ListDivider />
+                <ListItem size={childrenSize} linkProps={{ href: '#' }}>
+                    Link item 1
+                </ListItem>
+                <>
+                    <ListItem size={childrenSize}>Non clickable (=non navigable) item</ListItem>
+                    <ListSubheader>Header</ListSubheader>
+                    <ListItem size={childrenSize} linkProps={{ href: '#' }}>
+                        Link item 2
+                    </ListItem>
+                    <ListSubheader>Header</ListSubheader>
+                </>
+                <ListItem size={childrenSize} linkProps={{ href: '#' }} isDisabled>
+                    Disabled link item
+                </ListItem>
+                <ListItem size={childrenSize} onItemSelected={childrenOnItemSelected} isDisabled>
+                    Disabled button item
+                </ListItem>
+                <CustomListItem size={childrenSize} onItemSelected={childrenOnItemSelected} />
+                {[
+                    <ListItem size={childrenSize} key="1" linkProps={{ href: '#' }}>
+                        Link item 4
+                    </ListItem>,
+                ]}
+            </List>
+            <pre>{`
+                When focused:
+                arrow up/down to move focus on list item
+                tab/shift+tab to move focus on list item AND outside the list
+            `}</pre>
+        </>
+    );
+};
+
+export const AsLink = () => (
+    <List>
+        <ListItem
+            before={<Icon icon={mdiAccount} />}
+            className="lumx-color-background-dark-L6"
+            linkProps={{ href: '#' }}
+        >
+            <span>My first link</span>
+        </ListItem>
+        <ListItem
+            className="lumx-color-background-dark-L6"
+            after={<Icon icon={mdiOpenInNew} />}
+            linkProps={{ href: 'https://example.com', target: '_blank' }}
+        >
+            <span>Google</span>
+        </ListItem>
+    </List>
+);
+
+export const WithCustomChildren = ({
+    'children.onItemSelected': childrenOnItemSelected,
+    'children.size': childrenSize,
+    ...props
+}: any) => (
+    <List {...props}>
+        <CustomListItem size={childrenSize} onItemSelected={childrenOnItemSelected} />
+        <CustomListItem size={childrenSize} onItemSelected={childrenOnItemSelected} />
+        <CustomListItem size={childrenSize} onItemSelected={childrenOnItemSelected} />
+    </List>
+);

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

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

package/src/components/list/List.tsx

@@ -0,0 +1,104 @@
+import { Key, ReactNode, SyntheticEvent, useRef } from 'react';
+
+import classNames from 'classnames';
+
+import { Size } from '@lumx/react';
+import { useKeyboardListNavigation } from '@lumx/react/hooks/useKeyboardListNavigation';
+import { GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { useInteractiveList } from './useInteractiveList';
+
+/**
+ * Defines the props of the component.
+ */
+export interface ListProps extends GenericProps {
+    /** List content (should be ListItem, ListSubheader or ListDivider). */
+    children: ReactNode;
+    /**
+     * Whether the list items are clickable.
+     * @deprecated not needed anymore.
+     */
+    isClickable?: boolean;
+    /** Item padding size. */
+    itemPadding?: Extract<Size, 'big' | 'huge'>;
+    /** Tab index of the list. Default to -1 */
+    tabIndex?: number;
+    /**
+     * On list item selected callback.
+     *
+     * @param key   React key of the selected item.
+     * @param index Index of the selected item among the sibling items.
+     * @param evt   Source event (either mouse or keyboard event).
+     */
+    onListItemSelected?(key: Key, index: number, evt: SyntheticEvent): void;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'List';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<ListProps> = {
+    tabIndex: -1,
+};
+
+/* eslint-disable jsx-a11y/no-noninteractive-tabindex */
+/**
+ * List component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const InternalList = forwardRef<ListProps, HTMLUListElement>((props, ref) => {
+    const {
+        children,
+        className,
+        isClickable,
+        itemPadding,
+        onListItemSelected,
+        tabIndex = DEFAULT_PROPS.tabIndex,
+        ...forwardedProps
+    } = props;
+    const listElementRef = useRef<HTMLUListElement>(null);
+
+    const { items, hasClickableItem } = useInteractiveList({
+        items: children,
+        ref: listElementRef,
+        onListItemSelected,
+    });
+    const clickable = hasClickableItem || isClickable;
+
+    return (
+        <ul
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    prefix: CLASSNAME,
+                    itemPadding: itemPadding ?? (clickable ? Size.big : undefined),
+                }),
+            )}
+            tabIndex={tabIndex}
+            ref={mergeRefs(ref, listElementRef)}
+        >
+            {items}
+        </ul>
+    );
+});
+InternalList.displayName = COMPONENT_NAME;
+InternalList.className = CLASSNAME;
+InternalList.defaultProps = DEFAULT_PROPS;
+
+export const List = Object.assign(InternalList, { useKeyboardListNavigation });

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

@@ -0,0 +1,12 @@
+import { withWrapper } from '@lumx/react/stories/decorators/withWrapper';
+import { List } from '@lumx/react';
+import { ListDivider } from './ListDivider';
+
+export default {
+    title: 'LumX components/list/ListDivider',
+    component: ListDivider,
+    args: ListDivider.defaultProps,
+    decorators: [withWrapper({}, List)],
+};
+
+export const Default = {};

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

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

package/src/components/list/ListDivider.tsx

@@ -0,0 +1,35 @@
+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 type ListDividerProps = GenericProps;
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'ListDivider';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * ListDivider component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const ListDivider = forwardRef<ListDividerProps, HTMLLIElement>((props, ref) => {
+    const { className, ...forwardedProps } = props;
+
+    return <li ref={ref} {...forwardedProps} className={classNames(className, CLASSNAME)} />;
+});
+ListDivider.displayName = COMPONENT_NAME;
+ListDivider.className = CLASSNAME;

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

@@ -0,0 +1,66 @@
+import { List, ListItemSize, Size } from '@lumx/react';
+
+import { withWrapper } from '@lumx/react/stories/decorators/withWrapper';
+import { CustomLink } from '@lumx/react/stories/utils/CustomLink';
+import { withCombinations } from '@lumx/react/stories/decorators/withCombinations';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { isEqual } from '@lumx/react/utils/object/isEqual';
+import { ListItem } from './ListItem';
+
+const sizes: ListItemSize[] = [Size.tiny, Size.regular, Size.big];
+
+export default {
+    title: 'LumX components/list/ListItem',
+    component: ListItem,
+    args: ListItem.defaultProps,
+    argTypes: {
+        size: getSelectArgType(sizes),
+    },
+    decorators: [withWrapper({}, List)],
+};
+
+/**
+ * Default list item with text
+ */
+export const Default = {
+    args: { children: 'List item' },
+};
+
+/**
+ * Inject a custom link component
+ */
+export const CustomLink_ = {
+    args: {
+        linkAs: CustomLink,
+        children: 'List item custom link',
+    },
+};
+
+/**
+ * Combination of all states (size, clickable and non-clickable states)
+ */
+export const AllStates = {
+    args: { children: 'List item' },
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'size', options: sizes },
+                cols: {
+                    Default: {},
+                    Disabled: { isDisabled: true },
+                    'ARIA Disabled': { 'aria-disabled': true },
+                    Selected: { isSelected: true },
+                    Highlighted: { isHighlighted: true },
+                },
+                sections: {
+                    Default: {},
+                    'As button': { onItemSelected: () => {} },
+                    'As link': { linkProps: { href: '#' } },
+                },
+            },
+            // Only keep size variants for non clickable list items
+            excludeCombination: (props) =>
+                !props.onItemSelected && !props.linkProps?.href && !isEqual(Object.keys(props), ['size', 'children']),
+        }),
+    ],
+};