feat: init

epicweb-dev · Nov 28, 2023 · 77ab3d9 · 77ab3d9
commit 77ab3d9
Show file tree

Hide file tree

Showing 7 changed files with 970 additions and 0 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,68 @@
+name: release
+on: [push, pull_request]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: 🧪 Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📥 Download deps
+        uses: bahmutov/npm-install@v1
+        with:
+          useLockFile: false
+
+      - name: 🧪 Test
+        run: npm run test
+
+  release:
+    name: 🚀 Release
+    needs: [test]
+    runs-on: ubuntu-latest
+    if:
+      ${{ github.repository == 'epicweb-dev/restore-scroll' &&
+      contains('refs/heads/main,refs/heads/beta,refs/heads/next,refs/heads/alpha',
+      github.ref) && github.event_name == 'push' }}
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📥 Download deps
+        uses: bahmutov/npm-install@v1
+        with:
+          useLockFile: false
+
+      - name: 📦 Run Build
+        run: npm run build
+
+      - name: 🚀 Release
+        uses: cycjimmy/semantic-release-action@v4
+        with:
+          semantic_version: 17
+          branches: |
+            [
+              '+([0-9])?(.{+([0-9]),x}).x',
+              'main',
+              'next',
+              'next-major',
+              {name: 'beta', prerelease: true},
+              {name: 'alpha', prerelease: true}
+            ]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,8 @@
+dist
+node_modules
+tsconfig.tsbuildinfo
+coverage
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
diff --git a/README.md b/README.md
@@ -0,0 +1,98 @@
+<div>
+  <h1 align="center"><a href="https://npm.im/@epic-web/restore-scroll">🌀 @epic-web/restore-scroll</a></h1>
+  <strong>
+    Restore scroll position of elements on page navigation
+  </strong>
+  <p>
+    The `<body>` isn't the only thing that scrolls. When the user scrolls a list, then navigates back and forth, you may want to keep their scroll position where it was when they left. This library makes that easy.
+  </p>
+</div>
+
+```
+npm install @epic-web/restore-scroll
+```
+
+<div align="center">
+  <a
+    alt="Epic Web logo"
+    href="https://www.epicweb.dev"
+  >
+    <img
+      width="300px"
+      src="https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/257881576-fd66040b-679f-4f25-b0d0-ab886a14909a.png"
+    />
+  </a>
+</div>
+
+<hr />
+
+<!-- prettier-ignore-start -->
+[![Build Status][build-badge]][build]
+[![MIT License][license-badge]][license]
+[![Code of Conduct][coc-badge]][coc]
+<!-- prettier-ignore-end -->
+
+## The Problem
+
+When a user navigates to a new page, the browser will scroll the page to the
+position it was at when the user left the page. This is a great feature, but
+it's not perfect. The browser only scrolls the `<body>` element. If the user
+scrolls a list, then navigates back and forth, the browser will scroll the page
+to the top, but the list will still be scrolled to the position it was at when
+the user left the page.
+
+## The Solution
+
+This library provides a way to restore the scroll position of any element on the
+page you choose. It does this by storing the scroll position of the element in
+session storage and then restoring it when the user navigates back to the page
+(very similar to how Remix handles scroll restoration for the `<body>`).
+
+This depends on Remix's `useBeforeUnload`, `useNavigation`, and `useLocation`
+hooks. There's probably an easy way we could make this support React Router in
+general. PRs welcome!
+
+## Usage
+
+```tsx
+import { ElementScrollRestoration } from '@epic-web/restore-scroll'
+
+// ... Stick this in your root component somewhere:
+return (
+	<html>
+		<body>
+			{/* ... */}
+			<ElementScrollRestoration elementQuery="[data-restore-scroll='true']" />
+			{/* ... */}
+		</body>
+	</html>
+)
+```
+
+Then, for any element for which you wish to restore scroll position, simply add
+the `data-restore-scroll="true"` attribute:
+
+```tsx
+<ul data-restore-scroll="true">
+	<li>...</li>
+	<li>...</li>
+	<li>...</li>
+</ul>
+```
+
+And that's it! Now when the user navigates away from the page and then back to
+it, the list will be scrolled to the position it was at when the user left the
+page.
+
+## License
+
+MIT
+
+<!-- prettier-ignore-start -->
+[build-badge]: https://img.shields.io/github/actions/workflow/status/epicweb-dev/restore-scroll/release.yml?branch=main&logo=github&style=flat-square
+[build]: https://github.com/epicweb-dev/restore-scroll/actions?query=workflow%3Arelease
+[license-badge]: https://img.shields.io/badge/license-MIT%20License-blue.svg?style=flat-square
+[license]: https://github.com/epicweb-dev/restore-scroll/blob/main/LICENSE
+[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
+[coc]: https://kentcdodds.com/conduct
+<!-- prettier-ignore-end -->