@lumx/react 3.7.6-test.1 → 3.8.1-alpha.0

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

@@ -1,10 +1,13 @@
 import React from 'react';
 
+import uniqueId from 'lodash/uniqueId';
+
 import { mdiAbTesting } from '@lumx/icons';
 import {
     Alignment,
     AspectRatio,
     Badge,
+    Button,
     FlexBox,
     GridColumn,
     Icon,
@@ -411,3 +414,35 @@ export const ObjectFit = {
         withWrapper({ maxColumns: 3, itemMinWidth: 350 }, GridColumn),
     ],
 };
+
+/**
+ * Demonstrate loading a small image and then use it as the loading placeholder image when loading a bigger image
+ */
+export const LoadingPlaceholderImage = () => {
+    const [isShown, setShown] = React.useState(false);
+    const imgRef = React.useRef() as React.RefObject<HTMLImageElement>;
+    return (
+        <>
+            <Button onClick={() => setShown((shown) => !shown)}>
+                Display bigger image using the small image as a placeholder
+            </Button>
+            <FlexBox orientation="horizontal">
+                <Thumbnail alt="Small image" imgRef={imgRef} image="https://picsum.photos/id/15/128/85" />
+                {isShown && (
+                    <div style={{ maxHeight: 400 }}>
+                        <Thumbnail
+                            image={`https://picsum.photos/id/15/2500/1667?cacheBust${uniqueId()}`}
+                            alt="Large image"
+                            // Loading placeholder image
+                            loadingPlaceholderImageRef={imgRef}
+                            // Reserve space
+                            imgProps={{ width: 2500, height: 1667 }}
+                        />
+                    </div>
+                )}
+            </FlexBox>
+        </>
+    );
+};
+// Disables Chromatic snapshot (not relevant for this story).
+LoadingPlaceholderImage.parameters = { chromatic: { disable: true } };

package/src/components/thumbnail/Thumbnail.tsx

