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

package/src/components/tooltip/Tooltip.tsx

@@ -0,0 +1,165 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+import React, { ReactNode, useState } from 'react';
+
+import classNames from 'classnames';
+
+import { DOCUMENT, VISUALLY_HIDDEN } from '@lumx/react/constants';
+import { GenericProps, HasCloseMode } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { useMergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { Placement } from '@lumx/react/components/popover';
+import { TooltipContextProvider } from '@lumx/react/components/tooltip/context';
+import { useId } from '@lumx/react/hooks/useId';
+import { usePopper } from '@lumx/react/hooks/usePopper';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { ARIA_LINK_MODES, TOOLTIP_ZINDEX } from '@lumx/react/components/tooltip/constants';
+import { Portal } from '@lumx/react/utils';
+import { useInjectTooltipRef } from './useInjectTooltipRef';
+import { useTooltipOpen } from './useTooltipOpen';
+
+/** Position of the tooltip relative to the anchor element. */
+export type TooltipPlacement = Extract<Placement, 'top' | 'right' | 'bottom' | 'left'>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface TooltipProps extends GenericProps, HasCloseMode {
+    /** Anchor (element on which we activate the tooltip). */
+    children: ReactNode;
+    /** Delay (in ms) before closing the tooltip. */
+    delay?: number;
+    /** Whether the tooltip is displayed even without the mouse hovering the anchor. */
+    forceOpen?: boolean;
+    /** Label text. */
+    label?: string | null | false;
+    /** Placement of the tooltip relative to the anchor. */
+    placement?: TooltipPlacement;
+    /** Choose how the tooltip text should link to the anchor */
+    ariaLinkMode?: (typeof ARIA_LINK_MODES)[number];
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Tooltip';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<TooltipProps> = {
+    placement: Placement.BOTTOM,
+    closeMode: 'unmount',
+    ariaLinkMode: 'aria-describedby',
+    zIndex: TOOLTIP_ZINDEX,
+};
+
+/**
+ * Arrow size (in pixel).
+ */
+const ARROW_SIZE = 8;
+
+/**
+ * Tooltip component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Tooltip = forwardRef<TooltipProps, HTMLDivElement>((props, ref) => {
+    const {
+        label,
+        children,
+        className,
+        delay,
+        placement = DEFAULT_PROPS.placement,
+        forceOpen,
+        closeMode = DEFAULT_PROPS.closeMode,
+        ariaLinkMode = DEFAULT_PROPS.ariaLinkMode,
+        zIndex = DEFAULT_PROPS.zIndex,
+        ...forwardedProps
+    } = props;
+    // Disable in SSR.
+    if (!DOCUMENT) {
+        return <>{children}</>;
+    }
+
+    const id = useId();
+
+    const [popperElement, setPopperElement] = useState<null | HTMLElement>(null);
+    const [anchorElement, setAnchorElement] = useState<null | HTMLElement>(null);
+    const { styles, attributes, update } = usePopper(anchorElement, popperElement, {
+        placement,
+        modifiers: [
+            {
+                name: 'offset',
+                options: { offset: [0, ARROW_SIZE] },
+            },
+        ],
+    });
+
+    const position = attributes?.popper?.['data-popper-placement'] ?? placement;
+    const { isOpen: isActivated, onPopperMount } = useTooltipOpen(delay, anchorElement);
+    const isOpen = (isActivated || forceOpen) && !!label;
+    const isMounted = !!label && (isOpen || closeMode === 'hide');
+    const isHidden = !isOpen && closeMode === 'hide';
+    const wrappedChildren = useInjectTooltipRef({
+        children,
+        setAnchorElement,
+        isMounted,
+        id,
+        label,
+        ariaLinkMode: ariaLinkMode as any,
+    });
+
+    // Update on open
+    React.useEffect(() => {
+        if (isOpen || popperElement) update?.();
+    }, [isOpen, update, popperElement]);
+
+    const labelLines = label ? label.split('\n') : [];
+
+    const tooltipRef = useMergeRefs(ref, setPopperElement, onPopperMount);
+
+    return (
+        <>
+            <TooltipContextProvider>{wrappedChildren}</TooltipContextProvider>
+            {isMounted && (
+                <Portal>
+                    <div
+                        ref={tooltipRef}
+                        {...forwardedProps}
+                        id={id}
+                        role="tooltip"
+                        className={classNames(
+                            className,
+                            handleBasicClasses({
+                                prefix: CLASSNAME,
+                                position,
+                                isInitializing: !styles.popper?.transform,
+                            }),
+                            isHidden && VISUALLY_HIDDEN,
+                        )}
+                        style={{ ...(isHidden ? undefined : styles.popper), zIndex }}
+                        {...attributes.popper}
+                    >
+                        <div className={`${CLASSNAME}__arrow`} />
+                        <div className={`${CLASSNAME}__inner`}>
+                            {labelLines.map((line) => (
+                                <p key={line}>{line}</p>
+                            ))}
+                        </div>
+                    </div>
+                </Portal>
+            )}
+        </>
+    );
+});
+Tooltip.displayName = COMPONENT_NAME;
+Tooltip.className = CLASSNAME;
+Tooltip.defaultProps = DEFAULT_PROPS;

package/src/components/tooltip/constants.ts

@@ -0,0 +1,8 @@
+import { POPOVER_ZINDEX } from '../popover/constants';
+
+export const ARIA_LINK_MODES = ['aria-describedby', 'aria-labelledby'] as const;
+
+/**
+ * Make sure tooltip appear above popovers.
+ */
+export const TOOLTIP_ZINDEX = POPOVER_ZINDEX + 1;

package/src/components/tooltip/context.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+/** Empty object */
+type TooltipContextValue = NonNullable<unknown>;
+
+const DEFAULT_VALUE = {};
+
+/**
+ * Tooltip react context simply used as a marker to know when parent react node have a tooltip
+ */
+const TooltipContext = React.createContext<TooltipContextValue | undefined>(undefined);
+
+export const TooltipContextProvider: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+    <TooltipContext.Provider value={DEFAULT_VALUE}>{children}</TooltipContext.Provider>
+);
+
+export const useTooltipContext = () => React.useContext(TooltipContext);

