@lumx/react 3.0.7 → 3.1.0

package/dist/src/components/thumbnail/Thumbnail.tsx

@@ -0,0 +1,222 @@
+import React, {
+    CSSProperties,
+    forwardRef,
+    ImgHTMLAttributes,
+    KeyboardEventHandler,
+    MouseEventHandler,
+    ReactElement,
+    ReactNode,
+    Ref,
+    useState,
+} from 'react';
+import classNames from 'classnames';
+
+import { AspectRatio, HorizontalAlignment, Icon, Size, Theme } from '@lumx/react';
+
+import { Comp, Falsy, GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+
+import { mdiImageBroken } from '@lumx/icons';
+import { mergeRefs } from '@lumx/react/utils/mergeRefs';
+import { useImageLoad } from '@lumx/react/components/thumbnail/useImageLoad';
+import { useFocusPointStyle } from '@lumx/react/components/thumbnail/useFocusPointStyle';
+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;
+    /** Size variant of the component. */
+    size?: ThumbnailSize;
+    /** Image loading mode. */
+    loading?: ImgHTMLProps['loading'];
+    /** 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',
+    theme: Theme.light,
+};
+
+/**
+ * Thumbnail component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Thumbnail: Comp<ThumbnailProps> = forwardRef((props, ref) => {
+    const {
+        align,
+        alt,
+        aspectRatio = AspectRatio.original,
+        badge,
+        className,
+        crossOrigin,
+        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,
+        loading,
+        size,
+        theme,
+        variant,
+        linkProps,
+        linkAs,
+        ...forwardedProps
+    } = props;
+    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 isButton = !!forwardedProps.onClick;
+    const isClickable = isButton || isLink;
+
+    let Wrapper: any = 'div';
+    const wrapperProps = { ...forwardedProps };
+    if (isLink) {
+        Wrapper = linkAs || 'a';
+        Object.assign(wrapperProps, linkProps);
+    } else if (isButton) {
+        Wrapper = 'button';
+        wrapperProps.type = forwardedProps.type || 'button';
+        wrapperProps['aria-label'] = forwardedProps['aria-label'] || alt;
+    }
+
+    return (
+        <Wrapper
+            {...wrapperProps}
+            ref={ref}
+            className={classNames(
+                linkProps?.className,
+                className,
+                handleBasicClasses({
+                    align,
+                    aspectRatio,
+                    prefix: CLASSNAME,
+                    size,
+                    theme,
+                    variant,
+                    isClickable,
+                    hasError,
+                    hasIconErrorFallback,
+                    hasCustomErrorFallback,
+                    isLoading,
+                    hasBadge: !!badge,
+                }),
+                fillHeight && `${CLASSNAME}--fill-height`,
+            )}
+        >
+            <div className={`${CLASSNAME}__background`}>
+                <img
+                    {...imgProps}
+                    style={{
+                        ...imgProps?.style,
+                        ...imageErrorStyle,
+                        ...focusPointStyle,
+                    }}
+                    ref={mergeRefs(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 && (
+                    <div className={`${CLASSNAME}__fallback`}>
+                        {hasIconErrorFallback ? (
+                            <Icon icon={fallback as string} size={Size.xxs} theme={theme} />
+                        ) : (
+                            fallback
+                        )}
+                    </div>
+                )}
+            </div>
+            {badge &&
+                React.cloneElement(badge, { className: classNames(`${CLASSNAME}__badge`, badge.props.className) })}
+        </Wrapper>
+    );
+});
+Thumbnail.displayName = COMPONENT_NAME;
+Thumbnail.className = CLASSNAME;
+Thumbnail.defaultProps = DEFAULT_PROPS;

package/dist/src/components/thumbnail/__snapshots__/Thumbnail.test.tsx.snap

@@ -0,0 +1,130 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<Thumbnail> Snapshots and structure should render story 'Clickable' 1`] = `
+<button
+  aria-label="Click me"
+  className="lumx-thumbnail lumx-thumbnail--aspect-ratio-original lumx-thumbnail--size-xxl lumx-thumbnail--theme-light lumx-thumbnail--is-clickable lumx-thumbnail--is-loading"
+  onClick={[Function]}
+  type="button"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Click me"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+</button>
+`;
+
+exports[`<Thumbnail> Snapshots and structure should render story 'ClickableCustomLink' 1`] = `
+<CustomLink
+  className="custom-class-name lumx-thumbnail lumx-thumbnail--aspect-ratio-original lumx-thumbnail--size-xxl lumx-thumbnail--theme-light lumx-thumbnail--is-clickable lumx-thumbnail--is-loading"
+  href="https://google.fr"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Click me"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+</CustomLink>
+`;
+
+exports[`<Thumbnail> Snapshots and structure should render story 'ClickableLink' 1`] = `
+<a
+  className="lumx-thumbnail lumx-thumbnail--aspect-ratio-original lumx-thumbnail--size-xxl lumx-thumbnail--theme-light lumx-thumbnail--is-clickable lumx-thumbnail--is-loading"
+  href="https://google.fr"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Click me"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+</a>
+`;
+
+exports[`<Thumbnail> Snapshots and structure should render story 'Default' 1`] = `
+<div
+  className="lumx-thumbnail lumx-thumbnail--aspect-ratio-original lumx-thumbnail--theme-light lumx-thumbnail--variant-squared lumx-thumbnail--is-loading"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Image alt text"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+</div>
+`;
+
+exports[`<Thumbnail> Snapshots and structure should render story 'WithBadge' 1`] = `
+<div
+  className="lumx-thumbnail lumx-thumbnail--aspect-ratio-square lumx-thumbnail--size-l lumx-thumbnail--theme-light lumx-thumbnail--variant-rounded lumx-thumbnail--is-loading lumx-thumbnail--has-badge"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Image alt text"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+  <Badge
+    className="lumx-thumbnail__badge"
+    color="primary"
+  >
+    <Icon
+      icon="M4 2A2 2 0 0 0 2 4V12H4V8H6V12H8V4A2 2 0 0 0 6 2H4M4 4H6V6H4M22 15.5V14A2 2 0 0 0 20 12H16V22H20A2 2 0 0 0 22 20V18.5A1.54 1.54 0 0 0 20.5 17A1.54 1.54 0 0 0 22 15.5M20 20H18V18H20V20M20 16H18V14H20M5.79 21.61L4.21 20.39L18.21 2.39L19.79 3.61Z"
+    />
+  </Badge>
+</div>
+`;
+
+exports[`<Thumbnail> Snapshots and structure should render story 'WithCustomImageClassName' 1`] = `
+<div
+  className="lumx-thumbnail lumx-thumbnail--aspect-ratio-square lumx-thumbnail--size-l lumx-thumbnail--theme-light lumx-thumbnail--variant-rounded lumx-thumbnail--is-loading lumx-thumbnail--has-badge"
+>
+  <div
+    className="lumx-thumbnail__background"
+  >
+    <img
+      alt="Image alt text"
+      className="lumx-thumbnail__image lumx-thumbnail__image--is-loading custom-image-class-name"
+      loading="lazy"
+      src="/demo-assets/landscape1.jpg"
+      style={{}}
+    />
+  </div>
+  <Badge
+    className="lumx-thumbnail__badge"
+    color="primary"
+  >
+    <Icon
+      icon="M4 2A2 2 0 0 0 2 4V12H4V8H6V12H8V4A2 2 0 0 0 6 2H4M4 4H6V6H4M22 15.5V14A2 2 0 0 0 20 12H16V22H20A2 2 0 0 0 22 20V18.5A1.54 1.54 0 0 0 20.5 17A1.54 1.54 0 0 0 22 15.5M20 20H18V18H20V20M20 16H18V14H20M5.79 21.61L4.21 20.39L18.21 2.39L19.79 3.61Z"
+    />
+  </Badge>
+</div>
+`;

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

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

package/dist/src/components/thumbnail/types.ts

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

package/dist/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/dist/src/components/thumbnail/useFocusPointStyle.tsx

@@ -0,0 +1,111 @@
+import { CSSProperties, useEffect, useMemo, useState } from 'react';
+import { AspectRatio } from '@lumx/react/components';
+import { ThumbnailProps } from '@lumx/react/components/thumbnail/Thumbnail';
+
+// 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);
+}
+
+type Size = { width: number; height: number };
+
+// 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: Size | 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<Size | 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, setStyle] = useState<CSSProperties>({});
+    useEffect(() => {
+        // 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).
+            setStyle({ visibility: 'hidden' });
+            return;
+        }
+        if (!containerSize) {
+            // Missing container size abort focus point compute.
+            setStyle({});
+            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}%`;
+        // Update only if needed.
+        setStyle((oldStyle) => (oldStyle.objectPosition === objectPosition ? oldStyle : { objectPosition }));
+    }, [aspectRatio, containerSize, element, focusPoint?.x, focusPoint?.y, image, imageSize]);
+
+    return style;
+};

package/dist/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 loaded empty.
+    if (event?.type === 'error' || (img?.complete && (img?.naturalWidth === 0 || img?.naturalHeight === 0))) {
+        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;
+}