@musecat/functionkit 1.2.0 → 1.2.2

package/.agents/references/utils/floatingMotion.md

@@ -0,0 +1,67 @@
+# floatingMotion
+
+## Purpose
+
+Provides animation presets and transform utilities for floating UI elements: tooltips, popovers, modals, and mobile sheets. Calculates `initial`, `animate`, and `exit` states for Framer Motion.
+
+## Usage Logic
+
+**`getFloatingMotionPreset(mode, placement?)`**: Returns a complete Framer Motion preset object based on the mode and optional placement.
+
+**`getFloatingTransformOrigin(placement)`**: Returns the correct `transformOrigin` string for a given placement.
+**`getFloatingHiddenTransform(placement)`**: Returns the hidden-state transform offset for a given placement.
+
+### Modes
+| Mode | Description | Animation |
+|------|-------------|-----------|
+| `anchored` | Tooltips, popovers | Scale + fade from placement origin |
+| `center-selected` | Center-positioned selection | Scale in place |
+| `modal-center` | Modal windows | Scale + fade in center |
+| `mobile-sheet` | Bottom sheets | Slide up from bottom |
+
+## Type Signatures
+
+```ts
+type FloatingMotionMode = "anchored" | "center-selected" | "modal-center" | "mobile-sheet";
+type FloatingPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "top-end" | ...;
+type FloatingMotionPreset = {
+  initial: Variants;
+  animate: Variants;
+  exit: Variants;
+  transition: Transition;
+};
+
+function getFloatingMotionPreset(
+  mode: FloatingMotionMode,
+  placement?: FloatingPlacement
+): FloatingMotionPreset;
+
+function getFloatingTransformOrigin(placement: FloatingPlacement): string;
+function getFloatingHiddenTransform(placement: FloatingPlacement): { x?: number; y?: number };
+```
+
+## Example Code
+
+```tsx
+import { getFloatingMotionPreset } from "@musecat/functionkit";
+import { motion, AnimatePresence } from "framer-motion";
+
+function Tooltip({ open, children }: { open: boolean; children: ReactNode }) {
+  const preset = getFloatingMotionPreset("anchored", "top");
+
+  return (
+    <AnimatePresence>
+      {open && (
+        <motion.div
+          variants={preset}
+          initial="initial"
+          animate="animate"
+          exit="exit"
+        >
+          {children}
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+```

package/.agents/references/utils/getDeviceInfo.md

@@ -0,0 +1,43 @@
+# getDeviceInfo (checkDevice)
+
+## Purpose
+
+Parses the User-Agent string to detect the user's device type, operating system, and browser. Callable at module scope — no `window` required.
+
+## Usage Logic
+
+Analyzes `navigator.userAgent` with a series of regex checks. Returns a `DeviceInfo` object with boolean flags. SSR-safe — can be called in Server Components, RSC, or module initialization.
+
+## Type Signatures
+
+```ts
+interface DeviceInfo {
+  isMobile: boolean;
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isIOSSafari: boolean;
+  isMacSafari: boolean;
+  isSamsungBrowser: boolean;
+  isTouchDevice: boolean;
+  browser: string | null;
+}
+
+function getDeviceInfo(): DeviceInfo;
+```
+
+## Example Code
+
+```tsx
+import { getDeviceInfo } from "@musecat/functionkit";
+
+const { isMobile, isIOS, isIOSSafari } = getDeviceInfo();
+
+// Call at module scope
+const platform = isIOS ? "ios" : isAndroid ? "android" : "web";
+
+export function detectBrowser() {
+  const { isSafari, browser } = getDeviceInfo();
+  return { isSafari, browser };
+}
+```

package/.agents/references/utils/isEditableKeyboardTarget.md

@@ -0,0 +1,35 @@
+# isEditableKeyboardTarget (keyboardTarget)
+
+## Purpose
+
+Checks if a keyboard event target is an editable element (`input`, `textarea`, `select`, or `contentEditable`). Used to prevent keyboard navigation hooks from interfering with native input editing.
+
+## Usage Logic
+
+Examines the target element's tag name and `isContentEditable` property. Excludes buttons, checkboxes, and radio inputs from the editable set.
+
+## Type Signature
+
+```ts
+function isEditableKeyboardTarget(target: EventTarget | null): boolean;
+```
+
+## Example Code
+
+```tsx
+import { isEditableKeyboardTarget, useKeyboardListNavigation } from "@musecat/functionkit";
+
+function SearchableList({ items }: { items: string[] }) {
+  const { handleListKeyDown } = useKeyboardListNavigation({
+    itemCount: items.length,
+    onSelect: (i) => console.log(items[i]),
+  });
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (isEditableKeyboardTarget(e.target)) return; // Don't steal from inputs
+    handleListKeyDown(e);
+  };
+
+  return <ul onKeyDown={onKeyDown}>...</ul>;
+}
+```

