@musecat/functionkit 1.0.0 → 1.0.2

package/packages/hooks/useDoubleClick.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { type MouseEvent, useCallback, useEffect, useRef } from "react";
+
+type UseDoubleClickProps<E extends HTMLElement> = {
+	delay?: number;
+	click?: (event: MouseEvent<E>) => void;
+	doubleClick: (event: MouseEvent<E>) => void;
+};
+
+export function useDoubleClick<E extends HTMLElement = HTMLElement>({
+	delay = 250,
+	click,
+	doubleClick,
+}: UseDoubleClickProps<E>) {
+	const clickTimeout = useRef<number | null>(null);
+
+	const savedClick = useRef(click);
+	const savedDoubleClick = useRef(doubleClick);
+	savedClick.current = click;
+	savedDoubleClick.current = doubleClick;
+
+	useEffect(() => {
+		return () => {
+			if (clickTimeout.current != null) {
+				window.clearTimeout(clickTimeout.current);
+			}
+		};
+	}, []);
+
+	const handleEvent = useCallback(
+		(event: MouseEvent<E>) => {
+			if (clickTimeout.current != null) {
+				window.clearTimeout(clickTimeout.current);
+				clickTimeout.current = null;
+			}
+
+			if (event.detail === 1 && savedClick.current) {
+				clickTimeout.current = window.setTimeout(() => {
+					clickTimeout.current = null;
+					savedClick.current?.(event);
+				}, delay);
+			}
+
+			if (event.detail === 2) {
+				savedDoubleClick.current(event);
+			}
+		},
+		[delay],
+	);
+
+	return handleEvent;
+}

package/packages/hooks/useGeolocation.ts

@@ -0,0 +1,146 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+type GeolocationData = {
+	latitude: number;
+	longitude: number;
+	accuracy: number;
+	altitude: number | null;
+	altitudeAccuracy: number | null;
+	heading: number | null;
+	speed: number | null;
+	timestamp: number;
+};
+
+const MOUNT_BEHAVIOR = { GET: "get", WATCH: "watch" } as const;
+
+type MountBehavior = (typeof MOUNT_BEHAVIOR)[keyof typeof MOUNT_BEHAVIOR];
+
+type UseGeolocationOptions = {
+	mountBehavior?: MountBehavior;
+	enableHighAccuracy?: boolean;
+	timeout?: number;
+	maximumAge?: number;
+};
+
+export function useGeolocation(options?: UseGeolocationOptions) {
+	const [state, setState] = useState<{
+		loading: boolean;
+		error: string | null;
+		data: GeolocationData | null;
+	}>({
+		loading: !!options?.mountBehavior,
+		error: null,
+		data: null,
+	});
+	const [isTracking, setIsTracking] = useState(false);
+	const watchIdRef = useRef<number | null>(null);
+
+	const isSupported = useCallback(() => {
+		if (typeof window === "undefined" || !navigator.geolocation) {
+			setState((prev) => ({
+				...prev,
+				loading: false,
+				error: "Geolocation is not supported by this environment.",
+			}));
+			return false;
+		}
+		return true;
+	}, []);
+
+	const handleSuccess = useCallback((position: GeolocationPosition) => {
+		const { coords } = position;
+		setState((prev) => ({
+			...prev,
+			loading: false,
+			error: null,
+			data: {
+				latitude: coords.latitude,
+				longitude: coords.longitude,
+				accuracy: coords.accuracy,
+				altitude: coords.altitude,
+				altitudeAccuracy: coords.altitudeAccuracy,
+				heading: coords.heading,
+				speed: coords.speed,
+				timestamp: position.timestamp,
+			},
+		}));
+	}, []);
+
+	const handleError = useCallback((error: GeolocationPositionError) => {
+		setState((prev) => ({
+			...prev,
+			loading: false,
+			error: error.message,
+		}));
+	}, []);
+
+	const geoOptions = useCallback(
+		() => ({
+			enableHighAccuracy: options?.enableHighAccuracy ?? false,
+			maximumAge: options?.maximumAge ?? 0,
+			timeout: options?.timeout ?? Infinity,
+		}),
+		[options?.enableHighAccuracy, options?.maximumAge, options?.timeout],
+	);
+
+	const getCurrentPosition = useCallback(() => {
+		if (!isSupported()) return;
+		setState((prev) => ({ ...prev, loading: true }));
+		navigator.geolocation.getCurrentPosition(
+			handleSuccess,
+			handleError,
+			geoOptions(),
+		);
+	}, [handleSuccess, handleError, geoOptions, isSupported]);
+
+	const startTracking = useCallback(() => {
+		if (!isSupported()) return;
+
+		if (watchIdRef.current !== null) {
+			navigator.geolocation.clearWatch(watchIdRef.current);
+		}
+
+		setState((prev) => ({ ...prev, loading: true }));
+
+		watchIdRef.current = navigator.geolocation.watchPosition(
+			(position) => {
+				setIsTracking(true);
+				handleSuccess(position);
+			},
+			handleError,
+			geoOptions(),
+		);
+	}, [handleSuccess, handleError, geoOptions, isSupported]);
+
+	const stopTracking = useCallback(() => {
+		if (watchIdRef.current === null) return;
+		navigator.geolocation.clearWatch(watchIdRef.current);
+		watchIdRef.current = null;
+		setIsTracking(false);
+	}, []);
+
+	useEffect(() => {
+		if (options?.mountBehavior === MOUNT_BEHAVIOR.WATCH) {
+			startTracking();
+		} else if (options?.mountBehavior === MOUNT_BEHAVIOR.GET) {
+			getCurrentPosition();
+		}
+
+		return () => {
+			if (watchIdRef.current !== null) {
+				navigator.geolocation.clearWatch(watchIdRef.current);
+				watchIdRef.current = null;
+			}
+		};
+	}, [options?.mountBehavior, getCurrentPosition, startTracking]);
+
+	return {
+		...state,
+		getCurrentPosition,
+		startTracking,
+		stopTracking,
+		isTracking,
+	};
+}

