use-element-scroll-restoration 1.0.1

package/README.md

@@ -0,0 +1,50 @@
+## React custom hook for scroll restoration
+
+This is a custom React hook that facilitates scroll restoration for a specific element. It allows you to save and restore the scroll position of an element, optionally persisting it to `localStorage` or `sessionStorage`. This can be useful in scenarios where you want to maintain scroll positions across navigation or page refreshes.<br>
+It differs from [ScrollRestoration](https://reactrouter.com/en/main/components/scroll-restoration) in that it can be attached to a specific dom element.
+
+### Demo
+
+https://codesandbox.io/p/sandbox/aged-tree-kr7y6w
+
+### Installation
+
+```bash
+npm install use-scroll-restoration
+```
+
+### Usage
+
+Here's how you can use the `useScrollRestoration` hook in your React components:
+
+```jsx
+import React from 'react';
+import { useScrollRestoration } from 'use-scroll-restoration';
+
+function ScrollRestorationExample() {
+  const { ref, setScroll } = useScrollRestoration('exampleKey', {
+    debounceTime: 200,
+    persist: 'localStorage',
+  });
+
+  return (
+    <div ref={ref} style={{ height: '500px', overflow: 'auto' }}>
+      {/* Your scrollable content */}
+    </div>
+  );
+}
+```
+
+### API
+
+#### `useScrollRestoration(key: string, options?: ScrollRestorationOptions)`
+
+- `key` (required): A unique key to identify the scroll restoration context.
+- `options` (optional): An object containing additional options:
+    - `debounceTime` (default: `100`): The debounce time (in milliseconds) before saving scroll position.
+    - `persist` (default: `false`): Specifies where to persist scroll position. Can be `false`, `'localStorage'`, or `'sessionStorage'`.
+
+Returns an object with the following properties:
+
+- `ref`: A callback that sets the DOM element reference. Attach this to the `ref` prop of the scrollable element you want to manage.
+- `setScroll({ x, y })`: A function to manually set the scroll position, where `x` and `y` are optional scroll coordinates.

package/dist/hooks/useElementScrollRestoration.d.ts

@@ -0,0 +1,12 @@
+interface ScrollRestorationOptions {
+    debounceTime?: number;
+    persist?: false | "localStorage" | "sessionStorage";
+}
+export declare function useElementScrollRestoration<U extends HTMLElement>(key: string, { debounceTime, persist }?: ScrollRestorationOptions): {
+    ref: (element: U | null) => void;
+    setScroll: ({ x, y }: {
+        x?: number;
+        y?: number;
+    }) => void;
+};
+export {};

package/dist/hooks/useElementScrollRestoration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { useElementScrollRestoration } from './hooks/useElementScrollRestoration';

package/dist/index.js

@@ -0,0 +1,82 @@
+import { useState as u, useCallback as L, useEffect as f } from "react";
+const T = (o, a) => {
+  let l;
+  return (...i) => {
+    l && clearTimeout(l), l = setTimeout(() => {
+      o(...i), l = null;
+    }, a);
+  };
+};
+function E(o, { debounceTime: a = 100, persist: l = !1 } = {}) {
+  const [i, c] = u({}), [r, g] = u(null), m = L((t) => {
+    t && g(t);
+  }, []), e = i[o], S = o in i;
+  return f(() => {
+    if (!r) return;
+    const t = T(() => {
+      const s = r.scrollTop, n = r.scrollLeft;
+      c((R) => ({
+        ...R,
+        [o]: { scrollTop: s, scrollLeft: n }
+      }));
+    }, a);
+    return r.addEventListener("scroll", t), () => {
+      r.removeEventListener("scroll", t);
+    };
+  }, [a, o, r, l, c]), f(() => {
+    if (r)
+      if (S)
+        r.scrollTo(
+          e.scrollLeft,
+          e.scrollTop
+        );
+      else {
+        let t = {
+          scrollTop: r.scrollTop,
+          scrollLeft: r.scrollLeft
+        };
+        if (l === "localStorage") {
+          const s = localStorage.getItem(
+            `scrollRestoration-${o}`
+          );
+          s && (t = JSON.parse(s));
+        }
+        if (l === "sessionStorage") {
+          const s = sessionStorage.getItem(
+            `scrollRestoration-${o}`
+          );
+          s && (t = JSON.parse(s));
+        }
+        c((s) => ({
+          ...s,
+          [o]: t
+        }));
+      }
+  }, [
+    e,
+    r,
+    o,
+    l,
+    S,
+    c
+  ]), f(() => {
+    !l || !e || (l === "localStorage" ? localStorage.setItem(
+      `scrollRestoration-${o}`,
+      JSON.stringify(e)
+    ) : l === "sessionStorage" && sessionStorage.setItem(
+      `scrollRestoration-${o}`,
+      JSON.stringify(e)
+    ));
+  }, [o, l, e]), { ref: m, setScroll: ({ x: t, y: s }) => {
+    c((n) => ({
+      ...n,
+      [o]: {
+        scrollLeft: t !== void 0 ? t : n[o].scrollLeft,
+        scrollTop: s !== void 0 ? s : n[o].scrollTop
+      }
+    }));
+  } };
+}
+export {
+  E as useElementScrollRestoration
+};

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+(function(r,n){typeof exports=="object"&&typeof module<"u"?n(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],n):(r=typeof globalThis<"u"?globalThis:r||self,n(r.index={},r.React))})(this,(function(r,n){"use strict";const d=(o,a)=>{let t;return(...u)=>{t&&clearTimeout(t),t=setTimeout(()=>{o(...u),t=null},a)}};function g(o,{debounceTime:a=100,persist:t=!1}={}){const[u,i]=n.useState({}),[s,m]=n.useState(null),R=n.useCallback(e=>{e&&m(e)},[]),c=u[o],S=o in u;return n.useEffect(()=>{if(!s)return;const e=d(()=>{const l=s.scrollTop,f=s.scrollLeft;i(T=>({...T,[o]:{scrollTop:l,scrollLeft:f}}))},a);return s.addEventListener("scroll",e),()=>{s.removeEventListener("scroll",e)}},[a,o,s,t,i]),n.useEffect(()=>{if(s)if(S)s.scrollTo(c.scrollLeft,c.scrollTop);else{let e={scrollTop:s.scrollTop,scrollLeft:s.scrollLeft};if(t==="localStorage"){const l=localStorage.getItem(`scrollRestoration-${o}`);l&&(e=JSON.parse(l))}if(t==="sessionStorage"){const l=sessionStorage.getItem(`scrollRestoration-${o}`);l&&(e=JSON.parse(l))}i(l=>({...l,[o]:e}))}},[c,s,o,t,S,i]),n.useEffect(()=>{!t||!c||(t==="localStorage"?localStorage.setItem(`scrollRestoration-${o}`,JSON.stringify(c)):t==="sessionStorage"&&sessionStorage.setItem(`scrollRestoration-${o}`,JSON.stringify(c)))},[o,t,c]),{ref:R,setScroll:({x:e,y:l})=>{i(f=>({...f,[o]:{scrollLeft:e!==void 0?e:f[o].scrollLeft,scrollTop:l!==void 0?l:f[o].scrollTop}}))}}}r.useElementScrollRestoration=g,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));

package/dist/utils/debounce.d.ts

@@ -0,0 +1,3 @@
+type DebounceFunction = <T extends never[]>(func: (...args: T) => void, delay: number) => (...args: T) => void;
+export declare const debounce: DebounceFunction;
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "use-element-scroll-restoration",
+  "author": "Jacob Cutshall",
+  "license": "MIT",
+  "version": "1.0.1",
+  "description": "React hook for rstoring scroll position on specific elements",
+  "type": "module",
+  "main": "dist/index.umd.cjs",
+  "moudle": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpcutshall/use-element-scroll-restoration"
+  },
+  "homepage": "https://github.com/jpcutshall/use-element-scroll-restoration",
+  "keywords": [
+    "react",
+    "hook",
+    "scroll-restoration",
+    "use-scroll-restoration",
+    "use-element-scroll-restoration"
+  ],
+  "dependencies": {
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.19.12",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.3",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.3.0",
+    "happy-dom": "^20.7.0",
+    "typescript": "^5.0.2",
+    "typescript-eslint": "^8.56.1",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}