package/src/components/tooltip/index.ts

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

package/src/components/tooltip/useInjectTooltipRef.tsx

@@ -0,0 +1,55 @@
+import React, { cloneElement, ReactNode, useMemo } from 'react';
+
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+
+interface Options {
+    /** Original tooltip anchor */
+    children: ReactNode;
+    /** Set tooltip anchor element */
+    setAnchorElement: (e: HTMLDivElement) => void;
+    /** Whether the tooltip is open or not */
+    isMounted: boolean | undefined;
+    /** Tooltip id */
+    id: string;
+    /** Tooltip label*/
+    label?: string | null | false;
+    /** Choose how the tooltip text should link to the anchor */
+    ariaLinkMode: 'aria-describedby' | 'aria-labelledby';
+}
+
+/**
+ * Add ref and ARIA attribute(s) in tooltip children or wrapped children.
+ * Button, IconButton, Icon and React HTML elements don't need to be wrapped but any other kind of children (array, fragment, custom components)
+ * will be wrapped in a <span>.
+ */
+export const useInjectTooltipRef = (options: Options): ReactNode => {
+    const { children, setAnchorElement, isMounted, id, label, ariaLinkMode } = options;
+    // Only add link when mounted
+    const linkId = isMounted ? id : undefined;
+
+    return useMemo(() => {
+        if (!label) return children;
+
+        // Non-disabled element
+        if (React.isValidElement(children) && children.props.disabled !== true && children.props.isDisabled !== true) {
+            const ref = mergeRefs((children as any).ref, setAnchorElement);
+            const props = { ...children.props, ref };
+
+            // Do not add label/description if the tooltip label is already in aria-label
+            if (linkId && label !== props['aria-label']) {
+                if (props[ariaLinkMode]) props[ariaLinkMode] += ' ';
+                else props[ariaLinkMode] = '';
+                props[ariaLinkMode] += linkId;
+            }
+
+            return cloneElement(children, props);
+        }
+
+        const aria = linkId ? { [ariaLinkMode]: linkId } : undefined;
+        return (
+            <div className="lumx-tooltip-anchor-wrapper" ref={setAnchorElement} {...aria}>
+                {children}
+            </div>
+        );
+    }, [label, children, setAnchorElement, linkId, ariaLinkMode]);
+};

package/src/components/tooltip/useTooltipOpen.tsx