package/.agents/references/utils/mergeRefs.md

@@ -0,0 +1,29 @@
+# mergeRefs
+
+## Purpose
+
+Combines multiple React refs (callback refs and/or object refs) into a single callback ref. Useful when forwarding refs from parent components while keeping internal refs.
+
+## Usage Logic
+
+Returns a callback ref that, when called with a DOM node, sets `ref.current` on all object refs and invokes all callback refs with the node. Filters out `undefined` refs.
+
+## Type Signature
+
+```ts
+function mergeRefs<T>(
+  ...refs: (React.Ref<T> | undefined)[]
+): (node: T) => void;
+```
+
+## Example Code
+
+```tsx
+import { mergeRefs } from "@musecat/functionkit";
+import { forwardRef, useRef } from "react";
+
+const Input = forwardRef<HTMLInputElement, Props>((props, ref) => {
+  const internalRef = useRef<HTMLInputElement>(null);
+  return <input ref={mergeRefs(ref, internalRef)} {...props} />;
+});
+```

package/.agents/references/utils/seen.md

@@ -0,0 +1,37 @@
+# seen
+
+## Purpose
+
+Manages a "user has already seen this" state as a JSON string. Useful for marking items as read, dismissing onboarding prompts, or tracking feature discovery without server state.
+
+## Usage Logic
+
+Stores an array of string keys serialized as JSON. `parseSeen` deserializes, `hasSeenKey` checks a specific key, and `buildSeenValue` appends a new key and returns the updated JSON string. SSR-safe — pure functions with no side effects.
+
+## Type Signatures
+
+```ts
+const SEEN_STORAGE_KEY = "seen";
+
+function parseSeen(seen: string | null): string[];
+function hasSeenKey(seen: string | null, key: string): boolean;
+function buildSeenValue(prev: string | null, key: string): string;
+```
+
+## Example Code
+
+```tsx
+import { hasSeenKey, buildSeenValue, SEEN_STORAGE_KEY } from "@musecat/functionkit";
+import { getLocalStorage, updateLocalStorage } from "@musecat/functionkit";
+
+function useOnboarding() {
+  const stored = getLocalStorage(SEEN_STORAGE_KEY);
+  const hasSeenWalkthrough = hasSeenKey(stored, "walkthrough-v1");
+
+  const dismissWalkthrough = () => {
+    updateLocalStorage(SEEN_STORAGE_KEY, buildSeenValue(stored, "walkthrough-v1"));
+  };
+
+  return { hasSeenWalkthrough, dismissWalkthrough };
+}
+```

package/.agents/references/utils/subscribeKeyboardHeight.md

@@ -0,0 +1,35 @@
+# subscribeKeyboardHeight
+
+## Purpose
+
+A low-level utility that subscribes to `visualViewport` resize/scroll events and reports the estimated keyboard height. Used internally by `useKeyboardHeight`.
+
+## Usage Logic
+
+Attaches `resize` and `scroll` event listeners to `window.visualViewport`. Computes keyboard height as `window.innerHeight - visualViewport.height`. Throttles callbacks at the specified interval (default 16ms). Returns an unsubscribe function.
+
+## Type Signature
+
+```ts
+function subscribeKeyboardHeight(
+  handler: (height: number) => void,
+  throttleMs?: number
+): { unsubscribe: () => void };
+```
+
+## Example Code
+
+```tsx
+import { subscribeKeyboardHeight } from "@musecat/functionkit";
+import { useEffect } from "react";
+
+function useCustomKeyboardHandler() {
+  useEffect(() => {
+    const { unsubscribe } = subscribeKeyboardHeight(
+      (height) => console.log("Keyboard height:", height),
+      100
+    );
+    return unsubscribe;
+  }, []);
+}
+```

package/AGENTS.md

