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

package/src/components/uploader/Uploader.tsx

@@ -0,0 +1,177 @@
+import React, { MouseEventHandler } from 'react';
+
+import classNames from 'classnames';
+
+import { AspectRatio, Icon, Size, Theme } from '@lumx/react';
+import { GenericProps, HasTheme, ValueOf } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { useBooleanState } from '@lumx/react/hooks/useBooleanState';
+import { useId } from '@lumx/react/hooks/useId';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { HasAriaDisabled } from '@lumx/react/utils/type/HasAriaDisabled';
+import { useDisableStateProps } from '@lumx/react/utils/disabled';
+import { VISUALLY_HIDDEN } from '@lumx/react/constants';
+
+/**
+ * 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'>;
+
+/**
+ * Extend native HTML input props with specialized `onChange` providing the a `File` array.
+ */
+interface FileInputProps extends Omit<React.ComponentProps<'input'>, 'onChange'> {
+    onChange(files: File[], evt: React.ChangeEvent<HTMLInputElement>): void;
+}
+
+/**
+ * Defines the props of the component.
+ */
+export interface UploaderProps extends GenericProps, HasTheme, HasAriaDisabled {
+    /** Image aspect ratio. */
+    aspectRatio?: AspectRatio;
+    /** Icon (SVG path). */
+    icon?: string;
+    /** Disabled state */
+    isDisabled?: boolean;
+    /** Label text. */
+    label?: string;
+    /** Size variant. */
+    size?: UploaderSize;
+    /** Variant. */
+    variant?: UploaderVariant;
+    /** On click callback. */
+    onClick?: MouseEventHandler;
+    /** Handle file selection with a native input file. */
+    fileInputProps?: FileInputProps;
+}
+
+/**
+ * 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,
+    variant: UploaderVariant.square,
+};
+
+/**
+ * Uploader component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Uploader = forwardRef<UploaderProps>((props, ref) => {
+    const { disabledStateProps, otherProps, isAnyDisabled } = useDisableStateProps(props);
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        aspectRatio = DEFAULT_PROPS.aspectRatio,
+        className,
+        label,
+        icon,
+        size = DEFAULT_PROPS.size,
+        theme = defaultTheme,
+        variant = DEFAULT_PROPS.variant,
+        fileInputProps,
+        onClick,
+        ...forwardedProps
+    } = otherProps;
+    // Adjust to square aspect ratio when using circle variants.
+    const adjustedAspectRatio = variant === UploaderVariant.circle ? AspectRatio.square : aspectRatio;
+
+    const handleClick: React.MouseEventHandler = React.useCallback(
+        (evt) => {
+            if (isAnyDisabled) {
+                evt.preventDefault();
+            } else {
+                onClick?.(evt);
+            }
+        },
+        [isAnyDisabled, onClick],
+    );
+
+    const generatedInputId = useId();
+    const inputId = fileInputProps?.id || generatedInputId;
+    const [isDragHovering, unsetDragHovering, setDragHovering] = useBooleanState(false);
+    const wrapper = fileInputProps
+        ? ({ Component: 'label', props: { htmlFor: inputId } } as const)
+        : ({ Component: 'button', props: { type: 'button', ...disabledStateProps } } as const);
+
+    const onChange = React.useMemo(() => {
+        if (isAnyDisabled || !fileInputProps?.onChange) return undefined;
+        return (evt: React.ChangeEvent<HTMLInputElement>) => {
+            const fileList = evt.target.files;
+            const files = fileList ? Array.from(fileList) : [];
+            fileInputProps.onChange(files, evt);
+        };
+    }, [isAnyDisabled, fileInputProps]);
+
+    return (
+        <wrapper.Component
+            ref={ref as any}
+            {...wrapper.props}
+            {...forwardedProps}
+            onClick={handleClick}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    aspectRatio: adjustedAspectRatio,
+                    prefix: CLASSNAME,
+                    size,
+                    theme,
+                    variant,
+                    isDragHovering,
+                    isDisabled: isAnyDisabled,
+                }),
+            )}
+        >
+            <span className={`${CLASSNAME}__background`} />
+
+            <span className={`${CLASSNAME}__wrapper`}>
+                {icon && <Icon className={`${CLASSNAME}__icon`} icon={icon} size={Size.s} />}
+
+                {label && <span className={`${CLASSNAME}__label`}>{label}</span>}
+            </span>
+
+            {fileInputProps && (
+                <input
+                    type="file"
+                    id={inputId}
+                    className={`${CLASSNAME}__input ${VISUALLY_HIDDEN}`}
+                    {...disabledStateProps}
+                    {...fileInputProps}
+                    readOnly={isAnyDisabled}
+                    onChange={onChange}
+                    onDragEnter={setDragHovering}
+                    onDragLeave={unsetDragHovering}
+                    onDrop={unsetDragHovering}
+                />
+            )}
+        </wrapper.Component>
+    );
+});
+Uploader.displayName = COMPONENT_NAME;
+Uploader.className = CLASSNAME;
+Uploader.defaultProps = DEFAULT_PROPS;

package/src/components/uploader/index.ts

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

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

@@ -0,0 +1,133 @@
+/* eslint-disable jsx-a11y/anchor-is-valid */
+import { mdiMenuDown, mdiStar } from '@lumx/icons';
+import { Badge, ColorPalette, Icon, IconButton, Link, Orientation, Size, Text } from '@lumx/react';
+import { CustomLink } from '@lumx/react/stories/utils/CustomLink';
+
+import { AVATAR_IMAGES } from '@lumx/react/stories/controls/image';
+import { withCombinations } from '@lumx/react/stories/decorators/withCombinations';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { withResizableBox } from '@lumx/react/stories/decorators/withResizableBox';
+import { UserBlock } from './UserBlock';
+
+const sizes = [Size.xs, Size.s, Size.m, Size.l];
+
+export default {
+    title: 'LumX components/user-block/UserBlock',
+    component: UserBlock,
+    args: UserBlock.defaultProps,
+    argTypes: {
+        size: getSelectArgType(sizes),
+        orientation: getSelectArgType(Orientation),
+    },
+    decorators: [withResizableBox({ width: 'auto', minWidth: 'min-content', height: 'auto' })],
+};
+
+/** Only an avatar */
+export const AvatarOnly = {
+    args: { avatarProps: { image: AVATAR_IMAGES.avatar1 } },
+};
+
+/** Avatar and name */
+export const AvatarAndName = {
+    args: { ...AvatarOnly.args, name: 'Emmitt O. Lum' },
+};
+
+/** Avatar and children */
+export const AvatarAndCustomName = {
+    args: {
+        ...AvatarOnly.args,
+        name: (
+            <Text as="span" color="green">
+                Emmitt O. Lum
+            </Text>
+        ),
+    },
+};
+
+/** Avatar, name and secondary fields */
+export const AvatarAndNameAndSecondaryFields = {
+    args: {
+        ...AvatarAndName.args,
+        fields: ['Creative developer', 'Denpasar'],
+    },
+};
+
+/** With Right component */
+export const WithAfter = {
+    args: {
+        ...AvatarAndNameAndSecondaryFields.args,
+        after: <IconButton label="View" icon={mdiMenuDown} emphasis="low" />,
+    },
+};
+
+/** With after component */
+export const WithAdditionalFields = {
+    args: {
+        ...AvatarAndName.args,
+        fields: [
+            <Text key={0} as="span" color="dark">
+                Published a post in <Link href="#">Space</Link>
+            </Text>,
+            <time key={1}>May 13, 2025</time>,
+        ],
+        additionalFields: (
+            <Text as="span" typography="body1">
+                Works at the Toronto office
+            </Text>
+        ),
+    },
+    parameters: {
+        // Testing constrained space
+        wrapperProps: { style: { width: 245 } },
+    },
+};
+
+/** Size variants */
+export const SizesAndOrientations = {
+    args: AvatarAndNameAndSecondaryFields.args,
+    decorators: [
+        withCombinations({
+            combinations: {
+                rows: { key: 'size', options: sizes },
+                cols: { key: 'orientation', options: Object.values(Orientation) },
+            },
+        }),
+    ],
+};
+
+/** Setting `onClick` to use it as a button */
+export const AsButton = {
+    args: AvatarAndNameAndSecondaryFields.args,
+    argTypes: { onClick: { action: true } },
+};
+
+/** Setting the `linkProps` prop to use it as a link */
+export const AsLink = {
+    args: {
+        ...AvatarAndNameAndSecondaryFields.args,
+        linkProps: { href: 'https://example.com' },
+    },
+};
+
+/** Setting the `linkAs` prop to inject a custom link component */
+export const AsCustomLink = {
+    args: {
+        ...AvatarAndNameAndSecondaryFields.args,
+        linkAs: CustomLink,
+    },
+};
+
+/** Setting the `avatarProps.badge` prop to inject a badge */
+export const WithBadge = {
+    args: {
+        ...AvatarAndNameAndSecondaryFields.args,
+        avatarProps: {
+            ...AvatarAndNameAndSecondaryFields.args.avatarProps,
+            badge: (
+                <Badge color={ColorPalette.blue}>
+                    <Icon icon={mdiStar} />
+                </Badge>
+            ),
+        },
+    },
+};

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