@@ -0,0 +1,143 @@
+import { MutableRefObject, useEffect, useRef, useState } from 'react';
+import { isHoverNotSupported } from '@lumx/react/utils/browser/isHoverNotSupported';
+import { IS_BROWSER, TOOLTIP_HOVER_DELAY, TOOLTIP_LONG_PRESS_DELAY } from '@lumx/react/constants';
+import { useCallbackOnEscape } from '@lumx/react/hooks/useCallbackOnEscape';
+import { isFocusVisible } from '@lumx/react/utils/browser/isFocusVisible';
+
+/**
+ * Hook controlling tooltip visibility using mouse hover the anchor and delay.
+ *
+ * @param  delay         Delay in millisecond to display the tooltip.
+ * @param  anchorElement Tooltip anchor element.
+ * @return whether or not to show the tooltip.
+ */
+export function useTooltipOpen(delay: number | undefined, anchorElement: HTMLElement | null) {
+    const [isOpen, setIsOpen] = useState(false);
+
+    const onPopperMount = useRef<any>(null) as MutableRefObject<(elem: HTMLElement | null) => void>;
+
+    // Global close on escape
+    const [closeCallback, setCloseCallback] = useState<undefined | (() => void)>(undefined);
+    useCallbackOnEscape(isOpen ? closeCallback : undefined);
+
+    useEffect(() => {
+        if (!anchorElement) {
+            return undefined;
+        }
+        let timer: number | undefined;
+        let openStartTime: number | undefined;
+        let shouldOpen: boolean | undefined;
+
+        // Run timer to defer updating the isOpen state.
+        const deferUpdate = (duration: number) => {
+            if (timer) clearTimeout(timer);
+            const update = () => {
+                setIsOpen(!!shouldOpen);
+            };
+            // Skip timeout in fake browsers
+            if (!IS_BROWSER) update();
+            else timer = setTimeout(update, duration) as any;
+        };
+
+        const hoverNotSupported = isHoverNotSupported();
+        const hasTouch = 'ontouchstart' in window;
+
+        // Adapt open/close delay
+        const openDelay = delay || (hoverNotSupported ? TOOLTIP_LONG_PRESS_DELAY.open : TOOLTIP_HOVER_DELAY.open);
+        const closeDelay = hoverNotSupported ? TOOLTIP_LONG_PRESS_DELAY.close : TOOLTIP_HOVER_DELAY.close;
+
+        // Open (or/and cancel closing) of tooltip.
+        const open = () => {
+            if (shouldOpen && !timer) return;
+            shouldOpen = true;
+            openStartTime = Date.now();
+            deferUpdate(openDelay);
+        };
+
+        // Close or cancel opening of tooltip
+        const getClose = (overrideDelay = closeDelay) => {
+            if (!shouldOpen && !timer) return;
+            shouldOpen = false;
+            deferUpdate(overrideDelay);
+        };
+        const close = () => getClose(closeDelay);
+        const closeImmediately = () => getClose(0);
+        setCloseCallback(() => closeImmediately);
+
+        // Adapt event to browsers with or without `hover` support.
+        const events: Array<[Node, Event['type'], any]> = [];
+        if (hoverNotSupported) {
+            /**
+             * Handle touchend event
+             * If end comes before the open delay => cancel tooltip (close immediate).
+             * Else if end comes after the open delay => tooltip takes priority, the anchor's default touch end event is prevented.
+             */
+            const longPressEnd = (evt: Event) => {
+                if (!openStartTime) return;
+                if (Date.now() - openStartTime >= openDelay) {
+                    // Tooltip take priority, event prevented.
+                    evt.stopPropagation();
+                    evt.preventDefault();
+                    anchorElement.focus();
+                    // Close with delay.
+                    close();
+                } else {
+                    // Close immediately.
+                    closeImmediately();
+                }
+            };
+
+            events.push(
+                [anchorElement, hasTouch ? 'touchstart' : 'mousedown', open],
+                [anchorElement, hasTouch ? 'touchend' : 'mouseup', longPressEnd],
+            );
+        } else {
+            events.push(
+                [anchorElement, 'mouseenter', open],
+                [anchorElement, 'mouseleave', close],
+                [anchorElement, 'mouseup', closeImmediately],
+            );
+
+            onPopperMount.current = (popperElement: HTMLElement | null) => {
+                if (!popperElement) return;
+                // Popper element hover
+                popperElement.addEventListener('mouseenter', open);
+                popperElement.addEventListener('mouseleave', close);
+                // Add to event list to remove on unmount
+                events.push([popperElement, 'mouseenter', open], [popperElement, 'mouseleave', close]);
+            };
+        }
+
+        // Events always applied no matter the browser:.
+        events.push(
+            // Open on focus (only if focus is visible).
+            [
+                anchorElement,
+                'focusin',
+                (e: Event) => {
+                    // Skip if focus is not visible
+                    if (!isFocusVisible(e.target as HTMLElement)) return;
+                    open();
+                },
+            ],
+            // Close on lost focus.
+            [anchorElement, 'focusout', closeImmediately],
+        );
+
+        // Attach events
+        for (const [node, eventType, eventHandler] of events) {
+            node.addEventListener(eventType, eventHandler);
+        }
+        return () => {
+            // Clear pending timers.
+            if (timer) clearTimeout(timer);
+
+            // Detach events.
+            for (const [node, eventType, eventHandler] of events) {
+                node.removeEventListener(eventType, eventHandler);
+            }
+        };
+    }, [anchorElement, delay]);
+
+    return { isOpen, onPopperMount: onPopperMount.current };
+}

