@musecat/functionkit 1.0.1 → 1.1.0

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

@@ -0,0 +1,41 @@
+# 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>;
+}
+```
+
+## Trade-off
+
+The `options` object is used as a `useMemo` dependency. If you pass an inline object (`{ threshold: 0.5 }`) on every render, the `IntersectionObserver` is recreated each time. Memoize options with `useMemo` or define them outside the component for stable references.

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

@@ -0,0 +1,44 @@
+# 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>;
+}
+```
+
+## Trade-off
+
+Internally uses `usePreservedCallback` to stabilize the callback. The callback always reflects the latest closure, but during the render-to-effect gap a stale version could theoretically fire. In practice this is never an issue since interval callbacks fire asynchronously after paint. See `usePreservedCallback` trade-off for details.

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

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

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

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

@@ -0,0 +1,37 @@
+# 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>;
+}
+```
+
+## 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/.agents/references/hooks/usePreservedReference.md

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

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

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

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

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

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

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

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

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

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

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