@lumx/react 3.0.7 → 3.1.0

package/dist/src/hooks/useFocusTrap.ts

@@ -0,0 +1,85 @@
+import { useEffect } from 'react';
+
+import { DOCUMENT } from '@lumx/react/constants';
+import { getFirstAndLastFocusable } from '@lumx/react/utils/focus/getFirstAndLastFocusable';
+import { Falsy } from '@lumx/react/utils/type';
+import { Listener, makeListenerTowerContext } from '@lumx/react/utils/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;
+        }
+
+        // Trap 'Tab' key down focus switch into the focus zone.
+        const trapTabFocusInFocusZone = (evt: KeyboardEvent) => {
+            const { key } = evt;
+            if (key !== 'Tab') {
+                return;
+            }
+            const focusable = getFirstAndLastFocusable(focusZoneElement);
+
+            // Prevent focus switch if no focusable available.
+            if (!focusable.first) {
+                evt.preventDefault();
+                return;
+            }
+
+            if (
+                // No previous focus
+                !document.activeElement ||
+                // Previous focus is at the end of the focus zone.
+                (!evt.shiftKey && document.activeElement === focusable.last) ||
+                // Previous focus is outside the focus zone
+                !focusZoneElement.contains(document.activeElement)
+            ) {
+                focusable.first.focus();
+                evt.preventDefault();
+                return;
+            }
+
+            if (
+                // Focus order reversed
+                evt.shiftKey &&
+                // Previous focus is at the start of the focus zone.
+                document.activeElement === focusable.first
+            ) {
+                focusable.last.focus();
+                evt.preventDefault();
+            }
+        };
+
+        const focusTrap: Listener = {
+            enable: () => rootElement.addEventListener('keydown', trapTabFocusInFocusZone),
+            disable: () => rootElement.removeEventListener('keydown', trapTabFocusInFocusZone),
+        };
+
+        // SETUP:
+        if (focusElement && focusZoneElement.contains(focusElement)) {
+            // Focus the given element.
+            focusElement.focus();
+        } else {
+            // Focus the first focusable element in the zone.
+            getFirstAndLastFocusable(focusZoneElement).first?.focus();
+        }
+        FOCUS_TRAPS.register(focusTrap);
+
+        // TEARDOWN:
+        return () => FOCUS_TRAPS.unregister(focusTrap);
+    }, [focusElement, focusZoneElement]);
+}

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

@@ -0,0 +1,60 @@
+import React, { 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/dist/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/dist/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]);
+}

package/dist/src/hooks/useKeyboardListNavigation.tsx

