@musecat/functionkit 1.0.2 → 1.2.0

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

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

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

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

package/.agents/references/hooks/useIntersectionObserver.md

@@ -1,37 +0,0 @@
-# useIntersectionObserver
-
-## Purpose
-
-Provides a convenient ref callback pattern for `IntersectionObserver`. Calls a callback when the observed element's intersection status changes.
-
-## Usage Logic
-
-Uses `useRefEffect` internally to attach the observer when the ref receives an element and clean up when it unmounts. Accepts standard `IntersectionObserverInit` options. The callback is stabilized with `usePreservedCallback`.
-
-## Type Signature
-
-```ts
-function useIntersectionObserver(
-  callback: IntersectionObserverCallback,
-  options?: IntersectionObserverInit
-): (node: HTMLElement | null) => void;
-```
-
-Returns a callback ref to assign to the target element.
-
-## Example Code
-
-```tsx
-import { useIntersectionObserver } from "@musecat/functionkit";
-
-function LazyImage() {
-  const ref = useIntersectionObserver(
-    ([entry]) => {
-      if (entry.isIntersecting) loadImage();
-    },
-    { threshold: 0.1 }
-  );
-
-  return <div ref={ref}>...</div>;
-}
-```

package/.agents/references/hooks/useInterval.md

@@ -1,40 +0,0 @@
-# useInterval
-
-## Purpose
-
-A `setInterval` wrapper hook that handles lifecycle cleanup and provides toggle control. Ideal for polling, timers, or any repeated execution.
-
-## Usage Logic
-
-Starts the interval immediately on mount (unless `enabled: false` is passed). The interval pauses when `delay` is `null` or when `enabled` is `false`. Supports `immediate` mode — fires the callback once immediately before the first interval tick.
-
-## Type Signature
-
-```ts
-function useInterval(
-  callback: () => void,
-  delay: number | null,
-  options?: {
-    immediate?: boolean;
-    enabled?: boolean;
-  }
-): void;
-```
-
-## Example Code
-
-```tsx
-import { useInterval } from "@musecat/functionkit";
-
-function PollingComponent() {
-  const [data, setData] = useState(null);
-
-  useInterval(
-    () => fetch("/api/status").then(setData),
-    5000,
-    { immediate: true }
-  );
-
-  return <div>{data}</div>;
-}
-```

package/.agents/references/hooks/useKeyboardHeight.md

@@ -1,33 +0,0 @@
-# useKeyboardHeight
-
-## Purpose
-
-Returns the current virtual keyboard height in pixels by subscribing to `visualViewport` changes. Useful for adjusting layout when the keyboard opens on mobile.
-
-## Usage Logic
-
-Internally uses `subscribeKeyboardHeight` which listens to `visualViewport.resize` and `visualViewport.scroll` events. Computes the height as the difference between the full viewport and the visual viewport.
-
-## Type Signature
-
-```ts
-function useKeyboardHeight(): number;
-```
-
-Returns the keyboard height in pixels (0 when the keyboard is closed).
-
-## Example Code
-
-```tsx
-import { useKeyboardHeight } from "@musecat/functionkit";
-
-function ChatLayout() {
-  const kbHeight = useKeyboardHeight();
-  return (
-    <div style={{ paddingBottom: kbHeight }}>
-      <MessageList />
-      <InputBar />
-    </div>
-  );
-}
-```

package/.agents/references/hooks/useKeyboardListNavigation.md