@@ -0,0 +1,128 @@
+# FunctionKit (@musecat/functionkit)
+
+React 19 frontend utility library. Single package, ESM.
+
+## Import Convention Enforcement (Mandatory)
+
+- **Barrel imports are the rule:** `import { useDebounce } from "@musecat/functionkit"`.
+- **Subpath imports are only allowed when:** the export is not in the barrel (`useCheckInvisible`, `SwitchCase`, `ScrolltoTop`) or tree-shaking is absolutely required.
+- **Type imports also go through the barrel:** `import type { AppLocale, DateInput } from "@musecat/functionkit"`.
+- **No reimplementation:** If FunctionKit already provides a feature, reuse it. Never write a duplicate.
+
+## SSR Safety Classification
+
+| Category | Condition | Examples |
+|---|---|---|
+| **SSR-safe** | No `"use client"`, pure function | `formatLongDate`, `mergeRefs`, `SwitchCase`, `getDeviceInfo`, `floatingMotion`, `seen`, `parseClientCookieNames`, `debounce` |
+| **Client-only** | `"use client"` or `window` access | All hooks, `ViewportPortal`, `ScrolltoTop`, `browserStorage`, `cookie` (except `parseClientCookieNames`), `clipboardShare`, `isEditableKeyboardTarget` |
+
+SSR-safe functions can be used freely in Server Components, RSC, and Client Components. Client-only items must only be used in `"use client"` components.
+
+## Barrel Export Mapping
+
+The barrel (`index.ts`) exports 63 named exports. **Items NOT in the barrel (require subpath imports):**
+- `SwitchCase` — component subpath
+- `ScrolltoTop` — component subpath
+- `useCheckInvisible` — `@musecat/functionkit/hooks/useCheckInvisible`
+- `useCheckScroll` — `@musecat/functionkit/hooks/useCheckScroll`
+
+When adding new features, register them in the barrel.
+
+## Hook Selection Guidelines
+
+| Scenario | Hook to Use |
+|---|---|
+| Debounce rapid state changes | `useDebounce` or `useDebouncedCallback` |
+| Polling / repeated execution | `useInterval` |
+| Delayed single execution | `useTimeout` |
+| Keyboard list navigation | `useKeyboardListNavigation` |
+| Long press gesture | `useLongPress` |
+| Single/double click distinction | `useDoubleClick` |
+| Geolocation tracking | `useGeolocation` |
+| Client date formatting | `useClientDateTime` |
+| Relative time ("3 minutes ago") | `useRelativeDateTime` |
+| IntersectionObserver | `useIntersectionObserver` |
+| Keyboard avoidance (mobile) | `useAvoidKeyboard` |
+| Viewport height | `useViewportHeight` |
+| Media query matching | `useViewportMatch` |
+| Scroll position detection | `useCheckScroll` (subpath) |
+| Element visibility detection | `useCheckInvisible` (subpath) |
+| Toggle state | `useToggleState` |
+| Hydration guard | `useHasMounted` |
+| Stable callback reference | `usePreservedCallback` |
+| Deep equality reference | `usePreservedReference` |
+| Ref lifecycle | `useRefEffect` |
+
+## Component Selection Guidelines
+
+- **SwitchCase** — Prefer over inline &&/ternary for multi-branch rendering. SSR-safe.
+- **ViewportPortal** — Fixed-position overlays, modals, toasts. Client-only.
+- **ScrolltoTop** — Scroll reset on page navigation. Client-only.
+
+Never write raw `createContext` + `Provider` + `useContext` boilerplate. Use `buildContext` instead.
+
+## DateTime Formatting Guidelines
+
+| Context | Use | SSR-safe |
+|---|---|---|
+| Server static date | `formatServerDate` / `formatServerDateTime` | Yes |
+| Client date | `formatClientDate` / `formatClientDateTime` | No |
+| Relative time ("3분 전") | `formatServerRelative` (server) / `formatClientRelative` (client) | Mixed |
+| Remaining time ("2일 3시간 남음") | `formatRemainingText` | Yes |
+| UTC key ("YYYY-MM-DD") | `formatUtcDateKey` / `parseUtcDateInput` | Yes |
+| Raw formatters | `formatLongDate`, `formatDotDate`, `formatKoreanTime` etc. | Yes |
+
+**Locale handling:** `DateInput` accepts `string | number | Date`. Use `normalizeAppLocale("ko")` → `"kr"`, `toIntlLocale("kr")` → `"ko-KR"`.
+
+## Cookie & Storage API Guidelines
+
+| Operation | API | SSR-safe |
+|---|---|---|
+| Read cookie | `getClientCookie(name)` | No |
+| Write cookie | `setClientCookie(name, value, days?)` | No |
+| Delete cookie | `clearClientCookie(name)` / `clearAllClientCookies()` | No |
+| Parse cookie names | `parseClientCookieNames(cookieString)` | **Yes** |
+| localStorage | `getLocalStorage` / `updateLocalStorage` / `removeLocalStorage` | No |
+| sessionStorage | `getSessionStorage` / `updateSessionStorage` / `removeSessionStorage` | No |
+
+`clearAllClientCookies` tries all domain/path combinations — use with caution.
+
+## Context & Utility Patterns
+
+- **`buildContext`:** Creates `createContext` + Provider + `useContext` in one call. `const [useMyCtx, MyProvider] = buildContext<MyType>()`.
+- **`mergeRefs`:** Merges multiple refs into a single callback ref. Use when forwarding refs.
+- **`getDeviceInfo`:** UA-based device detection. Callable at module scope. Returns `isMobile`, `isIOS`, `isAndroid`, etc.
+- **`isEditableKeyboardTarget`:** Checks if a key event target is an editable element. Use before keyboard navigation.
+- **`NavigatorClipboard` / `NavigatorShare`:** Clipboard copy/share with automatic fallback on failure.
+- **`floatingMotion`:** `getFloatingMotionPreset` for tooltip/popover/modal animation configs. 4 modes (anchored, center-selected, modal-center, mobile-sheet).
+- **`seen`:** `hasSeenKey` / `buildSeenValue` for "user has already seen" state management. SSR-safe.
+- **`subscribeKeyboardHeight`:** Low-level keyboard height change detection. Used internally by `useKeyboardHeight`.
+
+## Test Failure Resolution
+
+When a test fails, do not blindly patch it to turn green. Reason about intent:
+1. Understand the hook/component's design contract — what it should do vs. what it actually does.
+2. If the test correctly captures the intended behavior and the code violates it, fix the code.
+3. If the code correctly implements the intended behavior and the test reflects outdated assumptions, fix the test.
+4. If neither is clearly right, treat the source as the source of truth and align the test unless you have explicit user instruction to change the behavior.
+
+## Documentation Maintenance
+
+- **Documentation MUST Be Updated Immediately:** Every time you add, modify, or remove a hook, component, util, or any exported API/type, you MUST update the corresponding `.agents/references/` doc in the **same batch of tool calls** — not later, not after tests, not when asked. You must check what changed and update refs before moving to the next task.
+- When the barrel (`index.ts`) export list changes, update the Barrel Export Mapping section above.
+- Before using any feature, read the corresponding `.agents/references/` doc first.
+- If references have drifted from the actual code due to manual changes, analyze the source code and git history to align them.
+
+### Reference File Mapping
+
+| Category | File(s) |
+|---|---|
+| Components | `.agents/references/components/SwitchCase.md`, `ScrolltoTop.md`, `ViewportPortal.md` |
+| Hooks | `.agents/references/hooks/usePreservedCallback.md`, `usePreservedReference.md`, `useRefEffect.md`, `useDebounce.md`, `useDebouncedCallback.md`, `useInterval.md`, `useTimeout.md`, `useKeyboardListNavigation.md`, `useLongPress.md`, `useDoubleClick.md`, `useIntersectionObserver.md`, `useCheckInvisible.md`, `useCheckScroll.md`, `useViewportHeight.md`, `useViewportMatch.md`, `useAvoidKeyboard.md`, `useToggleState.md`, `useHasMounted.md`, `useGeolocation.md`, `useKeyboardHeight.md`, `useClientDateTime.md`, `useRelativeDateTime.md` |
+| Cookie | `.agents/references/cookie/cookie.md` |
+| DateTime | `.agents/references/datetime/dateTime.shared.md`, `dateTime.client.md`, `dateTime.server.md` |
+| Utils | `.agents/references/utils/buildContext.md`, `mergeRefs.md`, `floatingMotion.md`, `browserStorage.md`, `getDeviceInfo.md`, `clipboardShare.md`, `isEditableKeyboardTarget.md`, `seen.md`, `subscribeKeyboardHeight.md` |
+
+### usePreservedCallback Trade-off
+
+`usePreservedCallback` uses `useRef` + `useEffect` to keep a stable callback reference that always calls the latest version. Because the ref is synced via `useEffect` (after paint), the returned callback may hold a **stale value** during the first render or in the gap between a re-render and the effect flush. In practice this is never an issue — the callback is only invoked in event handlers that fire post-paint. This is the same pattern used by react-hook-form, Radix UI, and others. If synchronous invocation during render is required, use a regular `useCallback` with inline deps instead.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -29,6 +29,10 @@ export default function Example() {
 }
 ```
 
+## References
+
+This package includes `.agents/references/` directory with detailed documentation for every hook, component, and utility. Use it alongside TypeScript definitions as a guide when building with `@musecat/functionkit`.
+
 ## Acknowledgements
 
 - [toss/react-simplikit](https://github.com/toss/react-simplikit/)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@musecat/functionkit",
-	"version": "1.2.0",
+	"version": "1.2.2",
 	"description": "React 19 + TypeScript frontend utility library — hooks, components, datetime, cookie, and utils",
 	"keywords": [
 		"react",
@@ -18,6 +18,9 @@
 	"files": [
 		"index.ts",
 		"packages/",
+		".agents/",
+		"AGENTS.md",
+		"CLAUDE.md",
 		"README.md",
 		"LICENSE"
 	],