@lumx/react 4.17.1-alpha.2 → 4.17.1-alpha.3

package/_internal/hooks/useFocusTrap.js

@@ -0,0 +1,28 @@
+import { setupFocusTrap } from "../packages/lumx-core/src/js/utils/focus/setupFocusTrap.js";
+import { useEffect } from "react";
+//#region src/hooks/useFocusTrap.ts
+/**
+* Trap 'Tab' focus switch inside the `focusZoneElement`.
+*
+* If multiple focus traps are activated, only the last one is maintained and when a focus trap closes, the previous one
+* gets activated again.
+*
+* If the zone has no focusable descendant, the zone element itself receives focus (with a fallback `tabindex="-1"`).
+*
+* @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 — and finally the zone element itself if no focusable is found).
+*/
+function useFocusTrap(focusZoneElement, focusElement) {
+	useEffect(() => {
+		if (!focusZoneElement) return;
+		const controller = new AbortController();
+		setupFocusTrap({
+			focusZoneElement,
+			focusElement
+		}, controller.signal);
+		return () => controller.abort();
+	}, [focusElement, focusZoneElement]);
+}
+//#endregion
+export { useFocusTrap };

package/_internal/hooks/useFocusWithin.js

@@ -0,0 +1,27 @@
+import { useEffect } from "react";
+//#region src/hooks/useFocusWithin.ts
+/**
+* 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
+*/
+var useFocusWithin = ({ element, onFocusIn, onFocusOut }) => {
+	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
+	]);
+};
+//#endregion
+export { useFocusWithin };

package/_internal/hooks/useId.js

@@ -0,0 +1,16 @@
+import React from "react";
+//#region src/hooks/useId.ts
+var 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)
+*/
+function useId() {
+	return React.useMemo(() => {
+		i += 1;
+		return `:lumx${i}:`;
+	}, []);
+}
+//#endregion
+export { useId };

package/_internal/hooks/useImageSize.js

@@ -0,0 +1,19 @@
+import React from "react";
+//#region src/hooks/useImageSize.ts
+/** Get natural image size after load. */
+function useImageSize(imgRef, getInitialSize) {
+	const [imageSize, setImageSize] = React.useState(getInitialSize || null);
+	React.useEffect(() => {
+		const { current: img } = imgRef;
+		if (!img) return;
+		const onLoad = () => setImageSize({
+			width: img.naturalWidth,
+			height: img.naturalHeight
+		});
+		img.addEventListener("load", onLoad);
+		return () => img.removeEventListener("load", onLoad);
+	}, [imgRef]);
+	return imageSize;
+}
+//#endregion
+export { useImageSize };

package/_internal/hooks/useInfiniteScroll.js

@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+//#region src/hooks/useInfiniteScroll.tsx
+var 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.
+*/
+var useInfiniteScroll = (ref, callback, callbackOnMount = false, scrollTriggerMargin = SCROLL_TRIGGER_MARGIN) => {
+	useEffect(() => {
+		const { current } = ref;
+		if (!callback || !current) return;
+		const isAtBottom = () => Boolean(current && current.scrollHeight - (current.scrollTop + current.clientHeight) <= scrollTriggerMargin);
+		const onScroll = (e) => {
+			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]);
+};
+//#endregion
+export { useInfiniteScroll };

package/_internal/hooks/useIntersectionObserver.js

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+//#region src/hooks/useIntersectionObserver.tsx
+/**
+* Convenient hook to create interaction observers.
+*
+* @param elements Elements to observe.
+* @param options  IntersectionObserver options.
+* @return Map of intersections.
+*/
+function useIntersectionObserver(elements, options) {
+	const [intersections, setIntersections] = useState(() => /* @__PURE__ */ new Map());
+	useEffect(() => {
+		if (elements.length < 1 || !elements.some(Boolean)) return;
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) intersections.set(entry.target, entry);
+			setIntersections(new Map(intersections));
+		}, options);
+		for (const element of elements) if (element) observer.observe(element);
+		return () => observer.disconnect();
+	}, [...elements]);
+	return intersections;
+}
+//#endregion
+export { useIntersectionObserver };