@@ -1,58 +0,0 @@
-# useKeyboardListNavigation
-
-## Purpose
-
-Adds keyboard-based navigation (ArrowUp, ArrowDown, Home, End, Enter) to a list of items. Returns the active index, a ref setter, and a keydown handler.
-
-## Usage Logic
-
-Manages an `activeIndex` state updated by arrow keys. `Home`/`End` jump to the first/last item. `Enter` triggers the `onSelect` callback with the active index. Automatically skips navigation when the event target is an editable element (`isEditableKeyboardTarget`).
-
-| Option | Effect |
-|--------|--------|
-| `loop` | When `true`, navigating past the last item wraps to the first |
-| `disable` | When `true`, all keyboard handling is suspended |
-
-## Type Signature
-
-```ts
-function useKeyboardListNavigation(options: {
-  itemCount: number;
-  onSelect: (index: number) => void;
-  disable?: boolean;
-  loop?: boolean;
-}): {
-  activeIndex: number;
-  setItemRef: (index: number) => (el: HTMLElement | null) => void;
-  handleListKeyDown: (e: React.KeyboardEvent) => void;
-};
-```
-
-## Example Code
-
-```tsx
-import { useKeyboardListNavigation } from "@musecat/functionkit";
-
-function MenuList({ items }: { items: string[] }) {
-  const { activeIndex, setItemRef, handleListKeyDown } = useKeyboardListNavigation({
-    itemCount: items.length,
-    onSelect: (i) => console.log("selected:", items[i]),
-    loop: true,
-  });
-
-  return (
-    <ul onKeyDown={handleListKeyDown}>
-      {items.map((item, i) => (
-        <li
-          key={i}
-          ref={setItemRef(i)}
-          className={i === activeIndex ? "active" : ""}
-          tabIndex={-1}
-        >
-          {item}
-        </li>
-      ))}
-    </ul>
-  );
-}
-```

package/.agents/references/hooks/useLongPress.md

@@ -1,48 +0,0 @@
-# useLongPress
-
-## Purpose
-
-Detects a long press gesture on an element. Fires `onLongPress` after the user presses and holds for a configurable delay, with optional `onClick` for tap and `onLongPressEnd` for release.
-
-## Usage Logic
-
-Tracks both mouse and touch events. On `mousedown`/`touchstart`, starts a timer. If the pointer moves beyond `moveThreshold` pixels, the gesture is cancelled. If the timer expires without cancellation, `onLongPress` fires. On release, `onLongPressEnd` fires (if it was a long press), or `onClick` fires (if it was a short tap).
-
-## Type Signature
-
-```ts
-function useLongPress(
-  handlers: {
-    onLongPress: (e: MouseEvent | TouchEvent) => void;
-    onClick?: (e: MouseEvent | TouchEvent) => void;
-    onLongPressEnd?: (e: MouseEvent | TouchEvent) => void;
-  },
-  options?: {
-    delay?: number;
-    moveThreshold?: number;
-  }
-): {
-  onMouseDown: (e: React.MouseEvent) => void;
-  onTouchStart: (e: React.TouchEvent) => void;
-  onMouseUp: (e: React.MouseEvent) => void;
-  onTouchEnd: (e: React.TouchEvent) => void;
-  onMouseMove: (e: React.MouseEvent) => void;
-  onTouchMove: (e: React.TouchEvent) => void;
-};
-```
-
-## Example Code
-
-```tsx
-import { useLongPress } from "@musecat/functionkit";
-
-function LongPressButton() {
-  const handlers = useLongPress({
-    onLongPress: () => console.log("hold complete"),
-    onClick: () => console.log("tap"),
-    onLongPressEnd: () => console.log("released"),
-  });
-
-  return <button {...handlers}>Press & hold</button>;
-}
-```

package/.agents/references/hooks/usePreservedCallback.md

@@ -1,33 +0,0 @@
-# usePreservedCallback
-
-## Purpose
-
-Returns a stable function identity while always calling the latest version of the provided callback. Eliminates the need to list callback dependencies in `useEffect` or `useMemo` dependency arrays.
-
-## Usage Logic
-
-Stores the latest callback in a `useRef`, then returns a `useCallback`-wrapped proxy that always invokes `ref.current`. The returned function never changes identity, preventing unnecessary re-renders of memoized children.
-
-## Type Signature
-
-```ts
-function usePreservedCallback<T extends (...args: any[]) => any>(
-  callback: T
-): T;
-```
-
-## Example Code
-
-```tsx
-import { usePreservedCallback, useIntersectionObserver } from "@musecat/functionkit";
-
-function InfiniteScroll({ onLoadMore }: { onLoadMore: () => void }) {
-  const stableLoadMore = usePreservedCallback(onLoadMore);
-
-  const ref = useIntersectionObserver(([entry]) => {
-    if (entry.isIntersecting) stableLoadMore();
-  });
-
-  return <div ref={ref}>...</div>;
-}
-```

package/.agents/references/hooks/usePreservedReference.md

