@musecat/functionkit 1.1.0 → 1.2.0

package/.agents/references/utils/buildContext.md

@@ -1,47 +0,0 @@
-# buildContext
-
-## Purpose
-
-Eliminates `createContext` + `Provider` + `useContext` boilerplate. Creates a type-safe context pair in a single call: a typed accessor hook and a Provider component with automatic value memoization.
-
-## Usage Logic
-
-Creates a React context with the generic type `T`. Returns a tuple `[useCtx, Provider]`. The Provider wraps its `value` in `useMemo` to prevent unnecessary re-renders. If `displayName` is provided, it's assigned to the context for DevTools.
-
-## Type Signature
-
-```ts
-function buildContext<T>(
-  displayName?: string
-): [
-  useCtx: () => T,
-  Provider: React.FC<{ value: T; children: ReactNode }>
-];
-```
-
-## Example Code
-
-```tsx
-import { buildContext } from "@musecat/functionkit";
-
-interface Theme {
-  color: string;
-  bg: string;
-}
-
-const [useTheme, ThemeProvider] = buildContext<Theme>("ThemeContext");
-
-// Usage
-function App() {
-  return (
-    <ThemeProvider value={{ color: "#000", bg: "#fff" }}>
-      <ThemedButton />
-    </ThemeProvider>
-  );
-}
-
-function ThemedButton() {
-  const theme = useTheme();
-  return <button style={{ color: theme.color, background: theme.bg }}>Click</button>;
-}
-```

package/.agents/references/utils/clipboardShare.md

@@ -1,59 +0,0 @@
-# NavigatorClipboard / NavigatorShare (clipboardShare)
-
-## Purpose
-
-Provides easy-to-use React components for clipboard copy and native share. Handles error cases with automatic fallback (e.g., if `navigator.share` fails, falls back to clipboard).
-
-## Usage Logic
-
-**NavigatorClipboard**: On click, calls `navigator.clipboard.writeText(text)`. Calls `onComplete` with the result.
-
-**NavigatorShare**: On click, calls `navigator.share({ title, text, url })`. If share fails (or is unavailable), falls back to clipboard copy and calls `onComplete` with fallback info.
-
-## Type Signatures
-
-```ts
-interface NavigatorClipboardProps {
-  text: string;
-  onComplete?: (result: NavigatorClipboardResult) => void;
-  children?: ReactNode;
-}
-
-interface NavigatorShareProps {
-  title?: string;
-  text?: string;
-  url?: string;
-  onComplete?: (result: NavigatorShareResult) => void;
-  children?: ReactNode;
-}
-
-interface NavigatorClipboardResult {
-  copied: boolean;
-  error?: Error;
-}
-
-interface NavigatorShareResult {
-  shared: boolean;
-  copied: boolean;
-  error?: Error;
-}
-```
-
-## Example Code
-
-```tsx
-import { NavigatorClipboard, NavigatorShare } from "@musecat/functionkit";
-
-function ShareButton({ url }: { url: string }) {
-  return (
-    <div>
-      <NavigatorClipboard text={url}>
-        <button>Copy Link</button>
-      </NavigatorClipboard>
-      <NavigatorShare title="Check this out" url={url}>
-        <button>Share</button>
-      </NavigatorShare>
-    </div>
-  );
-}
-```

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

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

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

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

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

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

@@ -1,35 +0,0 @@
-# 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/.gitattributes

@@ -1,2 +0,0 @@
-# Auto detect text files and perform LF normalization
-* text=auto

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,31 +0,0 @@
----
-name: Bug report
-about: Report a bug to help us improve
-title: "[BUG] "
-labels: bug
----
-
-## Describe the Bug
-
-A clear and concise description of what the bug is.
-
-## To Reproduce
-
-Steps to reproduce the behavior:
-1. Import '...'
-2. Call '...'
-3. See error
-
-## Expected Behavior
-
-A clear and concise description of what you expected to happen.
-
-## Environment
-
-- React version:
-- @musecat/functionkit version:
-- Browser / Node version:
-
-## Additional Context
-
-Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,22 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: "[FEATURE] "
-labels: enhancement
----
-
-## Problem Statement
-
-Is your feature request related to a problem? Please describe clearly.
-
-## Proposed Solution
-
-A clear and concise description of what you want to happen.
-
-## Alternative Solutions
-
-A description of any alternative solutions or features you've considered.
-
-## Additional Context
-
-Add any other context or examples about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +0,0 @@
-## Description
-
-Please include a summary of the change and which issue is fixed.
-
-## Type of Change
-
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
-
-## How Has This Been Tested?
-
-Please describe the tests that you ran to verify your changes.
-
-## Checklist
-
-- [ ] My code follows the project's code style
-- [ ] I have added tests that prove my fix/feature works
-- [ ] `npm run lint` passes
-- [ ] `npm test` passes
-- [ ] Barrel exports (`index.ts`) are updated if needed

package/.github/workflows/ci.yml

@@ -1,20 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-
-jobs:
-  quality:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - run: npm ci
-      - run: npm run lint
-      - run: npm test

package/.local/state/gh/device-id

@@ -1 +0,0 @@
-f1f55548-1baa-4638-bd0f-f3da5e3262f0

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-	"useTabs": true,
-	"tabWidth": 2,
-	"printWidth": 100,
-	"singleQuote": false,
-	"semi": true,
-	"trailingComma": "all"
-}

package/AGENTS.md

@@ -1,119 +0,0 @@
-# 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`.
-
-## Documentation Maintenance
-
-- When hooks, components, or utils are added, modified, or removed, update the corresponding `.agents/references/` documentation.
-- 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.
-
-### 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/CODE_OF_CONDUCT.md

@@ -1,55 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment:
-
-- Demonstrating empathy and kindness toward other people
-- Being respectful of differing opinions, viewpoints, and experiences
-- Giving and gracefully accepting constructive feedback
-- Accepting responsibility and apologizing to those affected by our mistakes
-- Focusing on what is best not just for us as individuals, but for the overall community
-
-Examples of unacceptable behavior:
-
-- The use of sexualized language or imagery, and sexual attention or advances
-- Trolling, insulting or derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a professional setting
-
-## Enforcement Responsibilities
-
-Project maintainers are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the project maintainers. All complaints will be reviewed and
-investigated promptly and fairly.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
-version 2.1, available at
-https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.