@musecat/functionkit 1.0.0

package/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/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/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/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;
+}

package/hooks/useRelativeDateTime.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { formatClientRelative } from "../datetime/dateTime.client";
+import type { DateInput, DatePreset } from "../datetime/dateTime.shared";
+import { toDate } from "../datetime/dateTime.shared";
+
+type UseRelativeDateTimeOptions = {
+  locale?: string;
+  maxRelativeDays?: number;
+  fallbackDatePreset?: DatePreset;
+  updateIntervalMs?: number;
+};
+
+export function useRelativeDateTime(
+  value: DateInput,
+  options?: UseRelativeDateTimeOptions,
+) {
+  const [ready, setReady] = useState(false);
+  const [text, setText] = useState("");
+  const [isRelative, setIsRelative] = useState(false);
+
+  useEffect(() => {
+    const update = () => {
+      const next = formatClientRelative(value, {
+        locale: options?.locale,
+        maxRelativeDays: options?.maxRelativeDays,
+        fallbackDatePreset: options?.fallbackDatePreset,
+        now: Date.now(),
+      });
+      setText(next.text);
+      setIsRelative(next.isRelative);
+      setReady(true);
+    };
+
+    update();
+
+    const timer = window.setInterval(update, options?.updateIntervalMs ?? 1000);
+    return () => window.clearInterval(timer);
+  }, [
+    options?.fallbackDatePreset,
+    options?.locale,
+    options?.maxRelativeDays,
+    options?.updateIntervalMs,
+    value,
+  ]);
+
+  return {
+    ready,
+    text,
+    isRelative,
+    date: toDate(value),
+  };
+}

package/hooks/useTimeout.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+import { usePreservedCallback } from "./usePreservedCallback";
+
+type UseTimeoutOptions = {
+  enabled?: boolean;
+};
+
+export type UseTimeoutControls = {
+  start: (overrideDelay?: number) => void;
+  reset: (overrideDelay?: number) => void;
+  clear: () => void;
+  isPending: () => boolean;
+};
+
+export function useTimeout(
+  callback: () => void,
+  delay = 0,
+  options?: UseTimeoutOptions,
+): UseTimeoutControls {
+  const { enabled = true } = options ?? {};
+  const preservedCallback = usePreservedCallback(callback);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clear = useCallback(() => {
+    if (timeoutRef.current !== null) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  const start = useCallback(
+    (overrideDelay?: number) => {
+      clear();
+      timeoutRef.current = setTimeout(() => {
+        timeoutRef.current = null;
+        preservedCallback();
+      }, overrideDelay ?? delay);
+    },
+    [clear, delay, preservedCallback],
+  );
+
+  const isPending = useCallback(() => timeoutRef.current !== null, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    start();
+    return clear;
+  }, [enabled, start, clear]);
+
+  useEffect(() => clear, [clear]);
+
+  return { start, reset: start, clear, isPending };
+}

package/hooks/useToggleState.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+export function useToggleState(initialValue = false) {
+  const [value, setValue] = useState(initialValue);
+
+  const setTrue = useCallback(() => setValue(true), []);
+  const setFalse = useCallback(() => setValue(false), []);
+  const toggle = useCallback(() => setValue((v) => !v), []);
+
+  return { value, setValue, setTrue, setFalse, toggle };
+}

package/hooks/useViewportHeight.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export function useViewportHeight() {
+  const [height, setHeight] = useState(0);
+
+  useEffect(() => {
+    const update = () =>
+      setHeight(window.visualViewport?.height ?? window.innerHeight);
+
+    update();
+    window.visualViewport?.addEventListener("resize", update);
+    window.addEventListener("resize", update);
+
+    return () => {
+      window.visualViewport?.removeEventListener("resize", update);
+      window.removeEventListener("resize", update);
+    };
+  }, []);
+
+  return { height };
+}

package/hooks/useViewportMatch.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Tracks whether the current viewport matches a media query.
+ *
+ * @param mediaQuery CSS media query string.
+ * @returns True when current viewport matches the given query.
+ */
+export function useViewportMatch(mediaQuery: string): boolean {
+  const [isMatched, setIsMatched] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const mediaQueryList = window.matchMedia(mediaQuery);
+    const syncMatchState = () => {
+      setIsMatched(mediaQueryList.matches);
+    };
+
+    syncMatchState();
+    mediaQueryList.addEventListener("change", syncMatchState);
+
+    return () => {
+      mediaQueryList.removeEventListener("change", syncMatchState);
+    };
+  }, [mediaQuery]);
+
+  return isMatched;
+}

