@musecat/functionkit 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@musecat/functionkit",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "React 19 + TypeScript frontend utility library — hooks, components, datetime, cookie, and utils",
 	"keywords": [
 		"react",
@@ -10,6 +10,18 @@
 		"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"
@@ -31,6 +43,10 @@
 		"test": "vitest run",
 		"test:coverage": "vitest run --coverage"
 	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
 	"peerDependencies": {
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0"

package/packages/cookie/cookie.shared.ts

@@ -40,6 +40,7 @@ function parseClientCookie(cookieString: string): Record<string, string> {
 }
 
 import { parseClientCookieNames } from "./cookieNames.shared";
+
 export { parseClientCookieNames };
 
 export function getClientCookie(name: string): string | undefined {
@@ -50,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();
@@ -62,7 +70,7 @@ 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 {

package/packages/utils/floatingMotion.ts

@@ -57,9 +57,7 @@ function parsePlacement(placement: FloatingPlacement): [FloatingRow, FloatingCol
 	return [row, col];
 }
 
-export const getFloatingTransformOrigin = (
-	placement?: FloatingPlacement,
-): string => {
+export const getFloatingTransformOrigin = (placement?: FloatingPlacement): string => {
 	if (!placement) return "top center";
 
 	const [row, col] = parsePlacement(placement);

package/.agents/references/components/ScrolltoTop.md

@@ -1,36 +0,0 @@
-# ScrolltoTop
-
-## Purpose
-
-Scrolls the window to the top (`0, 0`) when the component mounts. Typically placed at the top of a page layout to reset scroll position on navigation.
-
-## Usage Logic
-
-Calls `window.scrollTo(0, 0)` inside a `useEffect` with empty dependencies. No state, no props.
-
-## Type Signature
-
-```ts
-function ScrolltoTop(): null;
-```
-
-Renders nothing — returns `null`.
-
-## Example Code
-
-```tsx
-import { ScrolltoTop } from "@musecat/functionkit";
-
-export default function Page() {
-  return (
-    <>
-      <ScrolltoTop />
-      <PageContent />
-    </>
-  );
-}
-```
-
-## Note
-
-Not exported from the barrel. Import via component subpath. Client-only (`"use client"`).

package/.agents/references/components/SwitchCase.md

@@ -1,47 +0,0 @@
-# SwitchCase
-
-## Purpose
-
-A declarative `switch`/`case` component for JSX. Renders the matching `ReactNode` based on a value, with an optional fallback (`otherwise`). Eliminates messy ternary chains and `&&` conditions.
-
-## Usage Logic
-
-Takes a `value` and a `cases` record. Iterates over the keys of `cases` and returns the first match using `Object.hasOwn`. If no key matches, renders `otherwise` (or `null`).
-
-SSR-safe — pure function with no `"use client"`.
-
-## Type Signature
-
-```ts
-interface SwitchCaseProps<T extends string | number> {
-  value: T;
-  cases: Partial<Record<T, ReactNode>>;
-  otherwise?: ReactNode;
-}
-
-function SwitchCase<T extends string | number>(props: SwitchCaseProps<T>): ReactNode;
-```
-
-## Example Code
-
-```tsx
-import { SwitchCase } from "@musecat/functionkit";
-
-function StatusBadge({ status }: { status: "loading" | "success" | "error" }) {
-  return (
-    <SwitchCase
-      value={status}
-      cases={{
-        loading: <Spinner />,
-        success: <CheckIcon />,
-        error: <ErrorIcon />,
-      }}
-      otherwise={<Fallback />}
-    />
-  );
-}
-```
-
-## Note
-
-Not exported from the barrel. Import via component subpath.

package/.agents/references/components/ViewportPortal.md

@@ -1,34 +0,0 @@
-# ViewportPortal
-
-## Purpose
-
-Renders children into a fixed-position portal root (`#viewport-portal-root`) using `createPortal`. Designed for overlays, modals, toasts, and tooltips that need to escape parent overflow/stacking contexts.
-
-## Usage Logic
-
-On first render, ensures the portal root `<div>` exists in `document.body`. Then portals children into it. The portal root has `position: fixed`, `inset: 0`, `z-index: 9999`, and `pointer-events: none`. Children must set `pointer-events: auto` to be interactive.
-
-## Type Signature
-
-```ts
-function ViewportPortal({ children }: { children: ReactNode }): ReactPortal;
-
-// Utility to get the portal root element
-function getViewportPortalRoot(): HTMLDivElement;
-```
-
-## Example Code
-
-```tsx
-import { ViewportPortal } from "@musecat/functionkit";
-
-function ToastContainer() {
-  return (
-    <ViewportPortal>
-      <div style={{ pointerEvents: "auto" }}>
-        <Toast message="Saved!" />
-      </div>
-    </ViewportPortal>
-  );
-}
-```

package/.agents/references/cookie/cookie.md

@@ -1,47 +0,0 @@
-# Cookie API
-
-## Purpose
-
-Client-side cookie read/write/delete utilities. All functions except `parseClientCookieNames` access `document.cookie` and are client-only.
-
-## Usage Logic
-
-Each function wraps native `document.cookie` operations. `setClientCookie` handles expiry via `Max-Age`. `clearClientCookie` and `clearAllClientCookies` set `Max-Age=0` to delete. `clearAllClientCookies` iterates over all domain/path combinations to ensure thorough cleanup.
-
-## Type Signatures
-
-```ts
-function getClientCookie(name: string): string | null;
-function setClientCookie(name: string, value: string, days?: number): void;
-function clearClientCookie(name: string, domain?: string, path?: string): void;
-function clearAllClientCookies(): void;
-function parseClientCookieNames(cookieString: string): string[]; // SSR-safe
-```
-
-## Example Code
-
-```tsx
-import {
-  getClientCookie,
-  setClientCookie,
-  clearClientCookie,
-  clearAllClientCookies,
-  parseClientCookieNames,
-} from "@musecat/functionkit";
-
-function useSession() {
-  const token = getClientCookie("session_token");
-
-  const login = (token: string) => setClientCookie("session_token", token, 7);
-
-  const logout = () => clearClientCookie("session_token");
-
-  return { token, login, logout };
-}
-
-// SSR-safe usage (Server Component)
-function CookieNames({ cookieString }: { cookieString: string }) {
-  const names = parseClientCookieNames(cookieString);
-  return <div>Cookies: {names.join(", ")}</div>;
-}
-```

package/.agents/references/datetime/dateTime.client.md

@@ -1,42 +0,0 @@
-# dateTime.client
-
-## Purpose
-
-Client-side date/time formatting wrappers. Same signatures as `dateTime.server` but bundled exclusively for client usage. Use in `"use client"` components only.
-
-## Usage Logic
-
-Same API surface as `dateTime.server` — identical function signatures. Separated to keep the server bundle clean of client-only code.
-
-## Type Signatures
-
-```ts
-function formatClientDate(date: DateInput, locale: AppLocale, preset?: DatePreset): string;
-function formatClientTime(date: DateInput, locale: AppLocale, preset?: TimePreset): string;
-function formatClientDateTime(
-  date: DateInput,
-  locale: AppLocale,
-  options?: { datePreset?: DatePreset; timePreset?: TimePreset }
-): string;
-function formatClientRelative(
-  date: DateInput,
-  locale: AppLocale,
-  options?: { maxRelativeDays?: number }
-): string;
-```
-
-## Example Code
-
-```tsx
-"use client";
-import { formatClientDate, formatClientRelative } from "@musecat/functionkit";
-
-function PostMeta({ createdAt }: { createdAt: string }) {
-  return (
-    <div>
-      <time>{formatClientDate(createdAt, "kr", "long")}</time>
-      <span>{formatClientRelative(createdAt, "kr")}</span>
-    </div>
-  );
-}
-```

package/.agents/references/datetime/dateTime.server.md

@@ -1,42 +0,0 @@
-# dateTime.server
-
-## Purpose
-
-Server-side date/time formatting wrappers. Use in Server Components, RSC, and any server-side rendering context. Pure functions, SSR-safe.
-
-## Usage Logic
-
-Delegates to `dateTime.shared` utilities internally. Provides simplified `DatePreset`/`TimePreset`-based APIs that compose multiple shared functions.
-
-## Type Signatures
-
-```ts
-function formatServerDate(date: DateInput, locale: AppLocale, preset?: DatePreset): string;
-function formatServerTime(date: DateInput, locale: AppLocale, preset?: TimePreset): string;
-function formatServerDateTime(
-  date: DateInput,
-  locale: AppLocale,
-  options?: { datePreset?: DatePreset; timePreset?: TimePreset }
-): string;
-function formatServerRelative(
-  date: DateInput,
-  locale: AppLocale,
-  options?: { maxRelativeDays?: number }
-): string;
-```
-
-## Example Code
-
-```tsx
-import { formatServerDate, formatServerRelative } from "@musecat/functionkit";
-
-// Server Component
-export default function ArticlePage({ post }: { post: { createdAt: string } }) {
-  return (
-    <article>
-      <time>{formatServerDate(post.createdAt, "kr", "long")}</time>
-      <span>{formatServerRelative(post.createdAt, "kr", { maxRelativeDays: 7 })}</span>
-    </article>
-  );
-}
-```

package/.agents/references/datetime/dateTime.shared.md

@@ -1,86 +0,0 @@
-# dateTime.shared
-
-## Purpose
-
-Core date/time formatting utilities and types. All functions are pure and SSR-safe — no `"use client"`, no `window` access. Forms the foundation for both server and client date wrappers.
-
-## Types
-
-```ts
-type AppLocale = "kr" | "en" | "jp";
-type DateInput = string | number | Date;
-type DatePreset = "long" | "dot";
-type TimePreset = "ko" | "12h" | "24h-minute" | "24h-second";
-```
-
-## Locale Conversion
-
-```ts
-// "ko" → "kr", "ja" → "jp", anything else → "en"
-function normalizeAppLocale(locale: string): AppLocale;
-
-// "kr" → "ko-KR", "jp" → "ja-JP", "en" → "en-US"
-function toIntlLocale(locale: AppLocale): string;
-```
-
-## UTC Date Utilities
-
-```ts
-function toDate(input: DateInput): Date | null;                        // NaN-safe Date conversion
-function toUtcMidnight(date: Date): Date;                              // UTC midnight of the given date
-function parseUtcDateInput(input: string): Date | null;                // "YYYY-MM-DD" → UTC Date
-function formatUtcDateKey(date: Date): string;                         // UTC Date → "YYYY-MM-DD"
-function getUtcWeekdayIndex(date: Date): number;                       // 0=Sunday
-function addUtcDays(date: Date, days: number): Date;                   // Add days in UTC
-```
-
-## Formatted Output Functions
-
-```ts
-// Long date: "2026년 7월 16일" / "July 16, 2026" / "2026年7月16日"
-function formatLongDate(date: DateInput, locale: AppLocale): string;
-
-// Dot date: "2026. 7. 16."
-function formatDotDate(date: DateInput, locale: AppLocale): string;
-
-// 24-hour time: "14:30" or "14:30:00"
-function format24HourTime(date: DateInput, options?: { withSeconds?: boolean }): string;
-
-// Korean time: "오후 2시 30분"
-function formatKoreanTime(date: DateInput): string;
-
-// 12-hour with locale: "오후 2:30" / "2:30 PM" / "午後 2:30"
-function formatTwelveHourTime(date: DateInput, locale: AppLocale): string;
-```
-
-## Relative / Remaining Time
-
-```ts
-// Relative: { text: "3분 전", isRelative: true }
-function formatRelativeText(diffMs: number, locale: AppLocale): { text: string; isRelative: boolean };
-
-// Remaining: "2일 3시간 남음" / "2 days 3 hours left" / "あと2日3時間"
-function formatRemainingText(diffMs: number, locale: AppLocale): string;
-```
-
-## Example Code
-
-```tsx
-import {
-  formatLongDate,
-  formatRelativeText,
-  formatUtcDateKey,
-  normalizeAppLocale,
-  toIntlLocale,
-} from "@musecat/functionkit";
-
-function EventDate({ date, locale }: { date: Date; locale: string }) {
-  const appLocale = normalizeAppLocale(locale);
-  return <time>{formatLongDate(date, appLocale)}</time>;
-}
-
-function RelativeTime({ diffMs }: { diffMs: number }) {
-  const { text, isRelative } = formatRelativeText(diffMs, "kr");
-  return <span>{text}</span>;
-}
-```

package/.agents/references/hooks/useAvoidKeyboard.md

@@ -1,29 +0,0 @@
-# useAvoidKeyboard
-
-## Purpose
-
-Returns a style object that pushes the bottom of the viewport upward via `translateY` when the virtual keyboard appears. Useful for fixing mobile layout issues where the keyboard overlaps input fields.
-
-## Usage Logic
-
-Internally subscribes to `useKeyboardHeight`. When the keyboard opens, the returned style applies a negative `translateY` equal to the keyboard height, keeping the focused element visible. The transition is animated via CSS `transition`.
-
-## Type Signature
-
-```ts
-function useAvoidKeyboard(): React.CSSProperties
-```
-
-Returns a style object containing `transform`, `transition`, and `willChange` properties.
-
-## Example Code
-
-```tsx
-import { useAvoidKeyboard } from "@musecat/functionkit";
-import { View } from "./YourView";
-
-function ChatInput() {
-  const keyboardStyle = useAvoidKeyboard();
-  return <View style={keyboardStyle}>...</View>;
-}
-```

package/.agents/references/hooks/useCheckInvisible.md

@@ -1,36 +0,0 @@
-# useCheckInvisible
-
-## Purpose
-
-Detects whether an element with a given CSS class name has scrolled above the viewport (`top < 0`). Useful for triggering "sticky" or "collapsed" states when a section scrolls out of view.
-
-## Usage Logic
-
-Uses `IntersectionObserver` or scroll event tracking to monitor the first element matching the provided class name. Returns `true` when the element's top edge is above the viewport.
-
-## Type Signature
-
-```ts
-function useCheckInvisible(className: string): boolean
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `className` | `string` | CSS class name of the element to monitor |
-
-Returns `boolean` — `true` when the element is scrolled out of view (top < 0).
-
-## Example Code
-
-```tsx
-import { useCheckInvisible } from "@musecat/functionkit/hooks/useCheckInvisible";
-
-function Header() {
-  const isHidden = useCheckInvisible("hero-section");
-  return <header className={isHidden ? "sticky" : ""}>...</header>;
-}
-```
-
-## Note
-
-Not exported from the barrel. Import via subpath only: `@musecat/functionkit/hooks/useCheckInvisible`.

package/.agents/references/hooks/useCheckScroll.md

@@ -1,36 +0,0 @@
-# useCheckScroll
-
-## Purpose
-
-Detects whether the page has been scrolled vertically (`window.scrollY > 0`). Returns an `isScrolled` flag for toggling UI states such as sticky header shadows or floating action buttons.
-
-## Usage Logic
-
-Listens to the `scroll` event on `window`. Memoizes the check to avoid unnecessary re-renders.
-
-## Type Signature
-
-```ts
-function useCheckScroll(): { isScrolled: boolean }
-```
-
-Returns `{ isScrolled: boolean }` — `isScrolled` is `true` when `window.scrollY > 0`.
-
-## Example Code
-
-```tsx
-import { useCheckScroll } from "@musecat/functionkit/hooks/useCheckScroll";
-
-function StickyHeader() {
-  const { isScrolled } = useCheckScroll();
-  return (
-    <header className={isScrolled ? "header--scrolled" : "header--top"}>
-      ...
-    </header>
-  );
-}
-```
-
-## Note
-
-Not exported from the barrel. Import via subpath only: `@musecat/functionkit/hooks/useCheckScroll`.

package/.agents/references/hooks/useClientDateTime.md

@@ -1,39 +0,0 @@
-# useClientDateTime
-
-## Purpose
-
-Formats a date on the client side using the user's locale and timezone. Returns the formatted text inside a `useEffect`, ensuring hydration safety via a `ready` flag.
-
-## Usage Logic
-
-Takes a `DateInput` and locale, then computes the formatted date/time string on mount and whenever inputs change. Returns a `ready` boolean (initially `false`) so the component can render a fallback (e.g., server-rendered date) before hydration completes.
-
-## Type Signature
-
-```ts
-function useClientDateTime(
-  date: DateInput,
-  locale: AppLocale,
-  options?: {
-    datePreset?: DatePreset;
-    timePreset?: TimePreset;
-  }
-): {
-  ready: boolean;
-  text: string;
-  date: Date | null;
-}
-```
-
-## Example Code
-
-```tsx
-import { useClientDateTime } from "@musecat/functionkit";
-
-function PostDate({ timestamp }: { timestamp: string }) {
-  const { ready, text } = useClientDateTime(timestamp, "kr", {
-    datePreset: "long",
-  });
-  return <time>{ready ? text : timestamp}</time>;
-}
-```

package/.agents/references/hooks/useDebounce.md

@@ -1,46 +0,0 @@
-# useDebounce / debounce
-
-## Purpose
-
-Delays the propagation of a rapidly changing value. Includes both a raw utility function (`debounce`) for non-React use and a React hook (`useDebounce`) that auto-cleans up on unmount.
-
-## Usage Logic
-
-**`debounce`**: A pure function that wraps any callback with configurable leading/trailing edge execution. Returns the debounced function with a `.cancel()` method.
-
-**`useDebounce`**: React hook that returns the debounced value. Internally uses `useState` + `useEffect` with the raw `debounce` utility. Automatically cancels pending timers on unmount.
-
-## Type Signatures
-
-```ts
-// Pure function — SSR-safe
-function debounce<T extends (...args: any[]) => any>(
-  fn: T,
-  delay: number,
-  options?: { leading?: boolean; trailing?: boolean }
-): T & { cancel: () => void };
-
-// React hook — client-only
-function useDebounce<T>(
-  value: T,
-  delay: number,
-  options?: { leading?: boolean; trailing?: boolean }
-): T;
-```
-
-## Example Code
-
-```tsx
-import { useDebounce } from "@musecat/functionkit";
-
-function SearchInput() {
-  const [query, setQuery] = useState("");
-  const debouncedQuery = useDebounce(query, 300);
-
-  useEffect(() => {
-    if (debouncedQuery) fetchResults(debouncedQuery);
-  }, [debouncedQuery]);
-
-  return <input onChange={(e) => setQuery(e.target.value)} />;
-}
-```

package/.agents/references/hooks/useDebouncedCallback.md

@@ -1,34 +0,0 @@
-# useDebouncedCallback
-
-## Purpose
-
-Provides a debounced callback for boolean value changes. Unlike `useDebounce` which debounces a value, this hook debounces the *invocation* of a callback, automatically canceling the previous pending call.
-
-## Usage Logic
-
-Wraps the `onChange` handler so it only fires after `timeThreshold` ms of inactivity. Each call replaces the previous pending timer, acting as a "settled" change detector.
-
-## Type Signature
-
-```ts
-function useDebouncedCallback(
-  onChange: (value: boolean) => void,
-  timeThreshold: number
-): (value: boolean) => void;
-```
-
-Returns a memoized setter that debounces calls to `onChange`.
-
-## Example Code
-
-```tsx
-import { useDebouncedCallback } from "@musecat/functionkit";
-
-function ToggleTracker() {
-  const handleChange = useDebouncedCallback((value) => {
-    console.log("Toggle settled:", value);
-  }, 500);
-
-  return <Toggle onChange={handleChange} />;
-}
-```