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

package/src/components/lightbox/Lightbox.tsx

@@ -0,0 +1,180 @@
+import { RefObject, useRef, useEffect, AriaAttributes } from 'react';
+
+import classNames from 'classnames';
+
+import { mdiClose } from '@lumx/icons';
+import { HeadingLevelProvider, IconButton, IconButtonProps } from '@lumx/react';
+import { DIALOG_TRANSITION_DURATION, DOCUMENT } from '@lumx/react/constants';
+import { GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+
+import { useFocusTrap } from '@lumx/react/hooks/useFocusTrap';
+import { useDisableBodyScroll } from '@lumx/react/hooks/useDisableBodyScroll';
+import { ClickAwayProvider } from '@lumx/react/utils/ClickAwayProvider';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { useCallbackOnEscape } from '@lumx/react/hooks/useCallbackOnEscape';
+import { useTransitionVisibility } from '@lumx/react/hooks/useTransitionVisibility';
+import { ThemeProvider } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { Portal } from '@lumx/react/utils';
+
+/**
+ * Defines the props of the component.
+ */
+export interface LightboxProps extends GenericProps, HasTheme, Pick<AriaAttributes, 'aria-label' | 'aria-labelledby'> {
+    /** Props to pass to the close button (minus those already set by the Lightbox props). */
+    closeButtonProps?: Pick<IconButtonProps, 'label'> &
+        Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis' | 'color'>;
+    /** Whether the component is open or not. */
+    isOpen?: boolean;
+    /** Reference to the element that triggered modal opening to set focus on. */
+    parentElement: RefObject<any>;
+    /** Reference to the element that should get the focus when the lightbox opens. By default, the close button or the lightbox itself will take focus. */
+    focusElement?: RefObject<HTMLElement>;
+    /** Whether to keep the dialog open on clickaway or escape press. */
+    preventAutoClose?: boolean;
+    /** Z-axis position. */
+    zIndex?: number;
+    /** On close callback. */
+    onClose?(): void;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Lightbox';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Lightbox component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Lightbox = forwardRef<LightboxProps, HTMLDivElement>((props, ref) => {
+    const {
+        'aria-labelledby': propAriaLabelledBy,
+        ariaLabelledBy = propAriaLabelledBy,
+        'aria-label': propAriaLabel,
+        ariaLabel = propAriaLabel,
+        children,
+        className,
+        closeButtonProps,
+        isOpen,
+        onClose,
+        parentElement,
+        focusElement,
+        preventAutoClose,
+        theme,
+        zIndex,
+        ...forwardedProps
+    } = props;
+    if (!DOCUMENT) {
+        // Can't render in SSR.
+        return null;
+    }
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const childrenRef = useRef<any>(null);
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const wrapperRef = useRef<HTMLDivElement>(null);
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const closeButtonRef = useRef<HTMLButtonElement>(null);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useDisableBodyScroll(isOpen && wrapperRef.current);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const isVisible = useTransitionVisibility(wrapperRef, !!isOpen, DIALOG_TRANSITION_DURATION);
+
+    // Handle focus trap.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useFocusTrap(
+        // Focus trap zone
+        isOpen && wrapperRef.current,
+        // Focus element (fallback on close button and then on the dialog)
+        focusElement?.current || closeButtonRef.current || wrapperRef.current,
+    );
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const previousOpen = useRef(isOpen);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(() => {
+        if (isOpen !== previousOpen.current) {
+            previousOpen.current = isOpen;
+
+            // Focus the parent element on close.
+            if (!isOpen && parentElement && parentElement.current) {
+                parentElement.current.focus();
+            }
+        }
+    }, [isOpen, parentElement]);
+
+    // Close lightbox on escape key pressed.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useCallbackOnEscape(onClose);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const clickAwayRefs = useRef([wrapperRef]);
+
+    if (!isOpen && !isVisible) return null;
+
+    return (
+        <Portal>
+            <div
+                ref={mergeRefs(ref, wrapperRef)}
+                {...forwardedProps}
+                aria-label={ariaLabel}
+                aria-labelledby={ariaLabelledBy}
+                aria-modal="true"
+                role="dialog"
+                tabIndex={-1}
+                className={classNames(
+                    className,
+                    handleBasicClasses({
+                        prefix: CLASSNAME,
+                        isHidden: !isOpen,
+                        isShown: isOpen || isVisible,
+                        theme,
+                    }),
+                )}
+                style={{ zIndex }}
+            >
+                {closeButtonProps && (
+                    <div className={`${CLASSNAME}__close`}>
+                        <IconButton
+                            {...closeButtonProps}
+                            ref={closeButtonRef}
+                            emphasis="low"
+                            hasBackground
+                            icon={mdiClose}
+                            theme="dark"
+                            type="button"
+                            onClick={onClose}
+                        />
+                    </div>
+                )}
+                <HeadingLevelProvider level={2}>
+                    <ThemeProvider value={undefined}>
+                        <ClickAwayProvider callback={!preventAutoClose && onClose} childrenRefs={clickAwayRefs}>
+                            <div ref={childrenRef} className={`${CLASSNAME}__wrapper`} role="presentation">
+                                {children}
+                            </div>
+                        </ClickAwayProvider>
+                    </ThemeProvider>
+                </HeadingLevelProvider>
+            </div>
+        </Portal>
+    );
+});
+Lightbox.displayName = COMPONENT_NAME;
+Lightbox.className = CLASSNAME;

