@musecat/functionkit 1.0.0 → 1.0.2

package/packages/datetime/dateTime.shared.ts

@@ -0,0 +1,358 @@
+export type AppLocale = "kr" | "en" | "jp";
+export type DateInput = string | number | Date;
+export type DatePreset = "long" | "dot";
+export type TimePreset = "ko" | "12h" | "24h-minute" | "24h-second";
+const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+type DateParts = {
+	year: string;
+	month: string;
+	day: string;
+};
+
+type TimeParts = {
+	hour: string;
+	minute: string;
+	second: string;
+};
+
+export function normalizeAppLocale(locale?: string): AppLocale {
+	const normalized =
+		typeof locale === "string" ? locale.trim().toLowerCase() : "";
+	if (normalized === "kr" || normalized === "ko") return "kr";
+	if (normalized === "jp" || normalized === "ja") return "jp";
+	return "en";
+}
+
+export function toIntlLocale(locale?: string): string {
+	switch (normalizeAppLocale(locale)) {
+		case "kr":
+			return "ko-KR";
+		case "jp":
+			return "ja-JP";
+		default:
+			return "en-US";
+	}
+}
+
+export function toDate(value: DateInput): Date | null {
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : new Date(value.getTime());
+	}
+
+	const date = new Date(value);
+	return Number.isNaN(date.getTime()) ? null : date;
+}
+
+export function toUtcMidnight(date: Date): Date {
+	return new Date(
+		Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+	);
+}
+
+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);
+
+		if (match) {
+			const [, year, month, day] = match;
+			return new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+		}
+	}
+
+	const parsed = value !== undefined && value !== null ? toDate(value) : null;
+	if (parsed) {
+		return toUtcMidnight(parsed);
+	}
+
+	if (fallback !== undefined) {
+		const fallbackDate = toDate(fallback);
+		if (fallbackDate) {
+			return toUtcMidnight(fallbackDate);
+		}
+	}
+
+	return null;
+}
+
+export function formatUtcDateKey(date: Date): string {
+	return [
+		date.getUTCFullYear(),
+		String(date.getUTCMonth() + 1).padStart(2, "0"),
+		String(date.getUTCDate()).padStart(2, "0"),
+	].join("-");
+}
+
+export function getUtcWeekdayIndex(date: Date): number {
+	return date.getUTCDay();
+}
+
+export function addUtcDays(date: Date, days: number): Date {
+	const next = new Date(date.getTime());
+	next.setUTCDate(next.getUTCDate() + days);
+	return next;
+}
+
+function getDateParts(date: Date, timeZone?: string): DateParts {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(date);
+
+	return {
+		year: parts.find((part) => part.type === "year")?.value ?? "0000",
+		month: parts.find((part) => part.type === "month")?.value ?? "00",
+		day: parts.find((part) => part.type === "day")?.value ?? "00",
+	};
+}
+
+function getTimeParts(date: Date, timeZone?: string): TimeParts {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23",
+	}).formatToParts(date);
+
+	return {
+		hour: parts.find((part) => part.type === "hour")?.value ?? "00",
+		minute: parts.find((part) => part.type === "minute")?.value ?? "00",
+		second: parts.find((part) => part.type === "second")?.value ?? "00",
+	};
+}
+
+export function formatLongDate(
+	date: Date,
+	locale?: string,
+	timeZone?: string,
+): string {
+	const localeKey = normalizeAppLocale(locale);
+	const { year, month, day } = getDateParts(date, timeZone);
+
+	if (localeKey === "kr") {
+		return `${year}년 ${Number(month)}월 ${Number(day)}일`;
+	}
+
+	if (localeKey === "jp") {
+		return `${year}年${Number(month)}月${Number(day)}日`;
+	}
+
+	return new Intl.DateTimeFormat(toIntlLocale(localeKey), {
+		timeZone,
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+	}).format(date);
+}
+
+export function formatDotDate(date: Date, timeZone?: string): string {
+	const { year, month, day } = getDateParts(date, timeZone);
+	return `${year}. ${Number(month)}. ${Number(day)}.`;
+}
+
+export function format24HourTime(
+	date: Date,
+	options?: {
+		includeSeconds?: boolean;
+		timeZone?: string;
+	},
+): string {
+	const { includeSeconds = false, timeZone } = options ?? {};
+	const { hour, minute, second } = getTimeParts(date, timeZone);
+	return includeSeconds ? `${hour}:${minute}:${second}` : `${hour}:${minute}`;
+}
+
+export function formatKoreanTime(date: Date, timeZone?: string): string {
+	const { hour, minute } = getTimeParts(date, timeZone);
+	const hourNumber = Number(hour);
+	const meridiem = hourNumber < 12 ? "오전" : "오후";
+	const hour12 = hourNumber % 12 === 0 ? 12 : hourNumber % 12;
+	return `${meridiem} ${hour12}시 ${minute}분`;
+}
+
+export function formatTwelveHourTime(
+	date: Date,
+	locale?: string,
+	timeZone?: string,
+): string {
+	const localeKey = normalizeAppLocale(locale);
+	if (localeKey === "kr") {
+		const { hour, minute } = getTimeParts(date, timeZone);
+		const hourNumber = Number(hour);
+		const meridiem = hourNumber < 12 ? "오전" : "오후";
+		const hour12 = hourNumber % 12 === 0 ? 12 : hourNumber % 12;
+		return `${meridiem} ${hour12}:${minute}`;
+	}
+
+	return new Intl.DateTimeFormat(toIntlLocale(localeKey), {
+		timeZone,
+		hour: "numeric",
+		minute: "2-digit",
+		hour12: true,
+	}).format(date);
+}
+
+export function formatRelativeText(
+	diffMs: number,
+	locale?: string,
+): { text: string; isRelative: boolean } {
+	const localeKey = normalizeAppLocale(locale);
+	const safeDiffMs = Math.max(0, diffMs);
+	const seconds = Math.max(1, Math.floor(safeDiffMs / 1000));
+	const minutes = Math.max(1, Math.floor(safeDiffMs / (60 * 1000)));
+	const hours = Math.max(1, Math.floor(safeDiffMs / (60 * 60 * 1000)));
+	const days = Math.max(1, Math.floor(safeDiffMs / (24 * 60 * 60 * 1000)));
+
+	if (safeDiffMs < 60 * 1000) {
+		return {
+			text: formatRelativeUnit(seconds, "second", localeKey),
+			isRelative: true,
+		};
+	}
+
+	if (safeDiffMs < 60 * 60 * 1000) {
+		return {
+			text: formatRelativeUnit(minutes, "minute", localeKey),
+			isRelative: true,
+		};
+	}
+
+	if (safeDiffMs < 24 * 60 * 60 * 1000) {
+		return {
+			text: formatRelativeUnit(hours, "hour", localeKey),
+			isRelative: true,
+		};
+	}
+
+	return { text: formatRelativeUnit(days, "day", localeKey), isRelative: true };
+}
+
+export function formatRemainingText(
+	diffMs: number,
+	locale?: string,
+	options?: {
+		includeSuffix?: boolean;
+	},
+): string {
+	const localeKey = normalizeAppLocale(locale);
+	const includeSuffix = options?.includeSuffix ?? true;
+	const safeDiffMs = Math.max(0, diffMs);
+
+	if (safeDiffMs === 0) {
+		if (localeKey === "kr") return "마감됨";
+		if (localeKey === "jp") return "締切終了";
+		return "Closed";
+	}
+
+	const units = [
+		{ label: "day", value: 24 * 60 * 60 * 1000 },
+		{ label: "hour", value: 60 * 60 * 1000 },
+		{ label: "minute", value: 60 * 1000 },
+		{ label: "second", value: 1000 },
+	] as const;
+
+	const parts: string[] = [];
+	let remaining = safeDiffMs;
+
+	for (const unit of units) {
+		const count = Math.floor(remaining / unit.value);
+		remaining -= count * unit.value;
+
+		if (count > 0) {
+			parts.push(formatRemainingUnit(count, unit.label, localeKey));
+		}
+
+		if (parts.length >= 2) break;
+	}
+
+	if (parts.length === 0) {
+		parts.push(formatRemainingUnit(1, "second", localeKey));
+	}
+
+	if (!includeSuffix) {
+		return parts.join(localeKey === "jp" ? "" : " ");
+	}
+
+	if (localeKey === "kr") {
+		return `${parts.join(" ")} 남음`;
+	}
+
+	if (localeKey === "jp") {
+		return `あと${parts.join("")}`;
+	}
+
+	return `${parts.join(" ")} left`;
+}
+
+function formatRelativeUnit(
+	count: number,
+	unit: "second" | "minute" | "hour" | "day",
+	locale: AppLocale,
+): string {
+	if (locale === "kr") {
+		const suffix =
+			unit === "second"
+				? "초"
+				: unit === "minute"
+					? "분"
+					: unit === "hour"
+						? "시간"
+						: "일";
+		return `${count}${suffix} 전`;
+	}
+
+	if (locale === "jp") {
+		const suffix =
+			unit === "second"
+				? "秒"
+				: unit === "minute"
+					? "分"
+					: unit === "hour"
+						? "時間"
+						: "日";
+		return `${count}${suffix}前`;
+	}
+
+	const englishUnit = count === 1 ? unit : `${unit}s`;
+	return `${count} ${englishUnit} ago`;
+}
+
+function formatRemainingUnit(
+	count: number,
+	unit: "second" | "minute" | "hour" | "day",
+	locale: AppLocale,
+): string {
+	if (locale === "kr") {
+		const suffix =
+			unit === "second"
+				? "초"
+				: unit === "minute"
+					? "분"
+					: unit === "hour"
+						? "시간"
+						: "일";
+		return `${count}${suffix}`;
+	}
+
+	if (locale === "jp") {
+		const suffix =
+			unit === "second"
+				? "秒"
+				: unit === "minute"
+					? "分"
+					: unit === "hour"
+						? "時間"
+						: "日";
+		return `${count}${suffix}`;
+	}
+
+	const englishUnit = count === 1 ? unit : `${unit}s`;
+	return `${count} ${englishUnit}`;
+}

