@omnitron-dev/prism 0.2.0 → 0.3.0

package/dist/use-timeout-D7U3EAtH.d.ts

@@ -1,808 +0,0 @@
-import { Breakpoint } from '@mui/material/styles';
-import { RefObject } from 'react';
-
-/**
- * Return type for useBoolean hook.
- */
-interface UseBooleanReturn {
-    /** Current boolean value */
-    value: boolean;
-    /** Set value to true */
-    onTrue: () => void;
-    /** Set value to false */
-    onFalse: () => void;
-    /** Toggle the value */
-    onToggle: () => void;
-    /** Set to specific value */
-    setValue: (value: boolean) => void;
-}
-/**
- * Hook for managing boolean state with convenient toggle methods.
- *
- * @param defaultValue - Initial boolean value (default: false)
- * @returns Boolean state and control methods
- *
- * @example
- * ```tsx
- * function Modal() {
- *   const dialog = useBoolean();
- *
- *   return (
- *     <>
- *       <Button onClick={dialog.onTrue}>Open</Button>
- *       <Dialog open={dialog.value} onClose={dialog.onFalse}>
- *         <DialogContent>...</DialogContent>
- *       </Dialog>
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Sidebar() {
- *   const { value: isCollapsed, onToggle } = useBoolean(false);
- *
- *   return (
- *     <nav style={{ width: isCollapsed ? 64 : 240 }}>
- *       <IconButton onClick={onToggle}>
- *         {isCollapsed ? <MenuIcon /> : <CloseIcon />}
- *       </IconButton>
- *     </nav>
- *   );
- * }
- * ```
- */
-declare function useBoolean(defaultValue?: boolean): UseBooleanReturn;
-
-/**
- * State updater function type.
- * Accepts partial state or a function that returns partial state.
- */
-type SetState<T extends Record<string, unknown>> = (patch: Partial<T> | ((prevState: T) => Partial<T>)) => void;
-/**
- * Return type for useSetState.
- */
-interface UseSetStateReturn<T extends Record<string, unknown>> {
-    /** Current state */
-    state: T;
-    /** Update state with partial values */
-    setState: SetState<T>;
-    /** Reset state to initial value */
-    resetState: () => void;
-}
-/**
- * useSetState - State hook with partial update support.
- * Works like React class component's setState method.
- *
- * @example
- * ```tsx
- * interface FormState {
- *   name: string;
- *   email: string;
- *   phone: string;
- * }
- *
- * function Form() {
- *   const { state, setState, resetState } = useSetState<FormState>({
- *     name: '',
- *     email: '',
- *     phone: '',
- *   });
- *
- *   return (
- *     <>
- *       <TextField
- *         value={state.name}
- *         onChange={(e) => setState({ name: e.target.value })}
- *       />
- *       <TextField
- *         value={state.email}
- *         onChange={(e) => setState({ email: e.target.value })}
- *       />
- *       <Button onClick={resetState}>Reset</Button>
- *     </>
- *   );
- * }
- * ```
- *
- * @param initialState - Initial state object
- * @returns State, setState, and resetState
- */
-declare function useSetState<T extends Record<string, unknown>>(initialState: T | (() => T)): UseSetStateReturn<T>;
-
-/**
- * Options for useMultiSelect.
- */
-interface UseMultiSelectOptions<T> {
-    /** Initial selected items */
-    initial?: T[];
-    /** Maximum selection count */
-    maxSelections?: number;
-    /** Callback when selection changes */
-    onChange?: (selected: T[]) => void;
-}
-/**
- * Return type for useMultiSelect.
- */
-interface UseMultiSelectReturn<T> {
-    /** Currently selected items */
-    selected: T[];
-    /** Number of selected items */
-    count: number;
-    /** Whether nothing is selected */
-    isEmpty: boolean;
-    /** Check if item is selected */
-    isSelected: (item: T) => boolean;
-    /** Toggle item selection */
-    toggle: (item: T) => void;
-    /** Select an item */
-    select: (item: T) => void;
-    /** Deselect an item */
-    deselect: (item: T) => void;
-    /** Select multiple items */
-    selectMany: (items: T[]) => void;
-    /** Deselect multiple items */
-    deselectMany: (items: T[]) => void;
-    /** Clear all selections */
-    clear: () => void;
-    /** Replace all selections */
-    setSelected: (items: T[]) => void;
-    /** Select all items from a list */
-    selectAll: (allItems: T[]) => void;
-    /** Check if all items are selected */
-    isAllSelected: (allItems: T[]) => boolean;
-    /** Check if some items are selected (for indeterminate state) */
-    isPartiallySelected: (allItems: T[]) => boolean;
-}
-/**
- * useMultiSelect - Multi-selection state management.
- *
- * @example
- * ```tsx
- * function UserList() {
- *   const users = ['Alice', 'Bob', 'Charlie'];
- *   const selection = useMultiSelect<string>();
- *
- *   return (
- *     <>
- *       <Checkbox
- *         checked={selection.isAllSelected(users)}
- *         indeterminate={selection.isPartiallySelected(users)}
- *         onChange={() => {
- *           if (selection.isAllSelected(users)) {
- *             selection.clear();
- *           } else {
- *             selection.selectAll(users);
- *           }
- *         }}
- *       />
- *       {users.map((user) => (
- *         <Checkbox
- *           key={user}
- *           checked={selection.isSelected(user)}
- *           onChange={() => selection.toggle(user)}
- *         />
- *       ))}
- *       <Button disabled={selection.isEmpty}>
- *         Delete ({selection.count})
- *       </Button>
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With objects and custom max
- * interface Item {
- *   id: string;
- *   name: string;
- * }
- *
- * function ItemPicker() {
- *   const items: Item[] = [...];
- *   const selection = useMultiSelect<string>({
- *     maxSelections: 5,
- *     onChange: (selected) => console.log('Selected:', selected),
- *   });
- *
- *   return items.map((item) => (
- *     <Chip
- *       key={item.id}
- *       selected={selection.isSelected(item.id)}
- *       onClick={() => selection.toggle(item.id)}
- *     >
- *       {item.name}
- *     </Chip>
- *   ));
- * }
- * ```
- *
- * @param options - Hook options
- * @returns Selection state and controls
- */
-declare function useMultiSelect<T>(options?: UseMultiSelectOptions<T>): UseMultiSelectReturn<T>;
-
-/**
- * Return type for useLocalStorage hook.
- */
-type UseLocalStorageReturn<T> = [
-    /** Current value */
-    T,
-    /** Set value (accepts value or updater function) */
-    (value: T | ((prev: T) => T)) => void,
-    /** Remove value from storage */
-    () => void
-];
-/**
- * Hook for persisting state to localStorage.
- *
- * @param key - Storage key
- * @param initialValue - Initial value (used if no stored value exists)
- * @returns Tuple of [value, setValue, removeValue]
- *
- * @example
- * ```tsx
- * function Settings() {
- *   const [theme, setTheme] = useLocalStorage('theme', 'light');
- *
- *   return (
- *     <Select
- *       value={theme}
- *       onChange={(e) => setTheme(e.target.value)}
- *     >
- *       <MenuItem value="light">Light</MenuItem>
- *       <MenuItem value="dark">Dark</MenuItem>
- *     </Select>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Counter() {
- *   const [count, setCount] = useLocalStorage('counter', 0);
- *
- *   return (
- *     <>
- *       <span>{count}</span>
- *       <Button onClick={() => setCount((prev) => prev + 1)}>
- *         Increment
- *       </Button>
- *     </>
- *   );
- * }
- * ```
- */
-declare function useLocalStorage<T>(key: string, initialValue: T): UseLocalStorageReturn<T>;
-
-/**
- * Copy state types.
- */
-type CopyState = 'idle' | 'success' | 'error';
-/**
- * Return type for useCopyToClipboard.
- */
-interface UseCopyToClipboardReturn {
-    /** Current copy state */
-    state: CopyState;
-    /** Copied text (null if not copied) */
-    copiedText: string | null;
-    /** Copy text to clipboard */
-    copy: (text: string) => Promise<boolean>;
-    /** Reset state to idle */
-    reset: () => void;
-}
-/**
- * Options for useCopyToClipboard.
- */
-interface UseCopyToClipboardOptions {
-    /** Reset to idle after this many ms (default: 2000) */
-    resetTimeout?: number;
-    /** Callback on successful copy */
-    onSuccess?: (text: string) => void;
-    /** Callback on copy error */
-    onError?: (error: Error) => void;
-}
-/**
- * useCopyToClipboard - Copy text to clipboard with state tracking.
- *
- * @example
- * ```tsx
- * function CopyButton({ text }: { text: string }) {
- *   const { state, copy } = useCopyToClipboard();
- *
- *   return (
- *     <Button onClick={() => copy(text)}>
- *       {state === 'success' ? 'Copied!' : 'Copy'}
- *     </Button>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With callback
- * function ShareLink({ url }: { url: string }) {
- *   const { state, copy } = useCopyToClipboard({
- *     onSuccess: () => enqueueSnackbar('Link copied!'),
- *     onError: (err) => enqueueSnackbar(`Failed to copy: ${err.message}`, { variant: 'error' }),
- *   });
- *
- *   return (
- *     <IconButton onClick={() => copy(url)}>
- *       {state === 'success' ? <CheckIcon /> : <CopyIcon />}
- *     </IconButton>
- *   );
- * }
- * ```
- *
- * @param options - Hook options
- * @returns Copy function and state
- */
-declare function useCopyToClipboard(options?: UseCopyToClipboardOptions): UseCopyToClipboardReturn;
-
-/**
- * Hook for debouncing a value.
- *
- * @param value - Value to debounce
- * @param delay - Debounce delay in milliseconds (default: 500)
- * @returns Debounced value
- *
- * @example
- * ```tsx
- * function SearchInput() {
- *   const [query, setQuery] = useState('');
- *   const debouncedQuery = useDebounce(query, 300);
- *
- *   useEffect(() => {
- *     if (debouncedQuery) {
- *       search(debouncedQuery);
- *     }
- *   }, [debouncedQuery]);
- *
- *   return (
- *     <TextField
- *       value={query}
- *       onChange={(e) => setQuery(e.target.value)}
- *       placeholder="Search..."
- *     />
- *   );
- * }
- * ```
- */
-declare function useDebounce<T>(value: T, delay?: number): T;
-/**
- * Hook for debouncing a callback function.
- *
- * @param callback - Function to debounce
- * @param delay - Debounce delay in milliseconds (default: 500)
- * @returns Debounced callback and cancel function
- *
- * @example
- * ```tsx
- * function AutoSave() {
- *   const [content, setContent] = useState('');
- *
- *   const { debouncedCallback: save, cancel } = useDebounceCallback(
- *     async (text: string) => {
- *       await api.saveDocument(text);
- *     },
- *     1000
- *   );
- *
- *   const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
- *     setContent(e.target.value);
- *     save(e.target.value);
- *   };
- *
- *   return <textarea value={content} onChange={handleChange} />;
- * }
- * ```
- */
-declare function useDebounceCallback<T extends (...args: never[]) => unknown>(callback: T, delay?: number): {
-    debouncedCallback: (...args: Parameters<T>) => void;
-    cancel: () => void;
-    flush: () => void;
-};
-
-/**
- * Countdown state.
- */
-interface CountdownState {
-    /** Remaining time in seconds */
-    seconds: number;
-    /** Whether countdown is running */
-    isRunning: boolean;
-    /** Whether countdown has finished */
-    isFinished: boolean;
-}
-/**
- * Countdown controls.
- */
-interface CountdownControls {
-    /** Start or resume the countdown */
-    start: () => void;
-    /** Pause the countdown */
-    pause: () => void;
-    /** Reset to initial duration */
-    reset: () => void;
-    /** Set a new duration and reset */
-    setDuration: (seconds: number) => void;
-}
-/**
- * Return type for useCountdown.
- */
-interface UseCountdownReturn extends CountdownState, CountdownControls {
-    /** Formatted time string (MM:SS or HH:MM:SS) */
-    formatted: string;
-    /** Time parts for custom formatting */
-    parts: {
-        hours: number;
-        minutes: number;
-        seconds: number;
-    };
-}
-/**
- * Options for useCountdown.
- */
-interface UseCountdownOptions {
-    /** Initial duration in seconds */
-    duration: number;
-    /** Auto-start countdown (default: false) */
-    autoStart?: boolean;
-    /** Callback when countdown finishes */
-    onComplete?: () => void;
-    /** Callback on each tick */
-    onTick?: (remaining: number) => void;
-    /** Tick interval in ms (default: 1000) */
-    interval?: number;
-}
-/**
- * useCountdown - Countdown timer hook.
- *
- * @example
- * ```tsx
- * function OTPTimer() {
- *   const { formatted, isFinished, reset } = useCountdown({
- *     duration: 60,
- *     autoStart: true,
- *     onComplete: () => console.log('Timer finished!'),
- *   });
- *
- *   return (
- *     <div>
- *       {isFinished ? (
- *         <Button onClick={reset}>Resend OTP</Button>
- *       ) : (
- *         <Typography>Resend in {formatted}</Typography>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * function QuizTimer() {
- *   const countdown = useCountdown({
- *     duration: 300, // 5 minutes
- *     onTick: (remaining) => {
- *       if (remaining === 60) {
- *         showWarning('1 minute remaining!');
- *       }
- *     },
- *     onComplete: () => submitQuiz(),
- *   });
- *
- *   return (
- *     <Box>
- *       <Typography variant="h4">{countdown.formatted}</Typography>
- *       <Button onClick={countdown.start}>Start</Button>
- *       <Button onClick={countdown.pause}>Pause</Button>
- *       <Button onClick={countdown.reset}>Reset</Button>
- *     </Box>
- *   );
- * }
- * ```
- *
- * @param options - Countdown options
- * @returns Countdown state and controls
- */
-declare function useCountdown(options: UseCountdownOptions): UseCountdownReturn;
-
-/**
- * Breakpoint values in pixels.
- */
-interface BreakpointValues {
-    xs: number;
-    sm: number;
-    md: number;
-    lg: number;
-    xl: number;
-}
-/**
- * Breakpoint state.
- */
-interface BreakpointState {
-    /** Current breakpoint name */
-    current: Breakpoint;
-    /** Is extra-small screen (< sm) */
-    isXs: boolean;
-    /** Is small screen (>= sm, < md) */
-    isSm: boolean;
-    /** Is medium screen (>= md, < lg) */
-    isMd: boolean;
-    /** Is large screen (>= lg, < xl) */
-    isLg: boolean;
-    /** Is extra-large screen (>= xl) */
-    isXl: boolean;
-    /** Is mobile (< md) */
-    isMobile: boolean;
-    /** Is tablet (>= md, < lg) */
-    isTablet: boolean;
-    /** Is desktop (>= lg) */
-    isDesktop: boolean;
-}
-/**
- * Return type for useBreakpoints hook.
- */
-interface UseBreakpointsReturn extends BreakpointState {
-    /** Check if viewport is >= breakpoint */
-    up: (breakpoint: Breakpoint) => boolean;
-    /** Check if viewport is < breakpoint */
-    down: (breakpoint: Breakpoint) => boolean;
-    /** Check if viewport is exactly at breakpoint range */
-    only: (breakpoint: Breakpoint) => boolean;
-    /** Check if viewport is between two breakpoints */
-    between: (start: Breakpoint, end: Breakpoint) => boolean;
-    /** Breakpoint values in pixels */
-    values: BreakpointValues;
-}
-/**
- * Hook for responsive breakpoint detection.
- *
- * @returns Breakpoint state and helper functions
- *
- * @example
- * ```tsx
- * function ResponsiveLayout() {
- *   const { isMobile, isDesktop, up, current } = useBreakpoints();
- *
- *   return (
- *     <Box>
- *       {isMobile && <MobileNav />}
- *       {isDesktop && <DesktopSidebar />}
- *       <Typography>Current: {current}</Typography>
- *       {up('md') && <AdvancedFeatures />}
- *     </Box>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * function DataGrid() {
- *   const { between, only } = useBreakpoints();
- *
- *   const columns = useMemo(() => {
- *     if (only('xs')) return 1;
- *     if (between('sm', 'md')) return 2;
- *     return 3;
- *   }, [only, between]);
- *
- *   return <Grid columns={columns}>...</Grid>;
- * }
- * ```
- */
-declare function useBreakpoints(): UseBreakpointsReturn;
-
-/**
- * Return type for useIsClient hook.
- */
-type UseIsClientReturn = boolean;
-/**
- * Hook to detect client-side rendering.
- *
- * @returns {boolean} True if running on client, false during SSR
- *
- * @example
- * ```tsx
- * function ClientOnlyComponent() {
- *   const isClient = useIsClient();
- *
- *   if (!isClient) {
- *     return <Skeleton />;
- *   }
- *
- *   return <BrowserOnlyFeature />;
- * }
- * ```
- */
-declare function useIsClient(): UseIsClientReturn;
-
-/**
- * Return type for useMounted hook.
- */
-interface UseMountedReturn {
-    /** Check if component is currently mounted */
-    isMounted: () => boolean;
-}
-/**
- * Hook to check if a component is currently mounted.
- * Useful for preventing state updates on unmounted components.
- *
- * @returns {UseMountedReturn} Mount state checker
- *
- * @example
- * ```tsx
- * function AsyncComponent() {
- *   const [data, setData] = useState(null);
- *   const { isMounted } = useMounted();
- *
- *   useEffect(() => {
- *     fetchData().then((result) => {
- *       if (isMounted()) {
- *         setData(result);
- *       }
- *     });
- *   }, [isMounted]);
- *
- *   return <div>{data}</div>;
- * }
- * ```
- */
-declare function useMounted(): UseMountedReturn;
-
-/**
- * Hook to track the previous value.
- *
- * @template T - Type of the value
- * @param {T} value - Current value to track
- * @returns {T | undefined} Previous value (undefined on first render)
- *
- * @example
- * ```tsx
- * function Counter() {
- *   const [count, setCount] = useState(0);
- *   const prevCount = usePrevious(count);
- *
- *   return (
- *     <div>
- *       Current: {count}, Previous: {prevCount ?? 'N/A'}
- *     </div>
- *   );
- * }
- * ```
- */
-declare function usePrevious<T>(value: T): T | undefined;
-
-/**
- * Supported event maps for different targets.
- */
-type WindowEventMap = globalThis.WindowEventMap;
-type HTMLElementEventMap = globalThis.HTMLElementEventMap;
-type DocumentEventMap = globalThis.DocumentEventMap;
-/**
- * Hook to attach event listeners with automatic cleanup.
- *
- * @template K - Event type key
- * @param {K} eventName - Name of the event
- * @param {function} handler - Event handler
- * @param {RefObject<HTMLElement>} [element] - Target element (defaults to window)
- * @param {AddEventListenerOptions} [options] - Event listener options
- *
- * @example
- * ```tsx
- * // Window event
- * function ScrollTracker() {
- *   useEventListener('scroll', () => console.log('Scrolled!'));
- *   return null;
- * }
- *
- * // Element event
- * function ClickTracker() {
- *   const ref = useRef<HTMLDivElement>(null);
- *   useEventListener('click', (e) => console.log('Clicked!', e), ref);
- *   return <div ref={ref}>Click me</div>;
- * }
- * ```
- */
-declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, element?: undefined, options?: AddEventListenerOptions): void;
-declare function useEventListener<K extends keyof HTMLElementEventMap>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, element: RefObject<HTMLElement | null>, options?: AddEventListenerOptions): void;
-declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, element: RefObject<Document>, options?: AddEventListenerOptions): void;
-
-/**
- * Hook to detect clicks outside of an element.
- *
- * @template T - Element type (defaults to HTMLElement)
- * @param {function} handler - Callback when clicked outside
- * @param {RefObject<T>} [providedRef] - Optional external ref
- * @returns {RefObject<T>} Ref to attach to the element
- *
- * @example
- * ```tsx
- * function Dropdown() {
- *   const [isOpen, setIsOpen] = useState(false);
- *   const ref = useClickOutside<HTMLDivElement>(() => setIsOpen(false));
- *
- *   return (
- *     <div ref={ref}>
- *       <button onClick={() => setIsOpen(true)}>Open</button>
- *       {isOpen && <DropdownMenu />}
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useClickOutside<T extends HTMLElement = HTMLElement>(handler: (event: MouseEvent | TouchEvent) => void, providedRef?: RefObject<T | null>): RefObject<T | null>;
-
-/**
- * Hook to run a callback at a specified interval.
- *
- * @param {function} callback - Function to call on each interval
- * @param {number | null} delay - Interval delay in ms (null to pause)
- *
- * @example
- * ```tsx
- * function Timer() {
- *   const [seconds, setSeconds] = useState(0);
- *   const [isRunning, setIsRunning] = useState(true);
- *
- *   useInterval(
- *     () => setSeconds((s) => s + 1),
- *     isRunning ? 1000 : null
- *   );
- *
- *   return (
- *     <div>
- *       <p>Seconds: {seconds}</p>
- *       <button onClick={() => setIsRunning(!isRunning)}>
- *         {isRunning ? 'Pause' : 'Resume'}
- *       </button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useInterval(callback: () => void, delay: number | null): void;
-
-/**
- * Return type for useTimeout hook.
- */
-interface UseTimeoutReturn {
-    /** Reset the timeout */
-    reset: () => void;
-    /** Clear the timeout */
-    clear: () => void;
-    /** Whether the timeout is active */
-    isActive: boolean;
-}
-/**
- * Hook to run a callback after a specified delay.
- *
- * @param {function} callback - Function to call after delay
- * @param {number} delay - Delay in milliseconds
- * @returns {UseTimeoutReturn} Timeout controls
- *
- * @example
- * ```tsx
- * function AutoSave() {
- *   const [content, setContent] = useState('');
- *   const { reset } = useTimeout(() => {
- *     saveContent(content);
- *   }, 3000);
- *
- *   const handleChange = (value: string) => {
- *     setContent(value);
- *     reset(); // Reset timer on each change
- *   };
- *
- *   return <textarea value={content} onChange={(e) => handleChange(e.target.value)} />;
- * }
- * ```
- */
-declare function useTimeout(callback: () => void, delay: number): UseTimeoutReturn;
-
-export { type CopyState as C, type SetState as S, type UseCopyToClipboardOptions as U, type CountdownControls as a, type CountdownState as b, type UseCopyToClipboardReturn as c, type UseCountdownOptions as d, type UseCountdownReturn as e, type UseMountedReturn as f, type UseMultiSelectOptions as g, type UseMultiSelectReturn as h, type UseSetStateReturn as i, type UseTimeoutReturn as j, useBreakpoints as k, useClickOutside as l, useCopyToClipboard as m, useCountdown as n, useDebounce as o, useDebounceCallback as p, useEventListener as q, useInterval as r, useIsClient as s, useLocalStorage as t, useBoolean as u, useMounted as v, useMultiSelect as w, usePrevious as x, useSetState as y, useTimeout as z };