@lumx/react 3.0.7 → 3.1.0

package/dist/src/components/tooltip/useInjectTooltipRef.tsx

@@ -0,0 +1,44 @@
+import { mergeRefs } from '@lumx/react/utils/mergeRefs';
+import get from 'lodash/get';
+import React, { cloneElement, ReactNode, useMemo } from 'react';
+
+/**
+ * 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>.
+ *
+ * @param  children         Original tooltip anchor.
+ * @param  setAnchorElement Set tooltip anchor element.
+ * @param  isOpen           Whether the tooltip is open or not.
+ * @param  id               Tooltip id.
+ * @return tooltip anchor.
+ */
+export const useInjectTooltipRef = (
+    children: ReactNode,
+    setAnchorElement: (e: HTMLDivElement) => void,
+    isOpen: boolean,
+    id: string,
+): ReactNode => {
+    return useMemo(() => {
+        const ariaProps = { 'aria-describedby': isOpen ? id : undefined };
+        if (
+            children &&
+            get(children, '$$typeof') &&
+            get(children, 'props.disabled') !== true &&
+            get(children, 'props.isDisabled') !== true
+        ) {
+            const element = children as any;
+
+            return cloneElement(element, {
+                ...element.props,
+                ...ariaProps,
+                ref: mergeRefs(element.ref, setAnchorElement),
+            });
+        }
+        return (
+            <div className="lumx-tooltip-anchor-wrapper" ref={setAnchorElement} {...ariaProps}>
+                {children}
+            </div>
+        );
+    }, [isOpen, id, children, setAnchorElement]);
+};

package/dist/src/components/tooltip/useTooltipOpen.tsx

