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

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

@@ -1,135 +0,0 @@
-/* eslint-disable jsx-a11y/anchor-is-valid */
-import React from 'react';
-
-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

@@ -1,108 +0,0 @@
-import React from 'react';
-
-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 = jest.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

@@ -1,193 +0,0 @@
-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

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

package/src/constants.ts

@@ -1,27 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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]);
-}

package/src/hooks/useChipGroupNavigation.tsx

@@ -1,75 +0,0 @@
-import { useState } from 'react';
-
-interface UseChipGroupNavigation {
-    /** the current active chip index */
-    activeChip: number;
-
-    /** callback to be executed when the backspace was pressed */
-    onBackspacePressed(): void;
-
-    /** function that allows to reset the navigation */
-    resetChipNavigation(): void;
-}
-
-export type useChipGroupNavigationType<C = any> = (
-    chips: C[],
-    onChipDeleted: (chip: C) => void,
-    initialActiveChip?: number,
-) => UseChipGroupNavigation;
-
-const INITIAL_STATE_ACTIVE_CHIP = -1;
-
-/**
- * Hook that provides the necessary information to manage chips navigation.
- * @param chips             List of chips selected.
- * @param onChipDeleted     Callback executed when a chip must be eliminated.
- * @param initialActiveChip Initial active chip index.
- *
- * @return chip navigation tools.
- */
-export const useChipGroupNavigation: useChipGroupNavigationType = (
-    chips,
-    onChipDeleted,
-    initialActiveChip = INITIAL_STATE_ACTIVE_CHIP,
-) => {
-    const [wasBackspacePressed, setWasBackspacePressed] = useState(false);
-    const [activeChip, setActiveChip] = useState(initialActiveChip);
-
-    /**
-     * Resets the active index and backspace control to their initial state
-     */
-    const resetChipNavigation = () => {
-        setWasBackspacePressed(false);
-        setActiveChip(initialActiveChip);
-    };
-
-    /**
-     * Callback to be executed when the backspace was pressed. If there are no chips
-     * selected, it will return immediately. If there are it will check if the
-     * backspace was already pressed. if it was, it means that the user wants to eliminate
-     * the chip, so we execute the `onChipDeleted` function and reset internal state.
-     *
-     * If it was not pressed before, we set the `wasBackspacePressed` flag to true and
-     * highlight the last chip.
-     */
-    const onBackspacePressed = () => {
-        if (chips.length === 0) {
-            return;
-        }
-
-        if (wasBackspacePressed) {
-            const chipDeleted: any = chips[chips.length - 1];
-            onChipDeleted(chipDeleted);
-            resetChipNavigation();
-        } else {
-            setActiveChip(chips.length - 1);
-            setWasBackspacePressed(true);
-        }
-    };
-
-    return {
-        activeChip,
-        onBackspacePressed,
-        resetChipNavigation,
-    };
-};

package/src/hooks/useClickAway.tsx

@@ -1,48 +0,0 @@
-import { RefObject, useEffect } from 'react';
-
-import { Falsy } from '@lumx/react/utils/type';
-
-import isEmpty from 'lodash/isEmpty';
-
-const EVENT_TYPES = ['mousedown', 'touchstart'];
-
-function isClickAway(targets: HTMLElement[], refs: Array<RefObject<HTMLElement>>): boolean {
-    // The targets elements are not contained in any of the listed element references.
-    return !refs.some((ref) => targets.some((target) => ref?.current?.contains(target)));
-}
-
-export interface ClickAwayParameters {
-    /**
-     * A callback function to call when the user clicks away from the elements.
-     */
-    callback: EventListener | Falsy;
-    /**
-     * Elements considered within the click away context (clicking outside them will trigger the click away callback).
-     */
-    childrenRefs: RefObject<Array<RefObject<HTMLElement>>>;
-}
-
-/**
- * Listen to clicks away from the given elements and callback the passed in function.
- *
- * Warning: If you need to detect click away on nested React portals, please use the `ClickAwayProvider` component.
- */
-export function useClickAway({ callback, childrenRefs }: ClickAwayParameters): void {
-    useEffect(() => {
-        const { current: currentRefs } = childrenRefs;
-        if (!callback || !currentRefs || isEmpty(currentRefs)) {
-            return undefined;
-        }
-        const listener: EventListener = (evt) => {
-            const targets = [evt.composedPath?.()[0], evt.target] as HTMLElement[];
-            if (isClickAway(targets, currentRefs)) {
-                callback(evt);
-            }
-        };
-
-        EVENT_TYPES.forEach((evtType) => document.addEventListener(evtType, listener));
-        return () => {
-            EVENT_TYPES.forEach((evtType) => document.removeEventListener(evtType, listener));
-        };
-    }, [callback, childrenRefs]);
-}

package/src/hooks/useDisableBodyScroll.ts

@@ -1,28 +0,0 @@
-import { useEffect } from 'react';
-import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock';
-import { Falsy } from '@lumx/react/utils/type';
-
-/**
- * Disables the scroll on the body to make it only usable in the current modal element.
- * When the modal element is not provided anymore, the scroll is restored.
- *
- * @param modalElement The modal element.
- */
-export const useDisableBodyScroll = (modalElement: Element | Falsy): void => {
-    useEffect(() => {
-        if (!modalElement) {
-            return undefined;
-        }
-        // Fixing the document overflow style to prevent a bug that scrolls the window to the top.
-        const previousDocumentOverflow = document.documentElement.style.overflow;
-        document.documentElement.style.overflow = 'visible';
-        disableBodyScroll(modalElement);
-        return () => {
-            enableBodyScroll(modalElement);
-            // Restore the previous overflow style.
-            requestAnimationFrame(() => {
-                document.documentElement.style.overflow = previousDocumentOverflow;
-            });
-        };
-    }, [modalElement]);
-};

package/src/hooks/useEventCallback.tsx

@@ -1,17 +0,0 @@
-import React from 'react';
-
-const useEnhancedEffect = typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
-
-/**
- * https://github.com/facebook/react/issues/14099#issuecomment-440013892
- *
- * @param fn A function to run
- * @return A React callback
- */
-export default function useEventCallback(fn: (...args: any[]) => any): (event: any) => any {
-    const ref = React.useRef(fn);
-    useEnhancedEffect(() => {
-        ref.current = fn;
-    });
-    return React.useCallback((event: any) => ref.current(event), []);
-}