@@ -0,0 +1,204 @@
+import { RefObject, SetStateAction, useEffect, useState } from 'react';
+
+import get from 'lodash/get';
+
+type Listener = (evt: KeyboardEvent) => void;
+
+interface UseKeyboardListNavigationType {
+    /** the current active index */
+    activeItemIndex: number;
+    /** callback to be used when a key is pressed. usually used with the native prop `onKeyDown` */
+    onKeyboardNavigation: Listener;
+    /** Resets the active index to the initial state */
+    resetActiveIndex(): void;
+    /** Sets the active index to a given value */
+    setActiveItemIndex(value: SetStateAction<number>): void;
+}
+
+export type useKeyboardListNavigationType = <I>(
+    items: I[],
+    ref: RefObject<HTMLElement>,
+    onListItemSelected: (itemSelected: I) => void,
+    onListItemNavigated?: (itemSelected: I) => void,
+    onEnterPressed?: (itemSelected: string) => void,
+    onBackspacePressed?: Listener,
+    keepFocusAfterSelection?: boolean,
+    initialIndex?: number,
+    preventTabOnEnteredValue?: boolean,
+) => UseKeyboardListNavigationType;
+
+const INITIAL_INDEX = -1;
+
+/**
+ * This custom hook provides the necessary set of functions and values to properly navigate
+ * a list using the keyboard.
+ *
+ * @param  items                    the list of items that will be navigated using the keyboard.
+ * @param  ref                      A reference to the element that is controlling the navigation.
+ * @param  onListItemSelected       callback to be executed when the ENTER key is pressed on an item.
+ * @param  onListItemNavigated      callback to be executed when the Arrow keys are pressed.
+ * @param  onEnterPressed           callback to be executed when the ENTER key is pressed.
+ * @param  onBackspacePressed       callback to be executed when the BACKSPACE key is pressed.
+ * @param  keepFocusAfterSelection  determines whether after selecting an item, the focus should be maintained on the current target or not.
+ * @param  initialIndex             where should the navigation start from. it defaults to `-1`, so the first item navigated is the item on position `0`.
+ * @param  preventTabOnEnteredValue determines whether upon TAB, if there is a value entered, the event is prevented or not.
+ * @return useKeyboardListNavigation helpers.
+ */
+export const useKeyboardListNavigation: useKeyboardListNavigationType = (
+    items,
+    ref,
+    onListItemSelected,
+    onListItemNavigated,
+    onEnterPressed,
+    onBackspacePressed,
+    keepFocusAfterSelection = false,
+    initialIndex = INITIAL_INDEX,
+    preventTabOnEnteredValue = true,
+) => {
+    const [activeItemIndex, setActiveItemIndex] = useState(initialIndex);
+
+    /**
+     * This function calculates the next index in the list to be highlighted
+     * @param key - key code pressed
+     * @return next active index
+     */
+    const calculateActiveIndex = (key: string): number => {
+        switch (key) {
+            case 'ArrowDown':
+                return activeItemIndex + 1 < items.length ? activeItemIndex + 1 : 0;
+            case 'ArrowUp':
+                return activeItemIndex - 1 >= 0 ? activeItemIndex - 1 : items.length - 1;
+            default:
+                return initialIndex;
+        }
+    };
+
+    /**
+     * Resets the active index to the initial state
+     */
+    const resetActiveIndex = () => {
+        setActiveItemIndex(initialIndex);
+    };
+
+    /**
+     * Prevents the default event and stops the propagation of said event
+     * @param evt - key pressed event
+     */
+    const preventDefaultAndStopPropagation: Listener = (evt) => {
+        evt.preventDefault();
+        evt.stopPropagation();
+    };
+
+    /**
+     * Handles navigation with the arrows using the keyboard
+     * @param evt - key pressed event
+     */
+    const onArrowPressed: Listener = (evt) => {
+        const { key } = evt;
+        const nextActiveIndex = calculateActiveIndex(key);
+        setActiveItemIndex(nextActiveIndex);
+        preventDefaultAndStopPropagation(evt);
+        if (onListItemNavigated) {
+            const selectedItem = items[nextActiveIndex];
+            onListItemNavigated(selectedItem);
+        }
+    };
+
+    /**
+     * Handles the event when the backspace key is pressed
+     * @param evt - key pressed event
+     */
+    const onBackspaceKeyPressed: Listener = (evt) => {
+        if (onBackspacePressed) {
+            onBackspacePressed(evt);
+        }
+    };
+
+    /**
+     * Handles when the ENTER key is pressed
+     * @param evt - key pressed event
+     */
+    const onEnterKeyPressed: Listener = (evt) => {
+        if (!onListItemSelected) {
+            return;
+        }
+
+        preventDefaultAndStopPropagation(evt);
+
+        if (!keepFocusAfterSelection) {
+            (evt.currentTarget as HTMLElement).blur();
+        }
+
+        const selectedItem = items[activeItemIndex];
+
+        if (selectedItem) {
+            onListItemSelected(selectedItem);
+            resetActiveIndex();
+        } else if (activeItemIndex === initialIndex && onEnterPressed) {
+            const value = get(evt, 'target.value');
+            onEnterPressed(value);
+            resetActiveIndex();
+        }
+    };
+
+    /**
+     * Handles when the TAB key is pressed
+     * @param evt - key pressed event
+     */
+    const onTabKeyPressed: Listener = (evt) => {
+        const value = get(evt, 'target.value');
+
+        if (preventTabOnEnteredValue && value && value.length > 0) {
+            preventDefaultAndStopPropagation(evt);
+        }
+    };
+
+    /**
+     * In order to make it easier in the future to add new events depending on the key
+     * a map was created to add these handlers. In the future, if there is another event
+     * that we need to manage depending on a specific key, we just need to add the key code
+     * here, and as a value, the handler for said key.
+     */
+    const eventsForKeyPressed: Record<string, Listener> = {
+        ArrowDown: onArrowPressed,
+        Tab: onTabKeyPressed,
+        ArrowUp: onArrowPressed,
+        Enter: onEnterKeyPressed,
+        Backspace: onBackspaceKeyPressed,
+    };
+
+    /**
+     * Calculates the next active item index depending on the key pressed.
+     * If the key pressed was ENTER, the function executes the callback `onListItemSelected`
+     * and resets the active index, since an item was selected.
+     * @param evt - key pressed or key down event
+     */
+    const onKeyboardNavigation: Listener = (evt) => {
+        const { key } = evt;
+        const handler = eventsForKeyPressed[key];
+
+        if (handler) {
+            handler(evt);
+        }
+    };
+
+    useEffect(() => {
+        const { current: currentElement } = ref;
+        if (!currentElement) {
+            return undefined;
+        }
+        currentElement.addEventListener('focus', resetActiveIndex);
+        currentElement.addEventListener('keydown', onKeyboardNavigation);
+        return () => {
+            currentElement.removeEventListener('focus', resetActiveIndex);
+            currentElement.removeEventListener('keydown', onKeyboardNavigation);
+        };
+    });
+
+    return {
+        activeItemIndex,
+        onKeyboardNavigation,
+        resetActiveIndex,
+        setActiveItemIndex,
+    };
+};