package/_internal/hooks/useInterval.js

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from "react";
+import isFunction from "lodash/isFunction.js";
+//#region src/hooks/useInterval.tsx
+/**
+* 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.
+*/
+function useInterval(callback, delay) {
+	const savedCallback = useRef();
+	useEffect(() => {
+		savedCallback.current = callback;
+	});
+	useEffect(() => {
+		if (delay === null) return void 0;
+		function tick() {
+			if (isFunction(savedCallback.current)) savedCallback.current();
+		}
+		const id = setInterval(tick, delay);
+		return () => clearInterval(id);
+	}, [delay]);
+}
+//#endregion
+export { useInterval };

package/_internal/hooks/useIsomorphicLayoutEffect.js

@@ -0,0 +1,9 @@
+import { useEffect, useLayoutEffect } from "react";
+//#region src/hooks/useIsomorphicLayoutEffect.tsx
+/**
+* SSR-safe version of `useLayoutEffect`.
+* Uses `useLayoutEffect` on the client and `useEffect` on the server to avoid React SSR warnings.
+*/
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+//#endregion
+export { useIsomorphicLayoutEffect };

package/_internal/hooks/useKeyboardListNavigation.d.ts

@@ -0,0 +1,17 @@
+import { RefObject, SetStateAction } from "react";
+
+//#region src/hooks/useKeyboardListNavigation.d.ts
+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;
+}
+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;
+//#endregion
+export { useKeyboardListNavigationType };

package/_internal/hooks/useKeyboardListNavigation.js

