@musecat/functionkit 1.0.0

package/hooks/useDebounce.ts

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+
+import { usePreservedCallback } from "./usePreservedCallback";
+
+export function debounce<F extends (...args: unknown[]) => void>(
+  func: F,
+  debounceMs: number,
+  {
+    edges = ["leading", "trailing"],
+  }: { edges?: Array<"leading" | "trailing"> } = {},
+): {
+  (...args: Parameters<F>): void;
+  cancel: () => void;
+} {
+  let pendingThis: ThisParameterType<F> | undefined;
+  let pendingArgs: Parameters<F> | null = null;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const leading = edges.includes("leading");
+  const trailing = edges.includes("trailing");
+
+  const invoke = () => {
+    if (pendingArgs !== null) {
+      func.apply(pendingThis, pendingArgs);
+      pendingThis = undefined;
+      pendingArgs = null;
+    }
+  };
+
+  const cancelTimer = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  const cancel = () => {
+    cancelTimer();
+    pendingThis = undefined;
+    pendingArgs = null;
+  };
+
+  const schedule = () => {
+    cancelTimer();
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      if (trailing) invoke();
+      cancel();
+    }, debounceMs);
+  };
+
+  const debounced = function (
+    this: ThisParameterType<F>,
+    ...args: Parameters<F>
+  ) {
+    pendingThis = this;
+    pendingArgs = args;
+
+    const isFirstCall = timeoutId == null;
+
+    schedule();
+
+    if (leading && isFirstCall) {
+      invoke();
+    }
+  } as {
+    (...args: Parameters<F>): void;
+    cancel: () => void;
+  };
+
+  debounced.cancel = cancel;
+  return debounced;
+}
+
+type DebounceOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+
+export function useDebounce<F extends (...args: unknown[]) => void>(
+  callback: F,
+  wait: number,
+  options: DebounceOptions = {},
+) {
+  const preservedCallback = usePreservedCallback(callback) as F;
+
+  const { leading = false, trailing = true } = options;
+
+  const edges = useMemo(() => {
+    const _edges: Array<"leading" | "trailing"> = [];
+    if (leading) {
+      _edges.push("leading");
+    }
+
+    if (trailing) {
+      _edges.push("trailing");
+    }
+
+    return _edges;
+  }, [leading, trailing]);
+
+  const debounced = useMemo(() => {
+    return debounce(preservedCallback, wait, { edges });
+  }, [preservedCallback, wait, edges]);
+
+  useEffect(
+    function cancelDebouncedOnUnmount() {
+      return () => {
+        debounced.cancel();
+      };
+    },
+    [debounced],
+  );
+
+  return debounced;
+}

package/hooks/useDebouncedCallback.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+import { debounce } from "./useDebounce";
+import { usePreservedCallback } from "./usePreservedCallback";
+
+type DebounceOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+
+export function useDebouncedCallback({
+  onChange,
+  timeThreshold,
+  leading = false,
+  trailing = true,
+}: DebounceOptions & {
+  onChange: (newValue: boolean) => void;
+  timeThreshold: number;
+}) {
+  const handleChange = usePreservedCallback(onChange);
+  const ref = useRef({ value: false, clearPreviousDebounce: () => {} });
+
+  useEffect(function clearDebouncedOnUnmount() {
+    const current = ref.current;
+    return () => {
+      current.clearPreviousDebounce();
+    };
+  }, []);
+
+  const edges = useMemo(() => {
+    const _edges: Array<"leading" | "trailing"> = [];
+    if (leading) {
+      _edges.push("leading");
+    }
+
+    if (trailing) {
+      _edges.push("trailing");
+    }
+
+    return _edges;
+  }, [leading, trailing]);
+
+  return useCallback(
+    (nextValue: boolean) => {
+      if (nextValue === ref.current.value) {
+        return;
+      }
+
+      const debounced = debounce(
+        () => {
+          handleChange(nextValue);
+
+          ref.current.value = nextValue;
+        },
+        timeThreshold,
+        { edges },
+      );
+
+      ref.current.clearPreviousDebounce();
+
+      debounced();
+
+      ref.current.clearPreviousDebounce = debounced.cancel;
+    },
+    [handleChange, timeThreshold, edges],
+  );
+}

package/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/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/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/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/hooks/useInterval.ts

@@ -0,0 +1,55 @@
+"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/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/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,
+  };
+}