@@ -17,7 +17,7 @@ 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 { useMergeRefs } 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';
@@ -58,6 +58,8 @@ export interface ThumbnailProps extends GenericProps, HasTheme {
     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. */
@@ -115,6 +117,7 @@ export const Thumbnail: Comp<ThumbnailProps> = forwardRef((props, ref) => {
         isLoading: isLoadingProp,
         objectFit,
         loading,
+        loadingPlaceholderImageRef,
         size,
         theme,
         variant,
@@ -159,6 +162,16 @@ export const Thumbnail: Comp<ThumbnailProps> = forwardRef((props, ref) => {
         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}
@@ -186,13 +199,19 @@ export const Thumbnail: Comp<ThumbnailProps> = forwardRef((props, ref) => {
         >
             <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={mergeRefs(setImgElement, propImgRef)}
+                    ref={useMergeRefs(setImgElement, propImgRef)}
                     className={classNames(
                         handleBasicClasses({
                             prefix: `${CLASSNAME}__image`,

package/src/components/thumbnail/useFocusPointStyle.tsx

@@ -1,6 +1,7 @@
 import { CSSProperties, useEffect, useMemo, useState } from 'react';
 import { AspectRatio } from '@lumx/react/components';
 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({
@@ -24,8 +25,6 @@ export function shiftPosition({
     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,
@@ -33,7 +32,7 @@ export const useFocusPointStyle = (
     isLoaded: boolean,
 ): CSSProperties => {
     // Get natural image size from imgProps or img element.
-    const imageSize: Size | undefined = useMemo(() => {
+    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 };
@@ -42,7 +41,7 @@ export const useFocusPointStyle = (
     }, [aspectRatio, element, focusPoint?.x, focusPoint?.y, height, image, isLoaded, width]);
 
     // Get container size (dependant on imageSize).
-    const [containerSize, setContainerSize] = useState<Size | undefined>(undefined);
+    const [containerSize, setContainerSize] = useState<RectSize | undefined>(undefined);
     useEffect(
         function updateContainerSize() {
             const cWidth = element?.offsetWidth;

package/src/hooks/useElementSizeDependentOfWindowSize.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+
+import throttle from 'lodash/throttle';
+import { RectSize } from '@lumx/react/utils/type';
+
+/**
+ * Observe element size (only works if it's size depends on the window size).
+ *
+ * (Not using ResizeObserver for better browser backward compat)
+ *
+ * @param elementRef Element to observe
+ * @return the size and a manual update callback
+ */
+export function useElementSizeDependentOfWindowSize(
+    elementRef: React.RefObject<HTMLElement>,
+): [RectSize | null, () => void] {
+    const [size, setSize] = React.useState<null | RectSize>(null);
+    const updateSize = React.useMemo(
+        () =>
+            throttle(() => {
+                const newSize = elementRef.current?.getBoundingClientRect();
+                if (newSize) setSize(newSize);
+            }, 10),
+        [elementRef],
+    );
+    React.useEffect(() => {
+        updateSize();
+        window.addEventListener('resize', updateSize);
+        return () => window.removeEventListener('resize', updateSize);
+    }, [updateSize]);
+    return [size, updateSize];
+}

package/src/hooks/useImageSize.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { RectSize } from '@lumx/react/utils/type';
+
+/** Get natural image size after load. */
+export function useImageSize(imgRef: React.RefObject<HTMLImageElement>, getInitialSize?: () => RectSize | null) {
+    const [imageSize, setImageSize] = React.useState<null | RectSize>(getInitialSize || null);
+    React.useEffect(() => {
+        const { current: img } = imgRef;
+        if (!img) {
+            return undefined;
+        }
+        const onLoad = () => setImageSize({ width: img.naturalWidth, height: img.naturalHeight });
+        img.addEventListener('load', onLoad);
+        return () => img.removeEventListener('load', onLoad);
+    }, [imgRef]);
+    return imageSize;
+}

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './components/grid';
 export * from './components/grid-column';
 export * from './components/icon';
 export * from './components/image-block';
+export * from './components/image-lightbox';
 export * from './components/inline-list';
 export * from './components/input-helper';
 export * from './components/input-label';

package/src/stories/generated/ImageLightbox/Demos.stories.tsx

@@ -0,0 +1,6 @@
+/**
+ * File generated when storybook is started. Do not edit directly!
+ */
+export default { title: 'LumX components/image-lightbox/ImageLightbox Demos' };
+
+export { App as Default } from './default';

package/src/utils/DOM/findImage.tsx

@@ -0,0 +1,3 @@
+/** Find image in element including the element */
+export const findImage = (element: HTMLElement | null): HTMLImageElement | null =>
+    element?.matches('img') ? (element as HTMLImageElement) : element?.querySelector('img') || null;

package/src/utils/DOM/startViewTransition.ts

@@ -0,0 +1,56 @@
+import ReactDOM from 'react-dom';
+
+import { MaybeElementOrRef } from '@lumx/react/utils/type';
+
+import { unref } from '../react/unref';
+import { getPrefersReducedMotion } from '../browser/getPrefersReducedMotion';
+
+function setTransitionViewName(elementRef: MaybeElementOrRef<HTMLElement>, name: string | null | undefined) {
+    const element = unref(elementRef) as any;
+    if (element) element.style.viewTransitionName = name;
+}
+
+/**
+ * Wrapper around the `document.startViewTransition` handling browser incompatibilities, react DOM flush and
+ * user preference.
+ *
+ * @param changes                callback containing the changes to apply within the view transition.
+ * @param setViewTransitionName  set the `viewTransitionName` style on a `source` & `target` to morph these elements.
+ */
+export async function startViewTransition({
+    changes,
+    viewTransitionName,
+}: {
+    changes: () => void;
+    viewTransitionName: {
+        source: MaybeElementOrRef<HTMLElement>;
+        target: MaybeElementOrRef<HTMLElement>;
+        name: string;
+    };
+}) {
+    const start = (document as any)?.startViewTransition?.bind(document);
+    const prefersReducedMotion = getPrefersReducedMotion();
+    const { flushSync } = ReactDOM as any;
+    if (prefersReducedMotion || !start || !flushSync || !viewTransitionName?.source || !viewTransitionName?.target) {
+        // Skip, apply changes without a transition
+        changes();
+        return;
+    }
+
+    // Set transition name on source element
+    setTransitionViewName(viewTransitionName.source, viewTransitionName.name);
+
+    // Start view transition, apply changes & flush to DOM
+    await start(() => {
+        // Un-set transition name on source element
+        setTransitionViewName(viewTransitionName.source, null);
+
+        flushSync(changes);
+
+        // Set transition name on target element
+        setTransitionViewName(viewTransitionName.target, viewTransitionName.name);
+    }).updateCallbackDone;
+
+    // Un-set transition name on target element
+    setTransitionViewName(viewTransitionName.target, null);
+}

package/src/utils/browser/getPrefersReducedMotion.ts

@@ -0,0 +1,6 @@
+import { WINDOW } from '@lumx/react/constants';
+
+/** Check if user prefers reduced motion */
+export function getPrefersReducedMotion() {
+    return WINDOW?.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+}

package/src/utils/object/isEqual.test.ts

@@ -0,0 +1,25 @@
+import { isEqual } from './isEqual';
+
+test(isEqual.name, () => {
+    expect(isEqual('', '')).toBe(true);
+    expect(isEqual(0, 0)).toBe(true);
+    expect(isEqual(Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY)).toBe(true);
+
+    expect(isEqual('', 0)).toBe(false);
+
+    expect(isEqual({}, {})).toBe(true);
+    expect(isEqual({ a: 1 }, { a: 1 })).toBe(true);
+    expect(isEqual({ a: { a: 1 } }, { a: { a: 1 } })).toBe(true);
+
+    expect(isEqual([], [])).toBe(true);
+
+    expect(isEqual([1], [2])).toBe(false);
+    expect(isEqual([1], [1, 2])).toBe(false);
+    expect(isEqual([1, 2], [2, 1])).toBe(false);
+
+    expect(isEqual({ a: 1 }, { a: 2 })).toBe(false);
+    expect(isEqual({ a: 1 }, {})).toBe(false);
+    expect(isEqual({}, { a: 1 })).toBe(false);
+    expect(isEqual({ a: { a: 1 } }, { a: { a: 2 } })).toBe(false);
+    expect(isEqual({ a: 1 }, { a: 1, b: 1 })).toBe(false);
+});

package/src/utils/object/isEqual.ts

@@ -0,0 +1,11 @@
+/** Minimal recursive deep equal of JS values */
+export function isEqual(obj1: any, obj2: any): boolean {
+    if (obj1 === obj2) return true;
+    if (typeof obj1 === 'object' && typeof obj2 === 'object') {
+        const keys1 = Object.keys(obj1);
+        const keys2 = Object.keys(obj2);
+        if (keys1.length !== keys2.length) return false;
+        return keys1.every((key1) => isEqual(obj1[key1], obj2[key1]));
+    }
+    return false;
+}

package/src/utils/react/unref.ts

@@ -0,0 +1,7 @@
+import { MaybeElementOrRef } from '@lumx/react/utils/type';
+
+/** Unref a react ref or element */
+export function unref(maybeElement: MaybeElementOrRef<HTMLElement>) {
+    if (maybeElement instanceof HTMLElement) return maybeElement;
+    return maybeElement?.current;
+}

package/src/utils/type.ts

@@ -139,3 +139,18 @@ export type ComponentRef<C> = C extends keyof JSX.IntrinsicElements
       : C extends React.JSXElementConstructor<{ ref?: infer R }>
         ? R
         : never;
+
+/**
+ * Rectangle size
+ */
+export type RectSize = { width: number; height: number };
+
+/**
+ * Maybe a HTMLElement or a React ref of a HTMLElement
+ */
+export type MaybeElementOrRef<E extends HTMLElement> = E | React.RefObject<E | null> | null | undefined;
+
+/**
+ * A point coordinate in 2D space
+ */
+export type Point = { x: number; y: number };

package/src/hooks/useOnResize.ts

@@ -1,41 +0,0 @@
-import { Callback, Falsy } from '@lumx/react/utils/type';
-import { MutableRefObject, RefObject, useEffect, useRef } from 'react';
-import { WINDOW } from '@lumx/react/constants';
-import { ResizeObserver as Polyfill } from '@juggle/resize-observer';
-
-const ResizeObserver: typeof Polyfill = (WINDOW as any)?.ResizeObserver || Polyfill;
-
-export function useOnResize(element: HTMLElement | Falsy, update: RefObject<Callback>): void {
-    const observerRef = useRef(null) as MutableRefObject<Polyfill | null>;
-    const previousSize = useRef<{ width: number; height: number }>();
-
-    useEffect(() => {
-        if (!element || !update) {
-            return undefined;
-        }
-
-        previousSize.current = undefined;
-        const observer =
-            observerRef.current ||
-            new ResizeObserver(([entry]) => {
-                const updateFunction = update.current;
-                if (!updateFunction) {
-                    return;
-                }
-
-                const { width, height } = entry.contentRect;
-                if (previousSize.current?.width === width && previousSize.current?.height === height) {
-                    return;
-                }
-
-                window.requestAnimationFrame(() => updateFunction());
-                previousSize.current = entry.contentRect;
-            });
-        if (!observerRef.current) observerRef.current = observer;
-
-        observer.observe(element);
-        return () => {
-            observer.unobserve(element);
-        };
-    }, [element, update]);
-}