@vtaits/filterlist

Api reference

Util for creating lists with filters, sotring, paginatinon, endless scroll etc.

Installation

npm install @vtaits/filterlist --save

or

yarn add @vtaits/filterlist

or

bun add @vtaits/filterlist

Api

1import { Filterlist } from '@vtaits/filterlist';
2
3/*
4 * assuming the API returns something like this:
5 *   const json = {
6 *     results: [
7 *       {
8 *         value: 1,
9 *         label: 'Audi',
10 *       },
11 *       {
12 *         value: 2,
13 *         label: 'Mercedes',
14 *       },
15 *       {
16 *         value: 3,
17 *         label: 'BMW',
18 *       },
19 *     ],
20 *     total: 50,
21 *   };
22 */
23
24const filterlist = new Filterlist({
25  loadItems: async ({
26    // currently applied filters
27    appliedFilters,
28    // current page
29    page,
30    // number of items on one page
31    pageSize,
32    // sorting state
33    sort: {
34      // sorting parameter
35      param,
36      // asc or desc (boolean)
37      asc,
38    },
39  }, {
40    items,
41  }) => {
42    const response = await fetch(`/awesome-api-url/?page=${page}`);
43    const responseJSON = await response.json();
44
45    return {
46      items: responseJSON.results,
47      total: responseJSON.total,
48    };
49  },
50});
51
52filterlist.emitter.on(eventTypes.changeListState, (nextListState) => {
53  // change ui
54  document.getElementById('loader').style.display = nextListState.loading ? 'block' : 'none';
55});
56
57// load next chunk of   for the infinite list
58filterlist.loadMore();
59
60// change runtime value of filter (e.g. on keyboard input)
61filterlist.setFilterValue('foo', 'bar');
62
63// apply runtime value and reload the list
64filterlist.applyFilter('foo');
65
66// change value of the filter and reload the list
67filterlist.setAndApplyFilter('foo', 'bar');
68
69// reset value of the filter and reload the list
70filterlist.resetFilter('foo');
71
72// bulk change values of filters (e.g. on keyboard input)
73filterlist.setFiltersValues({
74  foo: 'value',
75  bar: ['baz', 'qux'],
76}));
77
78// bulk apply runtime values and reload the list
79filterlist.applyFilters(['foo', 'bar']);
80
81// bulk change values of filters and reload the list
82filterlist.setAndApplyFilters({
83  foo: 'value',
84  bar: ['baz', 'qux'],
85});
86
87// bulk change empty values of filters and reload the list
88filterlist.setAndApplyEmptyFilters({
89  foo: 'value',
90  bar: ['baz', 'qux'],
91});
92
93// bulk reset values of filters and reload the list
94filterlist.resetFilters(['foo', 'bar']);
95
96// reset all setted filters and reload the list
97filterlist.resetAllFilters();
98
99// set sorting state and reload the list
100filterlist.setSorting('id');
101// asc
102filterlist.setSorting('id', true);
103// desc
104filterlist.setSorting('id', false);
105
106// reload sorting state and reload the list
107filterlist.resetSorting();
108
109// reload current list
110filterlist.reload();
111
112// change current page reload the list (for pagination bases lists)
113filterlist.setPage(3);
114
115// change current page reload the list
116filterlist.setPageSize(nextPage);
117
118const {
119  // currently applied filters
120  appliedFilters,
121  // current page
122  page,
123  // number of items on one page
124  pageSize,
125  // sorting state
126  sort: {
127    // sorting parameter
128    param,
129    // asc or desc (boolean)
130    asc,
131  },
132} = filterlist.getRequestParams();
133
134const {
135  // runtime values of filters
136  filters,
137  // is the list currently loading
138  loading,
139  // list of loading items
140  items,
141} = filterlist.getListState();

Filterlist parameters

1const filterlist = new Filterlist({
2	// Create data store to store parameters such as currently applied filtes, sorting state, current page and number of items on one page
3	createDataStore,
4	// function that loads items into the list
5	loadItems,
6	// initially defined list of items
7	items,
8	// initial sorting
9	sort,
10	// filters and their values that applied by default
11	appliedFilters,
12	// request items on init
13	autoload,
14	// debounce timeout to prevent extra requests
15	debounceTimeout,
16	// default `asc` param after change sorting column
17	isDefaultSortAsc,
18	// filters and their values that will be set after filter reset
19	resetFiltersTo,
20	// by default items are cleared if filters or sorting changed. If `saveItemsWhileLoad` is `true`, previous list items are saved while load request is pending
21	saveItemsWhileLoad,
22	// initial page
23	page,
24	// initial size of the page
25	pageSize,
26  // check whether the list should be refreshed by timeout
27  shouldRefresh,
28	// timeout to refresh the list
29	refreshTimeout,
30	// total count of items
31	total,
32});

Navigator url sync

You can use createDataStore parameter

There's an example of synchronization using window.history and window.location here:

1import {
2	createEmitter,
3	createStringBasedDataStore,
4} from "@vtaits/filterlist/datastore/string";
5
6const historyEmitter = createEmitter();
7
8window.addEventListener("popstate", () => {
9	historyEmitter.emit();
10});
11
12function createDataStore() {
13  return createStringBasedDataStore(
14    () => window.location.search,
15    (nextSearch) => {
16      window.history.pushState('', '', `${window.location.pathname}?${nextSearch}`);
17    },
18    historyEmitter,
19    options,
20  );
21};
22
23const filterlist = new Filterlist({
24  createDataStore,
25  // ...
26})

Events

emitter is the instance of mitt.

1import { EventType } from '@vtaits/filterlist';
2
3filterlist.emitter.on(EventType.changeListState, (listState) => {
4  // ...
5});

List of event types:

Name	When triggered
loadMore	after load items on init or call loadMore method
setFilterValue	after call setFilterValue method
applyFilter	after call applyFilter method
setAndApplyFilter	after call setAndApplyFilter method
resetFilter	after call resetFilter method
setFiltersValues	after call setFiltersValues method
applyFilters	after call applyFilters method
setAndApplyFilters	after call setAndApplyFilters method
setAndApplyEmptyFilters	after call setAndApplyEmptyFilters method
setPage	after call setPage method
setPageSize	after call setPageSize method
resetFilters	after call resetFilters method
resetAllFilters	after call resetAllFilters method
setSorting	after call setSorting method
resetSorting	after call resetSorting method
reload	after call reload method
updateStateAndRequest	after call updateStateAndRequest method
changeLoadParams	after call some of next methods: loadMore, applyFilter, setAndApplyFilter, resetFilter, applyFilters, setAndApplyFilters, resetFilters, resetAllFilters, setSorting, resetSorting, updateStateAndRequest
insertItem	after call insertItem method
deleteItem	after call deleteItem method
updateItem	after call updateItem method
requestItems	before load items
loadItemsSuccess	after successfully load
loadItemsError	after load with error
changeListState	after every change of list state