@pol-studios/hooks 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,357 @@
+# @pol-studios/hooks
+
+> React hooks for POL applications
+
+A comprehensive collection of React hooks for state management, storage, device detection, network status, file handling, toasts, forms, and debugging.
+
+## Installation
+
+```bash
+pnpm add @pol-studios/hooks
+```
+
+## Peer Dependencies
+
+```bash
+pnpm add react react-dom @pol-studios/features @pol-studios/utils
+```
+
+## Quick Start
+
+```tsx
+import {
+  useLocalStorage,
+  useOnline,
+  useMobile,
+  useToast,
+} from "@pol-studios/hooks";
+
+function MyComponent() {
+  // Persist state to localStorage
+  const [theme, setTheme] = useLocalStorage("theme", "light");
+
+  // Check network status
+  const isOnline = useOnline();
+
+  // Check device type
+  const isMobile = useMobile();
+
+  // Show toast notifications
+  const { toast } = useToast();
+
+  return (
+    <button onClick={() => toast({ title: "Hello!" })}>
+      Show Toast
+    </button>
+  );
+}
+```
+
+## Subpath Exports
+
+| Path | Description |
+|------|-------------|
+| `@pol-studios/hooks` | All exports |
+| `@pol-studios/hooks/state` | State management hooks (usePartialState, useQueuedState, useDelayedValue) |
+| `@pol-studios/hooks/scroll` | Scroll hooks (useScrollPosition, useScrollDirection, useHideOnScroll) |
+| `@pol-studios/hooks/storage` | Storage hooks (useLocalStorage, useSessionStorage, useIndexedDB) |
+| `@pol-studios/hooks/device` | Device hooks (useDevice, useMobile, useTheme, useDimensions) |
+| `@pol-studios/hooks/network` | Network hooks (useOnline, useNetworkStatus, useMutationQueue) |
+| `@pol-studios/hooks/lifecycle` | Lifecycle hooks (useMounted, useAfterMount, useOnScreen) |
+| `@pol-studios/hooks/file` | File hooks (useFileDialog, useDownload) |
+| `@pol-studios/hooks/toast` | Toast hooks (useToast, toast) |
+| `@pol-studios/hooks/form` | Form hooks (OnValueChangedContext) |
+| `@pol-studios/hooks/debug` | Debug hooks (useRenderCount, useStateTracker) |
+| `@pol-studios/hooks/utils` | Utilities (withComponentMemo, isDevEnvironment) |
+
+## API Reference
+
+### State Hooks
+
+#### usePartialState
+Partial state updates without spreading.
+
+```tsx
+import { usePartialState } from "@pol-studios/hooks/state";
+
+const [state, updateState] = usePartialState({ name: "", email: "" });
+updateState({ name: "John" }); // Only updates name, keeps email
+```
+
+#### useQueuedState
+Queue state updates for batching.
+
+```tsx
+import { useQueuedState } from "@pol-studios/hooks/state";
+
+const [state, queueUpdate, flush] = useQueuedState(initialState);
+```
+
+#### useDelayedValue
+Debounce value changes.
+
+```tsx
+import { useDelayedValue, useDelayedState } from "@pol-studios/hooks/state";
+
+const debouncedSearch = useDelayedValue(searchTerm, 300);
+const [value, setValue, debouncedValue] = useDelayedState("", 300);
+```
+
+#### useChangeTracking
+Track changes to state values.
+
+```tsx
+import { useChangeTracking, ChangeTrackingProvider } from "@pol-studios/hooks/state";
+
+const { hasChanges, trackChange, resetChanges } = useChangeTracking();
+```
+
+### Storage Hooks
+
+#### useLocalStorage
+Persist state to localStorage.
+
+```tsx
+import { useLocalStorage, useLocalStorageState } from "@pol-studios/hooks/storage";
+
+const [value, setValue] = useLocalStorage("key", defaultValue);
+```
+
+#### useSessionStorage
+Persist state to sessionStorage.
+
+```tsx
+import { useSessionStorage } from "@pol-studios/hooks/storage";
+
+const [value, setValue] = useSessionStorage("key", defaultValue);
+```
+
+#### useIndexedDB
+Interact with IndexedDB.
+
+```tsx
+import { useIndexedDB, IndexedDBService } from "@pol-studios/hooks/storage";
+
+const db = useIndexedDB({ dbName: "myDb", storeName: "myStore" });
+await db.set("key", value);
+const data = await db.get("key");
+```
+
+### Device Hooks
+
+#### useMobile
+Detect mobile devices.
+
+```tsx
+import { useMobile, useIsMobile } from "@pol-studios/hooks/device";
+
+const isMobile = useMobile();
+```
+
+#### useTheme
+Detect and manage theme preference.
+
+```tsx
+import { useTheme, useThemeDetector } from "@pol-studios/hooks/device";
+
+const theme = useThemeDetector(); // "light" | "dark"
+```
+
+#### useDimensions
+Track element dimensions.
+
+```tsx
+import { useDimensions, useWindowDimensions } from "@pol-studios/hooks/device";
+
+const [ref, dimensions] = useDimensions();
+const { width, height } = useWindowDimensions();
+```
+
+#### useReducedMotion
+Respect user motion preferences.
+
+```tsx
+import { useReducedMotion } from "@pol-studios/hooks/device";
+
+const prefersReducedMotion = useReducedMotion();
+```
+
+### Network Hooks
+
+#### useOnline
+Check online status.
+
+```tsx
+import { useOnline, useNetworkStatus } from "@pol-studios/hooks/network";
+
+const isOnline = useOnline();
+const { online, effectiveType } = useNetworkStatus();
+```
+
+#### useMutationQueue
+Queue mutations for offline support.
+
+```tsx
+import { useMutationQueue } from "@pol-studios/hooks/network";
+
+const { queue, addMutation, processMutations } = useMutationQueue();
+```
+
+### Scroll Hooks
+
+#### useScrollPosition
+Track scroll position.
+
+```tsx
+import { useScrollPosition, useScrollDirection } from "@pol-studios/hooks/scroll";
+
+const scrollY = useScrollPosition();
+const direction = useScrollDirection(); // "up" | "down"
+```
+
+#### useHideOnScroll
+Hide elements on scroll down.
+
+```tsx
+import { useHideOnScroll } from "@pol-studios/hooks/scroll";
+
+const isHidden = useHideOnScroll();
+```
+
+### Lifecycle Hooks
+
+#### useMounted
+Check if component is mounted.
+
+```tsx
+import { useMounted, useAfterMount } from "@pol-studios/hooks/lifecycle";
+
+const isMounted = useMounted();
+
+useAfterMount(() => {
+  // Runs after first render
+});
+```
+
+#### useOnScreen
+Detect element visibility.
+
+```tsx
+import { useOnScreen } from "@pol-studios/hooks/lifecycle";
+
+const [ref, isVisible] = useOnScreen({ threshold: 0.5 });
+```
+
+### File Hooks
+
+#### useFileDialog
+Open file picker dialog.
+
+```tsx
+import { useFileDialog } from "@pol-studios/hooks/file";
+
+const { openDialog, files } = useFileDialog({ accept: "image/*" });
+```
+
+#### useDownload
+Download files programmatically.
+
+```tsx
+import { useDownload, useDownloadApiFile } from "@pol-studios/hooks/file";
+
+const download = useDownload();
+download(blob, "filename.pdf");
+```
+
+### Toast Hooks
+
+#### useToast
+Show toast notifications.
+
+```tsx
+import { useToast, toast } from "@pol-studios/hooks/toast";
+
+const { toast: showToast, dismiss } = useToast();
+
+// Imperative API
+toast({ title: "Success!", description: "Operation completed." });
+
+// Hook API
+showToast({ title: "Hello", variant: "success" });
+```
+
+### Form Hooks
+
+#### OnValueChangedContext
+Track form value changes.
+
+```tsx
+import {
+  OnValueChangedContextProvider,
+  OnValueChangedContext,
+} from "@pol-studios/hooks/form";
+
+<OnValueChangedContextProvider onTrigger={handleFieldChange}>
+  <MyForm />
+</OnValueChangedContextProvider>
+```
+
+### Debug Hooks
+
+#### useRenderCount
+Count component renders (dev only).
+
+```tsx
+import { useRenderCount, useStateTracker } from "@pol-studios/hooks/debug";
+
+useRenderCount("MyComponent"); // Logs render count
+
+useStateTracker(state, "myState"); // Logs state changes
+```
+
+### Utilities
+
+#### withComponentMemo
+HOC for memoizing components.
+
+```tsx
+import { withComponentMemo } from "@pol-studios/hooks/utils";
+
+const MemoizedComponent = withComponentMemo(MyComponent);
+```
+
+## TypeScript Types
+
+```tsx
+import type {
+  // Toast types
+  ToasterToast,
+  Toast,
+  ToastState,
+  ToastAction,
+
+  // Network types
+  NetworkStatus,
+  OnlineStatus,
+  QueuedMutation,
+
+  // Storage types
+  StorageService,
+  IndexDbService,
+  DBOptions,
+
+  // Form types
+  ValueChangeTrigger,
+  OnValueChangedContextValue,
+} from "@pol-studios/hooks";
+```
+
+## Related Packages
+
+- [@pol-studios/utils](../utils) - Utility functions
+- [@pol-studios/features](../features) - Feature modules
+- [@pol-studios/ui](../ui) - UI components
+
+## License
+
+UNLICENSED

