@musecat/functionkit 1.0.0 → 1.0.2

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

@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+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/packages/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/packages/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/packages/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,
+	};
+}

package/packages/utils/clipboardShare.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import type {
+	NavigatorClipboardProps,
+	NavigatorClipboardResult,
+	NavigatorShareProps,
+	NavigatorShareResult,
+} from "./clipboardShare.types";
+
+export function NavigatorClipboard({
+	text,
+}: NavigatorClipboardProps): Promise<NavigatorClipboardResult> {
+	return navigator.clipboard.writeText(text).then(
+		() => ({ success: true }),
+		() => ({ success: false }),
+	);
+}
+
+export function NavigatorShare({
+	title,
+	text,
+	link,
+}: NavigatorShareProps): Promise<NavigatorShareResult> {
+	if (navigator.share) {
+		return navigator.share({ title, text, url: link }).then(
+			() => ({ success: true, method: "share" }),
+			(error) => {
+				if (error instanceof DOMException && error.name === "AbortError") {
+					return { success: false, method: "share" };
+				}
+				return clipboardFallback(link);
+			},
+		);
+	}
+
+	return clipboardFallback(link);
+}
+
+function clipboardFallback(link: string): Promise<NavigatorShareResult> {
+	if (navigator.clipboard) {
+		return navigator.clipboard.writeText(link).then(
+			() => ({ success: true, method: "clipboard" }),
+			() => ({ success: false, method: "unsupported" }),
+		);
+	}
+	return Promise.resolve({ success: false, method: "unsupported" });
+}

package/{utils → packages/utils}/clipboardShare.types.ts

@@ -1,18 +1,18 @@
 export type NavigatorClipboardProps = {
-  text: string;
+	text: string;
 };
 
 export type NavigatorShareProps = {
-  title: string;
-  text: string;
-  link: string;
+	title: string;
+	text: string;
+	link: string;
 };
 
 export type NavigatorClipboardResult = {
-  success: boolean;
+	success: boolean;
 };
 
 export type NavigatorShareResult = {
-  success: boolean;
-  method: "share" | "clipboard" | "unsupported";
+	success: boolean;
+	method: "share" | "clipboard" | "unsupported";
 };

package/packages/utils/floatingMotion.ts

@@ -0,0 +1,99 @@
+export type FloatingMotionMode =
+	| "anchored"
+	| "center-selected"
+	| "modal-center"
+	| "mobile-sheet";
+
+export type FloatingPlacement =
+	| "top-left"
+	| "top-center"
+	| "top-right"
+	| "middle-left"
+	| "middle-center"
+	| "middle-right"
+	| "bottom-left"
+	| "bottom-center"
+	| "bottom-right";
+
+export interface FloatingMotionPreset {
+	enterMs: number;
+	exitMs: number;
+	ease: string;
+}
+
+export const getFloatingMotionPreset = (
+	mode: FloatingMotionMode,
+): FloatingMotionPreset => {
+	if (mode === "mobile-sheet") {
+		return {
+			enterMs: 360,
+			exitMs: 280,
+			ease: "cubic-bezier(0.2, 0.8, 0.2, 1)",
+		};
+	}
+
+	if (mode === "modal-center") {
+		return {
+			enterMs: 340,
+			exitMs: 260,
+			ease: "cubic-bezier(0.22, 1, 0.36, 1)",
+		};
+	}
+
+	if (mode === "center-selected") {
+		return {
+			enterMs: 190,
+			exitMs: 140,
+			ease: "cubic-bezier(0.2, 0, 0, 1)",
+		};
+	}
+
+	return {
+		enterMs: 230,
+		exitMs: 170,
+		ease: "cubic-bezier(0.16, 1, 0.3, 1)",
+	};
+};
+
+export const getFloatingTransformOrigin = (
+	placement?: FloatingPlacement,
+): string => {
+	if (!placement) return "top center";
+
+	const [row, col] = placement.split("-") as [
+		"top" | "middle" | "bottom",
+		"left" | "center" | "right",
+	];
+	const y = row === "top" ? "bottom" : row === "bottom" ? "top" : "center";
+	const x = col === "right" ? "right" : col === "left" ? "left" : "center";
+
+	return `${y} ${x}`;
+};
+
+export const getFloatingHiddenTransform = ({
+	mode,
+	placement,
+}: {
+	mode: FloatingMotionMode;
+	placement?: FloatingPlacement;
+}): string => {
+	if (mode === "mobile-sheet") return "translateY(1.8rem) scale(1)";
+	if (mode === "modal-center") return "translateY(.8rem) scale(.94)";
+	if (mode === "center-selected") return "translateY(.45rem) scale(.99)";
+	if (!placement) return "translateY(.4rem) scale(.975)";
+
+	const [row, col] = placement.split("-") as [
+		"top" | "middle" | "bottom",
+		"left" | "center" | "right",
+	];
+
+	if (row === "top") return "translateY(.4rem) scale(.975)";
+	if (row === "bottom") return "translateY(-.4rem) scale(.975)";
+
+	if (row === "middle") {
+		if (col === "left") return "translateX(.4rem) scale(.975)";
+		if (col === "right") return "translateX(-.4rem) scale(.975)";
+	}
+
+	return "translateY(.4rem) scale(.975)";
+};

