@musecat/functionkit 1.0.0 → 1.0.2

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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,34 @@
+# 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

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,86 @@
+# 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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,39 @@
+# 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

@@ -0,0 +1,46 @@
+# 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

@@ -0,0 +1,34 @@
+# 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} />;
+}
+```

package/.agents/references/hooks/useDoubleClick.md

@@ -0,0 +1,40 @@
+# useDoubleClick
+
+## Purpose
+
+Distinguishes between a single click and a double click on the same element. Fires `click` on a single click after a configurable delay, or `doubleClick` if a second click arrives within the delay window.
+
+## Usage Logic
+
+Maintains an internal timer. On the first click it waits for `delay` ms. If a second click arrives within that window, it fires `doubleClick` and clears the timer. Otherwise it fires `click` after the delay expires.
+
+## Type Signature
+
+```ts
+function useDoubleClick(
+  handlers: {
+    click?: () => void;
+    doubleClick?: () => void;
+  },
+  delay?: number
+): {
+  onClick: () => void;
+};
+```
+
+Returns an `onClick` handler to spread onto the target element.
+
+## Example Code
+
+```tsx
+import { useDoubleClick } from "@musecat/functionkit";
+
+function FileIcon() {
+  const { onClick } = useDoubleClick({
+    click: () => console.log("select"),
+    doubleClick: () => console.log("open"),
+  });
+
+  return <div onClick={onClick}>📄</div>;
+}
+```

package/.agents/references/hooks/useGeolocation.md

@@ -0,0 +1,37 @@
+# useGeolocation
+
+## Purpose
+
+Wraps the Geolocation API (`navigator.geolocation`) for retrieving the user's current position or continuously watching position changes.
+
+## Usage Logic
+
+Supports two modes via the `action` option: `"GET"` calls `getCurrentPosition` once, `"WATCH"` uses `watchPosition` for continuous tracking. Provides imperative `startTracking` / `stopTracking` controls.
+
+## Type Signature
+
+```ts
+interface UseGeolocationOptions {
+  action?: "GET" | "WATCH";
+}
+
+function useGeolocation(options?: UseGeolocationOptions): {
+  latitude: number | null;
+  longitude: number | null;
+  error: GeolocationPositionError | null;
+  startTracking: () => void;
+  stopTracking: () => void;
+};
+```
+
+## Example Code
+
+```tsx
+import { useGeolocation } from "@musecat/functionkit";
+
+function LocationDisplay() {
+  const { latitude, longitude, error } = useGeolocation({ action: "GET" });
+  if (error) return <div>Location unavailable</div>;
+  return <div>{latitude}, {longitude}</div>;
+}
+```

package/.agents/references/hooks/useHasMounted.md

@@ -0,0 +1,27 @@
+# useHasMounted
+
+## Purpose
+
+Returns a boolean indicating whether the component has mounted on the client. A simple hydration guard for preventing server-client content mismatches.
+
+## Usage Logic
+
+Uses `useEffect` to set `true` after mount. Returns `false` on the server and during the first client render before hydration.
+
+## Type Signature
+
+```ts
+function useHasMounted(): boolean;
+```
+
+## Example Code
+
+```tsx
+import { useHasMounted } from "@musecat/functionkit";
+
+function ClientOnly() {
+  const mounted = useHasMounted();
+  if (!mounted) return <Fallback />;
+  return <ClientContent />;
+}
+```