package/dist/_utils/index.d.ts

@@ -0,0 +1,54 @@
+import React__default, { ComponentType } from 'react';
+
+/**
+ * Checks if a value is usable (not undefined, not null, and not NaN if it's a number)
+ */
+declare function isUsable(value: any): value is {};
+
+/**
+ * Checks if the current environment is development mode
+ */
+declare function isDevEnvironment(): boolean;
+/**
+ * Alias for isDevEnvironment
+ */
+declare function isDev(): boolean;
+
+/**
+ * JSON reviver function that converts ISO date strings to Moment objects
+ */
+declare function dateReviver(key: any, value: any): any;
+/**
+ * JSON reviver function that converts ISO date strings to native Date objects
+ */
+declare function parseWithDate(key: any, value: any): any;
+
+/**
+ * Downloads a file using POST request
+ */
+declare function getFilePost(url: string, fileName: string, queryParams: string): Promise<void>;
+/**
+ * Downloads a file using GET request
+ */
+declare function getFile(url: string | Request, fileName: string): Promise<void>;
+/**
+ * Downloads text content as a file
+ */
+declare function downloadFile(text: string): Promise<void>;
+
+/**
+ * Checks if the app is running as a PWA (Progressive Web App)
+ */
+declare function isPwaLaunched(): boolean;
+/**
+ * Checks if the current device is an iPhone
+ */
+declare function isIphone(): boolean;
+/**
+ * Checks if the device has a camera available
+ */
+declare function hasCameraAsync(): Promise<boolean>;
+
+declare function withComponentMemo<T extends ComponentType<any>>(Component: T, compareFn?: (prevProps: React__default.ComponentProps<T>, nextProps: React__default.ComponentProps<T>) => boolean): T;
+
+export { dateReviver, downloadFile, getFile, getFilePost, hasCameraAsync, isDev, isDevEnvironment, isIphone, isPwaLaunched, isUsable, parseWithDate, withComponentMemo };