package/packages/utils/keyboardTarget.ts

@@ -0,0 +1,13 @@
+"use client";
+
+export function isEditableKeyboardTarget(target: HTMLElement) {
+	return (
+		target.isContentEditable ||
+		target.tagName === "TEXTAREA" ||
+		target.tagName === "SELECT" ||
+		(target.tagName === "INPUT" &&
+			(target as HTMLInputElement).type !== "button" &&
+			(target as HTMLInputElement).type !== "checkbox" &&
+			(target as HTMLInputElement).type !== "radio")
+	);
+}

package/packages/utils/mergeRefs.ts

@@ -0,0 +1,15 @@
+import type { Ref, RefCallback } from "react";
+
+type ReactRef<T> = Ref<T> | undefined | null;
+
+export function mergeRefs<T>(...refs: ReactRef<T>[]): RefCallback<T> {
+	return (value: T | null) => {
+		for (const ref of refs) {
+			if (typeof ref === "function") {
+				ref(value);
+			} else if (ref && "current" in ref) {
+				(ref as { current: T | null }).current = value;
+			}
+		}
+	};
+}

package/packages/utils/seen.ts

@@ -0,0 +1,29 @@
+export const SEEN_STORAGE_KEY = "seen";
+
+type SeenMap = Partial<Record<string, boolean>>;
+
+export function parseSeen(raw: string | null): SeenMap {
+	if (!raw) return {};
+
+	try {
+		const parsed = JSON.parse(raw) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return {};
+		}
+
+		return parsed as SeenMap;
+	} catch {
+		return {};
+	}
+}
+
+export function hasSeenKey(raw: string | null, key: string) {
+	const map = parseSeen(raw);
+	return map[key] === true;
+}
+
+export function buildSeenValue(raw: string | null, key: string): string {
+	const map = parseSeen(raw);
+	map[key] = true;
+	return JSON.stringify(map);
+}

package/packages/utils/subscribeKeyboardHeight.ts

@@ -0,0 +1,54 @@
+"use client";
+
+type SubscribeKeyboardHeightOptions = {
+	callback: (height: number) => void;
+	immediate?: boolean;
+	throttleMs?: number;
+};
+
+export function subscribeKeyboardHeight({
+	callback,
+	immediate = false,
+	throttleMs = 16,
+}: SubscribeKeyboardHeightOptions) {
+	let ticking = false;
+	let lastHeight = 0;
+
+	const notify = (height: number) => {
+		if (ticking) return;
+		ticking = true;
+
+		const run = () => {
+			if (height !== lastHeight) {
+				lastHeight = height;
+				callback(height);
+			}
+			ticking = false;
+		};
+
+		if (throttleMs > 0) {
+			setTimeout(run, throttleMs);
+		} else {
+			run();
+		}
+	};
+
+	const handleResize = () => {
+		const vv = window.visualViewport;
+		if (!vv) return;
+		const diff = window.innerHeight - vv.height;
+		notify(diff > 0 ? diff : 0);
+	};
+
+	if (immediate) handleResize();
+
+	window.visualViewport?.addEventListener("resize", handleResize);
+	window.visualViewport?.addEventListener("scroll", handleResize);
+
+	return {
+		unsubscribe() {
+			window.visualViewport?.removeEventListener("resize", handleResize);
+			window.visualViewport?.removeEventListener("scroll", handleResize);
+		},
+	};
+}

package/tests/components/ScrolltoTop.test.tsx

@@ -0,0 +1,15 @@
+import { describe, test, expect, vi } from "vitest";
+import { render } from "@testing-library/react";
+import { ScrolltoTop } from "@/packages/components/ScrolltoTop";
+
+describe("ScrolltoTop", () => {
+	test("calls window.scrollTo(0, 0) on mount", () => {
+		const originalScrollTo = window.scrollTo;
+		window.scrollTo = vi.fn();
+
+		render(<ScrolltoTop />);
+		expect(window.scrollTo).toHaveBeenCalledWith(0, 0);
+
+		window.scrollTo = originalScrollTo;
+	});
+});

package/tests/components/SwitchCase.test.tsx

@@ -0,0 +1,34 @@
+import { describe, test, expect } from "vitest";
+import { render } from "@testing-library/react";
+import { SwitchCase } from "@/packages/components/SwitchCase";
+import React from "react";
+
+describe("SwitchCase", () => {
+	const cases = {
+		1: <div>Case 1</div>,
+		2: <div>Case 2</div>,
+		three: <div>Case Three</div>,
+	};
+
+	test("renders correctly matching case", () => {
+		const { container } = render(<SwitchCase value={1} cases={cases} />);
+		expect(container.textContent).toBe("Case 1");
+	});
+
+	test("renders another case", () => {
+		const { container } = render(<SwitchCase value="three" cases={cases} />);
+		expect(container.textContent).toBe("Case Three");
+	});
+
+	test("renders otherwise when case does not exist", () => {
+		const { container } = render(
+			<SwitchCase value={99} cases={cases} otherwise={<div>Fallback</div>} />,
+		);
+		expect(container.textContent).toBe("Fallback");
+	});
+
+	test("renders null when case does not exist and otherwise is not provided", () => {
+		const { container } = render(<SwitchCase value={99} cases={cases} />);
+		expect(container.innerHTML).toBe("");
+	});
+});