package/packages/hooks/useAvoidKeyboard.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { useKeyboardHeight } from "./useKeyboardHeight";
+
+type UseAvoidKeyboardOptions = {
+	safeAreaBottom?: number;
+	transitionDuration?: number;
+	transitionTimingFunction?: string;
+};
+
+export function useAvoidKeyboard(options?: UseAvoidKeyboardOptions) {
+	const {
+		safeAreaBottom = 0,
+		transitionDuration = 200,
+		transitionTimingFunction = "ease-out",
+	} = options ?? {};
+
+	const { keyboardHeight } = useKeyboardHeight();
+
+	const offset = keyboardHeight > 0 ? keyboardHeight : safeAreaBottom;
+
+	const style: React.CSSProperties = {
+		transform: offset > 0 ? `translateY(-${offset}px)` : undefined,
+		transition: `transform ${transitionDuration}ms ${transitionTimingFunction}`,
+	};
+
+	return { style };
+}

package/packages/hooks/useCheckInvisible.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export function useCheckInvisible(className: string) {
+	const [isInvisible, setIsInvisible] = useState(false);
+
+	useEffect(() => {
+		const handleScroll = () => {
+			const el = document.querySelector(`.${className}`);
+			if (el) {
+				const { top } = el.getBoundingClientRect();
+				setIsInvisible(top < 0);
+			} else {
+				setIsInvisible(false);
+			}
+		};
+
+		handleScroll();
+		window.addEventListener("scroll", handleScroll);
+		return () => window.removeEventListener("scroll", handleScroll);
+	}, [className]);
+
+	return { isInvisible };
+}