@@ -0,0 +1,106 @@
+import { commonTestsSuiteRTL, SetupRenderOptions } from '@lumx/react/testing/utils';
+import { render, within, screen } from '@testing-library/react';
+import { getByClassName, queryByClassName } from '@lumx/react/testing/utils/queries';
+import { Text, Thumbnail } from '@lumx/react';
+import userEvent from '@testing-library/user-event';
+
+import { UserBlock, UserBlockProps } from './UserBlock';
+
+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> = {}, { wrapper }: SetupRenderOptions = {}) => {
+    const props: UserBlockProps = { ...propsOverride };
+
+    render(<UserBlock {...props} />, { wrapper });
+    const userBlock = getByClassName(document.body, CLASSNAME);
+    const name = queryByClassName(userBlock, `${CLASSNAME}__name`);
+    const avatar = queryByClassName(userBlock, `${CLASSNAME}__avatar`);
+    const thumbnail = avatar && queryByClassName(avatar, Thumbnail.className as string);
+    const fields = queryByClassName(userBlock, `${CLASSNAME}__fields`);
+    const after = queryByClassName(userBlock, `${CLASSNAME}__after`);
+
+    return { props, userBlock, name, avatar, thumbnail, fields, after };
+};
+
+describe(`<${UserBlock.displayName}>`, () => {
+    describe('Props', () => {
+        it('should forward name props', () => {
+            const { name } = setup({ name: 'John Doe', nameProps: { 'data-custom-attribute': true } });
+
+            expect(name).toHaveAttribute('data-custom-attribute');
+        });
+
+        it('should render button', async () => {
+            const onClick = vi.fn();
+            const { name, thumbnail } = setup({
+                onClick,
+                name: 'John Doe',
+                avatarProps: { image: 'profile-picture.jpg' },
+            });
+
+            // Button name
+            expect(name?.tagName).toBe('BUTTON');
+            await userEvent.click(name as any);
+            expect(onClick).toHaveBeenCalled();
+
+            // Button thumbnail (but excluded from tab stops)
+            expect(thumbnail?.tagName).toBe('BUTTON');
+            expect(thumbnail?.tabIndex).toBe(-1);
+            onClick.mockClear();
+            await userEvent.click(thumbnail as any);
+            expect(onClick).toHaveBeenCalled();
+        });
+
+        it('should render link', async () => {
+            const { props, name, thumbnail } = setup({
+                linkProps: { href: 'https://example.com' },
+                name: 'John Doe',
+                avatarProps: { image: 'profile-picture.jpg' },
+            });
+
+            // Link name
+            expect(name?.tagName).toBe('A');
+            expect(name).toHaveAttribute('href', props.linkProps?.href);
+
+            // Link thumbnail (but excluded from tab stops)
+            expect(thumbnail?.tagName).toBe('A');
+            expect(thumbnail?.tabIndex).toBe(-1);
+            expect(thumbnail).toHaveAttribute('href', props.linkProps?.href);
+        });
+
+        it('should render fields', () => {
+            const { fields } = setup({ fields: ['Field 1', 'Field 2'] });
+            expect(fields).toBeInTheDocument();
+            expect(within(fields as any).getByText('Field 1')).toBeInTheDocument();
+            expect(within(fields as any).getByText('Field 2')).toBeInTheDocument();
+        });
+
+        it('should render additional fields', () => {
+            setup({ additionalFields: <Text as="span">Works in Toronto</Text> });
+            expect(screen.queryByText(/works in toronto/i)).toBeInTheDocument();
+        });
+
+        it('should render after', () => {
+            const { after } = setup({ after: <Text as="span">After</Text> });
+            expect(after).toBeInTheDocument();
+            expect(screen.queryByText(/after/i)).toBeInTheDocument();
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'userBlock',
+        forwardAttributes: 'userBlock',
+        forwardRef: 'userBlock',
+        applyTheme: {
+            affects: [{ element: 'userBlock' }],
+            viaProp: true,
+            viaContext: true,
+            defaultTheme: 'light',
+        },
+    });
+});

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

@@ -0,0 +1,193 @@
+import React, { ReactNode } from 'react';
+
+import classNames from 'classnames';
+import isEmpty from 'lodash/isEmpty';
+import set from 'lodash/set';
+
+import { Avatar, ColorPalette, Link, Orientation, Size, Theme } from '@lumx/react';
+import { GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { AvatarProps } from '../avatar/Avatar';
+
+/**
+ * User block sizes.
+ */
+export type UserBlockSize = Extract<Size, 'xs' | '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?: React.ReactNode;
+    /** 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;
+    /** Display additional fields below the original name and fields */
+    additionalFields?: React.ReactNode;
+    /** Display an additional element after the entire component. (to the right if orientation is horizontal, at the bottom if orientation is vertical) */
+    after?: React.ReactNode;
+}
+
+/**
+ * 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,
+};
+
+/**
+ * UserBlock component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const UserBlock = forwardRef<UserBlockProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        avatarProps,
+        className,
+        fields,
+        linkProps,
+        linkAs,
+        multipleActions,
+        name,
+        nameProps,
+        onClick,
+        onMouseEnter,
+        onMouseLeave,
+        orientation = DEFAULT_PROPS.orientation,
+        simpleAction,
+        size = DEFAULT_PROPS.size,
+        theme = defaultTheme,
+        children,
+        additionalFields,
+        after,
+        ...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 shouldDisplayFields = componentSize !== Size.s && componentSize !== Size.xs;
+
+    const fieldsBlock: ReactNode = fields && shouldDisplayFields && (
+        <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 || children || additionalFields) && (
+                <div className={`${CLASSNAME}__wrapper`}>
+                    {children || nameBlock}
+                    {fieldsBlock}
+                    {shouldDisplayFields ? additionalFields : null}
+                </div>
+            )}
+            {shouldDisplayActions && simpleAction && <div className={`${CLASSNAME}__action`}>{simpleAction}</div>}
+            {shouldDisplayActions && multipleActions && (
+                <div className={`${CLASSNAME}__actions`}>{multipleActions}</div>
+            )}
+            {after ? <div className={`${CLASSNAME}__after`}>{after}</div> : null}
+        </div>
+    );
+});
+UserBlock.displayName = COMPONENT_NAME;
+UserBlock.className = CLASSNAME;
+UserBlock.defaultProps = DEFAULT_PROPS;

package/src/components/user-block/index.ts

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

package/src/constants.ts

@@ -0,0 +1,27 @@
+export {
+    CSS_PREFIX,
+    DIALOG_TRANSITION_DURATION,
+    NOTIFICATION_TRANSITION_DURATION,
+    TOOLTIP_HOVER_DELAY,
+    TOOLTIP_LONG_PRESS_DELAY,
+} from '@lumx/core/js/constants';
+
+/**
+ * Optional global `window` instance (not defined when running SSR).
+ */
+export const WINDOW = typeof window !== 'undefined' ? window : undefined;
+
+/**
+ * Optional global `document` instance (not defined when running SSR).
+ */
+export const DOCUMENT = typeof document !== 'undefined' ? document : undefined;
+
+/**
+ * Check if we are running in a true browser
+ */
+export const IS_BROWSER = typeof navigator !== 'undefined' && !navigator.userAgent.includes('jsdom');
+
+/**
+ * Visually hidden a11y utility class name
+ */
+export const VISUALLY_HIDDEN = 'visually-hidden';

package/src/hooks/useBooleanState.tsx

@@ -0,0 +1,13 @@
+import { useCallback, useState } from 'react';
+
+export const useBooleanState = (defaultValue: boolean): [boolean, () => void, () => void, () => void] => {
+    const [booleanValue, setBoolean] = useState<boolean>(defaultValue);
+
+    const setToFalse = useCallback(() => setBoolean(false), []);
+
+    const setToTrue = useCallback(() => setBoolean(true), []);
+
+    const toggleBoolean = useCallback(() => setBoolean((previousValue) => !previousValue), []);
+
+    return [booleanValue, setToFalse, setToTrue, toggleBoolean];
+};

package/src/hooks/useCallbackOnEscape.ts

@@ -0,0 +1,34 @@
+import { DOCUMENT } from '@lumx/react/constants';
+import { Callback } from '@lumx/react/utils/type';
+import { onEscapePressed } from '@lumx/core/js/utils';
+import { useEffect } from 'react';
+import { Listener, makeListenerTowerContext } from '@lumx/react/utils/function/makeListenerTowerContext';
+
+const LISTENERS = makeListenerTowerContext();
+
+/**
+ * Register a global listener on 'Escape' key pressed.
+ *
+ * If multiple listener are registered, only the last one is maintained. When a listener is unregistered, the previous
+ * one gets activated again.
+ *
+ * @param callback      Callback
+ * @param closeOnEscape Disables the hook when false
+ */
+export function useCallbackOnEscape(callback: Callback | undefined, closeOnEscape = true) {
+    useEffect(() => {
+        const rootElement = DOCUMENT?.body;
+        if (!closeOnEscape || !callback || !rootElement) {
+            return undefined;
+        }
+        const onKeyDown = onEscapePressed(callback);
+
+        const listener: Listener = {
+            enable: () => rootElement.addEventListener('keydown', onKeyDown),
+            disable: () => rootElement.removeEventListener('keydown', onKeyDown),
+        };
+
+        LISTENERS.register(listener);
+        return () => LISTENERS.unregister(listener);
+    }, [callback, closeOnEscape]);
+}