@lesnoypudge/utils-react/build/hooks/useRefManager/useRefManager.d.ts

lesnoypudge's utils-react

export declare namespace useRefManager {
    type MaybeCleanup = (() => void) | void | undefined;
    export type EffectCallback<_Value> = (value: _Value) => MaybeCleanup;
    export type EffectCleanup = () => void;
    export type Effect<_Value> = (callback: EffectCallback<_Value>) => EffectCleanup;
    export type RefManager<_Value> = {
        current: _Value;
        effect: Effect<_Value>;
    };
    export type NullableRefManager<_Value> = {
        current: _Value | null;
        effect: Effect<_Value | null>;
    };
    export type Overload = {
        <_Value>(initialValue: _Value): RefManager<_Value>;
        <_Value>(initialValue: _Value | null): RefManager<_Value | null>;
        <_Value = undefined>(initialValue?: undefined): RefManager<_Value | undefined>;
    };
    export {};
}
/**
 * This hook provides an enhanced reference object (`RefManager`) that
 * triggers registered effects on value change.
 *
 * The `RefManager` object includes:
 * - `current`: Holds the current value of the ref.
 * - `effect`: A stable method to register effects that run
 * when the ref's value changes, returning a cleanup function.
 *
 * Example usage:
 *
 * ```tsx
 * const ExampleComponent: FC = () => {
 *     const refManager = useRefManager<HTMLButtonElement>(null);
 *     const [isVisible, setIsVisible] = useState(false);
 *
 *     useEffect(() => {
 *         // Effect registration
 *         return refManager.effect((buttonNode) => {
 *             if (!buttonNode) return;
 *
 *             const handler = () => {};
 *
 *             buttonNode.addEventListener('click', handler);
 *
 *             // Cleanup will be called on re-render
 *             // or value change
 *             return () => {
 *                 buttonNode.removeEventListener(
 *                     'click',
 *                     handler,
 *                 );
 *             };
 *         });
 *     }, [refManager]);
 *
 *     useEffect(() => {
 *         console.log(refManager.current); // null
 *
 *         const id = setTimeout(() => {
 *             setIsVisible(true);
 *         }, 3000);
 *
 *         return () => clearTimeout(id);
 *     }, []);
 *
 *     if (isVisible) {
 *         return (
 *             <button ref={refManager}>
 *                 <>Content</>
 *             </button>
 *         );
 *     }
 *
 *     return null;
 * };
 * ```
 */
export declare const useRefManager: useRefManager.Overload;