package/packages/hooks/useHasMounted.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export function useHasMounted() {
+	const [hasMounted, setHasMounted] = useState(false);
+
+	useEffect(() => {
+		setHasMounted(true);
+	}, []);
+
+	return hasMounted;
+}

package/packages/hooks/useIntersectionObserver.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { usePreservedCallback } from "./usePreservedCallback";
+import { useRefEffect } from "./useRefEffect";
+
+export function useIntersectionObserver<Element extends HTMLElement>(
+	callback: (entry: IntersectionObserverEntry) => void,
+	options: IntersectionObserverInit,
+): (element: Element | null) => void {
+	const preservedCallback = usePreservedCallback(callback);
+
+	const observer = useMemo(() => {
+		if (typeof IntersectionObserver === "undefined") {
+			return;
+		}
+
+		return new IntersectionObserver(([entry]) => {
+			preservedCallback(entry);
+		}, options);
+	}, [preservedCallback, options]);
+
+	return useRefEffect<Element>(
+		(element) => {
+			observer?.observe(element);
+
+			return () => {
+				observer?.unobserve(element);
+			};
+		},
+		[preservedCallback, options],
+	);
+}

package/packages/hooks/useInterval.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+import { usePreservedCallback } from "./usePreservedCallback";
+
+type IntervalOptions =
+	| number
+	| {
+			delay: number;
+			immediate?: boolean;
+			enabled?: boolean;
+	  };
+
+export function useInterval(callback: () => void, options: IntervalOptions) {
+	const delay = typeof options === "number" ? options : options.delay;
+	const immediate = typeof options === "number" ? false : options.immediate;
+	const enabled =
+		typeof options === "number" ? true : (options.enabled ?? true);
+
+	const preservedCallback = usePreservedCallback(callback);
+	const immediateCalledRef = useRef(false);
+
+	useEffect(
+		function runImmediateCallback() {
+			if (immediate !== true) {
+				immediateCalledRef.current = false;
+				return;
+			}
+
+			if (!enabled) {
+				return;
+			}
+
+			if (immediateCalledRef.current) {
+				return;
+			}
+
+			immediateCalledRef.current = true;
+			preservedCallback();
+		},
+		[immediate, preservedCallback, enabled],
+	);
+
+	useEffect(
+		function startInterval() {
+			if (!enabled) {
+				return;
+			}
+
+			const id = setInterval(preservedCallback, delay);
+			return () => clearInterval(id);
+		},
+		[delay, preservedCallback, enabled],
+	);
+}