package/dist/debug/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Debug hook that tracks how many times a component has rendered.
+ * Useful for debugging unnecessary re-renders.
+ *
+ * @returns The current render count
+ */
+declare const useRenderCount: () => number;
+
+/**
+ * Debug hook that tracks how many times a specific hook's value has changed.
+ * Useful for debugging when a dependency is causing unnecessary updates.
+ *
+ * @param hook - The hook value to track changes on
+ * @returns The number of times the hook value has changed
+ */
+declare const useRenderHookCount: <T>(hook: T) => number;
+
+/**
+ * Debug hook that logs state changes to the console.
+ * Only runs in development environment.
+ *
+ * @param state - The state value to track
+ */
+declare function useStateTracker<T>(state: T): void;
+
+/**
+ * Debug hook that provides useState with detailed logging of value changes.
+ * Logs the old value, new value, and stack trace when state changes.
+ *
+ * @param initialValue - Initial state value
+ * @param hookName - Name to identify this state in logs
+ * @returns Tuple of [state, setState]
+ */
+declare function useTrackedState<T>(initialValue: T, hookName: string): [T, (value: React.SetStateAction<T>) => void];
+
+export { useRenderCount, useRenderHookCount, useStateTracker, useTrackedState };

package/dist/device/index.d.ts

@@ -0,0 +1,139 @@
+import { RefObject } from 'react';
+
+interface DeviceInfo {
+    isMobile: boolean;
+    width: number;
+    height: number;
+    isPwa: boolean;
+}
+/**
+ * Hook to get device information including viewport size, mobile status, and PWA status.
+ * Combines useWindowDimensions, useMobile, and isPwaLaunched for a complete device context.
+ *
+ * @returns Object containing isMobile, width, height, and isPwa status
+ *
+ * @example
+ * ```tsx
+ * const { isMobile, width, height, isPwa } = useDevice();
+ *
+ * if (isPwa) {
+ *   // Show PWA-specific features
+ * }
+ * ```
+ */
+declare function useDevice(): DeviceInfo;
+
+/**
+ * Hook to detect if the current viewport is mobile-sized.
+ * Uses a media query listener for responsive updates.
+ *
+ * @returns true if viewport width is less than 768px, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMobile();
+ *
+ * return isMobile ? <MobileNav /> : <DesktopNav />;
+ * ```
+ */
+declare function useMobile(): boolean;
+/**
+ * @deprecated Use `useMobile` instead. This alias is provided for backwards compatibility.
+ */
+declare const useIsMobile: typeof useMobile;
+
+/**
+ * Hook to detect and apply the user's preferred color scheme (dark/light mode).
+ * Automatically listens for system preference changes and updates the document.
+ *
+ * @returns true if dark theme is active, false for light theme
+ *
+ * @example
+ * ```tsx
+ * const isDarkTheme = useTheme();
+ *
+ * return (
+ *   <div className={isDarkTheme ? 'bg-gray-900' : 'bg-white'}>
+ *     Content
+ *   </div>
+ * );
+ * ```
+ */
+declare function useTheme(): boolean;
+/**
+ * @deprecated Use `useTheme` instead. This alias is provided for backwards compatibility.
+ */
+declare const useThemeDetector: typeof useTheme;
+
+interface Dimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Hook to get the dimensions of a DOM element.
+ *
+ * Note: This is a naive implementation - for production use, consider attaching
+ * a resize observer. Also uses ref/effect instead of state/layoutEffect,
+ * so dimensions won't be available on initial render.
+ *
+ * @param ref - React ref to the element to measure
+ * @returns Object containing width and height of the element
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { width, height } = useDimensions(containerRef);
+ *
+ * return (
+ *   <div ref={containerRef}>
+ *     Size: {width}x{height}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useDimensions(ref: RefObject<HTMLElement>): Dimensions;
+
+interface WindowDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Hook to get the current window dimensions.
+ * Updates automatically when the window is resized.
+ *
+ * @returns Object containing current window width and height
+ *
+ * @example
+ * ```tsx
+ * const { width, height } = useWindowDimensions();
+ *
+ * return <div>Window size: {width}x{height}</div>;
+ * ```
+ */
+declare function useWindowDimensions(): WindowDimensions;
+
+/**
+ * Hook to detect if the user prefers reduced motion.
+ * Checks both the CSS media query and localStorage preference (if set).
+ *
+ * @returns true if reduced motion is preferred, false otherwise
+ *
+ * @example
+ * ```tsx
+ * const prefersReducedMotion = useReducedMotion();
+ *
+ * <motion.div
+ *   animate={{ opacity: prefersReducedMotion ? 1 : 0 }}
+ *   transition={{ duration: prefersReducedMotion ? 0 : 0.3 }}
+ * />
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+/**
+ * Set a user preference for reduced motion (overrides system preference).
+ *
+ * @param enabled - true to enable reduced motion, false to disable, null to use system preference
+ */
+declare function setReducedMotionPreference(enabled: boolean | null): void;
+
+export { setReducedMotionPreference, useDevice, useDimensions, useIsMobile, useMobile, useReducedMotion, useTheme, useThemeDetector, useWindowDimensions };

package/dist/file/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook that provides a function to open a file dialog programmatically.
+ *
+ * @returns Object containing openFileDialog function
+ */
+declare function useFileDialog(): {
+    openFileDialog: () => Promise<FileList>;
+};
+
+interface DownloadOptions {
+    url: string;
+    fileName: string;
+    queryParams: string;
+}
+/**
+ * Hook that provides a function to download files via POST request.
+ *
+ * @returns Download function
+ */
+declare function useDownload(): ({ url, fileName, queryParams }: DownloadOptions) => Promise<void>;
+/**
+ * @deprecated Use useDownload instead
+ */
+declare const useDownloadApiFile: typeof useDownload;
+
+export { useDownload, useDownloadApiFile, useFileDialog };

package/dist/form/index.d.ts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+type ValueChangeTrigger = "change" | "blur" | number;
+interface OnValueChangedContextValue {
+    trigger: ValueChangeTrigger;
+}
+declare const OnValueChangedContext: React.Context<OnValueChangedContextValue>;
+interface OnValueChangedContextProviderProps {
+    children: ReactNode;
+    trigger: ValueChangeTrigger;
+}
+declare const OnValueChangedContextProvider: ({ children, trigger, }: OnValueChangedContextProviderProps) => react_jsx_runtime.JSX.Element;
+/** @deprecated Use OnValueChangedContext instead */
+declare const OnValueChangedTriggerContext: React.Context<OnValueChangedContextValue>;
+/** @deprecated Use OnValueChangedContextProvider instead */
+declare const OnValueChangedTriggerContextProvider: ({ children, trigger, }: OnValueChangedContextProviderProps) => react_jsx_runtime.JSX.Element;
+
+export { OnValueChangedContext, OnValueChangedContextProvider, type OnValueChangedContextProviderProps, type OnValueChangedContextValue, OnValueChangedTriggerContext, OnValueChangedTriggerContextProvider, type ValueChangeTrigger };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { ChangeTrackingContext, ChangeTrackingProvider, useChangeTracking, useDelayedState, useDelayedValue, useForceUpdate, usePartialState, useQueuedState } from './state/index.js';
+export { DBOptions, IndexedDBService as IndexDb, IndexDbProvider, IndexDbService, IndexedDBService, LocalStorageProvider, LocalStorageService, StorageService, indexDbContext, localStorageContext, useIndexedDB as useIndexDbService, useIndexedDB, useLocalStorage, useLocalStorageService, useLocalStorageState, useQueuedLocalStorage, useQueuedLocalStorageState, useSessionStorage, useSessionStorageState } from './storage/index.js';
+export { useAfterMountedEffect as useAfterMount, useAfterMountedEffect, useMounted, useOnScreen } from './lifecycle/index.js';
+export { setReducedMotionPreference, useDevice, useDimensions, useIsMobile, useMobile, useReducedMotion, useTheme, useThemeDetector, useWindowDimensions } from './device/index.js';
+export { useDownload, useDownloadApiFile, useFileDialog } from './file/index.js';
+export { OnValueChangedContext, OnValueChangedContextProvider, OnValueChangedContextProviderProps, OnValueChangedContextValue, OnValueChangedTriggerContext, OnValueChangedTriggerContextProvider, ValueChangeTrigger } from './form/index.js';
+export { ActionType, Toast, ToastAction, ToastState, ToasterToast, actionTypes, reducer, toast, useToast } from './toast/index.js';
+export { useHideOnScroll, useHidingOnScroll, useScrollDirection, useScrollPosition, useScrollRestoration } from './scroll/index.js';
+export { NetworkStatus, NetworkStatus as OnlineStatus, QueuedMutation, useMutationQueue, useNetworkStatus, useOnline } from './network/index.js';
+export { useRenderCount, useRenderHookCount, useStateTracker, useTrackedState } from './debug/index.js';
+export { dateReviver, downloadFile, getFile, getFilePost, hasCameraAsync, isDev, isDevEnvironment, isIphone, isPwaLaunched, isUsable, parseWithDate, withComponentMemo } from './_utils/index.js';
+export { CommentProvider as CommentSectionProvider, FilterProvider, genId, getComparisonOptions, getDefaultCondition, getDefaultValue, useComments as useCommentSection, useFilterContext, useOrderManager as useOrderHintOld } from '@pol-studios/features';
+import 'react';
+import 'react/jsx-runtime';

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,22 @@
+import React__default from 'react';
+
+/**
+ * Hook that returns a function to check if the component is currently mounted.
+ * Useful for avoiding state updates after unmount in async operations.
+ *
+ * @returns A function that returns true if mounted, false otherwise
+ */
+declare function useMounted(): () => boolean;
+
+declare function useAfterMountedEffect(effect: React__default.EffectCallback, deps?: React__default.DependencyList): void;
+
+/**
+ * Hook that detects if an element is visible in the viewport using IntersectionObserver.
+ *
+ * @param ref - React ref to the element to observe
+ * @param rootMargin - Margin around the root (default: "0px")
+ * @returns boolean indicating if element is visible
+ */
+declare function useOnScreen(ref: React.RefObject<HTMLElement>, rootMargin?: string): boolean;
+
+export { useAfterMountedEffect as useAfterMount, useAfterMountedEffect, useMounted, useOnScreen };

package/dist/network/index.d.ts

@@ -0,0 +1,79 @@
+interface NetworkStatus {
+    isOnline: boolean;
+    isOffline: boolean;
+    wasOffline: boolean;
+}
+/**
+ * Hook to track network status across platforms.
+ * Works with TanStack Query's onlineManager for consistent offline handling.
+ *
+ * @returns Object with isOnline, isOffline, and wasOffline status
+ *
+ * @example
+ * ```tsx
+ * const { isOnline, isOffline, wasOffline } = useOnline();
+ *
+ * if (isOffline) {
+ *   return <OfflineBanner />;
+ * }
+ *
+ * if (wasOffline) {
+ *   // Show "back online" notification
+ * }
+ * ```
+ */
+declare function useOnline(): NetworkStatus;
+/**
+ * @deprecated Use `useOnline` instead. This alias is provided for backwards compatibility.
+ */
+declare const useNetworkStatus: typeof useOnline;
+
+interface QueuedMutation {
+    id: string;
+    mutationKey: string[];
+    mutationFn: () => Promise<any>;
+    variables: any;
+    timestamp: number;
+    retryCount: number;
+    error?: Error;
+}
+/**
+ * Hook to manage offline mutation queue.
+ * Queues mutations when offline and automatically retries when back online.
+ *
+ * Note: Currently stores mutations in memory only. Functions cannot be serialized,
+ * so mutations are lost on page refresh. Future enhancement: store mutation parameters
+ * and recreate mutations on retry.
+ *
+ * @returns Object with queue management functions and state
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   queueMutation,
+ *   queuedMutations,
+ *   queueCount,
+ *   clearQueue
+ * } = useMutationQueue();
+ *
+ * // Queue a mutation for offline execution
+ * queueMutation(
+ *   ['updateUser', userId],
+ *   () => api.updateUser(userId, data),
+ *   data
+ * );
+ *
+ * // Show pending count
+ * <Badge>{queueCount} pending</Badge>
+ * ```
+ */
+declare function useMutationQueue(): {
+    queuedMutations: QueuedMutation[];
+    queueMutation: (mutationKey: string[], mutationFn: () => Promise<any>, variables: any) => void;
+    removeQueuedMutation: (id: string) => void;
+    clearQueue: () => void;
+    processQueue: () => Promise<void>;
+    queueCount: number;
+};
+
+export { type NetworkStatus, type NetworkStatus as OnlineStatus, type QueuedMutation, useMutationQueue, useNetworkStatus, useOnline };

package/dist/scroll/index.d.ts

@@ -0,0 +1,101 @@
+import React__default, { RefObject } from 'react';
+
+interface ScrollPosition {
+    scrollY: number;
+    scrollHeight: number;
+}
+/**
+ * Hook to track scroll position of an element or the window.
+ *
+ * @param elementRef - Optional ref to a scrollable element. If not provided, tracks window scroll.
+ * @returns Object containing current scrollY position and total scrollHeight
+ *
+ * @example
+ * ```tsx
+ * // Track window scroll
+ * const { scrollY, scrollHeight } = useScrollPosition();
+ *
+ * // Track element scroll
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { scrollY, scrollHeight } = useScrollPosition(containerRef);
+ * ```
+ */
+declare function useScrollPosition(elementRef?: RefObject<HTMLElement>): ScrollPosition;
+
+/**
+ * Hook to detect the user's scroll direction.
+ *
+ * @param elementRef - Ref to the scrollable element to monitor
+ * @param threshold - Scroll position threshold for direction detection
+ * @returns true if user is scrolling up, false if scrolling down
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const isScrollingUp = useScrollDirection(containerRef, 100);
+ *
+ * return (
+ *   <div ref={containerRef}>
+ *     <header className={isScrollingUp ? 'visible' : 'hidden'}>
+ *       Navigation
+ *     </header>
+ *   </div>
+ * );
+ * ```
+ */
+declare function useScrollDirection(elementRef: RefObject<HTMLElement>, threshold: number): boolean;
+
+/**
+ * Hook to save and restore scroll position using sessionStorage.
+ * Useful for maintaining scroll position when navigating away and returning to a page.
+ *
+ * @param scrollAreaId - Unique identifier for this scroll area (used as storage key)
+ * @param ref - Optional ref to a scrollable element. If not provided, uses window scroll.
+ * @returns The restored scroll position (or NaN if none was saved)
+ *
+ * @example
+ * ```tsx
+ * // Restore window scroll
+ * useScrollRestoration("my-page");
+ *
+ * // Restore element scroll
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * useScrollRestoration("my-list", containerRef);
+ * ```
+ */
+declare function useScrollRestoration(scrollAreaId?: string, ref?: React__default.RefObject<any>): number;
+
+interface UseHideOnScrollProps {
+    height: number;
+    scrollRef?: React.MutableRefObject<HTMLElement>;
+    initialPercentVisible?: number;
+}
+/**
+ * Hook to create a hide-on-scroll effect, typically used for headers/navigation.
+ * Returns the percent visibility (0-1) that can be used to animate the element.
+ *
+ * @param props.height - The height of the element being hidden
+ * @param props.scrollRef - Optional ref to a scrollable element. Uses window if not provided.
+ * @param props.initialPercentVisible - Initial visibility (default: 1, fully visible)
+ * @returns Percent visible from 0 to 1
+ *
+ * @example
+ * ```tsx
+ * const percentVisible = useHideOnScroll({ height: 64 });
+ *
+ * return (
+ *   <motion.header
+ *     style={{ transform: `translateY(${(1 - percentVisible) * -100}%)` }}
+ *   >
+ *     Navigation
+ *   </motion.header>
+ * );
+ * ```
+ */
+declare function useHideOnScroll({ height, scrollRef, initialPercentVisible }: UseHideOnScrollProps): number;
+/**
+ * @deprecated Use `useHideOnScroll` instead. This alias is provided for backwards compatibility.
+ */
+declare const useHidingOnScroll: typeof useHideOnScroll;
+
+export { useHideOnScroll, useHidingOnScroll, useScrollDirection, useScrollPosition, useScrollRestoration };

package/dist/state/index.d.ts

@@ -0,0 +1,41 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare function usePartialState<T>(initialState: T): {
+    state: T;
+    patch: (newProps: Partial<T>) => void;
+    setState: React$1.Dispatch<React$1.SetStateAction<T>>;
+};
+
+declare function useQueuedState<T>(initialState: T): [
+    T,
+    (updateFn: React.SetStateAction<T>) => void
+];
+
+declare function useDelayedValue<T>(value: T, delayInMs: number): T;
+/** @deprecated Use useDelayedValue instead */
+declare const useDelayedState: typeof useDelayedValue;
+
+declare function useChangeTracking<T>(initialValue: T): {
+    initialValue: T;
+    update: (newProps: Partial<T>) => void;
+    value: T;
+    propertiesChanged: Set<string>;
+};
+
+declare function useForceUpdate(): () => void;
+
+interface ChangeTrackingContextValue {
+    initialValue: any;
+    value: any;
+    onChange: (newValue: Partial<any>) => void;
+    propertiesChanged: Set<any>;
+}
+declare const ChangeTrackingContext: React__default.Context<ChangeTrackingContextValue>;
+declare function ChangeTrackingProvider({ children, initialValue }: {
+    children: React__default.ReactNode;
+    initialValue?: any;
+}): react_jsx_runtime.JSX.Element;
+
+export { ChangeTrackingContext, ChangeTrackingProvider, useChangeTracking, useDelayedState, useDelayedValue, useForceUpdate, usePartialState, useQueuedState };

package/dist/storage/index.d.ts

@@ -0,0 +1,86 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default, { ReactNode } from 'react';
+
+declare function useLocalStorage<T>(key: string, initialValue?: T | (() => T) | undefined): [T | undefined, (value: React.SetStateAction<T>) => void, boolean];
+/** @deprecated Use useLocalStorage instead */
+declare const useLocalStorageState: typeof useLocalStorage;
+
+declare function useSessionStorage<T>(key: string, initialValue?: T): [T | undefined, React.Dispatch<React.SetStateAction<T | undefined>>];
+/** @deprecated Use useSessionStorage instead */
+declare const useSessionStorageState: typeof useSessionStorage;
+
+interface StorageService {
+    getItem<T>(key: string): Promise<T | null>;
+    setItem<T>(key: string, value: T): Promise<void>;
+    removeItem(key: string): void;
+    addItemChangeListener(key: string, handler: (event: {
+        key: string;
+        newValue: string;
+    }) => any): any;
+    removeItemChangeListener(key: string, handler: any): any;
+}
+declare const localStorageContext: React__default.Context<StorageService>;
+declare function LocalStorageProvider({ children, value, }: {
+    children: ReactNode;
+    value: StorageService;
+}): react_jsx_runtime.JSX.Element;
+interface IndexDbService {
+    getItem<T = any>(key: string): Promise<T | null>;
+    setItem<T = any>(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+}
+declare const storeNames$1: readonly ["cached-urls", "metadata"];
+type PolStoreName$1 = (typeof storeNames$1)[keyof typeof storeNames$1] & string;
+interface DBOptions$1 {
+    dbName: string;
+    storeName: PolStoreName$1;
+}
+declare const indexDbContext: React__default.Context<{
+    services: Map<DBOptions$1, IndexDbService>;
+}>;
+declare function IndexDbProvider({ children, value, }: {
+    children: ReactNode;
+    value: Map<DBOptions$1, IndexDbService>;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useIndexedDB(options: DBOptions$1): IndexDbService;
+
+declare function useQueuedLocalStorage<T>(storageKey: string, initialState: T): [T, (updateFn: React.SetStateAction<T>) => void, boolean];
+/** @deprecated Use useQueuedLocalStorage instead */
+declare const useQueuedLocalStorageState: typeof useQueuedLocalStorage;
+
+declare function useLocalStorageService(): StorageService;
+
+declare class LocalStorageService implements StorageService {
+    constructor();
+    addItemChangeListener(key: string, handler: (event: {
+        key: string;
+        newValue: string;
+    }) => any): () => void;
+    removeItemChangeListener(key: string, handler: any): void;
+    setItem<T>(key: string, value: T): Promise<void>;
+    getItem<T>(key: string): Promise<T | null>;
+    removeItem(key: string): void;
+}
+
+interface DBOptions<T> {
+    dbName: string;
+    storeName: PolStoreName;
+}
+declare const storeNames: readonly ["cached-urls", "metadata"];
+type PolStoreName = ((typeof storeNames)[keyof typeof storeNames]) & string;
+declare class IndexedDBService<T> implements IndexDbService {
+    private dbName;
+    private storeName;
+    private db;
+    constructor(options: DBOptions<T>);
+    private openDB;
+    private getDB;
+    setItem<T>(key: string, record: T): Promise<void>;
+    getItem<T = any>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+}
+
+export { type DBOptions$1 as DBOptions, IndexedDBService as IndexDb, IndexDbProvider, type IndexDbService, IndexedDBService, LocalStorageProvider, LocalStorageService, type StorageService, indexDbContext, localStorageContext, useIndexedDB, useLocalStorage, useLocalStorageService, useLocalStorageState, useQueuedLocalStorage, useQueuedLocalStorageState, useSessionStorage, useSessionStorageState };

package/dist/toast/index.d.ts

@@ -0,0 +1,48 @@
+import * as React from 'react';
+
+type ToasterToast = {
+    id: string;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    className?: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+} & React.HTMLAttributes<HTMLLIElement>;
+type Toast = Omit<ToasterToast, "id">;
+interface ToastState {
+    toasts: ToasterToast[];
+}
+declare const actionTypes: {
+    readonly ADD_TOAST: "ADD_TOAST";
+    readonly UPDATE_TOAST: "UPDATE_TOAST";
+    readonly DISMISS_TOAST: "DISMISS_TOAST";
+    readonly REMOVE_TOAST: "REMOVE_TOAST";
+};
+type ActionType = typeof actionTypes;
+type ToastAction = {
+    type: ActionType["ADD_TOAST"];
+    toast: ToasterToast;
+} | {
+    type: ActionType["UPDATE_TOAST"];
+    toast: Partial<ToasterToast>;
+} | {
+    type: ActionType["DISMISS_TOAST"];
+    toastId?: ToasterToast["id"];
+} | {
+    type: ActionType["REMOVE_TOAST"];
+    toastId?: ToasterToast["id"];
+};
+
+declare const reducer: (state: ToastState, action: ToastAction) => ToastState;
+declare function toast({ ...props }: Toast): {
+    id: string;
+    dismiss: () => void;
+    update: (props: ToasterToast) => void;
+};
+declare function useToast(): {
+    toast: typeof toast;
+    dismiss: (toastId?: string) => void;
+    toasts: ToasterToast[];
+};
+
+export { type ActionType, type Toast, type ToastAction, type ToastState, type ToasterToast, actionTypes, useToast as default, reducer, toast, useToast };

package/package.json

@@ -1,30 +1,63 @@
 {
   "name": "@pol-studios/hooks",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "React hooks for POL applications",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
-    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
-    "./state": { "import": "./dist/state/index.js", "types": "./dist/state/index.d.ts" },
-    "./scroll": { "import": "./dist/scroll/index.js", "types": "./dist/scroll/index.d.ts" },
-    "./storage": { "import": "./dist/storage/index.js", "types": "./dist/storage/index.d.ts" },
-    "./device": { "import": "./dist/device/index.js", "types": "./dist/device/index.d.ts" },
-    "./network": { "import": "./dist/network/index.js", "types": "./dist/network/index.d.ts" },
-    "./lifecycle": { "import": "./dist/lifecycle/index.js", "types": "./dist/lifecycle/index.d.ts" },
-    "./file": { "import": "./dist/file/index.js", "types": "./dist/file/index.d.ts" },
-    "./toast": { "import": "./dist/toast/index.js", "types": "./dist/toast/index.d.ts" },
-    "./form": { "import": "./dist/form/index.js", "types": "./dist/form/index.d.ts" },
-    "./debug": { "import": "./dist/debug/index.js", "types": "./dist/debug/index.d.ts" },
-    "./utils": { "import": "./dist/_utils/index.js", "types": "./dist/_utils/index.d.ts" }
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "prepublishOnly": "pnpm build"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./state": {
+      "import": "./dist/state/index.js",
+      "types": "./dist/state/index.d.ts"
+    },
+    "./scroll": {
+      "import": "./dist/scroll/index.js",
+      "types": "./dist/scroll/index.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage/index.js",
+      "types": "./dist/storage/index.d.ts"
+    },
+    "./device": {
+      "import": "./dist/device/index.js",
+      "types": "./dist/device/index.d.ts"
+    },
+    "./network": {
+      "import": "./dist/network/index.js",
+      "types": "./dist/network/index.d.ts"
+    },
+    "./lifecycle": {
+      "import": "./dist/lifecycle/index.js",
+      "types": "./dist/lifecycle/index.d.ts"
+    },
+    "./file": {
+      "import": "./dist/file/index.js",
+      "types": "./dist/file/index.d.ts"
+    },
+    "./toast": {
+      "import": "./dist/toast/index.js",
+      "types": "./dist/toast/index.d.ts"
+    },
+    "./form": {
+      "import": "./dist/form/index.js",
+      "types": "./dist/form/index.d.ts"
+    },
+    "./debug": {
+      "import": "./dist/debug/index.js",
+      "types": "./dist/debug/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/_utils/index.js",
+      "types": "./dist/_utils/index.d.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -41,10 +74,20 @@
     "lodash": "^4.17.21"
   },
   "devDependencies": {
-    "@pol-studios/features": "workspace:*",
-    "@pol-studios/utils": "workspace:*",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@pol-studios/features": "1.0.1",
+    "@pol-studios/utils": "1.0.1"
   },
-  "keywords": ["hooks", "react", "state", "storage", "toast"]
-}
+  "keywords": [
+    "hooks",
+    "react",
+    "state",
+    "storage",
+    "toast"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}