package/packages/hooks/useCheckScroll.ts

@@ -0,0 +1,19 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export function useCheckScroll() {
+	const [isScrolled, setIsScrolled] = useState(false);
+
+	useEffect(() => {
+		const handleScroll = () => {
+			setIsScrolled(window.scrollY > 0);
+		};
+
+		handleScroll();
+		window.addEventListener("scroll", handleScroll);
+		return () => window.removeEventListener("scroll", handleScroll);
+	}, []);
+
+	return { isScrolled };
+}

package/packages/hooks/useClientDateTime.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { formatClientDateTime } from "../datetime/dateTime.client";
+import type {
+	DateInput,
+	DatePreset,
+	TimePreset,
+} from "../datetime/dateTime.shared";
+import { toDate } from "../datetime/dateTime.shared";
+
+type UseClientDateTimeOptions = {
+	locale?: string;
+	timeZone?: string;
+	datePreset?: DatePreset;
+	timePreset?: TimePreset;
+};
+
+export function useClientDateTime(
+	value: DateInput,
+	options?: UseClientDateTimeOptions,
+) {
+	const [ready, setReady] = useState(false);
+	const [text, setText] = useState("");
+
+	useEffect(() => {
+		setText(
+			formatClientDateTime(value, {
+				locale: options?.locale,
+				timeZone: options?.timeZone,
+				datePreset: options?.datePreset,
+				timePreset: options?.timePreset,
+			}),
+		);
+		setReady(true);
+	}, [
+		options?.datePreset,
+		options?.locale,
+		options?.timePreset,
+		options?.timeZone,
+		value,
+	]);
+
+	return {
+		ready,
+		text,
+		date: toDate(value),
+	};
+}

package/packages/hooks/useDebounce.ts

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useMemo } 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/packages/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],
+	);
+}