package/dist/src/hooks/useListenFocus.tsx

@@ -0,0 +1,26 @@
+import { RefObject, useEffect, useState } from 'react';
+
+/**
+ * Listen on element focus to store the focus status.
+ */
+export function useListenFocus(ref: RefObject<HTMLElement>) {
+    const [isFocus, setFocus] = useState(false);
+
+    useEffect(() => {
+        const { current: element } = ref;
+        if (!element) {
+            return undefined;
+        }
+
+        const onFocus = () => setFocus(true);
+        const onBlur = () => setFocus(false);
+        element.addEventListener('focus', onFocus);
+        element.addEventListener('blur', onBlur);
+        return () => {
+            element.removeEventListener('focus', onFocus);
+            element.removeEventListener('blur', onBlur);
+        };
+    }, [ref, setFocus]);
+
+    return isFocus;
+}

package/dist/src/hooks/useOnResize.ts

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

package/dist/src/hooks/useRovingTabIndex.tsx

@@ -0,0 +1,90 @@
+import { RefObject, useEffect } from 'react';
+
+interface UseRovingTabIndexOptions {
+    parentRef: RefObject<HTMLElement>;
+    elementSelector: string;
+    keepTabIndex?: boolean;
+    /** Action to trigger when an element is focused using roving tab index */
+    onElementFocus?: (element: HTMLElement) => void;
+    /** List of values to be used as extra dependencies of the useEffect */
+    extraDependencies?: any[];
+}
+
+export const useRovingTabIndex = ({
+    parentRef,
+    elementSelector,
+    keepTabIndex,
+    onElementFocus,
+    extraDependencies = [],
+}: UseRovingTabIndexOptions): void => {
+    useEffect(
+        () => {
+            const parent = parentRef?.current;
+            if (!parent) {
+                return undefined;
+            }
+
+            const elements = parent.querySelectorAll(elementSelector) as NodeListOf<HTMLElement>;
+            const initialFocusableElement = parent?.querySelector(`${elementSelector}[tabindex="0"]`);
+
+            const handleKeyDown = (index: number) => (evt: KeyboardEvent) => {
+                let newTabFocus = index;
+                if (!(evt.key === 'ArrowRight' || evt.key === 'ArrowLeft')) {
+                    return;
+                }
+
+                if (evt.key === 'ArrowRight') {
+                    // Move right
+                    newTabFocus += 1;
+                    // If we're at the end, go to the start
+                    if (newTabFocus >= elements.length) {
+                        newTabFocus = 0;
+                    }
+                } else if (evt.key === 'ArrowLeft') {
+                    // Move left
+                    newTabFocus -= 1;
+                    if (newTabFocus < 0) {
+                        // If we're at the start, move to the end
+                        newTabFocus = elements.length - 1;
+                    }
+                }
+                const newElement = elements[newTabFocus];
+                newElement?.focus();
+
+                // When an element is focused using roving tab index, trigger the onElementFocus callback
+                if (newElement && onElementFocus) {
+                    onElementFocus(newElement);
+                }
+
+                if (keepTabIndex) {
+                    (evt.currentTarget as HTMLElement).setAttribute('tabindex', '-1');
+                    newElement?.setAttribute('tabindex', '0');
+                }
+            };
+
+            if (elements?.length > 0) {
+                elements.forEach((el, key) => {
+                    // if no element has tabindex set to 0, set the first element as focusable
+                    if (!initialFocusableElement && key === 0) {
+                        el.setAttribute('tabindex', '0');
+                        // set all other to -1
+                    } else if (initialFocusableElement !== el) {
+                        el.setAttribute('tabindex', '-1');
+                    }
+                    // add event listener
+                    el.addEventListener('keydown', handleKeyDown(key) as EventListener);
+                });
+            }
+
+            // Cleanup listeners
+            return () => {
+                if (elements?.length > 0) {
+                    elements.forEach((el, key) => {
+                        el.removeEventListener('keydown', handleKeyDown(key) as EventListener);
+                    });
+                }
+            };
+        }, // eslint-disable-next-line react-hooks/exhaustive-deps
+        [parentRef, ...extraDependencies],
+    );
+};