package/src/components/uploader/Uploader.stories.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import map from 'lodash/map';
+
+import { withCombinations } from '@lumx/react/stories/decorators/withCombinations';
+import { iconArgType } from '@lumx/react/stories/controls/icons';
+import { withNestedProps } from '@lumx/react/stories/decorators/withNestedProps';
+import { withWrapper } from '@lumx/react/stories/decorators/withWrapper';
+
+import { AspectRatio, GridColumn, Size, Uploader, UploaderVariant } from '@lumx/react';
+import { mdiTextBoxPlus } from '@lumx/icons';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { withUndefined } from '@lumx/react/stories/controls/withUndefined';
+
+export default {
+    title: 'LumX components/uploader/Uploader',
+    component: Uploader,
+    argTypes: {
+        onClick: { action: true },
+        icon: iconArgType,
+        aspectRatio: getSelectArgType(AspectRatio),
+    },
+};
+
+const UPLOADER_VARIANTS = [UploaderVariant.square, UploaderVariant.rounded, UploaderVariant.circle];
+const UPLOADER_SIZES = [Size.xl, Size.xxl];
+const ASPECT_RATIOS = [AspectRatio.wide, AspectRatio.horizontal, AspectRatio.vertical, AspectRatio.square];
+
+export const WithLabel = {
+    args: { label: 'Pick a file' },
+};
+
+export const WithLabelAndIcon = {
+    args: { label: 'Pick a file', icon: mdiTextBoxPlus },
+};
+
+// Decorator handling the file input change
+function withFileInputChange() {
+    // eslint-disable-next-line react/display-name
+    return (Story: any, ctx: any) => {
+        const [files, onChange] = React.useState<File[]>([]);
+        return (
+            <>
+                <Story args={{ ...ctx.args, fileInputProps: { ...ctx.args.fileInputProps, onChange } }} />
+                <p>Selection: {map(files, 'name').join(', ')}</p>
+            </>
+        );
+    };
+}
+
+/**
+ * Use the embedded native input file which also make it possible to drop files onto it.
+ */
+export const FileInput = {
+    ...WithLabelAndIcon,
+    decorators: [
+        withNestedProps(),
+        withFileInputChange(),
+        withCombinations({
+            combinations: {
+                sections: {
+                    'Single file': { fileInputProps: {} },
+                    'Multiple files': { fileInputProps: { multiple: true } },
+                    'Images only': { fileInputProps: { multiple: true, accept: 'image/*' } },
+                },
+            },
+        }),
+        withWrapper({ maxColumns: 3, itemMinWidth: 200 }, GridColumn),
+    ],
+};
+
+/** All variants */
+export const Variants = {
+    args: WithLabelAndIcon.args,
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'variant', options: UPLOADER_VARIANTS },
+                cols: {
+                    Default: {},
+                    Disabled: { isDisabled: true },
+                    'Aria Disabled': { 'aria-disabled': true },
+                },
+                sections: {
+                    Button: {},
+                    'File input': { fileInputProps: {} },
+                },
+            },
+        }),
+        withWrapper({ maxColumns: 2, itemMinWidth: 470 }, GridColumn),
+    ],
+};
+
+/** All sizes & ratio */
+export const RatioAndSize = {
+    args: WithLabelAndIcon.args,
+    decorators: [
+        withCombinations({
+            combinations: {
+                cols: { key: 'size', options: UPLOADER_SIZES },
+                rows: { key: 'aspectRatio', options: withUndefined(ASPECT_RATIOS) },
+                sections: {
+                    Button: {},
+                    'File input': { fileInputProps: {} },
+                },
+            },
+        }),
+        withWrapper({ maxColumns: 2, itemMinWidth: 470 }, GridColumn),
+    ],
+};

package/src/components/uploader/Uploader.test.tsx

