svelte-infinite 0.2.2 → 0.3.0

package/README.md

@@ -12,15 +12,18 @@
 [![](https://img.shields.io/npm/dm/svelte-infinite?style=for-the-badge&labelColor=black&color=black)](https://npmjs.org/packages/svelte-infinite)
 [![](https://img.shields.io/badge/demo-black?style=for-the-badge&logo=&logoColor=white&labelColor=black&color=black)](https://svelte-5-infinite.vercel.app)
 
-> Svelte Infinite Loader designed and rebuilt specifically for use in **Svelte 5** with runes
+> Svelte Infinite Loader designed and rebuilt specifically for use with **Svelte 5**
 
 ✨ Flexible  
 ⏰ Infinite Loop Detection  
 📣 Control Loader State  
 🔎 `IntersectionObserver` based  
+🔥 Using Runes and Snippets  
 🧑‍🔧 **Demo**: [svelte-5-infinite.vercel.app](https://svelte-5-infinite.vercel.app)
 
-Svelte 5 is still early days, but I couldn't find an infinite loader-type component that was maintained for the last few years of Svelte 4. So I had recently built this for a Svelte 5-based application I was working on and was pretty happy with it, so I decided to clean it up and share it with the world! As Svelte 5 inevitably changes over the next weeks and months, I plan to keep this package updated and working with the latest available version of Svelte 5.
+Svelte 5 is still early days, but I couldn't find an infinite loader-type component that was maintained for the last few years of Svelte 4 even. So I had recently built this for a Svelte 5-based application I'm working on and was pretty happy with it, so I decided to share it with the world! 
+
+As Svelte 5 inevitably changes over the next weeks and months, I plan to keep this package updated and working with the latest available version of Svelte 5. Don't hesitate to open an issue if something has changed in the latest Svelte releases or you come across a bug!
 
 ## 🏗️ Getting Started
 
@@ -55,25 +58,26 @@ yarn add svelte-infinite
 </InfiniteLoader>
 ```
 
-The component should wrap your list of items, and `loaderState` should be used in your `triggerLoad` function (and/or elsewhere) to interact with the internal state of the Loader component. You tell it whether you're out of data, ran into an error, etc.
-
-See the example below and [in this repository](https://github.com/ndom91/svelte-infinite/blob/main/src/routes/%2Bpage.svelte#L12-L50) for more details.
-
 ## 🍍 Example
 
+This is a more realistic example use-case which includes a paginated data endpoint that your `triggerLoad` function should hit every time it's called to load more data. It also includes the use of some of the optional snippets to render custom markup inside the loader component.
+
 ```svelte
 <script lang="ts">
+  // +page.svelte
+
   import { InfiniteLoader, loaderState } from "svelte-infinite"
   import UserCard from "$components/UserCard.svelte"
 
   const LOAD_LIMIT = 20
+  // Assume `$page.data.items` is the `+page.server.ts` server-side loaded
+  // and rendered initial 20 items of the list
   const allItems = $state<{ id: number, body: string }[]>($page.data.items)
   let pageNumber = $state(1)
 
-  // 1. You'll have to pass the InfiniteLoader component a load function
+  // 1. This `loadMore` function is what we'll pass the InfiniteLoader component
   // to its `triggerLoad` prop.
   const loadMore = async () => {
-    // This is a relatively straight-forward load function with support for pagination
     try {
       pageNumber += 1
       const limit = String(LOAD_LIMIT)
@@ -82,20 +86,21 @@ See the example below and [in this repository](https://github.com/ndom91/svelte-
       // If there are less results on the first page (page.server loaded data)
       // than the limit, don't keep trying to fetch more. We're done.
       if (allItems.length < LOAD_LIMIT) {
-        loaderState.complete()
+        loaderState.complete()               // <--- using loaderState
         return
       }
 
       const searchParams = new URLSearchParams({ limit, skip })
 
-      // Execute the API call to grab more data
+      // Fetch an endpoint that supports server-side pagination
       const dataResponse = await fetch(`/api/data?${searchParams}`)
 
       // Ideally, like most paginated endpoints, this should return the data
       // you've requested for your page, as well as the total amount of data
       // available to page through
+
       if (!dataResponse.ok) {
-        loaderState.error()
+        loaderState.error()                 // <--- using loaderState
 
         // On errors, set the pageNumber back so we can retry
         // that page's data on the next 'loadMore' attempt
@@ -104,8 +109,7 @@ See the example below and [in this repository](https://github.com/ndom91/svelte-
       }
       const data = await dataResponse.json()
 
-      // If we've received data, push it to the reactive state variable
-      // rendering our items inside the `<InfiniteLoader />` below.
+      // If we've successfully received data, push it to the reactive state variable
       if (data.items.length) {
         allItems.push(...data.items)
       }
@@ -113,13 +117,13 @@ See the example below and [in this repository](https://github.com/ndom91/svelte-
       // If there are more (or equal) number of items loaded as are totally available
       // from the API, don't keep trying to fetch more. We're done.
       if (allItems.length >= data.totalCount) {
-        loaderState.complete()
+        loaderState.complete()               // <--- using loaderState
       } else {
-        loaderState.loaded()
+        loaderState.loaded()                 // <--- using loaderState
       }
     } catch (error) {
       console.error(error)
-      loaderState.error()
+      loaderState.error()                   // <--- using loaderState
       pageNumber -= 1
     }
   }
@@ -155,36 +159,36 @@ This package consists of two parts, first the `InfiniteLoader` component which i
 
 Second, there is also a `loaderState` import which you should use to interact with the internal state of the loader. For example, if your `fetch` call errored, or you've reached the maximum number of items, etc. you can communicate that to the loader. The most basic usage example can be seen in the 'Getting Started' section above. A more complex example can be seen in the 'Example' section, and of course the application in `/src/routes/+page.svelte` in this repository also has a "real-world" usage example.
 
-### loaderState
+### `loaderState` Controller
 
-The `loaderState` import is an object with 4 methods on it:
+The `loaderState` controller has 4 methods on it. You should call these at the appropriate times to control the internal state of the `InfiniteLoader`.
 
 - `loaderState.loaded()`
-  - Designed to be called after a successful fetch.
+  - Designed to be called after a successful fetch. Will set the internal state back to `READY` so another fetch can be attempted.
 - `loaderState.error()`
   - Designed to be called after a failed fetch or any other error. This will cause the `InfiniteLoader` to render a "Retry" button by default, or the `error` snippet.
 - `loaderState.complete()`
-  - Designed to be called when you've reached the end of your list and there are no more items to fetch. This will render a "No more data" string, or the `no-data` snippet.
+  - Designed to be called when you've reached the end of your list and there are no more items to fetch. This will render a "No more data" string, or the `noData` snippet.
 - `loaderState.reset()`
-  - Designed to be called when you want to reset the state of the `InfiniteLoader` to its initial state, for example if there is a search input tied to your infinite list and the user enters a new query.
+  - Designed to be called when you want to reset the state of the `InfiniteLoader` to its initial state, for example if there is a search input tied to your data and the user enters a new query.
 
-### Props
+### `InfiniteLoader` Props
 
 - `triggerLoad: () => Promise<void>` - **required**
   - The async function to call when we should attempt to load more data to show.
 - `intersectionOptions: `[`IntersectionObserverInit`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#options)` = { rootMargin: "0px 0px 200px 0px" }` - optional
   - The options to pass to the `IntersectionObserver` instance. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#options) for more details. The default `rootMargin` value will cause the target to intersect 200px earlier and trigger the `loadMore` function before it actually intersects with the root element (window by default). This has the effect of beginning to load the next page of data before the user has actually reached the current bottom of the list, making the experience feel more smooth.
-  - It may also be required to pass in a reference to your scroll container as the `root` option, if your scroll container is not the window.
-- `loopTimeout: number = 2000` - optional
-  - If the `loopMaxCalls` is reached within the detection timeout, a cool down period is triggered of this length (in milliseconds).
-- `loopDetectionTimeout: number = 1000` - optional
-  - The time in milliseconds in which the `loopMaxCalls` count must be hit in order to trigger a cool down period of `loopTimeout` length.
+  - If you are using a separate scroll container (element with `overflow-y: scroll`) other than the window / viewport, then it might be necessary for you to also pass a [custom `root` element](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/root) here.
+- `loopTimeout: number = 3000` - optional
+  - Length of the cool down period (in milliseconds).
+- `loopDetectionTimeout: number = 2000` - optional
+  - The time in milliseconds in which the `loopMaxCalls` count must be hit in order to trigger a cool down period.
 - `loopMaxCalls: number = 5` - optional
-  - The number of calls to the `triggerLoad` function within timeout which should trigger cool down period.
+  - The limit of `triggerLoad` executions which will trigger a cool down period, if reached within the `loopDetectionTimeout`.
 
-### Snippets
+### `InfiniteLoader` Snippets
 
-Snippets [replace slots](https://svelte-5-preview.vercel.app/docs/snippets#snippets-and-slots) in Svelte 5, and as such are used here to customize the content shown at the bottom of the scroller in various states. The `InfiniteLoader` component has 4 props for snippets available.
+Snippets [replace slots](https://svelte-5-preview.vercel.app/docs/snippets#snippets-and-slots) in Svelte 5, and as such are used here to customize the content shown at the bottom of the scroller in various states. The `InfiniteLoader` component has 5 snippet "slots" available.
 
 - `loading`
   - Shown while calling `triggerLoad` and waiting on a response.

package/dist/InfiniteLoader.svelte

@@ -1,35 +1,9 @@
-<script context="module">const STATUS = {
-  READY: "READY",
-  LOADING: "LOADING",
-  COMPLETE: "COMPLETE",
-  ERROR: "ERROR"
-};
-let isFirstLoad = $state(true);
-let status = $state(STATUS.READY);
-export const loaderState = {
-  loaded: () => {
-    isFirstLoad = false;
-    status = STATUS.READY;
-  },
-  complete: () => {
-    isFirstLoad = false;
-    status = STATUS.COMPLETE;
-  },
-  reset: () => {
-    status = STATUS.READY;
-    isFirstLoad = true;
-  },
-  error: () => {
-    status = STATUS.ERROR;
-  }
-};
-</script>
-
 <script>import { onMount, onDestroy } from "svelte";
+import { STATUS, loaderState } from "./loaderState.svelte";
 const {
   triggerLoad,
-  loopTimeout = 2e3,
-  loopDetectionTimeout = 1e3,
+  loopTimeout = 3e3,
+  loopDetectionTimeout = 2e3,
   loopMaxCalls = 5,
   intersectionOptions = {},
   children,
@@ -64,24 +38,24 @@ class LoopTracker {
 const loopTracker = new LoopTracker();
 let intersectionTarget = $state();
 let observer = $state();
-let showLoading = $derived(status === STATUS.LOADING);
-let showError = $derived(status === STATUS.ERROR);
-let showNoResults = $derived(status === STATUS.COMPLETE && isFirstLoad);
-let showNoData = $derived(status === STATUS.COMPLETE && !isFirstLoad);
-let showCoolingOff = $derived(status !== STATUS.COMPLETE && loopTracker.coolingOff);
+let showLoading = $derived(loaderState.status === STATUS.LOADING);
+let showError = $derived(loaderState.status === STATUS.ERROR);
+let showNoResults = $derived(loaderState.status === STATUS.COMPLETE && loaderState.isFirstLoad);
+let showNoData = $derived(loaderState.status === STATUS.COMPLETE && !loaderState.isFirstLoad);
+let showCoolingOff = $derived(loaderState.status !== STATUS.COMPLETE && loopTracker.coolingOff);
 async function attemptLoad() {
-  if (status === STATUS.COMPLETE || status !== STATUS.READY && status !== STATUS.ERROR) {
+  if (loaderState.status === STATUS.COMPLETE || loaderState.status !== STATUS.READY && loaderState.status !== STATUS.ERROR) {
     return;
   }
-  status = STATUS.LOADING;
+  loaderState.status = STATUS.LOADING;
   if (!loopTracker.coolingOff) {
     await triggerLoad();
     loopTracker.track();
   }
-  if (status !== STATUS.ERROR && status !== STATUS.COMPLETE) {
-    if (status === STATUS.LOADING) {
-      status = STATUS.READY;
-      isFirstLoad = false;
+  if (loaderState.status !== STATUS.ERROR && loaderState.status !== STATUS.COMPLETE) {
+    if (loaderState.status === STATUS.LOADING) {
+      loaderState.status = STATUS.READY;
+      loaderState.isFirstLoad = false;
     }
   }
 }
@@ -148,7 +122,11 @@ onDestroy(() => {
       {:else}
         <div class="infinite-error">
           <div class="infinite-label">Oops, something went wrong</div>
-          <button class="infinite-btn" disabled={status === STATUS.COMPLETE} onclick={attemptLoad}>
+          <button
+            class="infinite-btn"
+            disabled={loaderState.status === STATUS.COMPLETE}
+            onclick={attemptLoad}
+          >
             Retry
           </button>
         </div>

package/dist/InfiniteLoader.svelte.d.ts

@@ -1,10 +1,4 @@
 import { SvelteComponent } from "svelte";
-export declare const loaderState: {
-    loaded: () => void;
-    complete: () => void;
-    reset: () => void;
-    error: () => void;
-};
 import { type Snippet } from "svelte";
 declare const __propDef: {
     props: {

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import InfiniteLoader, { loaderState } from "./InfiniteLoader.svelte";
+import InfiniteLoader from "./InfiniteLoader.svelte";
+import { loaderState } from "./loaderState.svelte";
 export { InfiniteLoader, loaderState };

package/dist/index.js

@@ -1,2 +1,3 @@
-import InfiniteLoader, { loaderState } from "./InfiniteLoader.svelte";
+import InfiniteLoader from "./InfiniteLoader.svelte";
+import { loaderState } from "./loaderState.svelte";
 export { InfiniteLoader, loaderState };

package/dist/loaderState.svelte.d.ts

@@ -0,0 +1,16 @@
+export declare const STATUS: {
+    readonly READY: "READY";
+    readonly LOADING: "LOADING";
+    readonly COMPLETE: "COMPLETE";
+    readonly ERROR: "ERROR";
+};
+declare class LoaderState {
+    isFirstLoad: boolean;
+    status: "READY" | "LOADING" | "COMPLETE" | "ERROR";
+    loaded: () => void;
+    complete: () => void;
+    reset: () => void;
+    error: () => void;
+}
+export declare const loaderState: LoaderState;
+export {};

package/dist/loaderState.svelte.js

@@ -0,0 +1,26 @@
+export const STATUS = {
+    READY: "READY",
+    LOADING: "LOADING",
+    COMPLETE: "COMPLETE",
+    ERROR: "ERROR"
+};
+class LoaderState {
+    isFirstLoad = $state(true);
+    status = $state(STATUS.READY);
+    loaded = () => {
+        this.isFirstLoad = false;
+        this.status = STATUS.READY;
+    };
+    complete = () => {
+        this.isFirstLoad = false;
+        this.status = STATUS.COMPLETE;
+    };
+    reset = () => {
+        this.isFirstLoad = true;
+        this.status = STATUS.READY;
+    };
+    error = () => {
+        this.status = STATUS.ERROR;
+    };
+}
+export const loaderState = new LoaderState();

package/package.json

@@ -6,7 +6,7 @@
     "email": "yo@ndo.dev",
     "url": "https://ndo.dev"
   },
-  "version": "0.2.2",
+  "version": "0.3.0",
   "license": "MIT",
   "homepage": "https://svelte-5-infinite.vercel.app",
   "keywords": [
@@ -57,6 +57,7 @@
     "svelte-check": "^3.6.6",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3",
+    "typescript-svelte-plugin": "^0.3.37",
     "vite": "^5.1.4",
     "vitest": "^1.3.1"
   },