easing-scroll 1.0.3 → 1.0.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 ☃︎
+Copyright (c) 2022-2026 ☃︎
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,23 @@
 # easing-scroll
 
-[![npm-version](https://img.shields.io/npm/v/easing-scroll.svg)](https://npmjs.org/package/easing-scroll)
+[![npm version](https://img.shields.io/npm/v/easing-scroll.svg)](https://npmjs.org/package/easing-scroll)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/easing-scroll)](https://bundlephobia.com/package/easing-scroll)
+[![license](https://img.shields.io/npm/l/easing-scroll.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org)
 
-♿️ Smooth scrolling. [Demo](https://easing-scroll.vercel.app).
+Programmatic smooth scrolling with custom easing, abort support, and promise-based completion tracking.
+
+[Demo](https://easing-scroll-liard.vercel.app)
+
+## Highlights
+
+- **Zero dependencies** — ~450 bytes min+gzip
+- **TypeScript-first** — written in TypeScript, ships type declarations
+- **Dual package** — ESM and CJS builds
+- **Customizable** — bring your own [easing function](https://easings.net)
+- **Cancellable** — abort with [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+- **Promise-based** — `await` completion or track partial progress
+- **Universal** — works with any scrollable `Element`
 
 ## Install
 
@@ -10,89 +25,125 @@
 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
+```sh
+pnpm add easing-scroll
+```
 
-## Usage
+## Quick Start
 
 ```ts
 import { easingScroll } from "easing-scroll";
 
-const controller = new AbortController();
-// Abort scrolling
-// controller.abort(); ❌
-
-const target = document.querySelector(".container");
+const container = 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),
+await easingScroll(container, {
+  top: 300,
+  duration: 400,
+  easing: (x) => 1 - Math.pow(1 - x, 3), // easeOutCubic
 });
-
-if (progress === 1) {
-  console.log("Completed");
-} else {
-  console.log("Aborted");
-}
 ```
 
-### Animation
+## API
+
+### `easingScroll(target, options): Promise<number>`
+
+Smoothly scrolls `target` to the given position.
+
+#### `target`
+
+Type: `Element`
+
+Any scrollable DOM element.
 
-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.
+#### `options`
+
+| Option     | Type                    | Default    | Description                                                                  |
+| ---------- | ----------------------- | ---------- | ---------------------------------------------------------------------------- |
+| `top`      | `number`                | —          | Target vertical scroll position in pixels                                    |
+| `left`     | `number`                | —          | Target horizontal scroll position in pixels                                  |
+| `duration` | `number`                | `0`        | Animation duration in milliseconds                                           |
+| `easing`   | `(t: number) => number` | `(t) => t` | [Easing function](https://easings.net) mapping progress (0–1) to eased value |
+| `signal`   | `AbortSignal`           | —          | Signal to cancel the animation                                               |
+
+#### Return value
+
+Resolves with a `number` between `0` and `1` representing animation progress:
+
+| Value       | Meaning                                              |
+| ----------- | ---------------------------------------------------- |
+| `1`         | Animation completed fully                            |
+| `0 < x < 1` | Animation was aborted at _x_ progress                |
+| `0`         | Animation never started (signal was already aborted) |
+
+### Behavior
+
+- **Instant scroll** — when `duration` is `0` or negative, the element scrolls instantly and resolves `1`.
+- **No-op** — when both `top` and `left` are omitted, resolves `1` immediately.
+- **Clamping** — scroll values are clamped to the element's scrollable range. No visual flash occurs.
+- **Already-aborted signal** — resolves `0` without scrolling.
+
+## Examples
+
+### Custom Easing
+
+The default easing is linear `(t) => t`. Pass any function from [easings.net](https://easings.net):
 
 ```ts
-easingScroll(target, {
-  duration: 400, // ms
-  // 👀 https://easings.net/#easeOutCubic
+await easingScroll(element, {
+  top: 500,
+  duration: 600,
+  // https://easings.net/#easeOutCubic
   easing: (x) => 1 - Math.pow(1 - x, 3),
 });
 ```
 
-### Abort scrolling
+### Abort Scrolling
 
-Pass `signal` ([AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)),
-if you want to abort scrolling.
+Use an `AbortController` to cancel an in-flight animation:
 
 ```ts
 const controller = new AbortController();
-setTimeout(() => {
-  controller.abort();
-}, 100);
 
-const progress = await easingScroll(target, {
-  ...,
+setTimeout(() => controller.abort(), 100);
+
+const progress = await easingScroll(element, {
+  top: 1000,
+  duration: 400,
   signal: controller.signal,
 });
 
-if (progress !== 1) {
-  console.log('Scrolling has been aborted.');
+if (progress < 1) {
+  console.log(`Aborted at ${Math.round(progress * 100)}%`);
 }
 ```
 
-`progress` is a number from _0_ to _1_.
+### React Hook
 
-`1` - Scrolling is completed _100%_.
+A reusable hook that cancels the previous scroll when dependencies change or the component unmounts:
 
-`<1` - Scrolling has been aborted and completed _x%_.
+```tsx
+import { useEffect, RefObject } from "react";
+import { easingScroll } from "easing-scroll";
 
-```ts
-const progress = await easingScroll(target, {
-  ...,
-});
+function useEasingScroll(ref: RefObject<HTMLElement | null>, top: number) {
+  useEffect(() => {
+    const target = ref.current;
+    if (!target) return;
 
-if (progress !== 1) {
-  console.log('Scrolling has been aborted.');
-} else {
-  console.log('Completed.');
+    const controller = new AbortController();
+
+    easingScroll(target, {
+      top,
+      duration: 400,
+      signal: controller.signal,
+      easing: (x) => 1 - Math.pow(1 - x, 3),
+    });
+
+    return () => controller.abort();
+  }, [top]);
 }
 ```
+
+## License
+
+[MIT](LICENSE)

package/dist/easing-scroll.cjs

@@ -0,0 +1 @@
+"use strict";var f=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var y=(e,n)=>{for(var s in n)f(e,s,{get:n[s],enumerable:!0})},A=(e,n,s,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of M(n))!v.call(e,o)&&o!==s&&f(e,o,{get:()=>n[o],enumerable:!(r=x(n,o))||r.enumerable});return e};var O=e=>A(f({},"__esModule",{value:!0}),e);var h={};y(h,{easingScroll:()=>F});module.exports=O(h);var k=e=>e,l=(e,n,s)=>{e.scrollTop=n??e.scrollTop,e.scrollLeft=s??e.scrollLeft},F=(e,{top:n,left:s,signal:r,duration:o=0,easing:p=k})=>r?.aborted?Promise.resolve(0):n===void 0&&s===void 0?Promise.resolve(1):o<=0?(l(e,n,s),Promise.resolve(1)):new Promise(P=>{let d=e.scrollTop,u=e.scrollLeft;l(e,n,s),n=e.scrollTop,s=e.scrollLeft,e.scrollTop=d,e.scrollLeft=u;let c,m,a=t=>c===void 0?0:(t-c)/o,b=()=>{cancelAnimationFrame(m);let t=Math.max(0,Math.min(a(performance.now()),1));P(t)};r?.addEventListener("abort",b,{once:!0});let L=t=>{c===void 0&&(c=t);let i=a(t),T=n===void 0?void 0:d+(n-d)*p(i),E=s===void 0?void 0:u+(s-u)*p(i);if(i<1)l(e,T,E),m=requestAnimationFrame(L);else{l(e,n,s),r?.removeEventListener("abort",b),P(1);return}};m=requestAnimationFrame(L)});0&&(module.exports={easingScroll});

package/dist/easing-scroll.d.cts

@@ -0,0 +1,60 @@
+/** Pixel value */
+type Px = number;
+/** Milliseconds value */
+type Ms = number;
+/**
+ * Progress percentage as a number between 0 and 1.
+ *
+ * - `0` — 0% (animation not started or aborted immediately)
+ * - `1` — 100% (animation completed)
+ * - `0 < value < 1` — partial progress (animation was aborted mid-way)
+ */
+type Pct = number;
+type Options = {
+    /** Target vertical scroll position in pixels */
+    top?: Px;
+    /** Target horizontal scroll position in pixels */
+    left?: Px;
+    /**
+     * Animation duration in milliseconds.
+     * If `0` or negative, scrolls instantly without animation.
+     * @default 0
+     */
+    duration?: Ms;
+    /**
+     * An `AbortSignal` to cancel the scroll animation.
+     * When aborted, the promise resolves with the current progress (0–1).
+     */
+    signal?: AbortSignal;
+    /**
+     * Easing function that maps animation progress `t` (0–1) to eased value.
+     * @default linear
+     * @see Easing functions https://easings.net
+     */
+    easing?: (t: Pct) => Pct;
+};
+/**
+ * Smoothly scroll an element to the given position using a custom easing function.
+ *
+ * @param target - The scrollable HTML element
+ * @param options - Scroll options (top, left, duration, easing, signal)
+ * @returns A promise that resolves with the animation progress:
+ *   - `1` if the animation completed fully
+ *   - `0` if the signal was already aborted before starting
+ *   - `0 < value < 1` if the animation was aborted mid-way
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ *
+ * const progress = await easingScroll(element, {
+ *   top: 500,
+ *   duration: 400,
+ *   easing: (t) => 1 - Math.pow(1 - t, 3), // easeOutCubic
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+declare const easingScroll: <E extends Element>(target: E, { top, left, signal, duration, easing }: Options) => Promise<Pct>;
+
+export { easingScroll };

package/dist/easing-scroll.d.ts

@@ -1,20 +1,60 @@
-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 HTMLElement>(target: E, { top, left, signal, duration, easing }: Options) => Promise<Pct>;
-export {};
+/** Pixel value */
+type Px = number;
+/** Milliseconds value */
+type Ms = number;
+/**
+ * Progress percentage as a number between 0 and 1.
+ *
+ * - `0` — 0% (animation not started or aborted immediately)
+ * - `1` — 100% (animation completed)
+ * - `0 < value < 1` — partial progress (animation was aborted mid-way)
+ */
+type Pct = number;
+type Options = {
+    /** Target vertical scroll position in pixels */
+    top?: Px;
+    /** Target horizontal scroll position in pixels */
+    left?: Px;
+    /**
+     * Animation duration in milliseconds.
+     * If `0` or negative, scrolls instantly without animation.
+     * @default 0
+     */
+    duration?: Ms;
+    /**
+     * An `AbortSignal` to cancel the scroll animation.
+     * When aborted, the promise resolves with the current progress (0–1).
+     */
+    signal?: AbortSignal;
+    /**
+     * Easing function that maps animation progress `t` (0–1) to eased value.
+     * @default linear
+     * @see Easing functions https://easings.net
+     */
+    easing?: (t: Pct) => Pct;
+};
+/**
+ * Smoothly scroll an element to the given position using a custom easing function.
+ *
+ * @param target - The scrollable HTML element
+ * @param options - Scroll options (top, left, duration, easing, signal)
+ * @returns A promise that resolves with the animation progress:
+ *   - `1` if the animation completed fully
+ *   - `0` if the signal was already aborted before starting
+ *   - `0 < value < 1` if the animation was aborted mid-way
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ *
+ * const progress = await easingScroll(element, {
+ *   top: 500,
+ *   duration: 400,
+ *   easing: (t) => 1 - Math.pow(1 - t, 3), // easeOutCubic
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+declare const easingScroll: <E extends Element>(target: E, { top, left, signal, duration, easing }: Options) => Promise<Pct>;
+
+export { easingScroll };

package/dist/easing-scroll.js

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

package/package.json

@@ -1,31 +1,31 @@
 {
   "name": "easing-scroll",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "♿️ Smooth scrolling",
   "type": "module",
-  "source": "src/index.ts",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "types": "dist/easing-scroll.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"
+      "types": "./dist/easing-scroll.d.ts",
+      "require": {
+        "types": "./dist/easing-scroll.d.cts",
+        "default": "./dist/easing-scroll.cjs"
+      },
+      "import": "./dist/easing-scroll.js"
     }
   },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
   "scripts": {
+    "test": "vitest run",
     "check-types": "tsc",
-    "clean": "rm -r dist/*",
-    "build": "npm run clean && rollup -c",
+    "build": "tsup src/easing-scroll.ts --format cjs,esm --dts --minify --clean",
     "release:patch": "npm version patch",
     "preversion": "npm run check-types && npm run build",
-    "postversion": "git add . && git push && git push --tags && npm publish"
+    "postversion": "git add . && git push && git push --tags && npm publish",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
@@ -43,12 +43,13 @@
     "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"
+    "@vitest/coverage-v8": "^4.0.18",
+    "esbuild": "^0.27.3",
+    "husky": "^9.1.7",
+    "jsdom": "^28.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }

package/dist/easing-scroll.mjs

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/index.mjs

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

package/src/easing-scroll.ts

@@ -1,92 +0,0 @@
-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;
-
-const scrollTo = <E extends HTMLElement>(
-  target: E,
-  top: Options["top"],
-  left: Options["left"]
-) => {
-  target.scrollTop = top ?? target.scrollTop;
-  target.scrollLeft = left ?? target.scrollLeft;
-};
-
-export const easingScroll = <E extends HTMLElement>(
-  target: E,
-  { top, left, signal, duration = 0, easing = linear }: Options
-): Promise<Pct> => {
-  if (signal?.aborted) {
-    return Promise.resolve(0);
-  }
-
-  if (!duration) {
-    scrollTo(target, top, left);
-    return Promise.resolve(1);
-  }
-
-  return new Promise<Pct>((resolve) => {
-    const startTop = target.scrollTop;
-    const startLeft = target.scrollLeft;
-
-    scrollTo(target, top, left);
-    top = target.scrollTop;
-    left = 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) {
-        scrollTo(target, tickTop, tickLeft);
-        ramID = requestAnimationFrame(tick);
-      } else {
-        scrollTo(target, top, left);
-        signal?.removeEventListener("abort", abortHandler);
-        resolve(1);
-      }
-    };
-
-    ramID = requestAnimationFrame(tick);
-  });
-};

package/src/index.ts

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