@zayne-labs/toolkit-react 0.11.19 → 0.11.21

package/dist/esm/hooks-iZivekUZ.js

@@ -1,635 +0,0 @@
-import { composeRefs } from "./utils-Bvs8tFDM.js";
-import { createContext, use, useCallback, useDebugValue, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { copyToClipboard, createExternalStorageStore, createLocationStore, createScrollObserver, createSearchParams, debounce, lockScroll, on, onClickOutside, setAnimationInterval, shallowCompare, throttleByFrame, throttleBySetTimeout, throttleByTime, toArray } from "@zayne-labs/toolkit-core";
-import { isArray, isBoolean, isFunction, isPlainObject } from "@zayne-labs/toolkit-type-helpers";
-
-//#region src/hooks/createCustomContext.ts
-const createCustomContext = (options = {}) => {
-	const { defaultValue = null, errorMessage, extension, hookName = "useUnnamedContext", providerName = "UnnamedContextProvider", name = providerName.endsWith("Provider") ? providerName.slice(0, -8) : "UnnamedContext", strict = true } = options;
-	const Context = createContext(defaultValue);
-	Context.displayName = name;
-	const useCustomContext = () => {
-		const contextValue = use(Context);
-		const extendedContextValue = extension?.(contextValue) ?? contextValue;
-		if (strict && extendedContextValue === null) throw new ContextError(errorMessage ?? getErrorMessage(hookName, providerName));
-		return extendedContextValue;
-	};
-	return [Context, useCustomContext];
-};
-var ContextError = class extends Error {
-	name = "ContextError";
-};
-const getErrorMessage = (hook, provider) => {
-	return `${hook} returned "null". Did you forget to wrap the necessary components within ${provider}?`;
-};
-
-//#endregion
-//#region src/hooks/useCallbackRef.ts
-/**
-* Returns a stable function that always points to the latest version of the callback function.
-* @param callbackFn - The function to reference
-* @returns a stable function that always points to the latest version of the callback function
-*/
-const useCallbackRef = (callbackFn) => {
-	const callbackRef = useRef(callbackFn);
-	useInsertionEffect(() => {
-		callbackRef.current = callbackFn;
-	}, [callbackFn]);
-	return useCallback((...params) => callbackRef.current?.(...params), []);
-};
-
-//#endregion
-//#region src/hooks/effects/useAfterMountEffect.ts
-const useAfterMountEffect = (callBackFn, deps) => {
-	const isFirstMount = useRef(true);
-	const stableCallback = useCallbackRef(callBackFn);
-	useEffect(() => {
-		if (isFirstMount.current) {
-			isFirstMount.current = false;
-			return;
-		}
-		stableCallback();
-	}, deps);
-};
-
-//#endregion
-//#region src/hooks/effects/useAsyncEffect.ts
-function useAsyncEffect(effect, deps) {
-	const stableEffectCallback = useCallbackRef(effect);
-	const [destroy, setDestroy] = useState();
-	useEffect(() => {
-		const e = stableEffectCallback();
-		async function execute() {
-			setDestroy(await e);
-		}
-		execute();
-		return () => void destroy?.();
-	}, deps);
-}
-
-//#endregion
-//#region src/hooks/effects/useEffectOnce.ts
-const useEffectOnce = (callBackFn) => {
-	const stableCallback = useCallbackRef(callBackFn);
-	const effectGuardRef = useRef(false);
-	useEffect(() => {
-		if (effectGuardRef.current) return;
-		effectGuardRef.current = true;
-		return stableCallback();
-	}, []);
-};
-
-//#endregion
-//#region src/hooks/effects/useLifeCycle.ts
-const useLifeCycle = ({ onMount, onUnmount }) => {
-	const stableOnMount = useCallbackRef(onMount);
-	const stableOnUnmount = useCallbackRef(onUnmount);
-	useEffect(() => {
-		stableOnMount();
-		return stableOnUnmount;
-	}, []);
-};
-
-//#endregion
-//#region src/hooks/effects/useMountEffect.ts
-const useMountEffect = (callBackFn) => {
-	useLifeCycle({ onMount: callBackFn });
-};
-
-//#endregion
-//#region src/hooks/effects/useUnMountEffect.ts
-const useUnmountEffect = (cleanUpFn) => useLifeCycle({ onUnmount: cleanUpFn });
-
-//#endregion
-//#region src/hooks/useAnimateElementRefs.ts
-const removeClass = (target, className) => () => target.classList.remove(className);
-/**
-* This is a custom React hook that adds and removes animation classes to specified HTML elements.
-* @param elementsInfoArray - An array of objects that contain information about the animation class and the target HTML element.
-* @returns - An object containing the refs of the animated elements and a function to handle the initiation and removal animation.
-*/
-const useAnimateElementRefs = (elementsInfoArray) => {
-	const elementsRef = useRef({});
-	const addAnimationClasses = useCallbackRef(() => {
-		if (!isArray(elementsInfoArray)) {
-			console.error("elementsInfo is not an Array");
-			return;
-		}
-		for (const { animationClass, targetElement } of elementsInfoArray) {
-			if (!elementsRef.current[targetElement]) {
-				console.error("ElementError", `"${targetElement}" element does not exist`);
-				return;
-			}
-			elementsRef.current[targetElement].classList.add(animationClass);
-		}
-	});
-	const removeAnimationClasses = useCallbackRef(() => {
-		if (!isArray(elementsInfoArray)) {
-			console.error("elementsInfo is not an Array");
-			return;
-		}
-		for (const { animationClass, targetElement } of elementsInfoArray) {
-			if (!elementsRef.current[targetElement]) {
-				console.error("ElementError", `"${targetElement}" element does not exist`);
-				return;
-			}
-			on("transitionend", elementsRef.current[targetElement], removeClass(elementsRef.current[targetElement], animationClass));
-			on("animationend", elementsRef.current[targetElement], removeClass(elementsRef.current[targetElement], animationClass));
-		}
-	});
-	const handleElementsAnimation = useCallback(() => {
-		addAnimationClasses();
-		removeAnimationClasses();
-	}, [addAnimationClasses, removeAnimationClasses]);
-	return {
-		animatedElements: elementsRef.current,
-		handleElementsAnimation
-	};
-};
-
-//#endregion
-//#region src/hooks/useAnimationInterval.ts
-const useAnimationInterval = (options) => {
-	const { intervalDuration, onAnimation, once } = options;
-	const latestCallback = useCallbackRef(onAnimation);
-	const { start, stop } = useMemo(() => setAnimationInterval(latestCallback, intervalDuration, { once }), [
-		intervalDuration,
-		latestCallback,
-		once
-	]);
-	useEffect(() => {
-		if (intervalDuration === null) return;
-		start();
-		return stop;
-	}, [intervalDuration]);
-	return {
-		start,
-		stop
-	};
-};
-
-//#endregion
-//#region src/hooks/useClickOutside.ts
-const useClickOutside = (options) => {
-	const innerRef = useRef(null);
-	const { enabled = true, onClick, ref: refOrRefArray = innerRef } = options;
-	const savedOnClick = useCallbackRef(onClick);
-	useEffect(() => {
-		if (!enabled) return;
-		const elementArray = toArray(refOrRefArray).map((ref) => ref.current);
-		const cleanup = onClickOutside(elementArray, savedOnClick);
-		return () => cleanup();
-	}, [
-		enabled,
-		refOrRefArray,
-		savedOnClick
-	]);
-	return { ref: innerRef };
-};
-
-//#endregion
-//#region src/hooks/useComposeRefs.ts
-const useComposeRefs = (...refs) => {
-	return useMemo(() => composeRefs(...refs), refs);
-};
-
-//#endregion
-//#region src/hooks/useConstant.ts
-const useConstant = (initFn) => {
-	const resultRef = useRef(null);
-	if (resultRef.current === null) resultRef.current = initFn();
-	return resultRef.current;
-};
-const useLazyRef = (initFn) => {
-	const resultRef = useRef(null);
-	if (resultRef.current === null) resultRef.current = initFn();
-	return resultRef;
-};
-
-//#endregion
-//#region src/hooks/useControllable.ts
-/**
-* @description Given a prop value and state value, the useControllableProp hook is used to determine whether a component is controlled or uncontrolled, and also returns the computed value.
-*/
-const useControllableProp = (options) => {
-	const { prop, state } = options;
-	const isControlled = prop !== void 0;
-	const value = isControlled ? prop : state;
-	return useMemo(() => [isControlled, value], [isControlled, value]);
-};
-/**
-* @description React hook to manage state that can be either controlled or uncontrolled.
-* - When `options.value` is provided, the hook operates in controlled mode.
-*   In this mode, `value` always equals `options.value` and `setValue` will
-*   invoke `options.onChange(next)` without mutating internal state.
-* - When `options.value` is not provided, the hook operates in uncontrolled
-*   mode, initializing internal state from `options.defaultValue` and updating
-*   it via `setValue`.
-* - All updates are gated by `options.equalityFn(prev, next)` which defaults
-*   to `Object.is`.
-*
-* @param options - Configuration options for the hook.
-* @param options.value - Controlled value. If defined, the state is controlled.
-* @param options.defaultValue - Initial value for the uncontrolled state. Can be a
-* function for lazy initialization or a direct value.
-* @param options.onChange - Callback fired when a new value is requested. In
-* controlled mode, this is invoked instead of updating internal state. In
-* uncontrolled mode, it is called after the internal state updates.
-* @param options.equalityFn - Predicate that decides whether to commit an
-* update given `prevState` and `nextValue`. If the values are equal, the update
-* is skipped. Defaults to `Object.is`.
-* @returns A tuple `[value, setValue]`  just like React.useState.
-*
-* @example
-* // Uncontrolled usage
-* const [value, setValue] = useControllableState({ defaultValue: 0 });
-*
-* @example
-* // Controlled usage
-* const [value, setValue] = useControllableState({
-*   value: props.value,
-*   onChange: props.onChange,
-* });
-*/
-const useControllableState = (options) => {
-	const { defaultValue, equalityFn = Object.is, onChange: onChangeProp, value: valueProp } = options;
-	const savedOnchangeProp = useCallbackRef(onChangeProp);
-	const savedEqualityFn = useCallbackRef(equalityFn);
-	const [unControlledState, setUncontrolledState] = useState(defaultValue);
-	const isControlled = valueProp !== void 0;
-	const currentValue = isControlled ? valueProp : unControlledState;
-	const setValue = useCallback((newValue) => {
-		const nextValue = isFunction(newValue) ? newValue(currentValue) : newValue;
-		if (savedEqualityFn(currentValue, nextValue)) return;
-		if (isControlled) {
-			savedOnchangeProp(nextValue);
-			return;
-		}
-		setUncontrolledState(nextValue);
-		savedOnchangeProp(nextValue);
-	}, [
-		isControlled,
-		savedOnchangeProp,
-		savedEqualityFn,
-		currentValue
-	]);
-	return [currentValue, setValue];
-};
-
-//#endregion
-//#region src/hooks/useToggle.ts
-const useToggle = (initialValue = false) => {
-	const [value, setValue] = useState(initialValue);
-	const toggleValue = useCallback((newValue) => {
-		if (typeof newValue === "boolean") {
-			setValue(newValue);
-			return;
-		}
-		setValue((prev) => !prev);
-	}, []);
-	return [value, toggleValue];
-};
-
-//#endregion
-//#region src/hooks/useCopyToClipboard.ts
-const useCopyToClipboard = (options = {}) => {
-	const { mimeType, onCopied, onError, onSuccess, timeout = 1500 } = options;
-	const [value, setValue] = useState("");
-	const [hasCopied, toggleHasCopied] = useToggle(false);
-	const timeoutRef = useRef(null);
-	const savedOnError = useCallbackRef(onError);
-	const savedOnSuccess = useCallbackRef(onSuccess);
-	const savedOnCopied = useCallbackRef(onCopied);
-	const handleHasCopied = useCallback(() => {
-		toggleHasCopied(true);
-		timeoutRef.current && clearTimeout(timeoutRef.current);
-		timeoutRef.current = setTimeout(() => {
-			toggleHasCopied(false);
-		}, timeout);
-	}, [toggleHasCopied, timeout]);
-	return {
-		handleCopy: useCallback((valueToCopy) => {
-			setValue(valueToCopy);
-			copyToClipboard(valueToCopy, {
-				mimeType,
-				onCopied: () => {
-					savedOnCopied();
-					handleHasCopied();
-				},
-				onError: savedOnError,
-				onSuccess: savedOnSuccess
-			});
-		}, [
-			handleHasCopied,
-			mimeType,
-			savedOnCopied,
-			savedOnError,
-			savedOnSuccess
-		]),
-		hasCopied,
-		setValue,
-		value
-	};
-};
-
-//#endregion
-//#region src/hooks/useDebounce.ts
-const useDebouncedFn = (callBackFn, delay) => {
-	const latestCallback = useCallbackRef(callBackFn);
-	const debouncedFn = useMemo(() => debounce(latestCallback, delay), [delay, latestCallback]);
-	useUnmountEffect(() => {
-		debouncedFn.cancel();
-		debouncedFn.cancelMaxWait();
-	});
-	return debouncedFn;
-};
-const useDebouncedState = (defaultValue, delay) => {
-	const [value, setValue] = useState(defaultValue);
-	const setDebouncedValue = useMemo(() => debounce(setValue, delay), [delay]);
-	useUnmountEffect(() => {
-		setDebouncedValue.cancel();
-		setDebouncedValue.cancelMaxWait();
-	});
-	return [
-		value,
-		setDebouncedValue,
-		setValue
-	];
-};
-
-//#endregion
-//#region src/hooks/useDisclosure.ts
-const useDisclosure = (options = {}) => {
-	const { hasScrollControl = false, initialState = false } = options;
-	const [isOpen, toggleIsOpen] = useToggle(initialState);
-	const onOpen = useCallbackRef(() => {
-		toggleIsOpen(true);
-		hasScrollControl && lockScroll({ lock: true });
-	});
-	const onClose = useCallbackRef(() => {
-		toggleIsOpen(false);
-		hasScrollControl && lockScroll({ lock: false });
-	});
-	const onToggle = useCallbackRef((value) => {
-		if (isBoolean(value)) {
-			toggleIsOpen(value);
-			hasScrollControl && lockScroll({ lock: value });
-			return;
-		}
-		isOpen ? onClose() : onOpen();
-	});
-	return useMemo(() => ({
-		isOpen,
-		onClose,
-		onOpen,
-		onToggle
-	}), [
-		isOpen,
-		onClose,
-		onOpen,
-		onToggle
-	]);
-};
-
-//#endregion
-//#region src/hooks/useIsHydrated.ts
-const noop = () => {};
-const noopStore = {
-	getServerSnapshot: () => true,
-	getSnapshot: () => false,
-	subscribe: () => noop
-};
-/**
-* @description Return a boolean indicating if the JS has been hydrated already.
-* When doing Server-Side Rendering, the result will always be false.
-* When doing Client-Side Rendering, the result will always be false on the
-* first render and true from then on. Even if a new component renders it will
-* always start with true.
-*
-* @see https://github.com/sergiodxa/remix-utils/blob/main/src/react/use-hydrated.ts
-*
-* @see https://github.com/sergiodxa/remix-utils/blob/main/src/react/use-hydrated.ts
-*
-* @example
-* **Example: Disable a button that needs JS to work.**
-* ```tsx
-* const isHydrated = useIsHydrated();
-*
-* return (
-*   <button type="button" disabled={!isHydrated} onClick={doSomethingCustom}>
-*     Click me
-*   </button>
-* );
-* ```
-*/
-const useIsHydrated = () => {
-	return useSyncExternalStore(noopStore.subscribe, noopStore.getSnapshot, noopStore.getServerSnapshot);
-};
-
-//#endregion
-//#region src/hooks/useStore.ts
-const identity = (value) => value;
-const useStore = (store, selector = identity) => {
-	const slice = useSyncExternalStore(store.subscribe, useCallback(() => selector(store.getState()), [store, selector]), useCallback(() => selector(store.getInitialState()), [store, selector]));
-	useDebugValue(slice);
-	return slice;
-};
-
-//#endregion
-//#region src/hooks/useLocationState.ts
-const createUseLocationState = (options) => {
-	const locationStore = createLocationStore(options);
-	const useLocationState$1 = (selector) => {
-		return [useStore(locationStore, selector), locationStore];
-	};
-	Object.assign(useLocationState$1, locationStore);
-	return useLocationState$1;
-};
-const useLocationState = (selector, options = {}) => {
-	const { equalityFn } = options;
-	const savedEqualityFn = useCallbackRef(equalityFn);
-	const locationStore = useMemo(() => createLocationStore({ equalityFn: savedEqualityFn }), [savedEqualityFn]);
-	return [useStore(locationStore, selector), locationStore];
-};
-
-//#endregion
-//#region src/hooks/useScrollObserver.ts
-const useScrollObserver = (options = {}) => {
-	const { onIntersection, root, rootMargin = "10px 0px 0px 0px", threshold } = options;
-	const [isScrolled, setIsScrolled] = useState(false);
-	const savedOnIntersection = useCallbackRef(onIntersection);
-	const { handleObservation } = useMemo(() => {
-		return createScrollObserver({
-			onIntersection: (entry, observer) => {
-				const newIsScrolledState = !entry.isIntersecting;
-				setIsScrolled(newIsScrolledState);
-				entry.target.dataset.scrolled = String(newIsScrolledState);
-				savedOnIntersection(entry, observer);
-			},
-			root,
-			rootMargin,
-			threshold
-		});
-	}, [
-		root,
-		rootMargin,
-		savedOnIntersection,
-		threshold
-	]);
-	const observedElementRef = useCallbackRef((element) => {
-		const cleanupFn = handleObservation(element);
-		if (!element) {
-			cleanupFn?.();
-			return;
-		}
-		return cleanupFn;
-	});
-	return {
-		isScrolled,
-		observedElementRef
-	};
-};
-
-//#endregion
-//#region src/hooks/useSearch.ts
-const isSerializable = (item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean";
-const checkObjectPropsForQuery = (item, query) => {
-	for (const value of Object.values(item)) if (isSerializable(value) && value.toString().toLowerCase().includes(query)) return true;
-	return false;
-};
-const useSearch = (initialData, delay) => {
-	const [searchQuery, setSearchQuery] = useState("");
-	const [filteredData, setFilteredData] = useState(initialData);
-	const [isLoading, setIsLoading] = useState(false);
-	const handleDebouncedSearch = useDebouncedFn(() => {
-		const query = searchQuery.toLowerCase();
-		const filteredResults = initialData.filter((item) => {
-			if (isSerializable(item)) return item.toString().toLowerCase().includes(query);
-			if (isPlainObject(item)) return checkObjectPropsForQuery(item, query);
-			return false;
-		});
-		setFilteredData(filteredResults);
-		setIsLoading(false);
-	}, delay);
-	useAfterMountEffect(() => {
-		setIsLoading(true);
-		handleDebouncedSearch();
-	}, [searchQuery]);
-	return {
-		data: filteredData,
-		isLoading,
-		query: searchQuery,
-		setQuery: setSearchQuery
-	};
-};
-
-//#endregion
-//#region src/hooks/useSearchParams.ts
-const useSearchParams = (options) => {
-	const { action = "push",...restOfOptions } = options ?? {};
-	const [searchParams, actions] = useLocationState((state) => state.search, restOfOptions);
-	const setSearchParams = (newQueryParams) => {
-		const params = isFunction(newQueryParams) ? newQueryParams(searchParams) : newQueryParams;
-		const nextSearchParams = createSearchParams(params);
-		actions[action]({ search: nextSearchParams });
-	};
-	setSearchParams.triggerPopstateEvent = actions.triggerPopstateEvent;
-	return [searchParams, setSearchParams];
-};
-const useSearchParamsObject = (options) => {
-	const [searchParams, setSearchParams] = useSearchParams(options);
-	const searchParamsObject = Object.fromEntries(searchParams);
-	const setSearchParamsObject = (newQueryParams) => {
-		const params = isFunction(newQueryParams) ? newQueryParams(searchParamsObject) : newQueryParams;
-		setSearchParams(params);
-	};
-	setSearchParamsObject.triggerPopstateEvent = setSearchParams.triggerPopstateEvent;
-	return [searchParamsObject, setSearchParamsObject];
-};
-
-//#endregion
-//#region src/hooks/useShallowCompare.ts
-const useShallowCompSelector = (selector) => {
-	const prevStateRef = useRef(void 0);
-	return useCallbackRef((state) => {
-		const nextState = selector?.(state);
-		if (!nextState) return prevStateRef.current;
-		if (shallowCompare(prevStateRef.current, nextState)) return prevStateRef.current;
-		return prevStateRef.current = nextState;
-	});
-};
-const useShallowCompValue = (value) => {
-	const prevValueRef = useRef(value);
-	if (shallowCompare(prevValueRef.current, value)) return prevValueRef.current;
-	return prevValueRef.current = value;
-};
-
-//#endregion
-//#region src/hooks/useStorageState.ts
-/**
-* @description Creates a custom hook that returns a storage state and actions to modify it. You can use this if you need shared options.
-* @note You must use this if you want to be able to prevent syncing state across tabs.
-*/
-const createUseStorageState = (baseOptions) => {
-	const externalStore = createExternalStorageStore(baseOptions);
-	const useStorageState$1 = (selector) => {
-		return [useStore(externalStore, selector), externalStore];
-	};
-	Object.assign(useStorageState$1, externalStore);
-	return useStorageState$1;
-};
-const useStorageState = (key, initialValue, options) => {
-	const { equalityFn, logger, parser, partialize, select, serializer, storageArea, syncStateAcrossTabs } = options ?? {};
-	const savedEquality = useCallbackRef(equalityFn);
-	const savedLogger = useCallbackRef(logger);
-	const savedParser = useCallbackRef(parser);
-	const savedPartialize = useCallbackRef(partialize);
-	const savedSerializer = useCallbackRef(serializer);
-	const externalStore = useMemo(() => {
-		return createExternalStorageStore({
-			equalityFn: savedEquality,
-			initialValue,
-			key,
-			logger: savedLogger,
-			parser: savedParser,
-			partialize: savedPartialize,
-			serializer: savedSerializer,
-			storageArea,
-			syncStateAcrossTabs
-		});
-	}, [
-		initialValue,
-		key,
-		savedEquality,
-		savedLogger,
-		savedParser,
-		savedPartialize,
-		savedSerializer,
-		storageArea,
-		syncStateAcrossTabs
-	]);
-	return [useStore(externalStore, select), externalStore];
-};
-
-//#endregion
-//#region src/hooks/useThrottle.ts
-const useThrottleBySetTimeout = (callbackFn, delay) => {
-	const latestCallback = useCallbackRef(callbackFn);
-	const throttledCallback = useMemo(() => throttleBySetTimeout(latestCallback, delay), [delay, latestCallback]);
-	useUnmountEffect(() => throttledCallback.cancelTimeout());
-	return throttledCallback;
-};
-const useThrottleByTimer = (callbackFn, delay) => {
-	const latestCallback = useCallbackRef(callbackFn);
-	return useMemo(() => throttleByTime(latestCallback, delay), [delay, latestCallback]);
-};
-const useThrottleByFrame = (callbackFn) => {
-	const latestCallback = useCallbackRef(callbackFn);
-	const throttledCallback = useConstant(() => throttleByFrame(latestCallback));
-	useUnmountEffect(() => throttledCallback.cancelAnimation());
-	return throttledCallback;
-};
-
-//#endregion
-export { ContextError, createCustomContext, createUseLocationState, createUseStorageState, getErrorMessage, useAfterMountEffect, useAnimateElementRefs, useAnimationInterval, useAsyncEffect, useCallbackRef, useClickOutside, useComposeRefs, useConstant, useControllableProp, useControllableState, useCopyToClipboard, useDebouncedFn, useDebouncedState, useDisclosure, useEffectOnce, useIsHydrated, useLazyRef, useLifeCycle, useLocationState, useMountEffect, useScrollObserver, useSearch, useSearchParams, useSearchParamsObject, useShallowCompSelector, useShallowCompValue, useStorageState, useStore, useThrottleByFrame, useThrottleBySetTimeout, useThrottleByTimer, useToggle, useUnmountEffect };
-//# sourceMappingURL=hooks-iZivekUZ.js.map