package/index.ts

@@ -0,0 +1,111 @@
+// 컴포넌트
+export {
+  getViewportPortalRoot,
+  ViewportPortal
+} from "./components/ViewportPortal";
+// 쿠키
+export {
+  clearAllClientCookies,
+  clearClientCookie,
+  getClientCookie,
+  parseClientCookieNames,
+  setClientCookie
+} from "./cookie/cookie.shared";
+// 날짜/시간
+export {
+  formatClientDate,
+  formatClientDateTime,
+  formatClientRelative,
+  formatClientTime
+} from "./datetime/dateTime.client";
+export {
+  formatServerDate,
+  formatServerDateTime,
+  formatServerRelative,
+  formatServerTime
+} from "./datetime/dateTime.server";
+export {
+  addUtcDays,
+  format24HourTime,
+  formatDotDate,
+  formatKoreanTime,
+  formatLongDate,
+  formatRelativeText,
+  formatRemainingText,
+  formatTwelveHourTime,
+  formatUtcDateKey,
+  getUtcWeekdayIndex,
+  normalizeAppLocale,
+  parseUtcDateInput,
+  toDate,
+  toIntlLocale,
+  toUtcMidnight
+} from "./datetime/dateTime.shared";
+export type {
+  AppLocale,
+  DateInput,
+  DatePreset,
+  TimePreset
+} from "./datetime/dateTime.shared";
+// hooks
+export { useAvoidKeyboard } from "./hooks/useAvoidKeyboard";
+export { useClientDateTime } from "./hooks/useClientDateTime";
+export { useDebounce } from "./hooks/useDebounce";
+export { useDebouncedCallback } from "./hooks/useDebouncedCallback";
+export { useDoubleClick } from "./hooks/useDoubleClick";
+export { useGeolocation } from "./hooks/useGeolocation";
+export { useHasMounted } from "./hooks/useHasMounted";
+export { useIntersectionObserver } from "./hooks/useIntersectionObserver";
+export { useInterval } from "./hooks/useInterval";
+export { useKeyboardHeight } from "./hooks/useKeyboardHeight";
+export { useKeyboardListNavigation } from "./hooks/useKeyboardListNavigation";
+export { useLongPress } from "./hooks/useLongPress";
+export { usePreservedCallback } from "./hooks/usePreservedCallback";
+export { usePreservedReference } from "./hooks/usePreservedReference";
+export { useRefEffect } from "./hooks/useRefEffect";
+export { useRelativeDateTime } from "./hooks/useRelativeDateTime";
+export { useTimeout } from "./hooks/useTimeout";
+export { useToggleState } from "./hooks/useToggleState";
+export { useViewportHeight } from "./hooks/useViewportHeight";
+export { useViewportMatch } from "./hooks/useViewportMatch";
+// 유틸리티
+export {
+  getLocalStorage,
+  getSessionStorage,
+  removeLocalStorage,
+  removeSessionStorage,
+  updateLocalStorage,
+  updateSessionStorage
+} from "./utils/browserStorage";
+// 유틸리티
+export { buildContext } from "./utils/buildContext";
+export { getDeviceInfo } from "./utils/checkDevice";
+export type { DeviceInfo } from "./utils/checkDevice";
+export { NavigatorClipboard, NavigatorShare } from "./utils/clipboardShare";
+export type {
+  NavigatorClipboardProps,
+  NavigatorClipboardResult,
+  NavigatorShareProps,
+  NavigatorShareResult
+} from "./utils/clipboardShare.types";
+export {
+  getFloatingHiddenTransform,
+  getFloatingMotionPreset,
+  getFloatingTransformOrigin
+} from "./utils/floatingMotion";
+export type {
+  FloatingMotionMode,
+  FloatingMotionPreset,
+  FloatingPlacement
+} from "./utils/floatingMotion";
+// 유틸리티
+export { isEditableKeyboardTarget } from "./utils/keyboardTarget";
+export { mergeRefs } from "./utils/mergeRefs";
+export {
+  buildSeenValue,
+  hasSeenKey,
+  parseSeen,
+  SEEN_STORAGE_KEY
+} from "./utils/seen";
+export { subscribeKeyboardHeight } from "./utils/subscribeKeyboardHeight";
+

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@musecat/functionkit",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./*": "./*"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/utils/browserStorage.ts