@@ -1,34 +0,0 @@
-# usePreservedReference
-
-## Purpose
-
-Maintains a stable reference to a value, only updating it when the value meaningfully changes. Avoids unnecessary re-renders caused by new object/array identities on every render.
-
-## Usage Logic
-
-Compares the current and previous values using a custom comparator (defaults to `JSON.stringify`). If they are considered equal, the previous reference is returned instead of the new one.
-
-## Type Signature
-
-```ts
-function usePreservedReference<T>(
-  value: T,
-  compare?: (a: T, b: T) => boolean
-): T;
-```
-
-## Example Code
-
-```tsx
-import { usePreservedReference } from "@musecat/functionkit";
-
-function Filters({ filters }: { filters: { sort: string; page: number } }) {
-  const stableFilters = usePreservedReference(filters);
-
-  useEffect(() => {
-    fetchResults(stableFilters);
-  }, [stableFilters]); // Only fires when actual values change
-
-  return <div>...</div>;
-}
-```

package/.agents/references/hooks/useRefEffect.md

@@ -1,35 +0,0 @@
-# useRefEffect
-
-## Purpose
-
-Provides a ref callback that runs an effect when the element mounts and optionally runs a cleanup when it unmounts or when dependencies change. Similar to `useEffect` but keyed to a DOM element's lifecycle.
-
-## Usage Logic
-
-Returns a callback ref. When React calls the ref with an element, the effect function runs. When it's called with `null` (unmount) or when `deps` change, the previous cleanup is called before running the new effect.
-
-## Type Signatures
-
-```ts
-type CleanupCallback = () => void;
-
-function useRefEffect(
-  effect: (el: HTMLElement) => CleanupCallback | void,
-  deps?: any[]
-): (el: HTMLElement | null) => void;
-```
-
-## Example Code
-
-```tsx
-import { useRefEffect } from "@musecat/functionkit";
-
-function AutoFocus() {
-  const ref = useRefEffect((el) => {
-    el.focus();
-    return () => console.log("unmounted");
-  }, []);
-
-  return <input ref={ref} />;
-}
-```

package/.agents/references/hooks/useRelativeDateTime.md

@@ -1,35 +0,0 @@
-# useRelativeDateTime
-
-## Purpose
-
-Displays a date as a relative time string ("3 minutes ago", "2 hours ago") that updates automatically. Falls back to a formatted date string when the relative time exceeds a configurable threshold.
-
-## Usage Logic
-
-Computes the difference between now and the given date, then formats it using `formatRelativeText`. Recomputes on a configurable interval (`updateIntervalMs`, default 1000ms). If the difference exceeds `maxRelativeDays`, returns a standard date format instead.
-
-## Type Signature
-
-```ts
-function useRelativeDateTime(
-  date: DateInput,
-  locale: AppLocale,
-  options?: {
-    updateIntervalMs?: number;
-    maxRelativeDays?: number;
-  }
-): string;
-```
-
-## Example Code
-
-```tsx
-import { useRelativeDateTime } from "@musecat/functionkit";
-
-function Timestamp({ time }: { time: string }) {
-  const relative = useRelativeDateTime(time, "kr", {
-    maxRelativeDays: 7,
-  });
-  return <span>{relative}</span>;
-}
-```

package/.agents/references/hooks/useTimeout.md

@@ -1,42 +0,0 @@
-# useTimeout
-
-## Purpose
-
-A `setTimeout` wrapper hook that provides imperative controls: `start`, `reset`, `clear`, and an `isPending` state. Allows conditionally enabling the timeout.
-
-## Usage Logic
-
-Creates a timer on mount (unless `enabled: false`). The returned `start` begins the timeout, `clear` cancels it, and `reset` restarts it. `isPending` reflects whether a timeout is currently active.
-
-## Type Signatures
-
-```ts
-interface UseTimeoutControls {
-  start: () => void;
-  reset: () => void;
-  clear: () => void;
-  isPending: boolean;
-}
-
-function useTimeout(
-  callback: () => void,
-  delay: number,
-  options?: { enabled?: boolean }
-): UseTimeoutControls;
-```
-
-## Example Code
-
-```tsx
-import { useTimeout } from "@musecat/functionkit";
-
-function AutoDismiss({ onDismiss }: { onDismiss: () => void }) {
-  const { reset, isPending } = useTimeout(onDismiss, 5000);
-
-  return (
-    <div onMouseEnter={reset}>
-      Dismissing in {isPending ? "..." : "done"}
-    </div>
-  );
-}
-```

package/.agents/references/hooks/useToggleState.md