package/src/components/lightbox/index.ts

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

package/src/components/link/Link.stories.tsx

@@ -0,0 +1,195 @@
+import {
+    ColorPalette,
+    ColorVariant,
+    FlexBox,
+    Icon,
+    Text,
+    Link,
+    Typography,
+    TypographyInterface,
+    TypographyTitleCustom,
+    GenericBlock,
+} from '@lumx/react';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { colorArgType, colorVariantArgType } from '@lumx/react/stories/controls/color';
+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 { CustomLink } from '@lumx/react/stories/utils/CustomLink';
+import { withWrapper } from '@lumx/react/stories/decorators/withWrapper';
+import { withThemedBackground } from '@lumx/react/stories/decorators/withThemedBackground';
+import { mdiEarth, mdiFoodApple, mdiPencil } from '@lumx/icons';
+import { withNestedProps } from '@lumx/react/stories/decorators/withNestedProps';
+
+const linkTypographies = { ...TypographyInterface, ...TypographyTitleCustom };
+
+export default {
+    title: 'LumX components/link/Link',
+    component: Link,
+    argTypes: {
+        typography: getSelectArgType(linkTypographies),
+        color: colorArgType,
+        colorVariant: colorVariantArgType,
+        rightIcon: iconArgType,
+        leftIcon: iconArgType,
+    },
+    args: { ...Link.defaultProps, children: 'Link' },
+};
+
+/**
+ * Default link
+ */
+export const Default = {
+    args: { href: 'https://example.com', target: '_blank' },
+};
+
+/**
+ * Use custom component instead of <a> or <button>
+ */
+export const LinkAs = {
+    args: { linkAs: CustomLink },
+};
+
+/**
+ * Use a custom typography and customize it via CSS variable
+ */
+export const WithCustomizableTypography = {
+    typography: Typography.custom.title1,
+    // eslint-disable-next-line react/display-name
+    render: (props: any) => (
+        // Injecting CSS variable to customize the font size
+        <>
+            <style>{`
+            :root {
+                --lumx-typography-custom-title1-font-size: 5px;
+            }
+            `}</style>
+            <Link {...props} />
+        </>
+    ),
+};
+
+/**
+ * Show state combinations
+ */
+export const AllStates = {
+    argTypes: {
+        isDisabled: { control: false },
+        onClick: { action: true },
+    },
+    decorators: [
+        withThemedBackground(),
+        withCombinations({
+            combinations: {
+                sections: {
+                    Default: { href: '#' },
+                    'As button': {},
+                    'with icon': {
+                        children: ['Link', <Icon key="icon" icon={mdiEarth} />, 'with icon'],
+                    },
+                },
+                cols: {
+                    Default: {},
+                    Disabled: { isDisabled: true },
+                    Focused: { 'data-focus-visible-added': true },
+                    'ARIA Disabled': { 'aria-disabled': true },
+                    Hovered: { 'data-lumx-hover': true },
+                },
+                rows: {
+                    Default: {},
+                    'color=red': { color: 'red' },
+                    'theme=dark': { theme: 'dark' },
+                    'theme=dark & color=red': { theme: 'dark', color: 'red' },
+                },
+            },
+        }),
+        withWrapper({ orientation: 'horizontal', vAlign: 'space-evenly', wrap: true, gap: 'huge' }, FlexBox),
+    ],
+};
+
+/**
+ * Show all typographies
+ */
+export const AllTypography = {
+    args: {
+        children: ['Link', <Icon key="icon" icon={mdiEarth} />, 'with icon'],
+        rightIcon: mdiPencil,
+        leftIcon: mdiFoodApple,
+    },
+    argTypes: {
+        typography: { control: false },
+    },
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'typography', options: withUndefined(linkTypographies) },
+            },
+        }),
+    ],
+};
+
+/**
+ * Show all color combinations
+ */
+export const AllColors = {
+    argTypes: {
+        color: { control: false },
+        colorVariant: { control: false },
+    },
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'color', options: withUndefined(ColorPalette) },
+                cols: { key: 'colorVariant', options: withUndefined(ColorVariant) },
+            },
+        }),
+    ],
+};
+
+/**
+ * Check how link inherit parent typography & color.
+ * Typography should be inherited.
+ * Color should not.
+ */
+export const ParentTypographyAndColor = {
+    args: {
+        children: ['Link', <Icon key="icon" icon={mdiEarth} />, 'with icon'],
+        'parent.typography': undefined,
+        'parent.color': undefined,
+    },
+    render: ({ parent: { typography, color }, ...args }: any) => (
+        <Text as="p" color={color} typography={typography}>
+            <Link {...args} />
+        </Text>
+    ),
+    decorators: [
+        withNestedProps(),
+        withCombinations({
+            combinations: {
+                sections: { Button: {}, Link: { href: '#' } },
+                rows: {
+                    Default: {},
+                    'Parent typography=title': { 'parent.typography': 'title' },
+                    'Parent color=red': { 'parent.color': 'red' },
+                },
+            },
+        }),
+        withWrapper({ orientation: 'horizontal', vAlign: 'space-evenly', wrap: true, gap: 'huge' }, FlexBox),
+    ],
+};
+
+/** Check wrapping a block with a Link */
+export const WrappingBlock = {
+    render() {
+        return (
+            // eslint-disable-next-line jsx-a11y/anchor-is-valid
+            <Link href="#" color="dark">
+                <GenericBlock figure={<Icon icon={mdiEarth} hasShape color="red" />} hAlign="center">
+                    <Text as="p" typography="subtitle1">
+                        Hello Earth
+                    </Text>
+                </GenericBlock>
+            </Link>
+        );
+    },
+};

