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

package/src/components/thumbnail/Thumbnail.tsx

@@ -0,0 +1,248 @@
+import React, {
+    CSSProperties,
+    ImgHTMLAttributes,
+    KeyboardEventHandler,
+    MouseEventHandler,
+    ReactElement,
+    ReactNode,
+    Ref,
+    useState,
+} from 'react';
+
+import classNames from 'classnames';
+
+import { AspectRatio, HorizontalAlignment, Icon, Size, Theme, ThumbnailObjectFit } from '@lumx/react';
+import { Falsy, GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { mdiImageBroken } from '@lumx/icons';
+import { useMergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { useImageLoad } from '@lumx/react/components/thumbnail/useImageLoad';
+import { useFocusPointStyle } from '@lumx/react/components/thumbnail/useFocusPointStyle';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { useDisableStateProps } from '@lumx/react/utils/disabled';
+import { RawClickable } from '@lumx/react/utils/react/RawClickable';
+import { FocusPoint, ThumbnailSize, ThumbnailVariant } from './types';
+
+type ImgHTMLProps = ImgHTMLAttributes<HTMLImageElement>;
+
+/**
+ * Defines the props of the component.
+ */
+export interface ThumbnailProps extends GenericProps, HasTheme {
+    /** Alignment of the thumbnail in it's parent (requires flex parent). */
+    align?: HorizontalAlignment;
+    /** Image alternative text. */
+    alt: string;
+    /** Image aspect ratio. */
+    aspectRatio?: AspectRatio;
+    /** Badge. */
+    badge?: ReactElement | Falsy;
+    /** Image cross origin resource policy. */
+    crossOrigin?: ImgHTMLProps['crossOrigin'];
+    /** Fallback icon (SVG path) or react node when image fails to load. */
+    fallback?: string | ReactNode;
+    /** Whether the thumbnail should fill it's parent size (requires flex parent) or not. */
+    fillHeight?: boolean;
+    /** Apply relative vertical and horizontal shift (from -1 to 1) on the image position inside the thumbnail. */
+    focusPoint?: FocusPoint;
+    /** Image URL. */
+    image: string;
+    /** Props to inject into the native <img> element. */
+    imgProps?: ImgHTMLProps;
+    /** Reference to the native <img> element. */
+    imgRef?: Ref<HTMLImageElement>;
+    /** Set to true to force the display of the loading skeleton. */
+    isLoading?: boolean;
+    /** Set how the image should fit when its aspect ratio is constrained */
+    objectFit?: ThumbnailObjectFit;
+    /** Size variant of the component. */
+    size?: ThumbnailSize;
+    /** Image loading mode. */
+    loading?: ImgHTMLProps['loading'];
+    /** Ref of an existing placeholder image to display while loading. */
+    loadingPlaceholderImageRef?: React.RefObject<HTMLImageElement>;
+    /** On click callback. */
+    onClick?: MouseEventHandler<HTMLDivElement>;
+    /** On key press callback. */
+    onKeyPress?: KeyboardEventHandler<HTMLDivElement>;
+    /** Variant of the component. */
+    variant?: ThumbnailVariant;
+    /** Props to pass to the link wrapping the 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;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Thumbnail';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<ThumbnailProps> = {
+    fallback: mdiImageBroken,
+    loading: 'lazy',
+};
+
+/**
+ * Thumbnail component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Thumbnail = forwardRef<ThumbnailProps>((props, ref) => {
+    const { isAnyDisabled, otherProps, disabledStateProps } = useDisableStateProps(props);
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        align,
+        alt,
+        aspectRatio = AspectRatio.original,
+        badge,
+        className,
+        crossOrigin,
+        fallback = DEFAULT_PROPS.fallback,
+        fillHeight,
+        // `focusPoint` needs to be here to remove it from `forwardedProps`.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        focusPoint,
+        image,
+        imgProps,
+        imgRef: propImgRef,
+        isLoading: isLoadingProp,
+        objectFit,
+        loading = DEFAULT_PROPS.loading,
+        loadingPlaceholderImageRef,
+        size,
+        theme = defaultTheme,
+        variant,
+        linkProps,
+        linkAs,
+        ...forwardedProps
+    } = otherProps;
+    const [imgElement, setImgElement] = useState<HTMLImageElement>();
+
+    // Image loading state.
+    const loadingState = useImageLoad(image, imgElement);
+    const isLoaded = loadingState === 'isLoaded';
+    const isLoading = isLoadingProp || loadingState === 'isLoading';
+    const hasError = loadingState === 'hasError';
+
+    // Focus point.
+    const focusPointStyle = useFocusPointStyle(props, imgElement, isLoaded);
+
+    const hasIconErrorFallback = hasError && typeof fallback === 'string';
+    const hasCustomErrorFallback = hasError && !hasIconErrorFallback;
+    const imageErrorStyle: CSSProperties = {};
+    if (hasIconErrorFallback) {
+        // Keep the image layout on icon fallback.
+        imageErrorStyle.visibility = 'hidden';
+    } else if (hasCustomErrorFallback) {
+        // Remove the image on custom fallback.
+        imageErrorStyle.display = 'none';
+    }
+
+    const isLink = Boolean(linkProps?.href || linkAs);
+    const isClickable = !isAnyDisabled && Boolean(isLink || !!forwardedProps.onClick);
+
+    const Wrapper: any = isClickable ? RawClickable : 'div';
+    const wrapperProps = { ...forwardedProps };
+    if (isClickable) {
+        Object.assign(wrapperProps, { as: linkAs || (linkProps?.href ? 'a' : 'button') }, disabledStateProps);
+        if (isLink) {
+            Object.assign(wrapperProps, linkProps);
+        } else {
+            wrapperProps['aria-label'] = forwardedProps['aria-label'] || alt;
+        }
+    }
+
+    // If we have a loading placeholder image that is really loaded (complete)
+    const loadingPlaceholderImage =
+        (isLoading && loadingPlaceholderImageRef?.current?.complete && loadingPlaceholderImageRef?.current) ||
+        undefined;
+
+    // Set loading placeholder image as background
+    const loadingStyle = loadingPlaceholderImage
+        ? { backgroundImage: `url(${loadingPlaceholderImage.src})` }
+        : undefined;
+
+    return (
+        <Wrapper
+            {...wrapperProps}
+            ref={ref}
+            className={classNames(
+                linkProps?.className,
+                className,
+                handleBasicClasses({
+                    align,
+                    aspectRatio,
+                    prefix: CLASSNAME,
+                    size,
+                    theme,
+                    variant,
+                    isClickable,
+                    hasError,
+                    hasIconErrorFallback,
+                    hasCustomErrorFallback,
+                    isLoading,
+                    objectFit,
+                    hasBadge: !!badge,
+                }),
+                fillHeight && `${CLASSNAME}--fill-height`,
+            )}
+        >
+            <span className={`${CLASSNAME}__background`}>
+                <img
+                    // Use placeholder image size
+                    width={loadingPlaceholderImage?.naturalWidth}
+                    height={loadingPlaceholderImage?.naturalHeight}
+                    {...imgProps}
+                    style={{
+                        // Reserve space while loading (when possible)
+                        width: isLoading ? imgProps?.width || loadingPlaceholderImage?.naturalWidth : undefined,
+                        ...imgProps?.style,
+                        ...imageErrorStyle,
+                        ...focusPointStyle,
+                        ...loadingStyle,
+                    }}
+                    ref={useMergeRefs(setImgElement, propImgRef)}
+                    className={classNames(
+                        handleBasicClasses({
+                            prefix: `${CLASSNAME}__image`,
+                            isLoading,
+                            hasDefinedSize: Boolean(imgProps?.height && imgProps.width),
+                        }),
+                        imgProps?.className,
+                    )}
+                    crossOrigin={crossOrigin}
+                    src={image}
+                    alt={alt}
+                    loading={loading}
+                />
+                {!isLoading && hasError && (
+                    <span className={`${CLASSNAME}__fallback`}>
+                        {hasIconErrorFallback ? (
+                            <Icon icon={fallback as string} size={Size.xxs} theme={theme} />
+                        ) : (
+                            fallback
+                        )}
+                    </span>
+                )}
+            </span>
+            {badge &&
+                React.cloneElement(badge, { className: classNames(`${CLASSNAME}__badge`, badge.props.className) })}
+        </Wrapper>
+    );
+});
+Thumbnail.displayName = COMPONENT_NAME;
+Thumbnail.className = CLASSNAME;
+Thumbnail.defaultProps = DEFAULT_PROPS;

package/src/components/thumbnail/index.ts

@@ -0,0 +1,3 @@
+export * from './Thumbnail';
+export * from './types';
+export { useFocusPointStyle } from '@lumx/react/components/thumbnail/useFocusPointStyle';

package/src/components/thumbnail/types.ts

@@ -0,0 +1,48 @@
+import React from 'react';
+import { AspectRatio, Size } from '@lumx/react';
+import { ValueOf } from '@lumx/react/utils/type';
+
+/**
+ *  Focal point using vertical alignment, horizontal alignment or coordinates (from -1 to 1).
+ */
+export type FocusPoint = { x?: number; y?: number };
+
+/**
+ * Loading attribute is not yet supported in typescript, so we need
+ * to add it in order to avoid a ts error.
+ * https://github.com/typescript-cheatsheets/react-typescript-cheatsheet/blob/master/ADVANCED.md#adding-non-standard-attributes
+ */
+declare module 'react' {
+    interface ImgHTMLAttributes<T> extends React.HTMLAttributes<T> {
+        loading?: 'eager' | 'lazy';
+    }
+}
+
+/**
+ * All available aspect ratios.
+ * @deprecated
+ */
+export const ThumbnailAspectRatio: Record<string, AspectRatio> = { ...AspectRatio };
+
+/**
+ *  Thumbnail sizes.
+ */
+export type ThumbnailSize = Extract<Size, 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl'>;
+
+/**
+ * Thumbnail variants.
+ */
+export const ThumbnailVariant = {
+    squared: 'squared',
+    rounded: 'rounded',
+} as const;
+export type ThumbnailVariant = ValueOf<typeof ThumbnailVariant>;
+
+/**
+ * Thumbnail object fit.
+ */
+export const ThumbnailObjectFit = {
+    cover: 'cover',
+    contain: 'contain',
+} as const;
+export type ThumbnailObjectFit = ValueOf<typeof ThumbnailObjectFit>;

package/src/components/thumbnail/useFocusPointStyle.test.ts

@@ -0,0 +1,92 @@
+import { shiftPosition } from './useFocusPointStyle';
+
+describe('shiftPosition', () => {
+    it('should always return 0% if the imageSize fits the containerSize', () => {
+        expect(
+            shiftPosition({
+                scale: 1.5,
+                focusPoint: 0,
+                imageSize: 1200,
+                containerSize: 800,
+            }),
+        ).toEqual(0);
+        expect(
+            shiftPosition({
+                scale: 1,
+                focusPoint: 0.27,
+                imageSize: 1000,
+                containerSize: 1000,
+            }),
+        ).toEqual(0);
+        expect(
+            shiftPosition({
+                scale: 3,
+                focusPoint: 0.5,
+                imageSize: 1200,
+                containerSize: 400,
+            }),
+        ).toEqual(0);
+        expect(
+            shiftPosition({
+                scale: 2.4,
+                focusPoint: 1,
+                imageSize: 1200,
+                containerSize: 500,
+            }),
+        ).toEqual(0);
+    });
+
+    describe('with bigger side than container ', () => {
+        // This use case will come, for example, if you have an image in width 100%
+        // but the image after being resized to keep the ratio is higher than the container.
+        // Then we are calculating the y shift.
+
+        const image = { width: 1000, height: 1200 };
+        const container = { width: 1000, height: 300 };
+        // scale is always the minimum scale ratio. Here imagewidth/containerwidth.
+        const scale = image.width / container.width; // 1
+        it('should return 0% if focusPoint equals 0', () => {
+            expect(
+                shiftPosition({
+                    scale,
+                    focusPoint: 0,
+                    imageSize: image.height,
+                    containerSize: container.height,
+                }),
+            ).toEqual(0);
+        });
+
+        it('should return 100% if focusPoint equals 1', () => {
+            expect(
+                shiftPosition({
+                    scale,
+                    focusPoint: 1,
+                    imageSize: image.height,
+                    containerSize: container.height,
+                }),
+            ).toEqual(100);
+        });
+
+        it('should return 50% if focusPoint equals 0.5', () => {
+            expect(
+                shiftPosition({
+                    scale,
+                    focusPoint: 0.5,
+                    imageSize: image.height,
+                    containerSize: container.height,
+                }),
+            ).toEqual(50);
+        });
+
+        it('should return 16% if focusPoint equals 0.25', () => {
+            expect(
+                shiftPosition({
+                    scale,
+                    focusPoint: 0.25,
+                    imageSize: image.height,
+                    containerSize: container.height,
+                }),
+            ).toEqual(16);
+        });
+    });
+});

package/src/components/thumbnail/useFocusPointStyle.tsx

@@ -0,0 +1,107 @@
+import { CSSProperties, useEffect, useMemo, useState } from 'react';
+import { AspectRatio } from '@lumx/core/js/constants';
+import { ThumbnailProps } from '@lumx/react/components/thumbnail/Thumbnail';
+import { RectSize } from '@lumx/react/utils/type';
+
+// Calculate shift to center the focus point in the container.
+export function shiftPosition({
+    scale,
+    focusPoint,
+    imageSize,
+    containerSize,
+}: {
+    scale: number;
+    focusPoint: number;
+    imageSize: number;
+    containerSize: number;
+}) {
+    const scaledSize = imageSize / scale;
+    if (scaledSize === containerSize) return 0;
+
+    const scaledFocusHeight = focusPoint * scaledSize;
+    const startFocus = scaledFocusHeight - containerSize / 2;
+    const shift = startFocus / (scaledSize - containerSize);
+
+    return Math.floor(Math.max(Math.min(shift, 1), 0) * 100);
+}
+
+// Compute CSS properties to apply the focus point.
+export const useFocusPointStyle = (
+    { image, aspectRatio, focusPoint, imgProps: { width, height } = {} }: ThumbnailProps,
+    element: HTMLImageElement | undefined,
+    isLoaded: boolean,
+): CSSProperties => {
+    // Get natural image size from imgProps or img element.
+    const imageSize: RectSize | undefined = useMemo(() => {
+        // Focus point is not applicable => exit early
+        if (!image || aspectRatio === AspectRatio.original || (!focusPoint?.x && !focusPoint?.y)) return undefined;
+        if (typeof width === 'number' && typeof height === 'number') return { width, height };
+        if (element && isLoaded) return { width: element.naturalWidth, height: element.naturalHeight };
+        return undefined;
+    }, [aspectRatio, element, focusPoint?.x, focusPoint?.y, height, image, isLoaded, width]);
+
+    // Get container size (dependant on imageSize).
+    const [containerSize, setContainerSize] = useState<RectSize | undefined>(undefined);
+    useEffect(
+        function updateContainerSize() {
+            const cWidth = element?.offsetWidth;
+            const cHeight = element?.offsetHeight;
+            if (cWidth && cHeight) {
+                // Update only if needed.
+                setContainerSize((oldContainerSize) =>
+                    oldContainerSize?.width === cWidth && oldContainerSize.height === cHeight
+                        ? oldContainerSize
+                        : { width: cWidth, height: cHeight },
+                );
+            } else if (imageSize) {
+                // Wait for a render (in case the container size is dependent on the image size).
+                requestAnimationFrame(updateContainerSize);
+            }
+        },
+        [element?.offsetHeight, element?.offsetWidth, imageSize],
+    );
+
+    // Compute style.
+    const style: CSSProperties = useMemo(() => {
+        // Focus point is not applicable => exit early
+        if (!image || aspectRatio === AspectRatio.original || (!focusPoint?.x && !focusPoint?.y)) {
+            return {};
+        }
+        if (!element || !imageSize) {
+            // Focus point can be computed but now right now (image size unknown).
+            return { visibility: 'hidden' };
+        }
+        if (!containerSize || !imageSize.height || !imageSize.width) {
+            // Missing container or image size abort focus point compute.
+            return {};
+        }
+
+        const heightScale = imageSize.height / containerSize.height;
+        const widthScale = imageSize.width / containerSize.width;
+        const scale = Math.min(widthScale, heightScale);
+
+        // Focus Y relative to the top (instead of the center)
+        const focusPointFromTop = Math.abs((focusPoint?.y || 0) - 1) / 2;
+        const y = shiftPosition({
+            scale,
+            focusPoint: focusPointFromTop,
+            imageSize: imageSize.height,
+            containerSize: containerSize.height,
+        });
+
+        // Focus X relative to the left (instead of the center)
+        const focusPointFromLeft = Math.abs((focusPoint?.x || 0) + 1) / 2;
+        const x = shiftPosition({
+            scale,
+            focusPoint: focusPointFromLeft,
+            imageSize: imageSize.width,
+            containerSize: containerSize.width,
+        });
+
+        const objectPosition = `${x}% ${y}%`;
+
+        return { objectPosition };
+    }, [aspectRatio, containerSize, element, focusPoint?.x, focusPoint?.y, image, imageSize]);
+
+    return style;
+};

package/src/components/thumbnail/useImageLoad.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react';
+
+export type LoadingState = 'isLoading' | 'isLoaded' | 'hasError';
+
+function getState(img: HTMLImageElement | null | undefined, event?: Event) {
+    // Error event occurred or image has no source.
+    if (event?.type === 'error' || (img?.complete && !img.getAttribute('src'))) {
+        return 'hasError';
+    }
+    // Image is undefined or incomplete.
+    if (!img || !img.complete) {
+        return 'isLoading';
+    }
+    // Else loaded.
+    return 'isLoaded';
+}
+
+export function useImageLoad(imageURL: string, imgRef?: HTMLImageElement): LoadingState {
+    const [state, setState] = useState<LoadingState>(getState(imgRef));
+
+    // Update state when changing image URL or DOM reference.
+    useEffect(() => {
+        setState(getState(imgRef));
+    }, [imageURL, imgRef]);
+
+    // Listen to `load` and `error` event on image
+    useEffect(() => {
+        const img = imgRef;
+        if (!img) return undefined;
+        const update = (event?: Event) => setState(getState(img, event));
+        img.addEventListener('load', update);
+        img.addEventListener('error', update);
+        return () => {
+            img.removeEventListener('load', update);
+            img.removeEventListener('error', update);
+        };
+    }, [imgRef, imgRef?.src]);
+
+    return state;
+}

package/src/components/toolbar/Toolbar.tsx

@@ -0,0 +1,68 @@
+import { ReactNode } from 'react';
+
+import classNames from 'classnames';
+
+import { GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+/**
+ * Defines the props of the component.
+ */
+export interface ToolbarProps extends GenericProps {
+    /** After content (placed after the label). */
+    after?: ReactNode;
+    /** Before content (placed before the label). */
+    before?: ReactNode;
+    /** Label content. */
+    label?: ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Toolbar';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<ToolbarProps> = {};
+
+/**
+ * Toolbar component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Toolbar = forwardRef<ToolbarProps, HTMLDivElement>((props, ref) => {
+    const { after, before, className, label, ...forwardedProps } = props;
+
+    return (
+        <div
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    hasAfter: Boolean(after),
+                    hasBefore: Boolean(before),
+                    hasLabel: Boolean(label),
+                    prefix: CLASSNAME,
+                }),
+            )}
+        >
+            {before && <div className={`${CLASSNAME}__before`}>{before}</div>}
+            {label && <div className={`${CLASSNAME}__label`}>{label}</div>}
+            {after && <div className={`${CLASSNAME}__after`}>{after}</div>}
+        </div>
+    );
+});
+Toolbar.displayName = COMPONENT_NAME;
+Toolbar.className = CLASSNAME;
+Toolbar.defaultProps = DEFAULT_PROPS;

package/src/components/toolbar/index.ts

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