npm package: @loadingio/paginate
Description: Pagination library
Author: zbryikt
Latest version: 0.1.1

# @loadingio/paginate

Fetching data with paging functionality supported:

 - keep pagination state ( `limit` & `offset` )
 - auto fetching on scrolling or event
 - stop fetching on end of data ( returned length < limit )


# Usage

install dependencies (`proxise` and `@loadingio/debounce.js`) and `@loadingio/paginate` via npm:

    npm install @loadingio/paginate proxise @loadingio/debounce.js

and include them in HTML:

    <script src="path-to/debounce.js/index.min.js"></script>
    <script src="path-to/proxise/index.min.js"></script>
    <script src="path-to/paginate/index.min.js"></script>


create a paginate object:

    mypal = new paginate({
      fetch: -> ld$.fetch '...' , {}, {type: \json}
    })


you can process fetched data directly in the fetch function:

    mypal = new paginate do
      fetch: ->
        ld$.fetch '...' , {}, {type: \json}
          .then ->
            render(it)
            return it /* should return the fetched list */


see also `sample/index.ls`.


## Constructor Options

 - `limit`: default 20. maximal count return per fetch
 - `offset`: default 0. offset for fetch to start
 - `host`: container that scrolls. default `document.scrollingElement`.
 - `pivot`: element for determining if we should scroll. omitted if not provided.
   - when provided, `intersectionObserver` is used
 - `scrollDelay`: default 100. debounce time (ms) before fetching after scrolled.
 - `fetchDelay`: default 200. debounce time (ms) before fetching when fetch is called.
 - `fetchOnScroll`: default false. when true, fetch when scrolling to the bottom of `host`.
   - only applicable if `host` is provided
 - `fetchOnInit`: default false. should a fetch be called after init. possible values:
   - `always`: fetch after both `init` and `reset`
   - `once`:  fetch only after `init`
   - `lazy`: fetch when visibility of `host` is changed to visible, and `offset` = 0
   - false: never fetch on init
 - `boundary`: threshold of the distance to `host` bottom to trigger fetch.
   - default 5. rounding may lead to extra px uncounted so a small default value 5 is used here.
   - omitted if `fetchOnScroll` is false.
   - larger `boundary` makes fetch triggered earlier.
 - `fetch`: required custom function to fetch data according to `@loadingio/paginate`'s status.
   - when called, - use `this.limit` and `this.offset` for current position of fetch progress.
   - should return an Array. `@loadingio/paginate` use it to update `this.offset` and count progress.
 - `enabled`: default true. when false, fetch won't start until re-enabled by `toggle(v)`.


## Method

 - `reset()`: reset page.
 - `fetch()`: fetch data again.
 - `isEnd()`: is there anything to fetch.
 - `host(node)`: set scrolling host. use document.scrollingElement for the webpage itself.
 - `host(pivot)`: set pivot element ( for detecting refreshing )
 - `toggle(v)`: flip enabled/disabled statue. force set to v if v(true or false) is provided.


## Events

 - `empty`: fired when `@loadingio/paginate` confirms that the list is empty.
 - `finish`: fired when `@loadingio/paginate` confirms that all items are fetched.
 - `fetch`: fired when `@loadingio/paginate` fetch a new list of data
 - `scroll.fetch`: fired when `@loadingio/paginate` fetch a new list of data triggered by scrolling.
   - can happen along with `fetch` event.
 - `fetching`: fired before fetch is called.


## Auto Fetching Policy

You can decide when to fetch data by yourself but `@loadingio/pagination` still provides some handy mechanism to watch for scrolling or intersection events for you with following 2 options:

 - `fetchOnScroll`: when set to true, this triggers fetch when
   - `pivot` becomes visible ( if pivot is provided )
   - user scrolls to the bottom of `host` element ( if pivot is not provided )
     - this relies on `scroll` event and related attribues such as `scrollTop` thus is less efficient.
 - `fetchOnInit`: this defines how fetch should be done initially.
   - `always`: fetch called after paginate object constructed and reset everytime.
   - `once`: fetch called only after paginate object constructed.
   - `lazy`: fetch called only if offset = 0 and `host` becomes visible.
   - false: no fetch for initialization.

These are handy however may introduce inconsistency and confusion. Set both of them to `false` if you'd like to control how fetching is done manually.


# License

MIT