easing-scroll 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ☃︎
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# easing-scroll
+
+[![npm-version](https://img.shields.io/npm/v/easing-scroll.svg)](https://npmjs.org/package/easing-scroll)
+
+♿️ Smooth scrolling. [Demo](https://easing-scroll.vercel.app).
+
+## Install
+
+```sh
+npm install easing-scroll
+```
+
+## Features
+
+- 📦 Zero dependencies
+- 📈 Customize [easing function](https://easings.net)
+- 🚫 Abort scrolling ([AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal))
+- 🔄 Waiting for animation to end
+- ☸️ Supports vertical and horizontal scroll
+
+## Usage
+
+```ts
+import { easingScroll } from "easing-scroll";
+
+const controller = new AbortController();
+// Abort scrolling
+// controller.abort(); ❌
+
+const target = document.querySelector(".container");
+
+const progress = await easingScroll(target, {
+  left: 0, // px
+  top: 300, // px
+  duration: 400, // ms
+  signal: controller.signal,
+  // 👀 https://easings.net/#easeOutCubic
+  easing: (x) => 1 - Math.pow(1 - x, 3),
+});
+
+if (progress === 1) {
+  console.log("Completed");
+} else {
+  console.log("Aborted");
+}
+```
+
+### Animation
+
+Linear function `(t) => t` is used by default. Pass [easing](https://easings.net), if you want to change easing function.
+`duration` is animation duration in milliseconds.
+
+```ts
+easingScroll(target, {
+  duration: 400, // ms
+  // 👀 https://easings.net/#easeOutCubic
+  easing: (x) => 1 - Math.pow(1 - x, 3),
+});
+```
+
+### Abort scrolling
+
+Pass `signal` ([AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)),
+if you want to abort scrolling.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => {
+  controller.abort();
+}, 100);
+
+const progress = await easingScroll(target, {
+  ...,
+  signal: controller.signal,
+});
+
+if (progress !== 1) {
+  console.log('Scrolling has been aborted.');
+}
+```
+
+`progress` is a number from _0_ to _1_.
+
+`1` - Scrolling is completed _100%_.
+
+`<1` - Scrolling has been aborted and completed _x%_.
+
+```ts
+const progress = await easingScroll(target, {
+  ...,
+});
+
+if (progress !== 1) {
+  console.log('Scrolling has been aborted.');
+} else {
+  console.log('Completed.');
+}
+```

package/dist/easing-scroll.d.ts

@@ -0,0 +1,20 @@
+type Px = number;
+type Ms = number;
+/**
+ * Percent is number 0 - 1
+ *
+ * 0 = 0%, 1 = 100%
+ */
+type Pct = number;
+type Options = {
+    top: Px;
+    left: Px;
+    duration: Ms;
+    signal: AbortSignal;
+    /**
+     * @see Easing functions https://easings.net
+     */
+    easing: (t: Pct) => Pct;
+};
+export declare const easingScroll: <E extends Element>(target: E, { top, left, signal, duration, easing }: Partial<Options>) => Promise<Pct>;
+export {};

package/dist/easing-scroll.js

@@ -0,0 +1 @@
+"use strict";const b=o=>o,g=(o,{top:l,left:t,signal:e,duration:s=0,easing:i=b})=>e!=null&&e.aborted?Promise.resolve(0):s?new Promise(c=>{const a=o.scrollTop,m=o.scrollLeft,u=performance.now();let n;const v=()=>(performance.now()-u)/s,f=()=>{cancelAnimationFrame(n);const r=v();c(r)};e==null||e.addEventListener("abort",f);const p=()=>{const r=v(),d=l===void 0?void 0:a+(l-a)*i(r),T=t===void 0?void 0:m+(t-m)*i(r);r<1?(o.scrollTo({top:d,left:T}),n=requestAnimationFrame(p)):(o.scrollTo({top:l,left:t}),e==null||e.removeEventListener("abort",f),c(1))};n=requestAnimationFrame(p)}):(o.scrollTo({top:l,left:t}),Promise.resolve(1));exports.easingScroll=g;

package/dist/easing-scroll.mjs

@@ -0,0 +1 @@
+const u=o=>o,L=(o,{top:t,left:r,signal:n,duration:s=0,easing:i=u})=>n?.aborted?Promise.resolve(0):s?new Promise(a=>{const c=o.scrollTop,m=o.scrollLeft,f=performance.now();let l;const d=()=>(performance.now()-f)/s,p=()=>{cancelAnimationFrame(l);const e=d();a(e)};n?.addEventListener("abort",p);const v=()=>{const e=d(),T=t===void 0?void 0:c+(t-c)*i(e),b=r===void 0?void 0:m+(r-m)*i(e);e<1?(o.scrollTo({top:T,left:b}),l=requestAnimationFrame(v)):(o.scrollTo({top:t,left:r}),n?.removeEventListener("abort",p),a(1))};l=requestAnimationFrame(v)}):(o.scrollTo({top:t,left:r}),Promise.resolve(1));export{L as easingScroll};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { easingScroll } from "./easing-scroll";

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";const b=o=>o,g=(o,{top:l,left:t,signal:e,duration:s=0,easing:i=b})=>e!=null&&e.aborted?Promise.resolve(0):s?new Promise(c=>{const a=o.scrollTop,m=o.scrollLeft,u=performance.now();let n;const v=()=>(performance.now()-u)/s,f=()=>{cancelAnimationFrame(n);const r=v();c(r)};e==null||e.addEventListener("abort",f);const p=()=>{const r=v(),d=l===void 0?void 0:a+(l-a)*i(r),T=t===void 0?void 0:m+(t-m)*i(r);r<1?(o.scrollTo({top:d,left:T}),n=requestAnimationFrame(p)):(o.scrollTo({top:l,left:t}),e==null||e.removeEventListener("abort",f),c(1))};n=requestAnimationFrame(p)}):(o.scrollTo({top:l,left:t}),Promise.resolve(1));exports.easingScroll=g;

package/dist/index.mjs

@@ -0,0 +1 @@
+const u=o=>o,L=(o,{top:t,left:r,signal:n,duration:s=0,easing:i=u})=>n?.aborted?Promise.resolve(0):s?new Promise(a=>{const c=o.scrollTop,m=o.scrollLeft,f=performance.now();let l;const d=()=>(performance.now()-f)/s,p=()=>{cancelAnimationFrame(l);const e=d();a(e)};n?.addEventListener("abort",p);const v=()=>{const e=d(),T=t===void 0?void 0:c+(t-c)*i(e),b=r===void 0?void 0:m+(r-m)*i(e);e<1?(o.scrollTo({top:T,left:b}),l=requestAnimationFrame(v)):(o.scrollTo({top:t,left:r}),n?.removeEventListener("abort",p),a(1))};l=requestAnimationFrame(v)}):(o.scrollTo({top:t,left:r}),Promise.resolve(1));export{L as easingScroll};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "easing-scroll",
+  "version": "1.0.0",
+  "description": "♿️ Smooth scrolling",
+  "type": "module",
+  "source": "src/index.ts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./easing-scroll": {
+      "require": "./dist/easing-scroll.js",
+      "import": "./dist/easing-scroll.mjs",
+      "default": "./dist/easing-scroll.mjs"
+    }
+  },
+  "scripts": {
+    "check-types": "tsc",
+    "clean": "rm -r dist/*",
+    "build": "npm run clean && rollup -c",
+    "release": "npm run check-types && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faustienf/easing-scroll.git"
+  },
+  "keywords": [
+    "scroll",
+    "smooth",
+    "smooth-scroll",
+    "easing"
+  ],
+  "author": "@faustien",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/faustienf/easing-scroll/issues"
+  },
+  "homepage": "https://github.com/faustienf/easing-scroll#readme",
+  "prettier": {},
+  "devDependencies": {
+    "esbuild": "^0.16.12",
+    "rollup": "^3.9.0",
+    "rollup-plugin-esbuild": "^5.0.0",
+    "rollup-plugin-typescript2": "^0.34.1",
+    "typescript": "^4.9.4"
+  }
+}

package/src/easing-scroll.ts

@@ -0,0 +1,78 @@
+type Px = number;
+type Ms = number;
+/**
+ * Percent is number 0 - 1
+ *
+ * 0 = 0%, 1 = 100%
+ */
+type Pct = number;
+
+type Options = {
+  top: Px;
+  left: Px;
+  duration: Ms;
+  signal: AbortSignal;
+  /**
+   * @see Easing functions https://easings.net
+   */
+  easing: (t: Pct) => Pct;
+};
+
+const linear = (t: number): number => t;
+
+export const easingScroll = <E extends Element>(
+  target: E,
+  { top, left, signal, duration = 0, easing = linear }: Partial<Options>
+): Promise<Pct> => {
+  if (signal?.aborted) {
+    return Promise.resolve(0);
+  }
+
+  if (!duration) {
+    target.scrollTo({ top, left });
+    return Promise.resolve(1);
+  }
+
+  return new Promise<Pct>((resolve) => {
+    const startTop = target.scrollTop;
+    const startLeft = target.scrollLeft;
+    const startTimestamp = performance.now();
+    let ramID: number;
+
+    const getProgress = (): Pct => {
+      const elapsed = performance.now() - startTimestamp;
+      return elapsed / duration;
+    };
+
+    const abortHandler = () => {
+      cancelAnimationFrame(ramID);
+      const progress = getProgress();
+      resolve(progress);
+    };
+
+    signal?.addEventListener("abort", abortHandler);
+
+    const tick = () => {
+      const progress = getProgress();
+      const tickTop =
+        top === undefined
+          ? undefined
+          : startTop + (top - startTop) * easing(progress);
+      const tickLeft =
+        left === undefined
+          ? undefined
+          : startLeft + (left - startLeft) * easing(progress);
+
+      if (progress < 1) {
+        target.scrollTo({ top: tickTop, left: tickLeft });
+        ramID = requestAnimationFrame(tick);
+      } else {
+        target.scrollTo({ top, left });
+        signal?.removeEventListener("abort", abortHandler);
+        resolve(1);
+      }
+    };
+
+    ramID = requestAnimationFrame(tick);
+  });
+};

package/src/index.ts

@@ -0,0 +1 @@
+export { easingScroll } from "./easing-scroll";