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

package/src/hooks/useChipGroupNavigation.tsx

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

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

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

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

package/src/hooks/useFocus.tsx

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Hook focusing an element when defined and `focus` boolean `true`.
+ *
+ * @param element       Element to focus.
+ * @param shouldFocus   Boolean flag to trigger the focus
+ */
+export function useFocus(element: HTMLElement | null | undefined, shouldFocus = true): void {
+    const [wasFocus, setWasFocus] = useState(false);
+    useEffect(
+        () => {
+            if (shouldFocus && wasFocus !== shouldFocus && element) {
+                element.focus();
+                setWasFocus(shouldFocus);
+            }
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [element, shouldFocus],
+    );
+}

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,93 @@
+import { useEffect } from 'react';
+
+import { DOCUMENT } from '@lumx/react/constants';
+import { getFirstAndLastFocusable } from '@lumx/react/utils/browser/focus/getFirstAndLastFocusable';
+import { Falsy } from '@lumx/react/utils/type';
+import { Listener, makeListenerTowerContext } from '@lumx/react/utils/function/makeListenerTowerContext';
+
+const FOCUS_TRAPS = makeListenerTowerContext();
+
+/**
+ * Trap 'Tab' focus switch inside the `focusZoneElement`.
+ *
+ * If multiple focus trap are activated, only the last one is maintained and when a focus trap closes, the previous one
+ * gets activated again.
+ *
+ * @param focusZoneElement The element in which to trap the focus.
+ * @param focusElement     The element to focus when the focus trap is activated (otherwise the first focusable element
+ *                         will be focused).
+ */
+export function useFocusTrap(focusZoneElement: HTMLElement | Falsy, focusElement?: HTMLElement | null): void {
+    useEffect(() => {
+        // Body element can be undefined in SSR context.
+        const rootElement = DOCUMENT?.body;
+
+        if (!rootElement || !focusZoneElement) {
+            return undefined;
+        }
+
+        // Use the shadow root as focusZoneElement when available
+        const focusZoneElementOrShadowRoot = focusZoneElement.shadowRoot || focusZoneElement;
+
+        // Trap 'Tab' key down focus switch into the focus zone.
+        const trapTabFocusInFocusZone = (evt: KeyboardEvent) => {
+            const { key } = evt;
+            if (key !== 'Tab') {
+                return;
+            }
+
+            const focusable = getFirstAndLastFocusable(focusZoneElementOrShadowRoot);
+
+            // Prevent focus switch if no focusable available.
+            if (!focusable.first) {
+                evt.preventDefault();
+                return;
+            }
+
+            const activeElement = focusZoneElement.shadowRoot
+                ? focusZoneElement.shadowRoot.activeElement
+                : document.activeElement;
+
+            if (
+                // No previous focus
+                !activeElement ||
+                // Previous focus is at the end of the focus zone.
+                (!evt.shiftKey && activeElement === focusable.last) ||
+                // Previous focus is outside the focus zone
+                !focusZoneElementOrShadowRoot.contains(activeElement)
+            ) {
+                focusable.first.focus();
+                evt.preventDefault();
+                return;
+            }
+
+            if (
+                // Focus order reversed
+                evt.shiftKey &&
+                // Previous focus is at the start of the focus zone.
+                activeElement === focusable.first
+            ) {
+                focusable.last.focus();
+                evt.preventDefault();
+            }
+        };
+
+        const focusTrap: Listener = {
+            enable: () => rootElement.addEventListener('keydown', trapTabFocusInFocusZone),
+            disable: () => rootElement.removeEventListener('keydown', trapTabFocusInFocusZone),
+        };
+
+        // SETUP:
+        if (focusElement && focusZoneElementOrShadowRoot.contains(focusElement)) {
+            // Focus the given element.
+            focusElement.focus({ preventScroll: true });
+        } else {
+            // Focus the first focusable element in the zone.
+            getFirstAndLastFocusable(focusZoneElementOrShadowRoot).first?.focus({ preventScroll: true });
+        }
+        FOCUS_TRAPS.register(focusTrap);
+
+        // TEARDOWN:
+        return () => FOCUS_TRAPS.unregister(focusTrap);
+    }, [focusElement, focusZoneElement]);
+}

package/src/hooks/useFocusWithin.ts

@@ -0,0 +1,33 @@
+import { useEffect } from 'react';
+
+export interface UseFocusWithinOptions {
+    /** element to add the focus within to */
+    element: HTMLElement | null;
+    /** callback to be executed on focus in */
+    onFocusIn: (ev: FocusEvent) => void;
+    /** callback to be executed on focus out */
+    onFocusOut: (ev: FocusEvent) => void;
+}
+
+/**
+ * Hook that allows to control when there is a focus event within a given element, meaning
+ * that any element within the given target will trigger the focus in and focus out events.
+ * @param options - UseFocusWithinOptions
+ */
+export const useFocusWithin = ({ element, onFocusIn, onFocusOut }: UseFocusWithinOptions) => {
+    useEffect(() => {
+        if (element) {
+            element.addEventListener('focusin', onFocusIn);
+
+            element.addEventListener('focusout', onFocusOut);
+        }
+
+        return () => {
+            if (element) {
+                element.removeEventListener('focusin', onFocusIn);
+
+                element.removeEventListener('focusout', onFocusOut);
+            }
+        };
+    }, [onFocusIn, element, onFocusOut]);
+};

package/src/hooks/useId.test.tsx

@@ -0,0 +1,22 @@
+import { useId } from '@lumx/react/hooks/useId';
+import { render } from '@testing-library/react';
+
+function setup() {
+    const Component = (): any => useId();
+    const result = render(<Component />);
+    const rerender = () => result.rerender(<Component />);
+    return { ...result, rerender };
+}
+
+describe(useId, () => {
+    it('should render a unique id stable after re-renders', () => {
+        const result = setup();
+        // Id generated
+        const initialId = result.container.textContent;
+        expect(initialId).toMatch(/:lumx\d+:/);
+
+        // Id is stable after re-render
+        result.rerender();
+        expect(result.container.textContent).toEqual(initialId);
+    });
+});

package/src/hooks/useId.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+
+let i = 0;
+
+/**
+ * Generate a unique id (for use in a11y or other id based DOM linking).
+ *
+ * (Tries to emulate React 18 useId hook, to remove once we upgrade React)
+ */
+export function useId() {
+    return React.useMemo(() => {
+        i += 1;
+        return `:lumx${i}:`;
+    }, []);
+}

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/hooks/useInfiniteScroll.tsx

@@ -0,0 +1,60 @@
+import { useEffect } from 'react';
+
+type useInfiniteScrollType = (
+    ref: React.RefObject<HTMLElement>,
+    callback?: EventCallback,
+    callbackOnMount?: boolean,
+) => void;
+type EventCallback = (evt?: Event) => void;
+
+// The error margin in px we want to have for triggering infinite scroll
+const SCROLL_TRIGGER_MARGIN = 5;
+
+/**
+ * Listen to clicks away from a given element and callback the passed in function.
+ *
+ * @param  ref               A reference to the element on which you want to listen scroll event.
+ * @param  [callback]        A callback function to call when the bottom of the reference element is reached.
+ * @param  [callbackOnMount] A callback function to call when the component is mounted.
+ */
+export const useInfiniteScroll: useInfiniteScrollType = (
+    ref,
+    callback,
+    callbackOnMount = false,
+    scrollTriggerMargin = SCROLL_TRIGGER_MARGIN,
+) => {
+    useEffect(() => {
+        const { current } = ref;
+        if (!callback || !current) {
+            return undefined;
+        }
+
+        const isAtBottom = () =>
+            Boolean(
+                current && current.scrollHeight - (current.scrollTop + current.clientHeight) <= scrollTriggerMargin,
+            );
+
+        const onScroll = (e?: Event): void => {
+            if (isAtBottom()) {
+                callback(e);
+            }
+        };
+
+        if (isAtBottom()) {
+            onScroll();
+        }
+
+        current.addEventListener('scroll', onScroll);
+        current.addEventListener('resize', onScroll);
+        return () => {
+            current.removeEventListener('scroll', onScroll);
+            current.removeEventListener('resize', onScroll);
+        };
+    }, [ref, callback, scrollTriggerMargin]);
+
+    useEffect(() => {
+        if (callback && callbackOnMount) {
+            callback();
+        }
+    }, [callback, callbackOnMount]);
+};

package/src/hooks/useIntersectionObserver.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+
+export type Intersections<T> = Map<T, IntersectionObserverEntry>;
+
+/**
+ * Convenient hook to create interaction observers.
+ *
+ * @param elements Elements to observe.
+ * @param options  IntersectionObserver options.
+ * @return Map of intersections.
+ */
+export function useIntersectionObserver<T extends Element>(
+    elements: Array<T | null | undefined>,
+    options?: IntersectionObserverInit,
+): Intersections<T> {
+    const [intersections, setIntersections] = useState<Intersections<T>>(() => new Map());
+
+    useEffect(
+        () => {
+            if (elements.length < 1 || !elements.some(Boolean)) {
+                return undefined;
+            }
+
+            const observer = new IntersectionObserver((entries) => {
+                for (const entry of entries) {
+                    intersections.set(entry.target as T, entry);
+                }
+                setIntersections(new Map(intersections));
+            }, options);
+
+            for (const element of elements) {
+                if (element) {
+                    observer.observe(element);
+                }
+            }
+            return () => observer.disconnect();
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [...elements],
+    );
+
+    return intersections;
+}

package/src/hooks/useInterval.tsx

@@ -0,0 +1,31 @@
+import { useEffect, useRef } from 'react';
+
+import isFunction from 'lodash/isFunction';
+import { Callback } from '@lumx/react/utils/type';
+
+/**
+ * Making setInterval Declarative with React Hooks.
+ * Credits: https://overreacted.io/making-setinterval-declarative-with-react-hooks/
+ *
+ * @param callback Function called by setInterval.
+ * @param     delay    Delay for setInterval.
+ */
+export function useInterval(callback: Callback, delay: number | null): void {
+    const savedCallback = useRef<Callback>();
+
+    useEffect(() => {
+        savedCallback.current = callback;
+    });
+
+    useEffect(() => {
+        if (delay === null) return undefined;
+
+        function tick() {
+            if (isFunction(savedCallback.current)) {
+                savedCallback.current();
+            }
+        }
+        const id = setInterval(tick, delay);
+        return () => clearInterval(id);
+    }, [delay]);
+}