@@ -0,0 +1,146 @@
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+
+import { render, screen } from '@testing-library/react';
+import { getByClassName, getByTagName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import userEvent from '@testing-library/user-event';
+import { mdiPlus } from '@lumx/icons';
+import { Uploader, UploaderProps } from './Uploader';
+
+const CLASSNAME = Uploader.className as string;
+
+type SetupProps = Partial<UploaderProps>;
+
+/**
+ * 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(<Uploader {...props} />, { wrapper });
+    const uploader = getByClassName(document.body, CLASSNAME);
+    const label = queryByClassName(uploader, `${CLASSNAME}__label`);
+    const icon = queryByClassName(uploader, `${CLASSNAME}__icon`);
+    const input = queryByClassName(uploader, `${CLASSNAME}__input`);
+
+    return { props, uploader, label, icon, input };
+};
+
+describe(`<${Uploader.displayName}>`, () => {
+    describe('Props', () => {
+        it('should render default', () => {
+            const label = 'Label';
+            const { uploader } = setup({ label });
+
+            expect(uploader).toHaveClass(CLASSNAME);
+            expect(uploader).toBe(screen.queryByRole('button', { name: label }));
+            expect(uploader).toHaveClass('lumx-uploader--aspect-ratio-horizontal');
+            expect(uploader).toHaveClass('lumx-uploader--size-xl');
+            expect(uploader).toHaveClass('lumx-uploader--theme-light');
+            expect(uploader).toHaveClass('lumx-uploader--variant-square');
+        });
+
+        it('should render icon', () => {
+            const { icon } = setup({ icon: mdiPlus });
+            expect(icon).toBeInTheDocument();
+        });
+
+        it('should render variant circle', () => {
+            const { uploader } = setup({
+                variant: 'circle',
+                // Ratio should be ignored
+                aspectRatio: 'vertical',
+            });
+
+            expect(uploader).toHaveClass(CLASSNAME);
+            expect(uploader).toHaveClass('lumx-uploader--aspect-ratio-square');
+            expect(uploader).toHaveClass('lumx-uploader--size-xl');
+            expect(uploader).toHaveClass('lumx-uploader--theme-light');
+            expect(uploader).toHaveClass('lumx-uploader--variant-circle');
+        });
+
+        it('should render variant rounded', () => {
+            const { uploader } = setup({ variant: 'rounded' });
+
+            expect(uploader).toHaveClass(CLASSNAME);
+            expect(uploader).toHaveClass('lumx-uploader--aspect-ratio-horizontal');
+            expect(uploader).toHaveClass('lumx-uploader--size-xl');
+            expect(uploader).toHaveClass('lumx-uploader--theme-light');
+            expect(uploader).toHaveClass('lumx-uploader--variant-rounded');
+        });
+
+        it('should render file input', () => {
+            const label = 'Label';
+            const accept = '*';
+            const { uploader } = setup({ label, fileInputProps: { accept } as any });
+
+            expect(uploader.tagName).toBe('LABEL');
+            expect(uploader).toHaveTextContent(label);
+            const inputNative = getByTagName(uploader, 'input');
+            expect(inputNative).toHaveAttribute('type', 'file');
+            expect(inputNative).toHaveAttribute('accept', accept);
+            expect(uploader).toHaveAttribute('for', inputNative.id);
+        });
+    });
+
+    describe.each`
+        name                      | props
+        ${'button'}               | ${{}}
+        ${'button isDisabled   '} | ${{ isDisabled: true }}
+        ${'button aria-disabled'} | ${{ 'aria-disabled': true }}
+        ${'file input          '} | ${{ fileInputProps: { onChange: vi.fn() } }}
+    `('Events $name', ({ props }) => {
+        const onClick = vi.fn();
+        beforeEach(() => onClick.mockClear());
+        const assertClick = () => {
+            if (props.isDisabled || props['aria-disabled']) {
+                expect(onClick).not.toHaveBeenCalled();
+            } else {
+                expect(onClick).toHaveBeenCalled();
+            }
+        };
+
+        it('should trigger `onClick` when clicked', async () => {
+            const { uploader } = setup({ ...props, onClick });
+
+            await userEvent.click(uploader);
+            assertClick();
+        });
+
+        it('should trigger `onClick` when pressing Enter or Escape', async () => {
+            const { uploader, input } = setup({ ...props, onClick });
+
+            if (props.isDisabled) {
+                expect(props.fileInputProps ? input : uploader).toBeDisabled();
+                //Cannot test focus or activation
+                return;
+            }
+
+            await userEvent.tab();
+            expect(props.fileInputProps ? input : uploader).toHaveFocus();
+
+            // Activate with Enter
+            await userEvent.keyboard('[Enter]');
+            assertClick();
+
+            onClick.mockClear();
+
+            // Activate with Space
+            await userEvent.keyboard('[Space]');
+            assertClick();
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'uploader',
+        forwardAttributes: 'uploader',
+        forwardRef: 'uploader',
+        applyTheme: {
+            affects: [{ element: 'uploader' }],
+            viaProp: true,
+            viaContext: true,
+            defaultTheme: 'light',
+        },
+    });
+});