@tenedev/hooks/dist/index.d.cts

React Hooks

import { Dispatch, SetStateAction } from 'react';

/**
 * Return type of {@link useBoolean} hook.
 */
interface BooleanReturn {
    /** The current boolean value. */
    value: boolean;
    /** Directly sets the boolean state. */
    setValue: Dispatch<SetStateAction<boolean>>;
    /** Toggles the current value between `true` and `false`. */
    toggle: () => void;
    /** Sets the value to `true`. */
    setTrue: () => void;
    /** Sets the value to `false`. */
    setFalse: () => void;
    /** Resets the value back to the initial `defaultValue`. */
    reset: () => void;
}
/**
 * A simple and optimized React hook for managing boolean state.
 *
 * @remarks
 * This hook uses React hooks internally:
 * - {@link https://react.dev/reference/react/useState | useState} — to store and manage the boolean state.
 * - {@link https://react.dev/reference/react/useCallback | useCallback} — to memoize helper methods.
 *
 * @returns An object containing the current value and helper methods.
 *
 * @example
 * ```tsx
 * const { value, toggle, setTrue, setFalse, reset } = useBoolean();
 *
 * return (
 *   <>
 *     <p>{value ? 'ON' : 'OFF'}</p>
 *     <button onClick={toggle}>Toggle</button>
 *     <button onClick={setTrue}>Set True</button>
 *     <button onClick={setFalse}>Set False</button>
 *     <button onClick={reset}>Reset</button>
 *   </>
 * );
 * ```
 *
 * @since 0.3.0
 */
declare function useBoolean(
/**
 * The initial boolean value.
 *
 * @default false
 */
defaultValue?: boolean): BooleanReturn;

/**
 * Options for configuring the {@link useCounter} hook
 */
interface Counter {
    /**
     * Initial value of the counter
     *
     * @default 0
     */
    initialValue?: number;
    /**
     * Minimum value the counter can reach
     */
    min?: number;
    /**
     * Maximum value the counter can reach
     */
    max?: number;
    /**
     * Step size for increment and decrement
     *
     * @default 1
     */
    step?: number;
    /**
     * Callback function that is called whenever the counter value changes
     */
    onChange?: (
    /**
     * The new counter value
     */
    value: number) => void;
}
/**
 * Return type of {@link useCounter} hook
 */
interface CounterReturn {
    /**
     * Current counter value
     */
    count: number;
    /**
     * Set counter value directly (does NOT respect `min` and `max`)
     */
    setCount: Dispatch<SetStateAction<number>>;
    /**
     * Increment the counter by `step`, respecting `max`
     */
    increment: () => void;
    /**
     * Decrement the counter by `step`, respecting `min`
     */
    decrement: () => void;
    /**
     * Reset counter to the initial value, respecting `min`/`max`
     */
    reset: () => void;
    /**
     * Reset counter to a specific value, respecting `min`/`max`
     */
    resetTo: (
    /**
     * The value to reset the counter
     */
    value: number) => void;
    /**
     *  Boolean indicating if the counter is at its minimum value
     */
    isMin: boolean;
    /**
     * Boolean indicating if the counter is at its maximum value
     */
    isMax: boolean;
    /**
     * Sets the counter value directly while enforcing `min` and `max` boundaries
     *
     * @description
     * Accepts either a number or an updater function `(prev) => next`
     */
    setCountBounded: Dispatch<SetStateAction<number>>;
}
/**
 * A React hook to manage a numeric counter with min/max boundaries, step increments, and change callbacks
 *
 * @remarks
 * This hook uses React hooks internally:
 * - {@link https://react.dev/reference/react/useState | useState} - to manage the counter state
 * - {@link https://react.dev/reference/react/useCallback | useCallback} - to memoize increment, decrement, reset, and resetTo functions
 * - {@link https://react.dev/reference/react/useEffect | useEffect} - to call `onChange` whenever the counter changes
 *
 * @returns An object containing the counter state, controls, and helper flags
 *
 * @example
 * ```ts
 * const counter = useCounter({ initialValue: 5, min: 0, max: 10, step: 2 });
 * counter.increment(); // increases by 2
 * counter.decrement(); // decreases by 2
 * counter.reset();     // resets to 5
 * counter.resetTo(8);  // resets to 8
 * ```
 *
 * @since 0.1.0
 */
declare function useCounter({ initialValue, max, min, onChange, step, }?: Counter): CounterReturn;

/** Options to configure the behavior of {@link useDocumentTitle} */
interface UseDocumentTitleOptions {
    /**
     * Whether to restore the original document title when the component unmounts.
     *
     * If this value changes dynamically, the hook will respect the latest value on unmount.
     *
     * @default true
     */
    restoreOnUnmount?: boolean;
    /**
     * Optional template for the title, Use `%s` as a placeholder for the title.
     *
     * All occurrences of `%s` will be replaced by the provided `title`.
     *
     * @example
     * ```ts
     * template: '%s - MyApp'
     * ```
     *
     * @example
     * ```ts
     * template: '%s - %s - MyApp'
     * ```
     */
    template?: string;
    /**
     * If true, the hook will skip updating the title if the new title is identical to the current `document.title`.
     *
     * @default true
     */
    skipIfSame?: boolean;
}
/**
 * Updates the `document.title` for the current page.
 *
 * This hook automatically updates the document title when mounted, and optionally restores the original title when unmounted.
 *
 *
 * @remarks
 * This hook uses React hooks internally:
 * - {@link https://react.dev/reference/react/useCallback | useCallback} - to memoize formatting and setting functions.
 * - {@link https://react.dev/reference/react/useEffect | useEffect} - to perform the side-effects on mount/unmount.
 * - {@link https://react.dev/reference/react/useRef | useRef} - to persist the original title across renders.
 *
 *
 * @example
 * ```tsx
 * import { useDocumentTitle } from '@tenedev/hooks';
 *
 * export function Dashboard() {
 *  useDocumentTitle('Dashboard', { template: '%s - MyApp' });
 *
 *  return <h1>Dashboard</h1>;
 * };
 * ```
 *
 * @since 0.2.0
 */
declare function useDocumentTitle(
/** The new title to set */
title: string, 
/** Optional configuration */
{ restoreOnUnmount, template, skipIfSame }?: UseDocumentTitleOptions): void;

export { type BooleanReturn, type Counter, type CounterReturn, type UseDocumentTitleOptions, useBoolean, useCounter, useDocumentTitle };