@musecat/functionkit 1.0.2 → 1.2.0

package/index.ts

@@ -6,9 +6,9 @@ export {
 	clearAllClientCookies,
 	clearClientCookie,
 	getClientCookie,
-	parseClientCookieNames,
 	setClientCookie,
 } from "./packages/cookie/cookie.shared";
+export { parseClientCookieNames } from "./packages/cookie/cookieNames.shared";
 export {
 	formatClientDate,
 	formatClientDateTime,

package/package.json

@@ -1,6 +1,35 @@
 {
 	"name": "@musecat/functionkit",
-	"version": "1.0.2",
+	"version": "1.2.0",
+	"description": "React 19 + TypeScript frontend utility library — hooks, components, datetime, cookie, and utils",
+	"keywords": [
+		"react",
+		"hooks",
+		"typescript",
+		"utility",
+		"frontend"
+	],
+	"license": "MIT",
+	"private": false,
+	"author": "Musecat Team",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"files": [
+		"index.ts",
+		"packages/",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/TheTechclip/FunctionKit.git"
+	},
+	"bugs": {
+		"url": "https://github.com/TheTechclip/FunctionKit/issues"
+	},
+	"homepage": "https://musecat.app",
 	"type": "module",
 	"main": "./index.ts",
 	"types": "./index.ts",
@@ -11,7 +40,12 @@
 	"scripts": {
 		"lint": "biome check",
 		"format": "prettier --write . && biome format --write",
-		"test": "vitest run"
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
 	},
 	"peerDependencies": {
 		"react": "^19.0.0",
@@ -22,6 +56,7 @@
 		"@testing-library/jest-dom": "^6.6.3",
 		"@testing-library/react": "^16.2.0",
 		"@testing-library/user-event": "^14.6.1",
+		"@vitest/coverage-v8": "^4.1.10",
 		"jsdom": "^26.0.0",
 		"prettier": "^3.9.5",
 		"vitest": "^4.1.10"

package/packages/components/ScrolltoTop.tsx

@@ -5,5 +5,5 @@ import { useEffect } from "react";
 export function ScrolltoTop() {
 	useEffect(() => {
 		window.scrollTo(0, 0);
-	});
+	}, []);
 }

package/packages/components/ViewportPortal.tsx

@@ -18,8 +18,7 @@ export function getViewportPortalRoot() {
 	const root = document.createElement("div");
 	root.id = VIEWPORT_PORTAL_ROOT_ID;
 	root.setAttribute("data-viewport-portal-root", "true");
-	root.style.cssText =
-		"position:fixed;inset:0;pointer-events:none;z-index:9999;";
+	root.style.cssText = "position:fixed;inset:0;pointer-events:none;z-index:9999;";
 	document.body.appendChild(root);
 	return root;
 }

package/packages/cookie/cookie.shared.ts

@@ -22,10 +22,7 @@ type ClearAllClientCookiesOptions = ClearClientCookieOptions & {
 	cookieString?: string;
 };
 
-function findClientCookie(
-	name: string,
-	documentRef: DocumentCookieRef,
-): string | undefined {
+function findClientCookie(name: string, documentRef: DocumentCookieRef): string | undefined {
 	const parsed = parseClientCookie(documentRef.cookie);
 	return parsed[name];
 }
@@ -42,15 +39,9 @@ function parseClientCookie(cookieString: string): Record<string, string> {
 		}, {});
 }
 