package/packages/hooks/useKeyboardHeight.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { subscribeKeyboardHeight } from "../utils/subscribeKeyboardHeight";
+
+export function useKeyboardHeight() {
+	const [keyboardHeight, setKeyboardHeight] = useState(0);
+
+	useEffect(() => {
+		const { unsubscribe } = subscribeKeyboardHeight({
+			callback: setKeyboardHeight,
+			immediate: true,
+		});
+		return unsubscribe;
+	}, []);
+
+	return { keyboardHeight };
+}

package/packages/hooks/useKeyboardListNavigation.ts

@@ -0,0 +1,170 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { isEditableKeyboardTarget } from "../utils/keyboardTarget";
+
+const FIRST_ITEM_KEYS = new Set(["ArrowDown", "ArrowRight", "Home"]);
+const LAST_ITEM_KEYS = new Set(["ArrowUp", "ArrowLeft", "End"]);
+
+type UseKeyboardListNavigationOptions = {
+	itemCount: number;
+};
+
+export function useKeyboardListNavigation({
+	itemCount,
+}: UseKeyboardListNavigationOptions) {
+	const [activeIndex, setActiveIndex] = useState(-1);
+	const itemRefs = useRef<(HTMLElement | null)[]>([]);
+
+	const setItemRef = useCallback(
+		(index: number, element: HTMLElement | null) => {
+			itemRefs.current[index] = element;
+		},
+		[],
+	);
+
+	const focusItem = useCallback((index: number) => {
+		const target = itemRefs.current[index];
+		if (!target) {
+			return false;
+		}
+
+		setActiveIndex(index);
+		target.focus();
+		target.scrollIntoView({
+			block: "nearest",
+			inline: "nearest",
+		});
+		return true;
+	}, []);
+
+	const focusBoundaryItem = useCallback(
+		(key: string) => {
+			if (itemCount === 0) {
+				return false;
+			}
+
+			if (FIRST_ITEM_KEYS.has(key)) {
+				return focusItem(0);
+			}
+
+			if (LAST_ITEM_KEYS.has(key)) {
+				return focusItem(itemCount - 1);
+			}
+
+			return false;
+		},
+		[focusItem, itemCount],
+	);
+
+	const moveActiveItem = useCallback(
+		(key: string) => {
+			if (itemCount === 0) {
+				return false;
+			}
+
+			if (key === "Home") {
+				return focusItem(0);
+			}
+
+			if (key === "End") {
+				return focusItem(itemCount - 1);
+			}
+
+			if (key === "ArrowDown" || key === "ArrowRight") {
+				const nextIndex = activeIndex < 0 ? 0 : (activeIndex + 1) % itemCount;
+				return focusItem(nextIndex);
+			}
+
+			if (key === "ArrowUp" || key === "ArrowLeft") {
+				const nextIndex =
+					activeIndex < 0
+						? itemCount - 1
+						: (activeIndex - 1 + itemCount) % itemCount;
+				return focusItem(nextIndex);
+			}
+
+			return false;
+		},
+		[activeIndex, focusItem, itemCount],
+	);
+
+	const clickActiveItem = useCallback(() => {
+		if (activeIndex < 0) {
+			return false;
+		}
+
+		itemRefs.current[activeIndex]?.click();
+		return true;
+	}, [activeIndex]);
+
+	const handleListKeyDown = useCallback(
+		(
+			event: React.KeyboardEvent<HTMLElement>,
+			options?: { container?: HTMLElement | null },
+		) => {
+			if (itemCount === 0 || event.defaultPrevented) {
+				return;
+			}
+
+			const target = event.target as HTMLElement | null;
+
+			if (!target) {
+				return;
+			}
+
+			if (isEditableKeyboardTarget(target)) {
+				return;
+			}
+
+			if (options?.container && !options.container.contains(target)) {
+				return;
+			}
+
+			if (event.key === "Escape") {
+				setActiveIndex(-1);
+				return;
+			}
+
+			if (
+				event.key === "Enter" ||
+				event.key === " " ||
+				event.key === "ArrowDown" ||
+				event.key === "ArrowUp" ||
+				event.key === "ArrowLeft" ||
+				event.key === "ArrowRight" ||
+				event.key === "Home" ||
+				event.key === "End"
+			) {
+				event.preventDefault();
+			}
+
+			if (event.key === "Enter" || event.key === " ") {
+				clickActiveItem();
+				return;
+			}
+
+			if (moveActiveItem(event.key)) {
+				return;
+			}
+
+			if (focusBoundaryItem(event.key)) {
+				return;
+			}
+		},
+		[clickActiveItem, moveActiveItem, focusBoundaryItem, itemCount],
+	);
+
+	useEffect(() => {
+		itemRefs.current = itemRefs.current.slice(0, itemCount);
+	}, [itemCount]);
+
+	return {
+		activeIndex,
+		setActiveIndex,
+		setItemRef,
+		clickActiveItem,
+		focusBoundaryItem,
+		handleListKeyDown,
+	};
+}