package/src/components/link/Link.test.tsx

@@ -0,0 +1,127 @@
+import { ColorPalette, ColorVariant, Icon, Typography } from '@lumx/react';
+import { commonTestsSuiteRTL } from '@lumx/react/testing/utils';
+import { getByClassName, queryAllByClassName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { mdiCheck, mdiPlus } from '@lumx/icons';
+import { Link, LinkProps } from './Link';
+
+const CLASSNAME = Link.className as string;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (props: LinkProps = {}) => {
+    render(<Link {...props} />);
+    const link = getByClassName(document.body, CLASSNAME);
+    const rightIcon = queryByClassName(link, `${CLASSNAME}__right-icon`);
+    const leftIcon = queryByClassName(link, `${CLASSNAME}__left-icon`);
+    return { props, link, rightIcon, leftIcon };
+};
+
+describe(`<${Link.displayName}>`, () => {
+    describe('Props', () => {
+        it('should render link', () => {
+            const name = 'Link';
+            const { props, link, rightIcon, leftIcon } = setup({ href: 'https://example.com', children: name });
+
+            expect(link).toBe(screen.queryByRole('link', { name }));
+            expect(link).toHaveAttribute('href', props.href);
+            expect(link.className).toMatchInlineSnapshot('"lumx-link"');
+
+            expect(rightIcon).not.toBeInTheDocument();
+            expect(leftIcon).not.toBeInTheDocument();
+        });
+
+        it('should render color & color variant', () => {
+            const { link } = setup({
+                href: 'https://google.com',
+                color: ColorPalette.primary,
+                colorVariant: ColorVariant.D1,
+            });
+            expect(link.className).toBe('lumx-link lumx-link--color-primary lumx-link--color-variant-D1');
+        });
+
+        it('should render typography', () => {
+            const { link } = setup({ href: 'https://google.com', typography: Typography.title });
+            expect(link.className).toBe('lumx-link lumx-link--has-typography lumx-typography-title');
+        });
+
+        it('should render a button', () => {
+            const name = 'Link';
+            const onClick = vi.fn();
+            const { link } = setup({ onClick, children: name });
+            expect(link).toBe(screen.queryByRole('button', { name }));
+        });
+
+        it('should render with icons', () => {
+            const { link } = setup({
+                leftIcon: mdiCheck,
+                children: ['Link', <Icon key="icon" icon={mdiCheck} />, 'with icons'],
+                rightIcon: mdiPlus,
+            });
+            const icons = queryAllByClassName(link, Icon.className as string);
+            expect(icons).toHaveLength(3);
+
+            // Icons are all wrapped with spaces
+            for (const icon of icons) {
+                expect((icon.previousSibling as any).textContent).toEqual(' ');
+                expect((icon.nextSibling as any).textContent).toEqual(' ');
+            }
+        });
+    });
+
+    describe('Disabled state', () => {
+        it('should render disabled button', async () => {
+            const onClick = vi.fn();
+            const { link } = setup({ children: 'Label', isDisabled: true, onClick });
+            expect(link).toHaveAttribute('disabled');
+            await userEvent.click(link);
+            expect(onClick).not.toHaveBeenCalled();
+        });
+
+        it('should render disabled link', async () => {
+            const onClick = vi.fn();
+            const { link } = setup({ children: 'Label', isDisabled: true, href: 'https://example.com', onClick });
+            expect(screen.queryByRole('link')).toBeInTheDocument();
+            expect(link).toHaveAttribute('aria-disabled');
+            // Simulate standard disabled state (not focusable)
+            expect(link).toHaveAttribute('tabindex', '-1');
+            await userEvent.click(link);
+            expect(onClick).not.toHaveBeenCalled();
+        });
+
+        it('should render aria-disabled button', async () => {
+            const onClick = vi.fn();
+            const { link } = setup({ children: 'Label', 'aria-disabled': true, onClick });
+            expect(screen.queryByRole('button')).toBeInTheDocument();
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            expect(link).not.toHaveAttribute('tabindex');
+            await userEvent.click(link);
+            expect(onClick).not.toHaveBeenCalled();
+        });
+
+        it('should render aria-disabled link', async () => {
+            const onClick = vi.fn();
+            const { link } = setup({
+                children: 'Label',
+                'aria-disabled': true,
+                href: 'https://example.com',
+                onClick,
+            });
+            expect(link).toHaveAccessibleName('Label');
+            expect(screen.queryByRole('link')).toBeInTheDocument();
+            expect(link).toHaveAttribute('aria-disabled', 'true');
+            await userEvent.click(link);
+            expect(onClick).not.toHaveBeenCalled();
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardAttributes: 'link',
+        forwardClassName: 'link',
+        forwardRef: 'link',
+    });
+});

package/src/components/link/Link.tsx

@@ -0,0 +1,106 @@
+import classNames from 'classnames';
+
+import { ColorVariant, ColorWithVariants, Icon, Typography } from '@lumx/react';
+import { GenericProps } from '@lumx/react/utils/type';
+import {
+    getRootClassName,
+    getTypographyClassName,
+    handleBasicClasses,
+    resolveColorWithVariants,
+} from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { wrapChildrenIconWithSpaces } from '@lumx/react/utils/react/wrapChildrenIconWithSpaces';
+import { HasAriaDisabled } from '@lumx/react/utils/type/HasAriaDisabled';
+import { RawClickable } from '@lumx/react/utils/react/RawClickable';
+import { useDisableStateProps } from '@lumx/react/utils/disabled';
+
+type HTMLAnchorProps = React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface LinkProps extends GenericProps, HasAriaDisabled {
+    /** Color variant. */
+    color?: ColorWithVariants;
+    /** Lightened or darkened variant of the selected icon color. */
+    colorVariant?: ColorVariant;
+    /** Link href. */
+    href?: HTMLAnchorProps['href'];
+    /** Whether the component is disabled or not. */
+    isDisabled?: boolean;
+    /**
+     * Left icon (SVG path).
+     * @deprecated Instead, simply nest `<Icon />` in the children
+     */
+    leftIcon?: string;
+    /** Custom react component for the link (can be used to inject react router Link). */
+    linkAs?: 'a' | any;
+    /**
+     * Right icon (SVG path).
+     * @deprecated Instead, simply nest `<Icon />` in the children
+     */
+    rightIcon?: string;
+    /** Link target. */
+    target?: HTMLAnchorProps['target'];
+    /** Typography variant. */
+    typography?: Typography;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Link';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Link component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Link = forwardRef<LinkProps, HTMLAnchorElement | HTMLButtonElement>((props, ref) => {
+    const { disabledStateProps, otherProps } = useDisableStateProps(props);
+    const {
+        children,
+        className,
+        color: propColor,
+        colorVariant: propColorVariant,
+        leftIcon,
+        rightIcon,
+        typography,
+        linkAs,
+        ...forwardedProps
+    } = otherProps;
+    const [color, colorVariant] = resolveColorWithVariants(propColor, propColorVariant);
+
+    return (
+        <RawClickable
+            ref={ref as any}
+            as={linkAs || (forwardedProps.href ? 'a' : 'button')}
+            {...forwardedProps}
+            {...disabledStateProps}
+            className={classNames(
+                className,
+                handleBasicClasses({ prefix: CLASSNAME, color, colorVariant, hasTypography: !!typography }),
+                typography && getTypographyClassName(typography),
+            )}
+        >
+            {wrapChildrenIconWithSpaces(
+                <>
+                    {leftIcon && <Icon icon={leftIcon} className={`${CLASSNAME}__left-icon`} />}
+                    {children && <span className={`${CLASSNAME}__content`}>{children}</span>}
+                    {rightIcon && <Icon icon={rightIcon} className={`${CLASSNAME}__right-icon`} />}
+                </>,
+            )}
+        </RawClickable>
+    );
+});
+Link.displayName = COMPONENT_NAME;
+Link.className = CLASSNAME;

package/src/components/link/index.ts

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

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

@@ -0,0 +1,61 @@
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { headingElementArgType } from '@lumx/react/stories/controls/element';
+import { loremIpsum } from '@lumx/react/stories/utils/lorem';
+import { LANDSCAPE_IMAGES } from '@lumx/react/stories/controls/image';
+import { withNestedProps } from '@lumx/react/stories/decorators/withNestedProps';
+import { withWrapper } from '@lumx/react/stories/decorators/withWrapper';
+
+import { Size } from '@lumx/core/js/constants';
+import { LinkPreview, LinkPreviewProps } from './LinkPreview';
+
+export default {
+    title: 'LumX components/link-preview/Link preview',
+    component: LinkPreview,
+    decorators: [withNestedProps()],
+    args: {
+        ...LinkPreview.defaultProps,
+        title: '',
+        description: '',
+        link: 'https://example.com',
+    },
+    argTypes: {
+        size: getSelectArgType<LinkPreviewProps['size']>([Size.regular, Size.big]),
+        titleHeading: { if: { arg: 'title' }, ...headingElementArgType },
+    },
+};
+
+/**
+ * Default link preview with only the required props (link)
+ */
+export const Default = {};
+
+/**
+ * Link preview with title and description
+ */
+export const TitleAndDescription = {
+    args: {
+        title: 'Link title',
+        description: loremIpsum('short'),
+    },
+};
+
+/**
+ * Link preview with title, description and thumbnail
+ */
+export const AllFields = {
+    args: {
+        ...TitleAndDescription.args,
+        'thumbnailProps.image': LANDSCAPE_IMAGES.landscape1,
+    },
+};
+
+/**
+ * Big link preview with title, description and thumbnail
+ */
+export const Big = {
+    decorators: [withWrapper({ style: { width: '400px' } })],
+    args: {
+        ...AllFields.args,
+        size: Size.big,
+    },
+};