-export function parseClientCookieNames(cookieString: string): string[] {
-	return cookieString
-		.split(";")
-		.map((entry) => {
-			const eqPos = entry.indexOf("=");
-			return eqPos > -1 ? entry.slice(0, eqPos).trim() : entry.trim();
-		})
-		.filter(Boolean);
-}
+import { parseClientCookieNames } from "./cookieNames.shared";
+
+export { parseClientCookieNames };
 
 export function getClientCookie(name: string): string | undefined {
 	if (typeof document === "undefined") {
@@ -60,11 +51,18 @@ export function getClientCookie(name: string): string | undefined {
 	return findClientCookie(name, document);
 }
 
-export function setClientCookie(name: string, value: string, days?: number) {
+export function setClientCookie(
+	name: string,
+	value: string,
+	days?: number,
+	documentRef?: DocumentCookieRef,
+) {
 	if (typeof document === "undefined") {
 		return;
 	}
 
+	const ref = documentRef ?? document;
+
 	let expires = "";
 	if (days) {
 		const date = new Date();
@@ -72,31 +70,17 @@ export function setClientCookie(name: string, value: string, days?: number) {
 		expires = `; expires=${date.toUTCString()}`;
 	}
 
-	document.cookie = `${name}=${encodeURIComponent(value)}${expires}; path=/`;
+	ref.cookie = `${name}=${encodeURIComponent(value)}${expires}; path=/`;
 }
 
-export function clearClientCookie(
-	name: string,
-	options: ClearClientCookieOptions = {},
-): void {
-	const {
-		hostname = window.location.hostname,
-		path = "/",
-		documentRef = document,
-	} = options;
+export function clearClientCookie(name: string, options: ClearClientCookieOptions = {}): void {
+	const { hostname = window.location.hostname, path = "/", documentRef = document } = options;
 
 	documentRef.cookie = `${name}=; expires=${EXPIRED_COOKIE_DATE}; path=${path}; domain=${hostname};`;
 }
 
-export function clearAllClientCookies(
-	options: ClearAllClientCookiesOptions = {},
-): string[] {
-	const {
-		documentRef = document,
-		cookieStore,
-		includeRoot = false,
-		cookieString,
-	} = options;
+export function clearAllClientCookies(options: ClearAllClientCookiesOptions = {}): string[] {
+	const { documentRef = document, cookieStore, includeRoot = false, cookieString } = options;
 
 	const entries = cookieString
 		? parseClientCookieNames(cookieString)
@@ -124,8 +108,6 @@ export function clearAllClientCookies(
 	}
 
 	for (const name of entries) {
-		if (!name) continue;
-
 		for (const path of paths) {
 			for (let i = 0; i < hostnameParts.length; i++) {
 				const domain = hostnameParts.slice(i).join(".");

package/packages/cookie/cookieNames.shared.ts

@@ -0,0 +1,9 @@
+export function parseClientCookieNames(cookieString: string): string[] {
+	return cookieString
+		.split(";")
+		.map((entry) => {
+			const eqPos = entry.indexOf("=");
+			return eqPos > -1 ? entry.slice(0, eqPos).trim() : entry.trim();
+		})
+		.filter(Boolean);
+}

package/packages/datetime/dateTime.client.ts

@@ -72,9 +72,7 @@ export function formatClientDateTime(
 		timeZone: options.timeZone,
 		preset: options.timePreset ?? "24h-minute",
 	});
-	return dateText && timeText
-		? `${dateText} ${timeText}`
-		: dateText || timeText;
+	return dateText && timeText ? `${dateText} ${timeText}` : dateText || timeText;
 }
 
 export function formatClientRelative(

package/packages/datetime/dateTime.server.ts

@@ -72,9 +72,7 @@ export function formatServerDateTime(
 		timeZone: options.timeZone,
 		preset: options.timePreset ?? "24h-minute",
 	});
-	return dateText && timeText
-		? `${dateText} ${timeText}`
-		: dateText || timeText;
+	return dateText && timeText ? `${dateText} ${timeText}` : dateText || timeText;
 }
 
 export function formatServerRelative(

package/packages/datetime/dateTime.shared.ts

@@ -17,8 +17,7 @@ type TimeParts = {
 };
 
 export function normalizeAppLocale(locale?: string): AppLocale {
-	const normalized =
-		typeof locale === "string" ? locale.trim().toLowerCase() : "";
+	const normalized = typeof locale === "string" ? locale.trim().toLowerCase() : "";
 	if (normalized === "kr" || normalized === "ko") return "kr";
 	if (normalized === "jp" || normalized === "ja") return "jp";
 	return "en";
@@ -45,15 +44,10 @@ export function toDate(value: DateInput): Date | null {
 }
 
 export function toUtcMidnight(date: Date): Date {
-	return new Date(
-		Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
-	);
+	return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
 }
 
-export function parseUtcDateInput(
-	value?: DateInput | null,
-	fallback?: DateInput,
-): Date | null {
+export function parseUtcDateInput(value?: DateInput | null, fallback?: DateInput): Date | null {
 	if (typeof value === "string") {
 		const trimmed = value.trim();
 		const match = DATE_ONLY_PATTERN.exec(trimmed);
@@ -128,11 +122,7 @@ function getTimeParts(date: Date, timeZone?: string): TimeParts {
 	};
 }
 
-export function formatLongDate(
-	date: Date,
-	locale?: string,
-	timeZone?: string,
-): string {
+export function formatLongDate(date: Date, locale?: string, timeZone?: string): string {
 	const localeKey = normalizeAppLocale(locale);
 	const { year, month, day } = getDateParts(date, timeZone);
 
@@ -177,11 +167,7 @@ export function formatKoreanTime(date: Date, timeZone?: string): string {
 	return `${meridiem} ${hour12}시 ${minute}분`;
 }
 
-export function formatTwelveHourTime(
-	date: Date,
-	locale?: string,
-	timeZone?: string,
-): string {
+export function formatTwelveHourTime(date: Date, locale?: string, timeZone?: string): string {
 	const localeKey = normalizeAppLocale(locale);
 	if (localeKey === "kr") {
 		const { hour, minute } = getTimeParts(date, timeZone);
@@ -298,25 +284,13 @@ function formatRelativeUnit(
 ): string {
 	if (locale === "kr") {
 		const suffix =
-			unit === "second"
-				? "초"
-				: unit === "minute"
-					? "분"
-					: unit === "hour"
-						? "시간"
-						: "일";
+			unit === "second" ? "초" : unit === "minute" ? "분" : unit === "hour" ? "시간" : "일";
 		return `${count}${suffix} 전`;
 	}
 
 	if (locale === "jp") {
 		const suffix =
-			unit === "second"
-				? "秒"
-				: unit === "minute"
-					? "分"
-					: unit === "hour"
-						? "時間"
-						: "日";
+			unit === "second" ? "秒" : unit === "minute" ? "分" : unit === "hour" ? "時間" : "日";
 		return `${count}${suffix}前`;
 	}
 
@@ -331,25 +305,13 @@ function formatRemainingUnit(
 ): string {
 	if (locale === "kr") {
 		const suffix =
-			unit === "second"
-				? "초"
-				: unit === "minute"
-					? "분"
-					: unit === "hour"
-						? "시간"
-						: "일";
+			unit === "second" ? "초" : unit === "minute" ? "분" : unit === "hour" ? "시간" : "일";
 		return `${count}${suffix}`;
 	}
 
 	if (locale === "jp") {
 		const suffix =
-			unit === "second"
-				? "秒"
-				: unit === "minute"
-					? "分"
-					: unit === "hour"
-						? "時間"
-						: "日";
+			unit === "second" ? "秒" : unit === "minute" ? "分" : unit === "hour" ? "時間" : "日";
 		return `${count}${suffix}`;
 	}
 

package/packages/hooks/useCheckInvisible.ts

@@ -7,7 +7,7 @@ export function useCheckInvisible(className: string) {
 
 	useEffect(() => {
 		const handleScroll = () => {
-			const el = document.querySelector(`.${className}`);
+			const el = document.querySelector(`.${CSS.escape(className)}`);
 			if (el) {
 				const { top } = el.getBoundingClientRect();
 				setIsInvisible(top < 0);

package/packages/hooks/useClientDateTime.ts

@@ -2,11 +2,7 @@
 
 import { useEffect, useState } from "react";
 import { formatClientDateTime } from "../datetime/dateTime.client";
-import type {
-	DateInput,
-	DatePreset,
-	TimePreset,
-} from "../datetime/dateTime.shared";
+import type { DateInput, DatePreset, TimePreset } from "../datetime/dateTime.shared";
 import { toDate } from "../datetime/dateTime.shared";
 
 type UseClientDateTimeOptions = {
@@ -16,10 +12,7 @@ type UseClientDateTimeOptions = {
 	timePreset?: TimePreset;
 };
 
-export function useClientDateTime(
-	value: DateInput,
-	options?: UseClientDateTimeOptions,
-) {
+export function useClientDateTime(value: DateInput, options?: UseClientDateTimeOptions) {
 	const [ready, setReady] = useState(false);
 	const [text, setText] = useState("");
 
@@ -33,13 +26,7 @@ export function useClientDateTime(
 			}),
 		);
 		setReady(true);
-	}, [
-		options?.datePreset,
-		options?.locale,
-		options?.timePreset,
-		options?.timeZone,
-		value,
-	]);
+	}, [options?.datePreset, options?.locale, options?.timePreset, options?.timeZone, value]);
 
 	return {
 		ready,

package/packages/hooks/useDebounce.ts

@@ -7,9 +7,7 @@ import { usePreservedCallback } from "./usePreservedCallback";
 export function debounce<F extends (...args: unknown[]) => void>(
 	func: F,
 	debounceMs: number,
-	{
-		edges = ["leading", "trailing"],
-	}: { edges?: Array<"leading" | "trailing"> } = {},
+	{ edges = ["leading", "trailing"] }: { edges?: Array<"leading" | "trailing"> } = {},
 ): {
 	(...args: Parameters<F>): void;
 	cancel: () => void;
@@ -51,10 +49,7 @@ export function debounce<F extends (...args: unknown[]) => void>(
 		}, debounceMs);
 	};
 
-	const debounced = function (
-		this: ThisParameterType<F>,
-		...args: Parameters<F>
-	) {
+	const debounced = function (this: ThisParameterType<F>, ...args: Parameters<F>) {
 		pendingThis = this;
 		pendingArgs = args;
 

package/packages/hooks/useGeolocation.ts

@@ -88,11 +88,7 @@ export function useGeolocation(options?: UseGeolocationOptions) {
 	const getCurrentPosition = useCallback(() => {
 		if (!isSupported()) return;
 		setState((prev) => ({ ...prev, loading: true }));
-		navigator.geolocation.getCurrentPosition(
-			handleSuccess,
-			handleError,
-			geoOptions(),
-		);
+		navigator.geolocation.getCurrentPosition(handleSuccess, handleError, geoOptions());
 	}, [handleSuccess, handleError, geoOptions, isSupported]);
 
 	const startTracking = useCallback(() => {

package/packages/hooks/useInterval.ts

@@ -15,8 +15,7 @@ type IntervalOptions =
 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 enabled = typeof options === "number" ? true : (options.enabled ?? true);
 
 	const preservedCallback = usePreservedCallback(callback);
 	const immediateCalledRef = useRef(false);

package/packages/hooks/useKeyboardListNavigation.ts

@@ -10,18 +10,13 @@ type UseKeyboardListNavigationOptions = {
 	itemCount: number;
 };
 
-export function useKeyboardListNavigation({
-	itemCount,
-}: UseKeyboardListNavigationOptions) {
+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 setItemRef = useCallback((index: number, element: HTMLElement | null) => {
+		itemRefs.current[index] = element;
+	}, []);
 
 	const focusItem = useCallback((index: number) => {
 		const target = itemRefs.current[index];
@@ -59,18 +54,6 @@ export function useKeyboardListNavigation({
 
 	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);
@@ -78,15 +61,13 @@ export function useKeyboardListNavigation({
 
 			if (key === "ArrowUp" || key === "ArrowLeft") {
 				const nextIndex =
-					activeIndex < 0
-						? itemCount - 1
-						: (activeIndex - 1 + itemCount) % itemCount;
+					activeIndex < 0 ? itemCount - 1 : (activeIndex - 1 + itemCount) % itemCount;
 				return focusItem(nextIndex);
 			}
 
-			return false;
+			return focusBoundaryItem(key);
 		},
-		[activeIndex, focusItem, itemCount],
+		[activeIndex, focusItem, focusBoundaryItem, itemCount],
 	);
 
 	const clickActiveItem = useCallback(() => {
@@ -99,10 +80,7 @@ export function useKeyboardListNavigation({
 	}, [activeIndex]);
 
 	const handleListKeyDown = useCallback(
-		(
-			event: React.KeyboardEvent<HTMLElement>,
-			options?: { container?: HTMLElement | null },
-		) => {
+		(event: React.KeyboardEvent<HTMLElement>, options?: { container?: HTMLElement | null }) => {
 			if (itemCount === 0 || event.defaultPrevented) {
 				return;
 			}
@@ -144,15 +122,9 @@ export function useKeyboardListNavigation({
 				return;
 			}
 
-			if (moveActiveItem(event.key)) {
-				return;
-			}
-
-			if (focusBoundaryItem(event.key)) {
-				return;
-			}
+			moveActiveItem(event.key);
 		},
-		[clickActiveItem, moveActiveItem, focusBoundaryItem, itemCount],
+		[clickActiveItem, moveActiveItem, itemCount],
 	);
 
 	useEffect(() => {

package/packages/hooks/useLongPress.ts

@@ -14,12 +14,7 @@ export type UseLongPressOptions<E extends HTMLElement> = {
 
 export function useLongPress<E extends HTMLElement = HTMLElement>(
 	onLongPress: (event: MouseEvent<E> | TouchEvent<E>) => void,
-	{
-		delay = 500,
-		moveThreshold,
-		onClick,
-		onLongPressEnd,
-	}: UseLongPressOptions<E> = {},
+	{ delay = 500, moveThreshold, onClick, onLongPressEnd }: UseLongPressOptions<E> = {},
 ) {
 	const timeoutRef = useRef<number | null>(null);
 	const isLongPressActiveRef = useRef(false);
@@ -32,22 +27,18 @@ export function useLongPress<E extends HTMLElement = HTMLElement>(
 	savedOnClick.current = onClick;
 	savedOnLongPressEnd.current = onLongPressEnd;
 
-	const hasThreshold =
-		moveThreshold?.x !== undefined || moveThreshold?.y !== undefined;
+	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 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>) => {
@@ -113,8 +104,6 @@ export function useLongPress<E extends HTMLElement = HTMLElement>(
 		onMouseLeave: cancelLongPress,
 		onTouchStart: handlePressStart,
 		onTouchEnd: handlePressEnd,
-		...(hasThreshold
-			? { onTouchMove: handlePressMove, onMouseMove: handlePressMove }
-			: {}),
+		...(hasThreshold ? { onTouchMove: handlePressMove, onMouseMove: handlePressMove } : {}),
 	};
 }

package/packages/hooks/useRelativeDateTime.ts

@@ -12,10 +12,7 @@ type UseRelativeDateTimeOptions = {
 	updateIntervalMs?: number;
 };
 
-export function useRelativeDateTime(
-	value: DateInput,
-	options?: UseRelativeDateTimeOptions,
-) {
+export function useRelativeDateTime(value: DateInput, options?: UseRelativeDateTimeOptions) {
 	const [ready, setReady] = useState(false);
 	const [text, setText] = useState("");
 	const [isRelative, setIsRelative] = useState(false);

package/packages/hooks/useViewportHeight.ts

@@ -6,8 +6,7 @@ export function useViewportHeight() {
 	const [height, setHeight] = useState(0);
 
 	useEffect(() => {
-		const update = () =>
-			setHeight(window.visualViewport?.height ?? window.innerHeight);
+		const update = () => setHeight(window.visualViewport?.height ?? window.innerHeight);
 
 		update();
 		window.visualViewport?.addEventListener("resize", update);

package/packages/hooks/useViewportMatch.ts

@@ -6,10 +6,6 @@ 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);

package/packages/utils/buildContext.tsx

@@ -1,13 +1,12 @@
 "use client";
 
-import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { createContext, type ReactNode, useContext } 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>;
+		return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
 	}
 
 	function useValue() {