@musecat/functionkit 1.1.0 → 1.2.1

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

@@ -8,16 +8,22 @@ Client-side cookie read/write/delete utilities. All functions except `parseClien
 
 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.
 
+All mutation functions accept an optional `documentRef` to inject a mock document for testing. `setClientCookie` also accepts an optional `CookieStoreLike` via options.
+
 ## 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 getClientCookie(name: string): string | undefined;
+function setClientCookie(name: string, value: string, days?: number, documentRef?: DocumentCookieRef): void;
+function clearClientCookie(name: string, options?: ClearClientCookieOptions): void;
+function clearAllClientCookies(options?: ClearAllClientCookiesOptions): string[];
 function parseClientCookieNames(cookieString: string): string[]; // SSR-safe
 ```
 
+- `DocumentCookieRef` = `{ cookie: string }`
+- `ClearClientCookieOptions` = `{ hostname?: string; path?: string; documentRef?: DocumentCookieRef; cookieStore?: CookieStoreLike }`
+- `ClearAllClientCookiesOptions` extends `ClearClientCookieOptions` with `{ includeRoot?: boolean; cookieString?: string }`
+
 ## Example Code
 
 ```tsx

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.1.0",
+	"version": "1.2.1",
 	"description": "React 19 + TypeScript frontend utility library — hooks, components, datetime, cookie, and utils",
 	"keywords": [
 		"react",
@@ -10,6 +10,19 @@
 		"frontend"
 	],
 	"license": "MIT",
+	"private": false,
+	"author": "Musecat Team",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"files": [
+		"index.ts",
+		"packages/",
+		".agents/",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/TheTechclip/FunctionKit.git"
@@ -31,6 +44,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/.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.

package/CONTRIBUTING.md

@@ -1,39 +0,0 @@
-# Contributing to @musecat/functionkit
-
-Thank you for your interest in contributing! We welcome bug reports, feature suggestions, and pull requests.
-
-## Development Setup
-
-```bash
-git clone https://github.com/TheTechclip/FunctionKit.git
-cd FunctionKit
-npm install
-```
-
-## Available Scripts
-
-| Command | Description |
-|---|---|
-| `npm test` | Run all tests with Vitest |
-| `npm run test:coverage` | Run tests with coverage report |
-| `npm run lint` | Lint all files with Biome |
-| `npm run format` | Format all files with Prettier + Biome |
-
-## Code Standards
-
-- TypeScript strict mode is enabled — ensure your code compiles without errors.
-- All new features must include corresponding tests.
-- Hooks must start with `"use client"` directive. Pure utility functions must NOT.
-- Barrel exports (`index.ts`) must be updated for new public APIs.
-- Follow the existing code style (tabs, double quotes, semicolons).
-
-## Pull Request Process
-
-1. Create a feature branch from `master`.
-2. Write tests for your changes.
-3. Ensure `npm run lint && npm test` passes.
-4. Open a pull request describing the change and its motivation.
-
-## Questions?
-
-Feel free to open a discussion or issue for any questions.

package/biome.json

@@ -1,25 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/2.5.4/schema.json",
-	"assist": { "actions": { "source": { "organizeImports": "on" } } },
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"preset": "recommended"
-		}
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab",
-		"indentWidth": 2,
-		"lineWidth": 100
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "double",
-			"semicolons": "always"
-		}
-	},
-	"files": {
-		"includes": ["**", "!**/dist", "!**/coverage", "!**/node_modules"]
-	}
-}

package/tests/components/ScrolltoTop.test.tsx

@@ -1,15 +0,0 @@
-import { render } from "@testing-library/react";
-import { describe, expect, test, vi } from "vitest";
-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

@@ -1,33 +0,0 @@
-import { render } from "@testing-library/react";
-import { describe, expect, test } from "vitest";
-import { SwitchCase } from "@/packages/components/SwitchCase";
-
-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("");
-	});
-});

package/tests/components/ViewportPortal.test.tsx

@@ -1,46 +0,0 @@
-import { render, screen } from "@testing-library/react";
-import { beforeEach, describe, expect, test } from "vitest";
-import { getViewportPortalRoot, ViewportPortal } from "@/packages/components/ViewportPortal";
-
-describe("ViewportPortal", () => {
-	beforeEach(() => {
-		document.body.innerHTML = "";
-	});
-
-	test("getViewportPortalRoot creates a root element if it doesn't exist", () => {
-		const root = getViewportPortalRoot();
-		expect(root).not.toBeNull();
-		expect(root?.id).toBe("viewport-portal-root");
-		expect(document.getElementById("viewport-portal-root")).toBe(root);
-	});
-
-	test("getViewportPortalRoot returns existing root element if it exists", () => {
-		const root1 = getViewportPortalRoot();
-		const root2 = getViewportPortalRoot();
-		expect(root1).toBe(root2);
-		expect(document.querySelectorAll("#viewport-portal-root").length).toBe(1);
-	});
-
-	test("getViewportPortalRoot returns null when document is undefined (SSR)", () => {
-		const origDocument = global.document;
-		// @ts-expect-error
-		delete global.document;
-		expect(getViewportPortalRoot()).toBeNull();
-		global.document = origDocument;
-	});
-
-	test("ViewportPortal renders children into the portal root", () => {
-		render(
-			<ViewportPortal>
-				<div data-testid="portal-content">Portal Content</div>
-			</ViewportPortal>,
-		);
-
-		const root = document.getElementById("viewport-portal-root");
-		expect(root).not.toBeNull();
-
-		const content = screen.getByTestId("portal-content");
-		expect(content.textContent).toBe("Portal Content");
-		expect(root?.contains(content)).toBe(true);
-	});
-});