@@ -1,39 +0,0 @@
-# useToggleState
-
-## Purpose
-
-Simplifies boolean state management with explicit `setTrue`, `setFalse`, and `toggle` setters. A more expressive alternative to raw `useState(false)`.
-
-## Usage Logic
-
-Wraps `useState<boolean>` with named setter functions. Accepts an optional initial value (default `false`).
-
-## Type Signature
-
-```ts
-function useToggleState(
-  initial?: boolean | (() => boolean)
-): {
-  value: boolean;
-  setTrue: () => void;
-  setFalse: () => void;
-  toggle: () => void;
-};
-```
-
-## Example Code
-
-```tsx
-import { useToggleState } from "@musecat/functionkit";
-
-function Collapsible({ children }: { children: React.ReactNode }) {
-  const { value: isOpen, toggle } = useToggleState(false);
-
-  return (
-    <div>
-      <button onClick={toggle}>{isOpen ? "Hide" : "Show"}</button>
-      {isOpen && children}
-    </div>
-  );
-}
-```

package/.agents/references/hooks/useViewportHeight.md

@@ -1,26 +0,0 @@
-# useViewportHeight
-
-## Purpose
-
-Returns the current viewport height in pixels, reacting to resize events. Uses `visualViewport` when available, falling back to `window.innerHeight`.
-
-## Usage Logic
-
-Subscribes to `visualViewport.resize` (or `window.resize`) events and updates state accordingly. Debounces updates to avoid excessive re-renders during rapid resize.
-
-## Type Signature
-
-```ts
-function useViewportHeight(): number;
-```
-
-## Example Code
-
-```tsx
-import { useViewportHeight } from "@musecat/functionkit";
-
-function FullHeight() {
-  const height = useViewportHeight();
-  return <div style={{ height }}>Content</div>;
-}
-```

package/.agents/references/hooks/useViewportMatch.md

@@ -1,32 +0,0 @@
-# useViewportMatch
-
-## Purpose
-
-Returns whether the current viewport matches a CSS media query string. Reactive — updates when the match status changes (e.g., window resize).
-
-## Usage Logic
-
-Uses `window.matchMedia` to create a `MediaQueryList`, then subscribes to its `change` event to track live changes.
-
-## Type Signature
-
-```ts
-function useViewportMatch(query: string): boolean;
-```
-
-| Parameter | Type | Example |
-|-----------|------|---------|
-| `query` | `string` | `"(min-width: 768px)"`, `"(prefers-color-scheme: dark)"` |
-
-## Example Code
-
-```tsx
-import { useViewportMatch } from "@musecat/functionkit";
-
-function ResponsiveComponent() {
-  const isDesktop = useViewportMatch("(min-width: 1024px)");
-  const isDark = useViewportMatch("(prefers-color-scheme: dark)");
-
-  return <div className={isDesktop ? "desktop" : "mobile"}>...</div>;
-}
-```

package/.agents/references/utils/browserStorage.md

@@ -1,41 +0,0 @@
-# browserStorage
-
-## Purpose
-
-Provides typed JSON-serialized read/write/delete access to `localStorage` and `sessionStorage`. Gracefully handles missing `window` (SSR) by returning `null` silently.
-
-## Usage Logic
-
-Each function wraps the native Storage API with `JSON.stringify`/`JSON.parse`. SSR-safe at the call site — checks for `typeof window` before accessing storage.
-
-## Type Signatures
-
-```ts
-// localStorage
-function getLocalStorage<T = string>(key: string): T | null;
-function updateLocalStorage<T>(key: string, value: T): void;
-function removeLocalStorage(key: string): void;
-
-// sessionStorage
-function getSessionStorage<T = string>(key: string): T | null;
-function updateSessionStorage<T>(key: string, value: T): void;
-function removeSessionStorage(key: string): void;
-```
-
-## Example Code
-
-```tsx
-import { getLocalStorage, updateLocalStorage, removeLocalStorage } from "@musecat/functionkit";
-
-function useDraft() {
-  const draft = getLocalStorage<{ text: string }>("draft") ?? { text: "" };
-
-  const saveDraft = (text: string) => {
-    updateLocalStorage("draft", { text });
-  };
-
-  const clearDraft = () => removeLocalStorage("draft");
-
-  return { draft, saveDraft, clearDraft };
-}
-```