@@ -0,0 +1,59 @@
+"use client";
+
+type StorageKind = "localStorage" | "sessionStorage";
+
+function getStorage(kind: StorageKind): Storage | null {
+  if (typeof window === "undefined") return null;
+  return window[kind];
+}
+
+function saveStorage(kind: StorageKind, key: string, value: unknown) {
+  const storage = getStorage(kind);
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {}
+}
+
+function loadStorage(kind: StorageKind, key: string): unknown {
+  const storage = getStorage(kind);
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(key);
+    return raw === null ? null : (JSON.parse(raw) as unknown);
+  } catch {
+    return null;
+  }
+}
+
+function removeStorage(kind: StorageKind, key: string) {
+  const storage = getStorage(kind);
+  if (!storage) return;
+  try {
+    storage.removeItem(key);
+  } catch {}
+}
+
+export function getLocalStorage(key: string): unknown {
+  return loadStorage("localStorage", key);
+}
+
+export function updateLocalStorage(key: string, value: unknown) {
+  saveStorage("localStorage", key, value);
+}
+
+export function removeLocalStorage(key: string) {
+  removeStorage("localStorage", key);
+}
+
+export function getSessionStorage(key: string): unknown {
+  return loadStorage("sessionStorage", key);
+}
+
+export function updateSessionStorage(key: string, value: unknown) {
+  saveStorage("sessionStorage", key, value);
+}
+
+export function removeSessionStorage(key: string) {
+  removeStorage("sessionStorage", key);
+}

package/utils/buildContext.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+
+export function buildContext<T>(defaultValue: T) {
+  const Ctx = createContext<T>(defaultValue);
+
+  function Provider({ value, children }: { value: T; children: ReactNode }) {
+    const stable = useMemo(() => value, [value]);
+    return <Ctx.Provider value={stable}>{children}</Ctx.Provider>;
+  }
+
+  function useValue() {
+    const ctx = useContext(Ctx);
+    return ctx;
+  }
+
+  return [Provider, useValue] as const;
+}

package/utils/checkDevice.ts

@@ -0,0 +1,74 @@
+export type DeviceInfo = {
+  isMobile: boolean;
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isIOSSafari: boolean;
+  isMacSafari: boolean;
+  isSamsungBrowser: boolean;
+  isTouchDevice: boolean;
+  browser: string;
+};
+
+export function getDeviceInfo(): DeviceInfo {
+  let isMobile = false;
+  let isIOS = false;
+  let isAndroid = false;
+  let isSafari = false;
+  let isIOSSafari = false;
+  let isMacSafari = false;
+  let isSamsungBrowser = false;
+  let isTouchDevice = false;
+  let browser = "unknown";
+
+  if (typeof window === "undefined") {
+    return {
+      isMobile,
+      isIOS,
+      isAndroid,
+      isSafari,
+      isIOSSafari,
+      isMacSafari,
+      isSamsungBrowser,
+      isTouchDevice,
+      browser,
+    };
+  }
+
+  const ua = navigator.userAgent;
+
+  isMobile = /Mobi|Android|iPhone|iPad|iPod/i.test(ua);
+  isIOS = /iPhone|iPad|iPod/i.test(ua);
+  isAndroid = /Android/i.test(ua);
+  isSafari = /Safari/i.test(ua) && !/Chrome/i.test(ua);
+  isIOSSafari = isIOS && isSafari;
+  isMacSafari = /Macintosh/i.test(ua) && isSafari && !isIOS;
+  isSamsungBrowser = /SamsungBrowser/i.test(ua);
+  isTouchDevice = "ontouchstart" in window;
+
+  if (isSamsungBrowser) {
+    browser = "samsung";
+  } else if (isSafari) {
+    browser = "safari";
+  } else if (/Chrome/i.test(ua)) {
+    browser = "chrome";
+  } else if (/Firefox/i.test(ua)) {
+    browser = "firefox";
+  } else if (/Edge/i.test(ua)) {
+    browser = "edge";
+  } else {
+    browser = "unknown";
+  }
+
+  return {
+    isMobile,
+    isIOS,
+    isAndroid,
+    isSafari,
+    isIOSSafari,
+    isMacSafari,
+    isSamsungBrowser,
+    isTouchDevice,
+    browser,
+  };
+}