@@ -0,0 +1,113 @@
+import { onEscapePressed } from '@lumx/react/utils/event';
+import { useEffect, useState } from 'react';
+import { browserDoesNotSupportHover } from '@lumx/react/utils/browserDoesNotSupportHover';
+import { TOOLTIP_HOVER_DELAY, TOOLTIP_LONG_PRESS_DELAY } from '@lumx/react/constants';
+
+/**
+ * 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): boolean {
+    const [isOpen, setIsOpen] = useState(false);
+
+    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);
+            timer = setTimeout(() => {
+                setIsOpen(!!shouldOpen);
+            }, duration) as any;
+        };
+
+        const hoverNotSupported = browserDoesNotSupportHover();
+        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 close = (overrideDelay = closeDelay) => {
+            if (!shouldOpen && !timer) return;
+            shouldOpen = false;
+            deferUpdate(overrideDelay);
+        };
+        const closeImmediately = () => close(0);
+
+        /**
+         * Handle touchend event
+         * If `touchend` comes before the open delay => cancel tooltip (close immediate).
+         * Else if `touchend` comes after the open delay => tooltip takes priority, the anchor's default touch end event is prevented.
+         */
+        const touchEnd = (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();
+            }
+        };
+
+        // Adapt event to browsers with or without `hover` support.
+        const events: Array<[Node, Event['type'], any]> = hoverNotSupported
+            ? [
+                  [anchorElement, hasTouch ? 'touchstart' : 'mousedown', open],
+                  [anchorElement, hasTouch ? 'touchend' : 'mouseup', touchEnd],
+              ]
+            : [
+                  [anchorElement, 'mouseenter', open],
+                  [anchorElement, 'mouseleave', close],
+                  [anchorElement, 'mouseup', closeImmediately],
+              ];
+
+        // Events always applied no matter the browser:.
+        events.push(
+            // Open on focus.
+            [anchorElement, 'focusin', open],
+            // Close on lost focus.
+            [anchorElement, 'focusout', closeImmediately],
+            // Close on ESC keydown
+            [anchorElement, 'keydown', onEscapePressed(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;
+}

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

@@ -0,0 +1,87 @@
+import React, { ReactElement } from 'react';
+
+import { mount, shallow } from 'enzyme';
+import 'jest-enzyme';
+
+import { commonTestsSuite, Wrapper } from '@lumx/react/testing/utils';
+import { getBasicClass } from '@lumx/react/utils/className';
+
+import { Uploader, UploaderProps } from './Uploader';
+
+const DEFAULT_PROPS = Uploader.defaultProps as any;
+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 = {}, shallowRendering = true) => {
+    const props: any = { ...propsOverride };
+    const renderer: (el: ReactElement) => Wrapper = shallowRendering ? shallow : mount;
+    const wrapper: Wrapper = renderer(<Uploader {...props} />);
+
+    return { props, wrapper };
+};
+
+describe(`<${Uploader.displayName}>`, () => {
+    // 1. Test render via snapshot (default states of component).
+    describe('Snapshots and structure', () => {
+        // Here is an example of a basic rendering check, with snapshot.
+
+        it('should render correctly', () => {
+            const { wrapper } = setup();
+            expect(wrapper).toMatchSnapshot();
+
+            expect(wrapper).toExist();
+            expect(wrapper).toHaveClassName(CLASSNAME);
+        });
+    });
+
+    // 2. Test defaultProps value and important props custom values.
+    describe('Props', () => {
+        // Here are some examples of basic props check.
+
+        it('should use default props', () => {
+            const { wrapper } = setup();
+
+            Object.keys(DEFAULT_PROPS).forEach((prop: string) => {
+                expect(wrapper).toHaveClassName(
+                    getBasicClass({ prefix: CLASSNAME, type: prop, value: DEFAULT_PROPS[prop] }),
+                );
+            });
+        });
+    });
+
+    // 3. Test events.
+    describe('Events', () => {
+        // Here is an example how to check a `onClick` event.
+
+        const onClick: jest.Mock = jest.fn();
+
+        beforeEach(() => {
+            onClick.mockClear();
+        });
+
+        it('should trigger `onClick` when clicked', () => {
+            const { wrapper } = setup({ onClick }, false);
+
+            wrapper.simulate('click');
+
+            expect(onClick).toHaveBeenCalled();
+        });
+    });
+
+    // 4. Test conditions (i.e. things that display or not in the UI based on props).
+    describe('Conditions', () => {
+        // Nothing to do here.
+    });
+
+    // 5. Test state.
+    describe('State', () => {
+        // Nothing to do here.
+    });
+
+    // Common tests suite.
+    commonTestsSuite(setup, { className: 'wrapper', prop: 'wrapper' }, { className: CLASSNAME });
+});

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

@@ -0,0 +1,105 @@
+import React, { forwardRef, MouseEventHandler } from 'react';
+
+import classNames from 'classnames';
+
+import { AspectRatio, Icon, Size, Theme } from '@lumx/react';
+import { Comp, GenericProps, HasTheme, ValueOf } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+
+/**
+ * Uploader variants.
+ */
+export const UploaderVariant = {
+    square: 'square',
+    rounded: 'rounded',
+    circle: 'circle',
+} as const;
+export type UploaderVariant = ValueOf<typeof UploaderVariant>;
+
+/**
+ * Uploader sizes.
+ */
+export type UploaderSize = Extract<Size, 'xl' | 'xxl'>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface UploaderProps extends GenericProps, HasTheme {
+    /** Image aspect ratio. */
+    aspectRatio?: AspectRatio;
+    /** Icon (SVG path). */
+    icon?: string;
+    /** Label text. */
+    label?: string;
+    /** Size variant. */
+    size?: UploaderSize;
+    /** Variant. */
+    variant?: UploaderVariant;
+    /** On click callback. */
+    onClick?: MouseEventHandler<HTMLDivElement>;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Uploader';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<UploaderProps> = {
+    aspectRatio: AspectRatio.horizontal,
+    size: Size.xl,
+    theme: Theme.light,
+    variant: UploaderVariant.square,
+};
+
+/**
+ * Uploader component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Uploader: Comp<UploaderProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const { aspectRatio, className, label, icon, size, theme, variant, ...forwardedProps } = props;
+    // Adjust to square aspect ratio when using circle variants.
+    const adjustedAspectRatio = variant === UploaderVariant.circle ? AspectRatio.square : aspectRatio;
+
+    return (
+        <div
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    aspectRatio: adjustedAspectRatio,
+                    prefix: CLASSNAME,
+                    size,
+                    theme,
+                    variant,
+                }),
+            )}
+        >
+            <div className={`${CLASSNAME}__background`} />
+
+            <div className={`${CLASSNAME}__wrapper`}>
+                {icon && (
+                    <div className={`${CLASSNAME}__icon`}>
+                        <Icon icon={icon} size={Size.s} />
+                    </div>
+                )}
+
+                {label && <span className={`${CLASSNAME}__label`}>{label}</span>}
+            </div>
+        </div>
+    );
+});
+Uploader.displayName = COMPONENT_NAME;
+Uploader.className = CLASSNAME;
+Uploader.defaultProps = DEFAULT_PROPS;

package/dist/src/components/uploader/__snapshots__/Uploader.test.tsx.snap

@@ -0,0 +1,14 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<Uploader> Snapshots and structure should render correctly 1`] = `
+<div
+  className="lumx-uploader lumx-uploader--aspect-ratio-horizontal lumx-uploader--size-xl lumx-uploader--theme-light lumx-uploader--variant-square"
+>
+  <div
+    className="lumx-uploader__background"
+  />
+  <div
+    className="lumx-uploader__wrapper"
+  />
+</div>
+`;

package/dist/src/components/uploader/index.ts

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

package/dist/src/components/user-block/UserBlock.stories.tsx

@@ -0,0 +1,76 @@
+import React from 'react';
+
+import { mdiStar } from '@lumx/icons';
+import { Badge, ColorPalette, Icon, Size } from '@lumx/react';
+import { avatarImageKnob } from '@lumx/react/stories/knobs/image';
+import { CustomLink } from '@lumx/react/stories/utils/CustomLink';
+
+import { UserBlock } from './UserBlock';
+
+export default { title: 'LumX components/user-block/UserBlock' };
+
+const logAction = (action: string) => () => console.log(action);
+const sizes = [Size.s, Size.m, Size.l];
+
+export const Default = ({ theme }: any) => (
+    <UserBlock
+        theme={theme}
+        name="Emmitt O. Lum"
+        fields={['Creative developer', 'Denpasar']}
+        avatarProps={{ image: avatarImageKnob() }}
+        onMouseEnter={logAction('Mouse entered')}
+        onMouseLeave={logAction('Mouse left')}
+    />
+);
+
+export const Sizes = ({ theme }: any) =>
+    sizes.map((size) => (
+        <UserBlock
+            key={size}
+            theme={theme}
+            name="Emmitt O. Lum"
+            fields={['Creative developer', 'Denpasar']}
+            avatarProps={{ image: avatarImageKnob() }}
+            size={size}
+            onMouseEnter={logAction('Mouse entered')}
+            onMouseLeave={logAction('Mouse left')}
+        />
+    ));
+
+export const Clickable = ({ theme }: any) => {
+    const baseProps = {
+        theme,
+        name: 'Emmitt O. Lum',
+        nameProps: { 'aria-label': 'Emmitt O. Lum - open user profile' },
+        fields: ['Creative developer', 'Denpasar'],
+        avatarProps: { image: avatarImageKnob() },
+    } as any;
+    return (
+        <>
+            <p>As a button</p>
+            <UserBlock {...baseProps} onClick={logAction('UserBlock clicked')} />
+
+            <p>As a link</p>
+            <UserBlock {...baseProps} linkProps={{ href: 'https://example.com' }} />
+
+            <p>As a custom link component</p>
+            <UserBlock {...baseProps} linkAs={CustomLink} />
+        </>
+    );
+};
+
+export const WithBadge = ({ theme }: any) => (
+    <UserBlock
+        theme={theme}
+        name="Emmitt O. Lum"
+        fields={['Creative developer', 'Denpasar']}
+        avatarProps={{
+            image: avatarImageKnob(),
+            badge: (
+                <Badge color={ColorPalette.blue}>
+                    <Icon icon={mdiStar} />
+                </Badge>
+            ),
+        }}
+    />
+);

package/dist/src/components/user-block/UserBlock.test.tsx

@@ -0,0 +1,38 @@
+import React, { ReactElement } from 'react';
+
+import { mount, shallow } from 'enzyme';
+import 'jest-enzyme';
+
+import { commonTestsSuite, itShouldRenderStories, Wrapper } from '@lumx/react/testing/utils';
+
+import { UserBlock, UserBlockProps } from './UserBlock';
+import * as stories from './UserBlock.stories';
+
+const CLASSNAME = UserBlock.className as string;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = ({ ...propsOverride }: Partial<UserBlockProps> = {}, shallowRendering = true) => {
+    const props: UserBlockProps = { ...propsOverride };
+    const renderer: (el: ReactElement) => Wrapper = shallowRendering ? shallow : mount;
+    const wrapper: Wrapper = renderer(<UserBlock {...props} />);
+
+    return { props, wrapper };
+};
+
+describe(`<${UserBlock.displayName}>`, () => {
+    // 1. Test render via snapshot.
+    describe('Snapshots and structure', () => {
+        itShouldRenderStories(stories, UserBlock);
+
+        it('should forward name props', () => {
+            const { wrapper } = setup({ name: 'John Doe', nameProps: { 'data-custom-attribute': true } });
+
+            expect(wrapper.find('.lumx-user-block__name[data-custom-attribute]')).toHaveLength(1);
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuite(setup, { className: 'wrapper', prop: 'wrapper' }, { className: CLASSNAME });
+});

package/dist/src/components/user-block/UserBlock.tsx

@@ -0,0 +1,179 @@
+import React, { forwardRef, ReactNode } from 'react';
+import isEmpty from 'lodash/isEmpty';
+import classNames from 'classnames';
+import set from 'lodash/set';
+
+import { Avatar, ColorPalette, Link, Orientation, Size, Theme } from '@lumx/react';
+import { Comp, GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+
+import { AvatarProps } from '../avatar/Avatar';
+
+/**
+ * User block sizes.
+ */
+export type UserBlockSize = Extract<Size, 's' | 'm' | 'l'>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface UserBlockProps extends GenericProps, HasTheme {
+    /** Props to pass to the avatar. */
+    avatarProps?: Omit<AvatarProps, 'alt'>;
+    /** Additional fields used to describe the user. */
+    fields?: string[];
+    /** Props to pass to the link wrapping the avatar thumbnail. */
+    linkProps?: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;
+    /** Custom react component for the link (can be used to inject react router Link). */
+    linkAs?: 'a' | any;
+    /** Multiple action toolbar content. */
+    multipleActions?: ReactNode;
+    /** User name. */
+    name?: string;
+    /** Props to pass to the name block. */
+    nameProps?: GenericProps;
+    /** Orientation. */
+    orientation?: Orientation;
+    /** Simple action toolbar content. */
+    simpleAction?: ReactNode;
+    /** Size variant. */
+    size?: UserBlockSize;
+    /** On click callback. */
+    onClick?(): void;
+    /** On mouse enter callback. */
+    onMouseEnter?(): void;
+    /** On mouse leave callback. */
+    onMouseLeave?(): void;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'UserBlock';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<UserBlockProps> = {
+    orientation: Orientation.horizontal,
+    size: Size.m,
+    theme: Theme.light,
+};
+
+/**
+ * UserBlock component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const UserBlock: Comp<UserBlockProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const {
+        avatarProps,
+        className,
+        fields,
+        linkProps,
+        linkAs,
+        multipleActions,
+        name,
+        nameProps,
+        onClick,
+        onMouseEnter,
+        onMouseLeave,
+        orientation,
+        simpleAction,
+        size,
+        theme,
+        ...forwardedProps
+    } = props;
+    let componentSize = size;
+
+    // Special case - When using vertical orientation force the size to be Sizes.l.
+    if (orientation === Orientation.vertical) {
+        componentSize = Size.l;
+    }
+
+    const shouldDisplayActions: boolean = orientation === Orientation.vertical;
+
+    const isLink = Boolean(linkProps?.href || linkAs);
+    const isClickable = !!onClick || isLink;
+
+    const nameBlock: ReactNode = React.useMemo(() => {
+        if (isEmpty(name)) {
+            return null;
+        }
+        let NameComponent: any = 'span';
+        const nProps: any = {
+            ...nameProps,
+            className: classNames(`${CLASSNAME}__name`, linkProps?.className, nameProps?.className),
+        };
+        if (isClickable) {
+            NameComponent = Link;
+            Object.assign(nProps, {
+                ...linkProps,
+                onClick,
+                linkAs,
+                color: ColorPalette.dark,
+            });
+        }
+        // Disable avatar focus since the name block is the same link / same button.
+        if (avatarProps) {
+            set(avatarProps, ['thumbnailProps', 'tabIndex'], -1);
+        }
+        return <NameComponent {...nProps}>{name}</NameComponent>;
+    }, [avatarProps, isClickable, linkAs, linkProps, name, nameProps, onClick]);
+
+    const fieldsBlock: ReactNode = fields && componentSize !== Size.s && (
+        <div className={`${CLASSNAME}__fields`}>
+            {fields.map((field: string, idx: number) => (
+                <span key={idx} className={`${CLASSNAME}__field`}>
+                    {field}
+                </span>
+            ))}
+        </div>
+    );
+
+    return (
+        <div
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({ prefix: CLASSNAME, orientation, size: componentSize, theme, isClickable }),
+            )}
+            onMouseLeave={onMouseLeave}
+            onMouseEnter={onMouseEnter}
+        >
+            {avatarProps && (
+                <Avatar
+                    linkAs={linkAs}
+                    linkProps={linkProps}
+                    alt=""
+                    {...(avatarProps as any)}
+                    className={classNames(`${CLASSNAME}__avatar`, avatarProps.className)}
+                    size={componentSize}
+                    onClick={onClick}
+                    theme={theme}
+                />
+            )}
+            {(fields || name) && (
+                <div className={`${CLASSNAME}__wrapper`}>
+                    {nameBlock}
+                    {fieldsBlock}
+                </div>
+            )}
+            {shouldDisplayActions && simpleAction && <div className={`${CLASSNAME}__action`}>{simpleAction}</div>}
+            {shouldDisplayActions && multipleActions && (
+                <div className={`${CLASSNAME}__actions`}>{multipleActions}</div>
+            )}
+        </div>
+    );
+});
+UserBlock.displayName = COMPONENT_NAME;
+UserBlock.className = CLASSNAME;
+UserBlock.defaultProps = DEFAULT_PROPS;