package/packages/hooks/useLongPress.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { type MouseEvent, type TouchEvent, useCallback, useRef } from "react";
+
+export type UseLongPressOptions<E extends HTMLElement> = {
+	delay?: number;
+	moveThreshold?: {
+		x?: number;
+		y?: number;
+	};
+	onClick?: (event: MouseEvent<E> | TouchEvent<E>) => void;
+	onLongPressEnd?: (event: MouseEvent<E> | TouchEvent<E>) => void;
+};
+
+export function useLongPress<E extends HTMLElement = HTMLElement>(
+	onLongPress: (event: MouseEvent<E> | TouchEvent<E>) => void,
+	{
+		delay = 500,
+		moveThreshold,
+		onClick,
+		onLongPressEnd,
+	}: UseLongPressOptions<E> = {},
+) {
+	const timeoutRef = useRef<number | null>(null);
+	const isLongPressActiveRef = useRef(false);
+	const initialPositionRef = useRef({ x: 0, y: 0 });
+
+	const savedOnLongPress = useRef(onLongPress);
+	const savedOnClick = useRef(onClick);
+	const savedOnLongPressEnd = useRef(onLongPressEnd);
+	savedOnLongPress.current = onLongPress;
+	savedOnClick.current = onClick;
+	savedOnLongPressEnd.current = onLongPressEnd;
+
+	const hasThreshold =
+		moveThreshold?.x !== undefined || moveThreshold?.y !== undefined;
+
+	const getClientPosition = useCallback(
+		(event: MouseEvent<E> | TouchEvent<E>) => {
+			if ("touches" in event.nativeEvent) {
+				const touch = event.nativeEvent.touches[0];
+				return { x: touch.clientX, y: touch.clientY };
+			}
+			return {
+				x: event.nativeEvent.clientX,
+				y: event.nativeEvent.clientY,
+			};
+		},
+		[],
+	);
+
+	const isMovedBeyondThreshold = useCallback(
+		(event: MouseEvent<E> | TouchEvent<E>) => {
+			const { x, y } = getClientPosition(event);
+			const deltaX = Math.abs(x - initialPositionRef.current.x);
+			const deltaY = Math.abs(y - initialPositionRef.current.y);
+
+			return (
+				(moveThreshold?.x !== undefined && deltaX > moveThreshold.x) ||
+				(moveThreshold?.y !== undefined && deltaY > moveThreshold.y)
+			);
+		},
+		[getClientPosition, moveThreshold],
+	);
+
+	const cancelLongPress = useCallback(() => {
+		if (timeoutRef.current !== null) {
+			window.clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+	}, []);
+
+	const handlePressStart = useCallback(
+		(event: MouseEvent<E> | TouchEvent<E>) => {
+			cancelLongPress();
+			initialPositionRef.current = getClientPosition(event);
+			isLongPressActiveRef.current = false;
+
+			timeoutRef.current = window.setTimeout(() => {
+				isLongPressActiveRef.current = true;
+				savedOnLongPress.current(event);
+			}, delay);
+		},
+		[cancelLongPress, delay, getClientPosition],
+	);
+
+	const handlePressEnd = useCallback(
+		(event: MouseEvent<E> | TouchEvent<E>) => {
+			if (isLongPressActiveRef.current) {
+				savedOnLongPressEnd.current?.(event);
+			} else if (timeoutRef.current !== null) {
+				savedOnClick.current?.(event);
+			}
+
+			cancelLongPress();
+			isLongPressActiveRef.current = false;
+		},
+		[cancelLongPress],
+	);
+
+	const handlePressMove = useCallback(
+		(event: MouseEvent<E> | TouchEvent<E>) => {
+			if (timeoutRef.current !== null && isMovedBeyondThreshold(event)) {
+				cancelLongPress();
+			}
+		},
+		[cancelLongPress, isMovedBeyondThreshold],
+	);
+
+	return {
+		onMouseDown: handlePressStart,
+		onMouseUp: handlePressEnd,
+		onMouseLeave: cancelLongPress,
+		onTouchStart: handlePressStart,
+		onTouchEnd: handlePressEnd,
+		...(hasThreshold
+			? { onTouchMove: handlePressMove, onMouseMove: handlePressMove }
+			: {}),
+	};
+}

package/packages/hooks/usePreservedCallback.ts

@@ -0,0 +1,21 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+export function usePreservedCallback<
+	Arguments extends unknown[] = unknown[],
+	ReturnValue = unknown,
+>(callback: (...args: Arguments) => ReturnValue) {
+	const callbackRef = useRef(callback);
+
+	useEffect(
+		function syncCallbackRef() {
+			callbackRef.current = callback;
+		},
+		[callback],
+	);
+
+	return useCallback((...args: Arguments) => {
+		return callbackRef.current(...args);
+	}, []);
+}

package/packages/hooks/usePreservedReference.ts

@@ -0,0 +1,21 @@
+"use client";
+
+import { useMemo, useRef } from "react";
+
+function areDeeplyEqual<T>(a: T, b: T): boolean {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function usePreservedReference<T>(
+	value: T,
+	areValuesEqual: (a: T, b: T) => boolean = areDeeplyEqual,
+): T {
+	const ref = useRef(value);
+
+	return useMemo(() => {
+		if (!areValuesEqual(ref.current, value)) {
+			ref.current = value;
+		}
+		return ref.current;
+	}, [areValuesEqual, value]);
+}

package/packages/hooks/useRefEffect.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { type DependencyList, useCallback, useRef } from "react";
+
+import { usePreservedCallback } from "./usePreservedCallback";
+
+export type CleanupCallback = () => void;
+
+export function useRefEffect<RefElement extends HTMLElement = HTMLElement>(
+	callback: (element: RefElement) => CleanupCallback | undefined,
+	deps: DependencyList,
+): (element: RefElement | null) => void {
+	const preservedCallback = usePreservedCallback(callback);
+	const cleanupCallbackRef = useRef<CleanupCallback>(() => {});
+
+	const effect = useCallback(
+		(element: RefElement | null) => {
+			cleanupCallbackRef.current();
+			cleanupCallbackRef.current = () => {};
+
+			if (element == null) {
+				return;
+			}
+
+			const cleanup = preservedCallback(element);
+
+			if (typeof cleanup === "function") {
+				cleanupCallbackRef.current = cleanup;
+			}
+		},
+		[preservedCallback, ...deps],
+	);
+
+	return effect;
+}