The Three Ref-Driven Scroll Hooks I Actually Use

// Recipe 1. The simplest one. Returns [ref, scroll]. Caller attaches ref to
// any DOM node, then calls scroll(opts) to bring it into view.
const { useRef, useCallback } = (typeof React !== 'undefined' ? React : {
    useRef: (init) => ({ current: init }),
    useCallback: (f) => f,
});

function useScrollIntoView(defaultOpts) {
    const ref = useRef(null);
    const scroll = useCallback((opts) => {
        const node = ref.current;
        if (!node) return false;
        const merged = Object.assign({ behavior: 'smooth', block: 'center' }, defaultOpts || {}, opts || {});
        if (typeof node.scrollIntoView === 'function') node.scrollIntoView(merged);
        else console.log('would call scrollIntoView with', merged);
        return true;
    }, []);
    return [ref, scroll];
}

// Stand-in for a real DOM node so the snippet runs anywhere.
const calls = [];
const fakeNode = { scrollIntoView: (opts) => { calls.push(opts); } };

const [ref, scroll] = useScrollIntoView();
console.log('scroll before attach ->', scroll());
ref.current = fakeNode;
scroll();
scroll({ block: 'start' });
scroll({ behavior: 'auto' });
console.log('captured calls:', JSON.stringify(calls));

// Recipe 2. SPAs do not refresh the document scroll on a route change, so a
// long article followed by a short one leaves you halfway down the page. This
// hook watches a deps array and snaps a container to (0, 0) on every change.
// Mini React shim that defers effects to a flush step so refs can be attached
// between render-and-commit, mimicking real React behaviour.
const effectQueue = [];
let lastDeps = null;
function flushEffects() { const q = effectQueue.splice(0); q.forEach((fn) => fn()); }
const { useRef, useEffect } = (typeof React !== 'undefined' ? React : {
    useRef: (init) => ({ current: init }),
    useEffect: (fn, deps) => {
        const equal = lastDeps && lastDeps.length === deps.length
            && lastDeps.every((d, i) => Object.is(d, deps[i]));
        if (!equal) { effectQueue.push(fn); lastDeps = deps.slice(); }
    },
});

function useScrollToTop(deps) {
    const ref = useRef(null);
    useEffect(() => {
        const node = ref.current;
        if (!node) return;
        if (typeof node.scrollTo === 'function') node.scrollTo(0, 0);
        else if (typeof node.scrollTop === 'number') node.scrollTop = 0;
        else console.log('would scroll node to (0, 0)');
    }, deps);
    return ref;
}

// Stand-in container that records every scrollTo call for inspection.
const container = { scrollTop: 1200, scrollTo(x, y) { this.scrollTop = y; this._calls = (this._calls || 0) + 1; } };

// We simulate a remount-style flow: each render attaches the container to the
// hook's ref before the deps-effect runs. In real React the JSX `ref={...}`
// happens in the same render the hook returns from.
function renderWith(deps) {
    const ref = useScrollToTop(deps);
    ref.current = container; // <ContentArea ref={ref}> in real code
    flushEffects(); // commit phase: refs are attached, now effects fire
    return ref;
}

renderWith(['/articles/a']); // first nav fires the effect, scrolls to 0
console.log('after first route, scrollTop ->', container.scrollTop, '| total scrollTo calls:', container._calls);

container.scrollTop = 500; // user scrolls down within the page
renderWith(['/articles/a']); // same deps, effect skipped
console.log('same route, scrollTop preserved ->', container.scrollTop);

renderWith(['/articles/b']); // deps changed, effect fires
console.log('after route change, scrollTop ->', container.scrollTop, '| total scrollTo calls:', container._calls);

// Recipe 3. A page with N sections and a top nav that jumps to each. Single
// useRef per section is fine until N is dynamic; then I want a callback ref
// that registers each node in a shared Map keyed by id.
const { useRef, useCallback } = (typeof React !== 'undefined' ? React : {
    useRef: (init) => ({ current: init }),
    useCallback: (f) => f,
});

function useScrollableSection() {
    const mapRef = useRef(null);
    if (mapRef.current === null) mapRef.current = new Map();

    const register = useCallback((id) => (node) => {
        const map = mapRef.current;
        if (node) map.set(id, node);
        else map.delete(id);
    }, []);

    const scrollTo = useCallback((id, opts) => {
        const node = mapRef.current.get(id);
        if (!node) { console.log('no section registered for', id); return false; }
        const merged = Object.assign({ behavior: 'smooth', block: 'start' }, opts || {});
        if (typeof node.scrollIntoView === 'function') node.scrollIntoView(merged);
        else console.log('would scrollIntoView', id, 'with', merged);
        return true;
    }, []);

    return { register, scrollTo, ids: () => Array.from(mapRef.current.keys()) };
}

// Stand-in nodes.
const nodeFor = (id) => ({ id, scrollIntoView(opts) { console.log('jumped to', id, 'with', opts.block); } });

const nav = useScrollableSection();
// React would call these as ref={register('intro')} on each section.
nav.register('intro')(nodeFor('intro'));
nav.register('install')(nodeFor('install'));
nav.register('api')(nodeFor('api'));
console.log('registered:', nav.ids());
nav.scrollTo('install');
nav.scrollTo('does-not-exist');

// Section unmount: callback ref runs with null, removing it from the Map.
nav.register('install')(null);
console.log('after unmount:', nav.ids());

// Recipe 4. The `<Modal>` exposes open/close/focus to its parent without
// leaking the underlying DOM node. forwardRef forwards the ref, and
// useImperativeHandle replaces what `ref.current` resolves to.
const { useRef, useImperativeHandle, forwardRef } = (typeof React !== 'undefined' ? React : {
    useRef: (init) => ({ current: init }),
    useImperativeHandle: (ref, factory) => {
        if (!ref) return;
        if (typeof ref === 'function') ref(factory());
        else ref.current = factory();
    },
    forwardRef: (renderFn) => (props, ref) => renderFn(props || {}, ref),
});

const Modal = forwardRef(function Modal(props, ref) {
    // useRef-backed state so the imperative handle stays correct without
    // re-rendering on every open/close (this matches what I ship in real apps).
    const stateRef = useRef({ open: false });
    const dialogRef = useRef(null); // would be attached to the actual <dialog>
    const handle = {
        open: () => { stateRef.current.open = true; },
        close: () => { stateRef.current.open = false; },
        focus: () => {
            const node = dialogRef.current;
            if (node && typeof node.focus === 'function') node.focus();
            else console.log('would focus modal dialog');
        },
        isOpen: () => stateRef.current.open,
    };
    useImperativeHandle(ref, () => handle, []);
    return handle; // playground stand-in for the rendered tree
});

const modalRef = { current: null };
Modal({ title: 'Confirm' }, modalRef);
console.log('exposed methods:', Object.keys(modalRef.current).sort().join(', '));
modalRef.current.open();
console.log('isOpen after open():', modalRef.current.isOpen());
modalRef.current.focus();
modalRef.current.close();
console.log('isOpen after close():', modalRef.current.isOpen());
console.log('parent never saw the underlying dialogRef:', !('dialogRef' in modalRef.current));