2.4.0 • Published 9 months ago

@vtaits/filterlist v2.4.0

Weekly downloads
73
License
MIT
Repository
github
Last release
9 months ago

NPM dependencies status

@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

Api

import { Filterlist } from '@vtaits/filterlist';

/*
 * assuming the API returns something like this:
 *   const json = {
 *     results: [
 *       {
 *         value: 1,
 *         label: 'Audi',
 *       },
 *       {
 *         value: 2,
 *         label: 'Mercedes',
 *       },
 *       {
 *         value: 3,
 *         label: 'BMW',
 *       },
 *     ],
 *     total: 50,
 *   };
 */

const filterlist = new Filterlist({
  loadItems: async ({
    // currently applied filters
    appliedFilters,
    // current page
    page,
    // number of items on one page
    pageSize,
    // sorting state
    sort: {
      // sorting parameter
      param,
      // asc or desc (boolean)
      asc,
    },
  }, {
    items,
  }) => {
    const response = await fetch(`/awesome-api-url/?page=${page}`);
    const responseJSON = await response.json();

    return {
      items: responseJSON.results,
      total: responseJSON.total,
    };
  },
});

filterlist.emitter.on(eventTypes.changeListState, (nextListState) => {
  // change ui
  document.getElementById('loader').style.display = nextListState.loading ? 'block' : 'none';
});

// load next chunk of   for the infinite list
filterlist.loadMore();

// change runtime value of filter (e.g. on keyboard input)
filterlist.setFilterValue('foo', 'bar');

// apply runtime value and reload the list
filterlist.applyFilter('foo');

// change value of the filter and reload the list
filterlist.setAndApplyFilter('foo', 'bar');

// reset value of the filter and reload the list
filterlist.resetFilter('foo');

// bulk change values of filters (e.g. on keyboard input)
filterlist.setFiltersValues({
  foo: 'value',
  bar: ['baz', 'qux'],
}));

// bulk apply runtime values and reload the list
filterlist.applyFilters(['foo', 'bar']);

// bulk change values of filters and reload the list
filterlist.setAndApplyFilters({
  foo: 'value',
  bar: ['baz', 'qux'],
});

// bulk change empty values of filters and reload the list
filterlist.setAndApplyEmptyFilters({
  foo: 'value',
  bar: ['baz', 'qux'],
});

// bulk reset values of filters and reload the list
filterlist.resetFilters(['foo', 'bar']);

// reset all setted filters and reload the list
filterlist.resetAllFilters();

// set sorting state and reload the list
filterlist.setSorting('id');
// asc
filterlist.setSorting('id', true);
// desc
filterlist.setSorting('id', false);

// reload sorting state and reload the list
filterlist.resetSorting();

// reload current list
filterlist.reload();

// change current page reload the list (for pagination bases lists)
filterlist.setPage(3);

// change current page reload the list
filterlist.setPageSize(nextPage);

const {
  // currently applied filters
  appliedFilters,
  // current page
  page,
  // number of items on one page
  pageSize,
  // sorting state
  sort: {
    // sorting parameter
    param,
    // asc or desc (boolean)
    asc,
  },
} = filterlist.getRequestParams();

const {
  // runtime values of filters
  filters,
  // is the list currently loading
  loading,
  // list of loading items
  items,
} = filterlist.getListState();

Filterlist parameters

const filterlist = new Filterlist({
	// Create data store to store parameters such as currently applied filtes, sorting state, current page and number of items on one page
	createDataStore,
	// function that loads items into the list
	loadItems,
	// initially defined list of items
	items,
	// initial sorting
	sort,
	// filters and their values that applied by default
	appliedFilters,
	// request items on init
	autoload,
	// debounce timeout to prevent extra requests
	debounceTimeout,
	// default `asc` param after change sorting column
	isDefaultSortAsc,
	// filters and their values that will be set after filter reset
	resetFiltersTo,
	// by default items are cleared if filters or sorting changed. If `saveItemsWhileLoad` is `true`, previous list items are saved while load request is pending
	saveItemsWhileLoad,
	// initial page
	page,
	// initial size of the page
	pageSize,
  // check whether the list should be refreshed by timeout
  shouldRefresh,
	// timeout to refresh the list
	refreshTimeout,
	// total count of items
	total,
});

Navigator url sync

You can use createDataStore parameter

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

import {
	createEmitter,
	createStringBasedDataStore,
} from "@vtaits/filterlist/datastore/string";

const historyEmitter = createEmitter();

window.addEventListener("popstate", () => {
	historyEmitter.emit();
});

function createDataStore() {
  return createStringBasedDataStore(
    () => window.location.search,
    (nextSearch) => {
      window.history.pushState('', '', `${window.location.pathname}?${nextSearch}`);
    },
    historyEmitter,
    options,
  );
};

const filterlist = new Filterlist({
  createDataStore,
  // ...
})

Events

emitter is the instance of mitt.

import { EventType } from '@vtaits/filterlist';

filterlist.emitter.on(EventType.changeListState, (listState) => {
  // ...
});

List of event types:

NameWhen triggered
loadMoreafter load items on init or call loadMore method
setFilterValueafter call setFilterValue method
applyFilterafter call applyFilter method
setAndApplyFilterafter call setAndApplyFilter method
resetFilterafter call resetFilter method
setFiltersValuesafter call setFiltersValues method
applyFiltersafter call applyFilters method
setAndApplyFiltersafter call setAndApplyFilters method
setAndApplyEmptyFiltersafter call setAndApplyEmptyFilters method
setPageafter call setPage method
setPageSizeafter call setPageSize method
resetFiltersafter call resetFilters method
resetAllFiltersafter call resetAllFilters method
setSortingafter call setSorting method
resetSortingafter call resetSorting method
reloadafter call reload method
updateStateAndRequestafter call updateStateAndRequest method
changeLoadParamsafter call some of next methods: loadMore, applyFilter, setAndApplyFilter, resetFilter, applyFilters, setAndApplyFilters, resetFilters, resetAllFilters, setSorting, resetSorting, updateStateAndRequest
insertItemafter call insertItem method
deleteItemafter call deleteItem method
updateItemafter call updateItem method
requestItemsbefore load items
loadItemsSuccessafter successfully load
loadItemsErrorafter load with error
changeListStateafter every change of list state
2.4.0-signals.0

9 months ago

2.4.0

9 months ago

2.3.0

10 months ago

2.2.1

11 months ago

2.2.0

11 months ago

2.1.0

12 months ago

2.0.0

1 year ago

1.1.0

1 year ago

1.0.0

1 year ago

0.3.1

2 years ago

0.3.0

3 years ago

0.2.3

4 years ago

0.2.4

4 years ago

0.2.2

5 years ago

0.2.1

5 years ago

0.2.0

5 years ago

0.1.5

6 years ago

0.1.4

6 years ago

0.1.3

6 years ago

0.1.2

6 years ago

0.1.1

7 years ago

0.1.0

7 years ago