@@ -0,0 +1,136 @@
+import { useEffect, useState } from "react";
+import get from "lodash/get.js";
+//#region src/hooks/useKeyboardListNavigation.tsx
+var 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.
+*/
+var useKeyboardListNavigation = (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) => {
+		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 = (evt) => {
+		evt.preventDefault();
+		evt.stopPropagation();
+	};
+	/**
+	* Handles navigation with the arrows using the keyboard
+	* @param evt - key pressed event
+	*/
+	const onArrowPressed = (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 = (evt) => {
+		if (onBackspacePressed) onBackspacePressed(evt);
+	};
+	/**
+	* Handles when the ENTER key is pressed
+	* @param evt - key pressed event
+	*/
+	const onEnterKeyPressed = (evt) => {
+		if (!onListItemSelected) return;
+		preventDefaultAndStopPropagation(evt);
+		if (!keepFocusAfterSelection) evt.currentTarget.blur();
+		const selectedItem = items[activeItemIndex];
+		if (selectedItem) {
+			onListItemSelected(selectedItem);
+			resetActiveIndex();
+		} else if (activeItemIndex === initialIndex && onEnterPressed) {
+			onEnterPressed(get(evt, "target.value"));
+			resetActiveIndex();
+		}
+	};
+	/**
+	* Handles when the TAB key is pressed
+	* @param evt - key pressed event
+	*/
+	const onTabKeyPressed = (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 = {
+		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 = (evt) => {
+		const { key } = evt;
+		const handler = eventsForKeyPressed[key];
+		if (handler) handler(evt);
+	};
+	useEffect(() => {
+		const { current: currentElement } = ref;
+		if (!currentElement) return;
+		currentElement.addEventListener("focus", resetActiveIndex);
+		currentElement.addEventListener("keydown", onKeyboardNavigation);
+		return () => {
+			currentElement.removeEventListener("focus", resetActiveIndex);
+			currentElement.removeEventListener("keydown", onKeyboardNavigation);
+		};
+	});
+	return {
+		activeItemIndex,
+		onKeyboardNavigation,
+		resetActiveIndex,
+		setActiveItemIndex
+	};
+};
+//#endregion
+export { useKeyboardListNavigation };

package/_internal/hooks/useListenFocus.js

@@ -0,0 +1,23 @@
+import { useEffect, useState } from "react";
+//#region src/hooks/useListenFocus.tsx
+/**
+* Listen on element focus to store the focus status.
+*/
+function useListenFocus(ref) {
+	const [isFocus, setFocus] = useState(false);
+	useEffect(() => {
+		const { current: element } = ref;
+		if (!element) return;
+		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;
+}
+//#endregion
+export { useListenFocus };

package/_internal/hooks/useOverflowTooltipLabel.js

@@ -0,0 +1,27 @@
+import { useTooltipContext } from "../components/tooltip/context.js";
+import React from "react";
+import { classNames } from "@lumx/core/js/utils";
+//#region src/hooks/useOverflowTooltipLabel.tsx
+/**
+* Compute a tooltip label based on a label element `innerText` if the text overflows.
+* Updates dynamically on content changes (but not on resize!)
+*/
+var useOverflowTooltipLabel = (content) => {
+	const parentTooltip = useTooltipContext();
+	const [tooltipLabel, setTooltipLabel] = React.useState(void 0);
+	const [labelElement, setLabelElement] = React.useState(null);
+	React.useLayoutEffect(() => {
+		if (!parentTooltip && labelElement && !labelElement?.closest(`.${classNames.visuallyHidden()}`) && labelElement.offsetWidth < labelElement.scrollWidth) setTooltipLabel(labelElement.innerText);
+		else setTooltipLabel(void 0);
+	}, [
+		labelElement,
+		parentTooltip,
+		content
+	]);
+	return {
+		labelRef: setLabelElement,
+		tooltipLabel
+	};
+};
+//#endregion
+export { useOverflowTooltipLabel };

package/_internal/hooks/usePreviousValue.js

@@ -0,0 +1,15 @@
+import React from "react";
+//#region src/hooks/usePreviousValue.ts
+/**
+* Returns the value from the previous render.
+*/
+function usePreviousValue(value) {
+	const prevValueRef = React.useRef();
+	const prevValue = prevValueRef.current;
+	React.useEffect(() => {
+		prevValueRef.current = value;
+	}, [value]);
+	return prevValue;
+}
+//#endregion
+export { usePreviousValue };

package/_internal/hooks/useRestoreFocusOnClose.js

@@ -0,0 +1,47 @@
+import { getFirstAndLastFocusable } from "../packages/lumx-core/src/js/utils/focus/getFirstAndLastFocusable.js";
+import { OnBeforeUnmount } from "../utils/react/OnBeforeUnmount.js";
+import React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/hooks/useRestoreFocusOnClose.tsx
+/**
+* Provides an unmount sentinel to inject in the popover to detect when it closes and restore the focus to the
+* anchor if needed.
+*/
+function useRestoreFocusOnClose({ focusAnchorOnClose, anchorRef, parentElement }, popoverElement, isOpen) {
+	const onBeforeUnmountRef = React.useRef();
+	const prevIsOpenRef = React.useRef(isOpen);
+	const tryRestoreFocus = React.useCallback(() => {
+		if (!popoverElement || !focusAnchorOnClose) return;
+		const focusedAtClose = document.activeElement;
+		if (!popoverElement.contains(focusedAtClose)) return;
+		setTimeout(() => {
+			const active = document.activeElement;
+			if (active && active !== focusedAtClose && active !== document.body && active !== document.documentElement) return;
+			const anchor = anchorRef.current;
+			(parentElement?.current || (anchor ? getFirstAndLastFocusable(anchor).first : void 0) || anchor)?.focus({ preventScroll: true });
+		}, 0);
+	}, [
+		anchorRef,
+		focusAnchorOnClose,
+		parentElement,
+		popoverElement
+	]);
+	React.useEffect(() => {
+		if (!popoverElement || !focusAnchorOnClose) {
+			onBeforeUnmountRef.current = void 0;
+			return;
+		}
+		onBeforeUnmountRef.current = tryRestoreFocus;
+	}, [
+		focusAnchorOnClose,
+		popoverElement,
+		tryRestoreFocus
+	]);
+	React.useEffect(() => {
+		if (prevIsOpenRef.current && !isOpen) tryRestoreFocus();
+		prevIsOpenRef.current = isOpen;
+	}, [isOpen, tryRestoreFocus]);
+	return /* @__PURE__ */ jsx(OnBeforeUnmount, { callbackRef: onBeforeUnmountRef });
+}
+//#endregion
+export { useRestoreFocusOnClose };

package/_internal/hooks/useRovingTabIndexContainer.js

@@ -0,0 +1,31 @@
+import { setupRovingTabIndex } from "../packages/lumx-core/src/js/utils/focusNavigation/setupRovingTabIndex.js";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+import { useEventCallback } from "./useEventCallback.js";
+import { unref } from "../utils/react/unref.js";
+//#region src/hooks/useRovingTabIndexContainer.tsx
+var useRovingTabIndexContainer = ({ containerRef, itemSelector, onItemFocused: unstableOnItemFocused, direction, itemDisabledSelector, itemSelectedAttr }) => {
+	const onItemFocused = useEventCallback(unstableOnItemFocused);
+	useIsomorphicLayoutEffect(() => {
+		const container = unref(containerRef);
+		if (!container) return;
+		const abortController = new AbortController();
+		setupRovingTabIndex({
+			container,
+			itemSelector,
+			direction,
+			itemDisabledSelector,
+			itemSelectedAttr,
+			onItemFocused
+		}, abortController.signal);
+		return () => abortController.abort();
+	}, [
+		containerRef,
+		itemSelector,
+		direction,
+		itemDisabledSelector,
+		itemSelectedAttr,
+		onItemFocused
+	]);
+};
+//#endregion
+export { useRovingTabIndexContainer };

package/_internal/hooks/useSizeOnWindowResize.js

@@ -0,0 +1,26 @@
+import React from "react";
+import throttle from "lodash/throttle.js";
+//#region src/hooks/useSizeOnWindowResize.ts
+/**
+* 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
+*/
+function useSizeOnWindowResize(elementRef) {
+	const [size, setSize] = React.useState(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];
+}
+//#endregion
+export { useSizeOnWindowResize };

package/_internal/hooks/useSlideshowControls.d.ts

@@ -0,0 +1,63 @@
+//#region src/hooks/useSlideshowControls.d.ts
+interface UseSlideshowControlsOptions {
+  /** default active index to be displayed */
+  defaultActiveIndex?: number;
+  /** total slides to display */
+  itemsCount: number;
+  /** Index of the current slide. */
+  activeIndex?: number;
+  /** Whether the automatic rotation of the slideshow is enabled or not. */
+  autoPlay?: boolean;
+  /** Whether the image has to fill its container height or not. */
+  fillHeight?: boolean;
+  /** Number of slides to group together. */
+  groupBy?: number;
+  /** Interval between each slide when automatic rotation is enabled. */
+  interval?: number;
+  /** Callback when slide changes */
+  onChange?(index: number): void;
+  /** slideshow HTML id attribute */
+  id?: string;
+  /** slides wrapper HTML id attribute */
+  slidesId?: string;
+}
+interface UseSlideshowControls {
+  /** Index for the first visible slide, should be used when groupBy is passed in */
+  startIndexVisible: number;
+  /** Index for the last visible slide, should be used when groupBy is passed in */
+  endIndexVisible: number;
+  /** total slides to be displayed */
+  slidesCount: number;
+  /** callback to set  */
+  setSlideshow: (element: HTMLDivElement | null) => void;
+  /** reference to the slideshow element */
+  slideshow: HTMLDivElement | null;
+  /** id to be used for the slideshow */
+  slideshowId: string;
+  /** id to be used for the wrapper that contains the slides */
+  slideshowSlidesId: string;
+  /** callback that triggers the previous slide while using the slideshow controls  */
+  onPreviousClick: (loopback: boolean) => void;
+  /** callback that triggers the next slide while using the slideshow controls */
+  onNextClick: (loopback: boolean) => void;
+  /** callback that triggers a specific page while using the slideshow controls */
+  onPaginationClick: (index: number) => void;
+  /** whether the slideshow is autoplaying or not */
+  isAutoPlaying: boolean;
+  /** whether the slideshow was force paused or not */
+  isForcePaused: boolean;
+  /** callback to change whether the slideshow is autoplaying or not */
+  toggleAutoPlay: () => void;
+  /** calback to change whether the slideshow should be force paused or not */
+  toggleForcePause: () => void;
+  /** current active slide index  */
+  activeIndex: number;
+  /** set the current index as the active one */
+  setActiveIndex: (index: number) => void;
+  /** callback that stops the auto play */
+  stopAutoPlay: () => void;
+  /** callback that starts the auto play */
+  startAutoPlay: () => void;
+}
+//#endregion
+export { UseSlideshowControls, UseSlideshowControlsOptions };